@akanjs/devkit 3.2.0-rc.6 → 3.2.0-rc.8

package/commandDecorators/commandDecorators.test.ts

@@ -748,7 +748,7 @@ describe("a target left out where no terminal can ask for it", () => {
 
   test("exits at once with the choices and the line to rerun when there are several", async () => {
     const refused = await run(["web", "admin"]);
-    expect(refused.code).toBe(1);
+    expect(refused.code).toBe(2);
     expect(refused.stdout).toContain(
       "Missing app or lib: stdin is not a terminal to prompt on, so rerun it as `akan create-thing photo <app-or-lib> --force`",
     );
@@ -758,7 +758,7 @@ describe("a target left out where no terminal can ask for it", () => {
 
   test("a destructive command exits with the line to rerun even when the workspace has one app", async () => {
     const refused = await run(["web"], ["remove-thing"]);
-    expect(refused.code).toBe(1);
+    expect(refused.code).toBe(2);
     expect(refused.stdout).toContain(
       "Missing app: this command deletes files and never picks its target, so rerun it as `akan remove-thing <app>` (choices: web).",
     );
@@ -769,7 +769,10 @@ describe("a target left out where no terminal can ask for it", () => {
 
 describe("the exit code of a command that failed", () => {
   const track = tempRoots();
-  const run = async (failure: string, { option = "", args = [] as string[] } = {}) => {
+  const run = async (
+    failure: string,
+    { option = "", args = [], argv = ["verdict", ...args] }: { option?: string; args?: string[]; argv?: string[] } = {},
+  ) => {
     const { root } = track(await makeCliTempWorkspace());
     await writeText(path.join(root, "package.json"), '{ "name": "repo", "version": "1.0.0" }\n');
     await writeText(path.join(root, "tsconfig.json"), "{}\n");
@@ -777,7 +780,8 @@ describe("the exit code of a command that failed", () => {
     await writeText(
       entry,
       [
-        `import { command, ExitCodeError, markCliErrorPrinted, runCommands, runner, script } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        `import { AkanError } from ${JSON.stringify(Bun.resolveSync("akanjs/base", import.meta.dir))};`,
+        `import { CliError, command, ExitCodeError, markCliErrorPrinted, runCommands, runner, script } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
         'class VerdictRunner extends runner("verdict") {}',
         'class VerdictScript extends script("verdict", [VerdictRunner]) {}',
         'class VerdictCommand extends command("verdict", [VerdictScript], ({ public: target }) => ({',
@@ -789,7 +793,7 @@ describe("the exit code of a command that failed", () => {
         "",
       ].join("\n"),
     );
-    const proc = Bun.spawn(["bun", entry, "verdict", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const proc = Bun.spawn(["bun", entry, ...argv], { cwd: root, stdout: "pipe", stderr: "pipe" });
     const [stdout, stderr, code] = await Promise.all([
       new Response(proc.stdout).text(),
       new Response(proc.stderr).text(),
@@ -805,6 +809,28 @@ describe("the exit code of a command that failed", () => {
     expect((await run('new Error("broke")')).code).toBe(1);
   }, 30_000);
 
+  test("is the table's for a CliError's code, and 1 for an AkanError of any other code", async () => {
+    const [checked, unknown, gone] = await Promise.all([
+      run('new CliError("checkFailed", "found problems")'),
+      run('new CliError("unknownTarget", "no app shop")'),
+      run('new AkanError("documentNotFound", "gone")'),
+    ]);
+    expect([checked.code, unknown.code, gone.code]).toEqual([3, 2, 1]);
+    expect(checked.stdout).toContain("found problems");
+  }, 30_000);
+
+  test("is 2 for a flag commander refuses, a value outside the choices and an unknown command", async () => {
+    const choice = ' }).option("mode", String, { enum: ["a", "b"]';
+    const [flag, outside, unknownCommand] = await Promise.all([
+      run('new Error("broke")', { args: ["--nope"] }),
+      run('new Error("broke")', { option: choice, args: ["--mode", "c"] }),
+      run('new Error("broke")', { argv: ["verdikt"] }),
+    ]);
+    expect([flag.code, outside.code, unknownCommand.code]).toEqual([2, 2, 2]);
+    expect(outside.stdout).toContain("option '--mode' argument 'c' is invalid");
+    expect(unknownCommand.stderr).toContain("unknown command 'verdikt'");
+  }, 30_000);
+
   test("is usageExitCode for a flag commander refuses before the command runs, failureExitCode after", async () => {
     const option = ", failureExitCode: 4, usageExitCode: 2";
     expect((await run('new Error("broke")', { option, args: ["--nope"] })).code).toBe(2);
@@ -832,7 +858,7 @@ describe("the exit code of a command that failed", () => {
 
     const thrown = await run('new Error("broke")', { option, args: ["--json"] });
     expect(thrown.code).toBe(1);
-    expect(thrown.stdout).toContain("broke\n");
+    expect(thrown.stderr).toContain("broke\n");
     expect(lastOf(thrown.stdout)).toEqual({ message: "broke", usage: false, given: { json: true } });
 
     const help = await run('new Error("broke")', { option, args: ["--help"] });
@@ -840,6 +866,66 @@ describe("the exit code of a command that failed", () => {
     expect(help.stdout).not.toContain('"usage"');
   }, 60_000);
 
+  test("with JSON asked for, ends stdout with ok, error and code, and prints the message to stderr", async () => {
+    const json = ' }).option("json", Boolean, { default: false';
+    const format = ' }).option("format", String, { default: "text", enum: ["text", "json"]';
+    const marked =
+      '(() => { const error = new CliError("checkFailed", "verify failed"); markCliErrorPrinted(error); return error; })()';
+    const [unknown, plain, refused, answered, text] = await Promise.all([
+      run('new CliError("unknownTarget", "no app shop")', { option: json, args: ["--json"] }),
+      run('new Error("broke")', { option: format, args: ["--format", "json"] }),
+      run('new Error("broke")', { option: json, args: ["--json", "--nope"] }),
+      run(marked, { option: format, args: ["--format", "json"] }),
+      run('new Error("broke")', { option: format }),
+    ]);
+    expect(unknown.code).toBe(2);
+    expect(JSON.parse(unknown.stdout)).toEqual({ ok: false, error: "no app shop", code: "unknownTarget" });
+    expect(unknown.stderr).toContain("no app shop");
+    expect(plain.code).toBe(1);
+    expect(JSON.parse(plain.stdout)).toEqual({ ok: false, error: "broke", code: "failed" });
+    expect(refused.code).toBe(2);
+    expect(JSON.parse(refused.stdout)).toEqual({ ok: false, error: "unknown option '--nope'", code: "usage" });
+    expect(answered.code).toBe(3);
+    expect(answered.stdout.trim()).toBe("");
+    expect(text.stdout).toContain("broke\n");
+    expect(text.stdout).not.toContain('"code"');
+  }, 60_000);
+
+  test("is usageExitCode for a usage or unknown-target failure where 2 answers something else", async () => {
+    const option = ", usageExitCode: 1";
+    const [flag, unknown, verdict] = await Promise.all([
+      run('new Error("broke")', { option, args: ["--nope"] }),
+      run('new CliError("unknownTarget", "Unknown app \'shop\'")', { option }),
+      run('new ExitCodeError("needs a new store build", 2)', { option }),
+    ]);
+    expect([flag.code, unknown.code, verdict.code]).toEqual([1, 1, 2]);
+  }, 30_000);
+
+  test("is 130 for a prompt closed with Ctrl+C", async () => {
+    const closed = await run(
+      'Object.assign(new Error("User force closed the prompt with SIGINT"), { name: "ExitPromptError" })',
+    );
+    expect(closed.code).toBe(130);
+  }, 30_000);
+
+  test("answers JSON for an ExitCodeError, a thrown object and an unhandled rejection", async () => {
+    const json = ' }).option("json", Boolean, { default: false';
+    const late = 'await (void Promise.reject(new CliError("refused", "late")), new Promise(() => {}))';
+    const [verdict, checked, thrown, rejected] = await Promise.all([
+      run('new ExitCodeError("needs a new store build", 2)', { option: json, args: ["--json"] }),
+      run('new ExitCodeError("found problems", 3)', { option: json, args: ["--json"] }),
+      run('{ reason: "an object" }', { option: json, args: ["--json"] }),
+      run(late, { option: json, args: ["--json"] }),
+    ]);
+    expect(JSON.parse(verdict.stdout)).toEqual({ ok: false, error: "needs a new store build", code: "refused" });
+    expect(verdict.code).toBe(2);
+    expect(JSON.parse(checked.stdout)).toEqual({ ok: false, error: "found problems", code: "checkFailed" });
+    expect(checked.code).toBe(3);
+    expect(JSON.parse(thrown.stdout)).toEqual({ ok: false, error: '{"reason":"an object"}', code: "failed" });
+    expect(JSON.parse(rejected.stdout)).toEqual({ ok: false, error: "late", code: "refused" });
+    expect(rejected.code).toBe(2);
+  }, 60_000);
+
   test("prints nothing more for an error the command marked as printed", async () => {
     const marked = await run(
       '(() => { const error = new Error("printed already"); markCliErrorPrinted(error); return error; })()',

package/commandDecorators/exitCodeError.ts

@@ -1,15 +1,14 @@
+import { CliError } from "./cliError";
+
 //* A failure that is an answer, not a breakage: the CLI exits with its code, so a CI tells the two apart.
-export class ExitCodeError extends Error {
+export class ExitCodeError extends CliError {
   override readonly name = "ExitCodeError";
 
-  constructor(
-    message: string,
-    readonly exitCode: number,
-  ) {
-    super(message);
+  constructor(message: string, exitCode: number) {
+    super(exitCode === 2 ? "refused" : exitCode === 3 ? "checkFailed" : "failed", message, { exitCode });
   }
 
   static codeOf(error: unknown): number | null {
-    return error instanceof ExitCodeError ? error.exitCode : null;
+    return CliError.exitCodeOf(error);
   }
 }

package/commandDecorators/index.ts

@@ -1,4 +1,5 @@
 export * from "./argMeta";
+export * from "./cliError";
 export * from "./command";
 export * from "./commandBuilder";
 export * from "./dependencyBuilder";

package/commandDecorators/targetMeta.ts

@@ -44,6 +44,7 @@ export interface TargetOption {
   runsOnWorkspaceRoot?: boolean;
   stdio?: boolean;
   failureExitCode?: number;
+  /** The exit of a `usage` or `unknownTarget` failure, for a command whose 2 already answers something else. */
   usageExitCode?: number;
   /** It deletes files in its app, lib, pkg or module, so one left out or unknown is refused, never picked or asked. */
   destructive?: boolean;

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -68,6 +68,31 @@ describe("IncrementalBuilderHost", () => {
     host.stop();
   });
 
+  test("a stop while a restart is pending leaves the builder down once the delay passes", async () => {
+    const { spawns, host } = startRecordingHost();
+    spawns[0]?.options.onExit?.();
+    expect(host.status).toBe("restarting");
+
+    host.stop();
+    await wait(1_050);
+    expect(spawns).toHaveLength(1);
+    expect(host.status).toBe("stopped");
+  });
+
+  test("a builder that crashes again after coming back ready waits the first delay again", async () => {
+    const { spawns, host } = startRecordingHost();
+    spawns[0]?.options.onExit?.();
+    await wait(1_050);
+    expect(spawns).toHaveLength(2);
+
+    spawns[1]?.options.ipc?.({ type: "builder-ready" });
+    spawns[1]?.options.onExit?.();
+    await wait(1_050);
+    expect(spawns).toHaveLength(3);
+
+    host.stop();
+  });
+
   test("recycles a ready builder gracefully and replaces it immediately", async () => {
     const spawns = mockSpawns();
     const onRestartReady = mock();

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { Logger } from "akanjs/common";
+import { Logger, RestartSchedule } from "akanjs/common";
 import type { BuilderMessage, BuilderRequest } from "akanjs/server";
 import { CSR_DEV_DIRNAME, CSR_DEV_PATCHING_MARKER, SSR_DEV_DIRNAME } from "akanjs/server/hmr/csrDevManifest";
 import { MemoryLimit } from "akanjs/server/memoryLimit";
@@ -49,8 +49,6 @@ interface IncrementalBuilderStartOptions {
 }
 
 export class IncrementalBuilderHost {
-  static readonly #restartBaseDelayMs = 1_000;
-  static readonly #restartMaxDelayMs = 30_000;
   static readonly #recycleDrainTimeoutMs = 30_000;
   // apps/akan's builder peaks near 950MB holding the SSR registry's patcher through a route build, and arming CSR adds
   // a second patcher: this recycles only a builder grown well past both.
@@ -65,8 +63,7 @@ export class IncrementalBuilderHost {
   readonly #onOutput: ((kind: "stdout" | "stderr", text: string) => void) | null;
   #proc: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #status: IncrementalBuilderStatus = "stopped";
-  #restartAttempts = 0;
-  #restartTimer: ReturnType<typeof setTimeout> | null = null;
+  readonly #restart = new RestartSchedule({ min: 1_000, max: 30_000 });
   #recycleTimer: ReturnType<typeof setTimeout> | null = null;
   #recycleRequested: boolean = false;
   #spawnAfterRecycle: boolean = false;
@@ -136,7 +133,7 @@ export class IncrementalBuilderHost {
         if (msg.type === "builder-ready" && !this.ready) {
           this.ready = true;
           this.#status = "ready";
-          this.#restartAttempts = 0;
+          this.#restart.reset();
           if (isRestart) this.#startOptions.onRestartReady?.();
           else this.#startOptions.onReady?.();
         }
@@ -210,20 +207,13 @@ export class IncrementalBuilderHost {
     }
   }
   #scheduleRestart() {
-    if (this.#manualStop || this.#restartTimer) return;
+    if (this.#manualStop || this.#restart.pending) return;
     this.#status = "restarting";
-    const attempt = this.#restartAttempts;
-    const delay = Math.min(
-      IncrementalBuilderHost.#restartBaseDelayMs * 2 ** attempt,
-      IncrementalBuilderHost.#restartMaxDelayMs,
-    );
-    this.#restartAttempts = attempt + 1;
-    this.logger.warn(`builder exited after ready; restarting in ${delay}ms (attempt ${this.#restartAttempts})`);
-    this.#restartTimer = setTimeout(() => {
-      this.#restartTimer = null;
+    const delay = this.#restart.schedule(() => {
       if (this.#manualStop) return;
       this.#spawn(true);
-    }, delay);
+    });
+    this.logger.warn(`builder exited after ready; restarting in ${delay}ms (attempt ${this.#restart.attempts})`);
   }
   /** Drain-and-exit rather than `kill()`, so no rebuild is truncated; false when the request was not sent. */
   recycle(reason: string): boolean {
@@ -294,10 +284,7 @@ export class IncrementalBuilderHost {
     this.#manualStop = true;
     this.#clearRecycle();
     this.#failInFlight("builder was stopped before answering");
-    if (this.#restartTimer) {
-      clearTimeout(this.#restartTimer);
-      this.#restartTimer = null;
-    }
+    this.#restart.cancel();
     if (this.#proc) this.#proc.kill();
     this.#proc = null;
     this.ready = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.2.0-rc.6",
+  "version": "3.2.0-rc.8",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.6",
+    "@akanjs/language": "3.2.0-rc.8",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.2.0-rc.6",
+    "akanjs": "3.2.0-rc.8",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/typecheck/projectTypecheck.ts

@@ -1,5 +1,6 @@
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
+import { CliError } from "../commandDecorators/cliError";
 import type { TypecheckRecord } from "../typeChecker";
 import { TypecheckFailure } from "./typecheckFailure";
 
@@ -69,7 +70,10 @@ export class ProjectTypecheck {
     if (exitCode === 0) return;
     const records = report === "records" ? ProjectTypecheck.#parseRecords(stdout) : null;
     if (records?.length) throw new TypecheckFailure(records);
-    throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+    const output = (stderr || stdout).trim();
+    if (exitCode === TypecheckFailure.workerExitCode && report === "pretty")
+      throw new CliError("checkFailed", output || "Typecheck failed");
+    throw new Error(output || `Typecheck failed with exit code ${exitCode}`);
   }
 
   static #parseRecords(stdout: string): TypecheckRecord[] | null {

package/typecheck/typecheck.proc.ts

@@ -1,5 +1,6 @@
 import { Logger } from "akanjs/common";
 import { TypeChecker } from "../typeChecker";
+import { TypecheckFailure } from "./typecheckFailure";
 
 try {
   const filePath = process.env.AKAN_TYPECHECK_FILE;
@@ -28,11 +29,11 @@ try {
     //? Not process.cwd(): that is the realpath (/private/var on macOS) while TypeScript keeps the spelling it was given.
     const root = process.env.AKAN_TYPECHECK_ROOT ?? process.cwd();
     process.stdout.write(JSON.stringify(TypeChecker.toRecords(result.errors, root)));
-    process.exit(result.errors.length > 0 ? 1 : 0);
+    process.exit(result.errors.length > 0 ? TypecheckFailure.workerExitCode : 0);
   }
   if (result.errors.length > 0) {
     console.error(result.message);
-    process.exit(1);
+    process.exit(TypecheckFailure.workerExitCode);
   }
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));

package/typecheck/typecheckFailure.ts

@@ -1,8 +1,13 @@
+import { CliError } from "../commandDecorators/cliError";
 import type { TypecheckRecord } from "../typeChecker";
 
-export class TypecheckFailure extends Error {
+export class TypecheckFailure extends CliError<"checkFailed"> {
+  //? The worker's exit when the project has type errors, so its crash, which exits 1, is told apart.
+  static readonly workerExitCode = 3;
+
   constructor(readonly records: TypecheckRecord[]) {
     super(
+      "checkFailed",
       records
         .slice(0, 20)
         .map((record) => `${record.file ?? "-"}:${record.line}:${record.col} ${record.code} ${record.message}`)

package/workflow/artifacts.ts

@@ -95,11 +95,11 @@ export const createWorkflowApplyReport = ({
   postApplyChecks?: WorkflowApplyReport["postApplyChecks"];
   recommendations?: WorkflowApplyReport["recommendations"];
 }): WorkflowApplyReport => {
-  const validationCommands = recommendedValidationCommands ?? commands;
-  const nextActionsWithIntent = nextActions.map((action) => ({
-    ...action,
-    action: inferNextActionCode(action, diagnostics),
-  }));
+  const status = workflowStatus(diagnostics);
+  const validationCommands = status === "failed" ? [] : (recommendedValidationCommands ?? commands);
+  const nextActionsWithIntent = nextActions
+    .map((action) => ({ ...action, action: inferNextActionCode(action, diagnostics) }))
+    .filter((action) => status !== "failed" || action.action !== "validate");
   if (sourceChangeBlocked(diagnostics) && !nextActionsWithIntent.some((action) => action.action === "blocked")) {
     nextActionsWithIntent.unshift({
       command: `akan workflow explain ${workflow}`,
@@ -111,12 +111,13 @@ export const createWorkflowApplyReport = ({
     (left, right) => nextActionPriority(left, diagnostics) - nextActionPriority(right, diagnostics),
   );
   const sourceFilesChanged = uniqueBy(changedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
-  const generatedFilesSynced = uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
+  const generatedFilesSynced =
+    status === "failed" ? [] : uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
   return {
     schemaVersion: 1,
     workflow,
     mode,
-    status: workflowStatus(diagnostics),
+    status,
     summary: {
       sourceFilesChanged,
       generatedFilesSynced,

package/workflow/fieldType.ts

@@ -0,0 +1,92 @@
+import ts from "typescript";
+import type { Sys } from "../commandDecorators";
+import { ensureBaseImport, ensureNamedImport, getSysRoot, moduleComponentName, moduleSourcePaths } from "./source";
+import { sourceFileFor } from "./sourceAst";
+import type { WorkflowDiagnostic } from "./types";
+
+const builtInFieldTypes = new Set(["String", "Boolean", "Date", "Map"]);
+const baseFieldTypes = new Set(["Int", "Float", "ID", "Any", "Binary", "ImageResult"]);
+const fieldTypeReference = /^\[*([A-Za-z_$][\w$]*)((?:\.[A-Za-z_$][\w$]*)*)\]*$/;
+
+export const ensureBaseTypeImport = (content: string, typeName: string) => {
+  const [, name = "", member] = fieldTypeReference.exec(typeName) ?? [];
+  if (member || !baseFieldTypes.has(name)) return content;
+  return ensureBaseImport(content, name);
+};
+
+const valueNamesOf = (content: string) => {
+  const names = new Set<string>();
+  for (const statement of sourceFileFor("source.ts", content).statements) {
+    if (ts.isImportDeclaration(statement)) {
+      const clause = statement.importClause;
+      if (!clause || clause.isTypeOnly) continue;
+      if (clause.name) names.add(clause.name.text);
+      const bindings = clause.namedBindings;
+      if (bindings && ts.isNamespaceImport(bindings)) names.add(bindings.name.text);
+      else for (const element of bindings?.elements ?? []) if (!element.isTypeOnly) names.add(element.name.text);
+    } else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations)
+        if (ts.isIdentifier(declaration.name)) names.add(declaration.name.text);
+    } else if (
+      (ts.isClassDeclaration(statement) || ts.isEnumDeclaration(statement) || ts.isFunctionDeclaration(statement)) &&
+      statement.name
+    )
+      names.add(statement.name.text);
+  }
+  return names;
+};
+
+export const fieldTypeSource = async (
+  sys: Sys,
+  module: string,
+  typeName: string,
+  constantContent: string,
+): Promise<{ import?: { name: string; from: string }; diagnostic?: WorkflowDiagnostic }> => {
+  const reference = fieldTypeReference.exec(typeName);
+  if (!reference)
+    return {
+      diagnostic: {
+        severity: "error",
+        code: "primitive-field-type-unknown",
+        input: "type",
+        message: `Field type "${typeName}" is not a type name field() takes. Name one type, such as Address, or a list of one, such as [Address], then plan this again.`,
+      },
+    };
+  const [, name = "", member] = reference;
+  if (builtInFieldTypes.has(name) || baseFieldTypes.has(name) || valueNamesOf(constantContent).has(name)) return {};
+  const [scalars, models] = await Promise.all([sys.getScalarModules(), sys.getDatabaseModules()]);
+  const scalar = member ? undefined : scalars.find((scalarName) => moduleComponentName(scalarName) === name);
+  if (scalar) return { import: { name, from: `../__scalar/${scalar}/${scalar}.constant` } };
+  const model = member ? undefined : models.find((modelName) => moduleComponentName(modelName) === name);
+  if (model) return { import: { name, from: `../${model}/${model}.constant` } };
+  const root = getSysRoot(sys);
+  const constantPath = `${root}/${moduleSourcePaths(module).constant}`;
+  const named = (kind: string, names: string[]) =>
+    names.length ? `Its ${kind} are ${names.map(moduleComponentName).join(", ")}.` : `It has no ${kind}.`;
+  return {
+    diagnostic: {
+      severity: "error",
+      code: "primitive-field-type-unknown",
+      input: "type",
+      message: [
+        `Field type "${typeName}" names ${name}, which is not a built-in or akanjs/base type, not imported by ${constantPath}, and not a scalar or model in ${root}.`,
+        named("scalars", scalars),
+        named("models", models),
+        `Create the scalar with the create-scalar workflow first, or import ${name} into ${constantPath}, then plan this again.`,
+      ].join(" "),
+    },
+  };
+};
+
+export const withFieldTypeImport = async (
+  sys: Sys,
+  module: string,
+  typeName: string,
+  content: string,
+  diagnostics: WorkflowDiagnostic[],
+) => {
+  const withBaseImport = ensureBaseTypeImport(content, typeName);
+  const source = await fieldTypeSource(sys, module, typeName, withBaseImport);
+  if (source.diagnostic) diagnostics.push(source.diagnostic);
+  return source.import ? ensureNamedImport(withBaseImport, source.import.from, source.import.name) : withBaseImport;
+};

package/workflow/index.ts

@@ -1,5 +1,6 @@
 export * from "./artifacts";
 export * from "./executor";
+export * from "./fieldType";
 export * from "./guardCatalog";
 export * from "./interactionScaffold";
 export * from "./keyRename";

package/workflow/plan.ts

@@ -2,11 +2,12 @@ import { capitalize } from "akanjs/common";
 import type { Sys, Workspace } from "../commandDecorators";
 import { withoutApplyHints, workflowPlanApproval } from "./artifacts";
 import { resolveWorkflowSys } from "./executor";
+import { fieldTypeSource } from "./fieldType";
 import { InteractionScaffold } from "./interactionScaffold";
 import { KeyRename } from "./keyRename";
 import { MutationScaffold } from "./mutationScaffold";
 import { identifierPattern, sysNamePattern } from "./plainName";
-import { coerceFieldDefault, getSysRoot, moduleSourcePaths } from "./source";
+import { coerceFieldDefault, getSysRoot, moduleSourcePaths, normalizeFieldType } from "./source";
 import type {
   WorkflowDiagnostic,
   WorkflowInputSpec,
@@ -541,6 +542,13 @@ const moduleNotDatabase = async (sys: Sys, spec: WorkflowSpec, module: string):
   };
 };
 
+const fieldTypeUnknown = async (sys: Sys, spec: WorkflowSpec, module: string, type: string | null) => {
+  if (spec.name !== "add-field" || !type || ["enum", "number", "numeric", "upload"].includes(type.toLowerCase()))
+    return null;
+  const constant = await sys.readFile(moduleSourcePaths(module).constant);
+  return (await fieldTypeSource(sys, module, normalizeFieldType(type), constant)).diagnostic ?? null;
+};
+
 export const workflowTargetDiagnostics = async (
   workspace: Workspace,
   spec: WorkflowSpec,
@@ -563,7 +571,10 @@ export const workflowTargetDiagnostics = async (
   const module = planString(inputs, "module");
   const moduleSpec: WorkflowInputSpec | undefined = spec.inputs.module;
   if (!module || !moduleSpec?.mustExist) return [];
-  const refused = (await moduleMissing(workspace, sys, module)) ?? (await moduleNotDatabase(sys, spec, module));
+  const refused =
+    (await moduleMissing(workspace, sys, module)) ??
+    (await moduleNotDatabase(sys, spec, module)) ??
+    (await fieldTypeUnknown(sys, spec, module, planString(inputs, "type")));
   return refused ? [refused] : [];
 };
 

package/workflow/source.ts

@@ -238,11 +238,6 @@ export const ensureImportDeclaration = (content: string, moduleSpecifier: string
 
 export const ensureBaseImport = (content: string, name: string) => ensureNamedImport(content, "akanjs/base", name);
 
-export const ensureBaseTypeImport = (content: string, typeName: string) => {
-  if (typeName !== "Int" && typeName !== "Float") return content;
-  return ensureBaseImport(content, typeName);
-};
-
 export type FieldDefaultValue = string | number | boolean | null;
 
 const numericDefault = (typeName: "Int" | "Float", rawDefault: FieldDefaultValue): string | null => {