fix(appkit): don't misdirect cache-unrelated typegen fatals to .appkit/

Make TypegenFatalError's cacheInitialized snapshot optional. A cache-unrelated
fatal (e.g. a malformed definitions.json) now omits it and gets generic
"Fix the FATAL error(s) above, then re-run generate-types" wording, instead of
the bootstrap/drift message telling the operator to regenerate and commit
.appkit/ (which only applies to failures tied to the type cache).

Co-authored-by: Isaac
Signed-off-by: Atila Fassina <atila@fassina.eu>

Author: atilafassina

packages/appkit/src/type-generator/index.ts

@@ -178,17 +178,25 @@ export class TypegenFatalError extends Error {
   constructor(
     queries: QueryFatalError[],
     warehouseId?: string,
-    cacheInitialized: boolean = true,
+    cacheInitialized?: boolean,
   ) {
-    // Distinguish bootstrap (no committed cache yet) from drift (cache exists but is stale/missing key).
-    // Bootstrap → operator needs to initialize; drift → operator needs to regenerate the affected key.
-    const nextStep = cacheInitialized
-      ? // Drift: cache file exists but is missing/stale for the failing query/metric.
-        warehouseId
-        ? `The committed ${pc.bold(".appkit/")} cache is missing or stale for the failed ${plural(queries.length, "query", "queries")}. Regenerate with ${pc.bold("generate-types --wait")} against warehouse ${pc.bold(warehouseId)} and commit ${pc.bold(".appkit/")}.`
-        : `The committed ${pc.bold(".appkit/")} cache is missing or stale for the failed ${plural(queries.length, "query", "queries")}. Regenerate with ${pc.bold("generate-types --wait")} against a warehouse and commit ${pc.bold(".appkit/")}.`
-      : // Bootstrap: no committed cache found; operator needs to initialize from scratch.
-        `No committed type cache found (${pc.bold(".appkit/")}). Run ${pc.bold("generate-types --wait")} against a warehouse and commit ${pc.bold(".appkit/")} before building without warehouse access.`;
+    // The cache snapshot is optional: callers whose failure relates to the type
+    // cache pass it to get bootstrap/drift remediation; callers with an unrelated
+    // fatal (e.g. a malformed definitions.json) omit it and get generic wording.
+    const nextStep =
+      cacheInitialized === undefined
+        ? // No cache snapshot: the failure is unrelated to the cache — don't
+          // misdirect the operator toward regenerating/committing `.appkit/`.
+          `Fix the ${pc.bold("FATAL")} error(s) above, then re-run ${pc.bold("generate-types")}.`
+        : // Distinguish bootstrap (no committed cache yet) from drift (cache exists but is stale/missing key).
+          // Bootstrap → operator needs to initialize; drift → operator needs to regenerate the affected key.
+          cacheInitialized
+          ? // Drift: cache file exists but is missing/stale for the failing query/metric.
+            warehouseId
+            ? `The committed ${pc.bold(".appkit/")} cache is missing or stale for the failed ${plural(queries.length, "query", "queries")}. Regenerate with ${pc.bold("generate-types --wait")} against warehouse ${pc.bold(warehouseId)} and commit ${pc.bold(".appkit/")}.`
+            : `The committed ${pc.bold(".appkit/")} cache is missing or stale for the failed ${plural(queries.length, "query", "queries")}. Regenerate with ${pc.bold("generate-types --wait")} against a warehouse and commit ${pc.bold(".appkit/")}.`
+          : // Bootstrap: no committed cache found; operator needs to initialize from scratch.
+            `No committed type cache found (${pc.bold(".appkit/")}). Run ${pc.bold("generate-types --wait")} against a warehouse and commit ${pc.bold(".appkit/")} before building without warehouse access.`;
 
     super(
       formatTypegenFailureMessage({

packages/appkit/src/type-generator/tests/index.test.ts

@@ -727,6 +727,11 @@ describe("generateFromEntryPoint — metric-view emission", () => {
 
     expect(error).toBeInstanceOf(TypegenFatalError);
     expect((error as Error).message).toContain("definitions.json");
+    // A config parse error is unrelated to the type cache: the remediation must
+    // NOT tell the operator to regenerate/commit `.appkit/` (that's the cache
+    // bootstrap/drift wording, reserved for callers that pass the cache snapshot).
+    expect((error as Error).message).not.toContain(".appkit/");
+    expect((error as Error).message).toContain("Fix the");
     // Query types were written before the metric config was read.
     expect(fs.existsSync(outFile)).toBe(true);
   });