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

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.7",
+  "version": "3.2.0-rc.8",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.7",
+    "@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.7",
+    "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 => {