@akanjs/devkit 3.1.1-rc.8 → 3.1.1

package/typecheck/projectTypecheck.ts

@@ -1,11 +1,15 @@
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
+import type { TypecheckRecord } from "../typeChecker";
+import { TypecheckFailure } from "./typecheckFailure";
 
 export interface ProjectTypecheckOptions {
   clean?: boolean;
   incremental?: boolean;
   /** The project's own `*.test.ts` / `*.spec.ts` as well. */
   tests?: boolean;
+  /** `records` fails with a `TypecheckFailure` carrying one record per diagnostic instead of the printed report. */
+  report?: "pretty" | "records";
 }
 
 //* tsc checks what the entries import, and nothing imports a test, so a test is checked only when it is included by
@@ -25,7 +29,10 @@ export class ProjectTypecheck {
   }
 
   /** `entries`: relative to the typecheck folder (`../../server.ts`). */
-  async run(entries: string[], { clean = false, incremental = true, tests = false }: ProjectTypecheckOptions = {}) {
+  async run(
+    entries: string[],
+    { clean = false, incremental = true, tests = false, report = "pretty" }: ProjectTypecheckOptions = {},
+  ) {
     const name = tests ? "tsconfig.tests" : "tsconfig";
     await mkdir(this.typecheckDir, { recursive: true });
     const tsconfig = {
@@ -38,14 +45,19 @@ export class ProjectTypecheck {
     const tsconfigPath = path.join(this.typecheckDir, `${name}.json`);
     await Bun.write(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}\n`);
     if (clean) await rm(path.join(this.typecheckDir, `${name}.tsbuildinfo`), { force: true });
-    await this.#check(tsconfigPath);
+    await this.check(tsconfigPath, report);
     return tsconfigPath;
   }
 
-  async #check(tsconfigPath: string) {
+  async check(tsconfigPath: string, report: "pretty" | "records" = "pretty") {
     const proc = Bun.spawn([process.execPath, await ProjectTypecheck.workerEntry(this.workspaceRoot)], {
       cwd: this.workspaceRoot,
-      env: { ...this.env, AKAN_COMMAND_TYPE: "typecheck", AKAN_TYPECHECK_TSCONFIG: tsconfigPath },
+      env: {
+        ...this.env,
+        AKAN_COMMAND_TYPE: "typecheck",
+        AKAN_TYPECHECK_TSCONFIG: tsconfigPath,
+        ...(report === "records" ? { AKAN_TYPECHECK_FORMAT: "json", AKAN_TYPECHECK_ROOT: this.workspaceRoot } : {}),
+      },
       stdout: "pipe",
       stderr: "pipe",
     });
@@ -54,7 +66,19 @@ export class ProjectTypecheck {
       new Response(proc.stderr).text(),
       proc.exited,
     ]);
-    if (exitCode !== 0) throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+    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}`);
+  }
+
+  static #parseRecords(stdout: string): TypecheckRecord[] | null {
+    try {
+      const parsed: unknown = JSON.parse(stdout);
+      return Array.isArray(parsed) ? (parsed as TypecheckRecord[]) : null;
+    } catch {
+      return null;
+    }
   }
 
   //? The workspace's own devkit first, then an installed one, then the entry a bundle puts beside its chunks.

package/typecheck/typecheck.proc.ts

@@ -24,6 +24,12 @@ try {
   const configPath = process.env.AKAN_TYPECHECK_TSCONFIG;
   if (!configPath) throw new Error("AKAN_TYPECHECK_TSCONFIG is required");
   const result = TypeChecker.checkProject(configPath);
+  if (process.env.AKAN_TYPECHECK_FORMAT === "json") {
+    //? 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);
+  }
   if (result.errors.length > 0) {
     console.error(result.message);
     process.exit(1);

package/typecheck/typecheckFailure.ts

@@ -0,0 +1,13 @@
+import type { TypecheckRecord } from "../typeChecker";
+
+export class TypecheckFailure extends Error {
+  constructor(readonly records: TypecheckRecord[]) {
+    super(
+      records
+        .slice(0, 20)
+        .map((record) => `${record.file ?? "-"}:${record.line}:${record.col} ${record.code} ${record.message}`)
+        .join("\n") || "Typecheck failed",
+    );
+    this.name = "TypecheckFailure";
+  }
+}

package/types.ts

@@ -12,6 +12,7 @@ export interface PackageJson {
   optionalDependencies?: Record<string, string>;
   trustedDependencies?: string[];
   overrides?: Record<string, string>;
+  resolutions?: Record<string, string>;
   engines?: Record<string, string>;
   exports?: Record<string, string | Record<string, string>>;
   bun?: {

package/workflow/artifacts.ts

@@ -1,5 +1,6 @@
 import { capitalize } from "akanjs/common";
 import type { Workspace } from "../commandDecorators";
+import { InteractionScaffold } from "./interactionScaffold";
 import type {
   GeneratedSyncState,
   PrimitiveChangedFile,
@@ -156,11 +157,15 @@ export const workflowPathsForPlan = (plan: WorkflowPlan) => {
   const app = planInputString(plan, "app");
   const module = planInputString(plan, "module");
   const moduleClass = module ? capitalize(module) : "<Module>";
+  const rawInteraction = planInputString(plan, "interaction");
+  const interaction = rawInteraction ? (InteractionScaffold.nameOf(rawInteraction) ?? rawInteraction) : null;
   return plan.predictedChanges.map((change) =>
     change.target
       .replace(/^\*\//, app ? `apps/${app}/` : "")
       .replaceAll("<module>", module || "<module>")
-      .replaceAll("<Module>", moduleClass),
+      .replaceAll("<Module>", moduleClass)
+      .replaceAll("<interaction>", interaction || "<interaction>")
+      .replaceAll("<Interaction>", interaction ? capitalize(interaction) : "<Interaction>"),
   );
 };
 
@@ -277,6 +282,15 @@ const statusForValidationKind = (
   return matching.some((command) => command.status === "failed") ? "failed" : "passed";
 };
 
+//? `akan verify` syncs first and names a failed sync in its header line (`sync 1 error`), so one run answers both.
+const generatedSyncStatus = (commands: readonly WorkflowValidationCommandResult[]): WorkflowValidationStatus => {
+  const sync = statusForValidationKind(commands, "sync");
+  const verify = commands.filter((command) => command.kind === "verify");
+  if (sync !== "unknown" || verify.length === 0) return sync;
+  const syncFailed = verify.some((command) => /^verify fail · .*\bsync \d+ errors?\b/m.test(command.stdout ?? ""));
+  return syncFailed ? "failed" : "passed";
+};
+
 const statusForCommands = (commands: readonly WorkflowValidationCommandResult[]): WorkflowValidationStatus => {
   if (commands.length === 0) return "unknown";
   return commandStatus(commands) === "failed" ? "failed" : "passed";
@@ -433,7 +447,7 @@ const createValidationStatuses = (
     overallStatus,
     summary: {
       sourceChange: sourceStatus,
-      generatedSync: statusForValidationKind(commands, "sync"),
+      generatedSync: generatedSyncStatus(commands),
       validationCommands: validationCommandsStatus,
       baseline: baselineStatus,
       workspaceConfig: statusForScope(commands, diagnostics, scopes, "workspace-config"),

package/workflow/executor.ts

@@ -312,7 +312,7 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
   return { diagnostics, postApplyChecks };
 };
 
-const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
+export const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
   if (!target) return null;
   const [apps, libs] = await workspace.getSyss();
   if (apps.includes(target)) return AppExecutor.from(workspace, target);
@@ -375,10 +375,10 @@ const addMutationActionSurfaceInspection = (plan: WorkflowPlan): WorkflowStepRes
   const moduleClassName = moduleComponentName(module);
   return surfaceReview(plan, {
     code: "add-mutation-action-surface-review",
-    target: `*/${moduleSourcePaths(module).store}`,
-    action: `Name the endpoint's guards and add its dictionary .endpoint() entry with a .desc(). After sync, fetch.${mutation} exists; write a store action only for a toast, an optimistic update, or a multi-field write, and put the control that calls it in ${moduleClassName}.Util.tsx.`,
-    message: `Workflow apply does not write store or UI code for ${module}.${mutation}; review whether a screen should call it.`,
-    reason: "Review action surface guidance before manually editing store or UI files.",
+    target: `*/${moduleSourcePaths(module).util}`,
+    action: `Fill the ${moduleClassName} chain method (validate, mutate, return this) and replace its transition comment. After sync, call st.do.${mutation}(id) from the control in ${moduleClassName}.Util.tsx; a second write that must land with it is another with/after entry, never a second fetch in the store action.`,
+    message: `Workflow apply does not write UI code for ${module}.${mutation}; review which screen calls it.`,
+    reason: "Review action surface guidance before manually editing UI files.",
   });
 };
 
@@ -404,6 +404,7 @@ export const createWorkflowStepRegistry = ({
   addEnumField,
   addMutation,
   addSlice,
+  createInteraction,
 }: WorkflowPrimitiveOperations): WorkflowStepRegistry => {
   const inspect = async () => undefined;
   const commandOnly = async () => undefined;
@@ -484,17 +485,31 @@ export const createWorkflowStepRegistry = ({
       ),
     [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
     [workflowStepKey("add-enum-field", "update-option")]: inspect,
-    [workflowStepKey("add-mutation", "update-service")]: async (_step, plan) =>
+    [workflowStepKey("add-mutation", "update-document")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addMutation({
           app: workflowStringInput(plan.inputs.app),
           module: workflowStringInput(plan.inputs.module),
           mutation: workflowStringInput(plan.inputs.mutation),
+          guards: workflowStringArrayInput(plan.inputs.guard),
+          withCalls: workflowStringArrayInput(plan.inputs.with),
+          afterCalls: workflowStringArrayInput(plan.inputs.after),
         }),
       ),
+    [workflowStepKey("add-mutation", "update-service")]: inspect,
     [workflowStepKey("add-mutation", "update-signal")]: inspect,
-    [workflowStepKey("add-mutation", "update-action-surfaces")]: async (_step, plan) =>
+    [workflowStepKey("add-mutation", "update-store")]: inspect,
+    [workflowStepKey("add-mutation", "update-dictionary")]: inspect,
+    [workflowStepKey("add-mutation", "add-signal-test")]: inspect,
+    [workflowStepKey("add-mutation", "connect-action-ui")]: async (_step, plan) =>
       addMutationActionSurfaceInspection(plan),
+    [workflowStepKey("create-interaction", "create-interaction")]: async (_step, plan) =>
+      primitiveReportToWorkflowStepResult(
+        await createInteraction({
+          app: workflowStringInput(plan.inputs.app),
+          interaction: workflowStringInput(plan.inputs.interaction),
+        }),
+      ),
     [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addSlice({

package/workflow/guardCatalog.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { createTempApp, tempRoots, writeJson, writeText } from "../testHelpers";
+import { GuardCatalog } from "./guardCatalog";
+
+const track = tempRoots();
+
+const guardFile = (names: string[]) =>
+  names.map((name) => `export class ${name} implements Guard {\n  canPass() {\n    return true;\n  }\n}\n`).join("\n");
+
+const createAppWithLibs = async () => {
+  const temp = track(await createTempApp("demo"));
+  const lib = (name: string, files: Record<string, string>) =>
+    Promise.all([
+      writeText(path.join(temp.root, "libs", name, "akan.config.ts"), "export default {};\n"),
+      ...Object.entries(files).map(([file, content]) => writeText(path.join(temp.root, "libs", name, file), content)),
+    ]);
+  await lib("shared", {
+    "srvkit/guards.ts": guardFile(["Admin", "User"]),
+    "srvkit/internalArgs.ts": "export class Self implements InternalArg {}\n",
+    "srvkit/guards.signal.test.ts": guardFile(["TestOnly"]),
+    "akan.lib.json": JSON.stringify({ libDeps: ["util"] }),
+  });
+  await lib("util", { "srvkit/guards.ts": guardFile(["Machine"]) });
+  await lib("other", { "srvkit/guards.ts": guardFile(["Elsewhere"]) });
+  await writeText(path.join(temp.root, "apps/demo/srvkit/guards.ts"), guardFile(["LocalOnly"]));
+  return temp;
+};
+
+describe("GuardCatalog", () => {
+  test("reads the target's srvkit, the libs it reaches, and the framework's Public", async () => {
+    const { root, app } = await createAppWithLibs();
+    await writeJson(path.join(root, "apps/demo/akan.app.json"), { libDeps: ["shared"] });
+
+    const catalog = await GuardCatalog.load(app);
+
+    expect(catalog.reachedLibs).toEqual(["shared", "util"]);
+    expect(catalog.names.sort()).toEqual(["Admin", "LocalOnly", "Machine", "Public", "User"]);
+    expect(catalog.resolve("LocalOnly").specifier).toBe("@apps/demo/srvkit");
+    expect(catalog.resolve("Admin").specifier).toBe("@libs/shared/srvkit");
+    expect(catalog.resolve("Public").specifier).toBe("akanjs/signal");
+    expect(catalog.resolve("Elsewhere").specifier).toBeNull();
+  });
+
+  test("falls back to every workspace lib before a sync has recorded the target's deps", async () => {
+    const { app } = await createAppWithLibs();
+
+    expect((await GuardCatalog.load(app)).resolve("Elsewhere").specifier).toBe("@libs/other/srvkit");
+  });
+
+  test("names the acting user only when the guard guarantees one and its internal arg exists", async () => {
+    const { app } = await createAppWithLibs();
+    const catalog = await GuardCatalog.load(app);
+
+    expect(catalog.actingUserOf(["User"])).toMatchObject({ argName: "Self", specifier: "@libs/shared/srvkit" });
+    expect(catalog.actingUserOf(["Admin"])).toBeNull();
+    expect(catalog.actingUserOf(["SignedIn"])).toBeNull();
+  });
+});

package/workflow/guardCatalog.ts

@@ -0,0 +1,108 @@
+import type { Sys } from "../commandDecorators";
+
+interface CatalogEntry {
+  name: string;
+  specifier: string;
+}
+
+interface ActingUser {
+  argName: string;
+  specifier: string;
+  param: string;
+  value: string;
+  serviceParam: string;
+}
+
+export class GuardCatalog {
+  static readonly frameworkGuards = ["Public"] as const;
+  static readonly #actingArgOf = new Map<string, Omit<ActingUser, "specifier">>([
+    ["User", { argName: "Self", param: "self", value: "self.id", serviceParam: "selfId" }],
+    [
+      "SignedIn",
+      { argName: "CurrentUserId", param: "currentUserId", value: "currentUserId", serviceParam: "currentUserId" },
+    ],
+  ]);
+  readonly #guards: CatalogEntry[];
+  readonly #internalArgs: CatalogEntry[];
+  readonly reachedLibs: string[];
+
+  constructor(guards: CatalogEntry[], internalArgs: CatalogEntry[], reachedLibs: string[]) {
+    this.#guards = guards;
+    this.#internalArgs = internalArgs;
+    this.reachedLibs = reachedLibs;
+  }
+
+  static async load(sys: Sys) {
+    const reachedLibs = await GuardCatalog.#reachedLibs(sys);
+    const scopes = [{ type: sys.type, name: sys.name }, ...reachedLibs.map((name) => ({ type: "lib" as const, name }))];
+    const exports = (await Promise.all(scopes.map((scope) => GuardCatalog.#srvkitExports(sys, scope)))).flat();
+    const frameworkGuards = GuardCatalog.frameworkGuards.map((name) => ({ name, specifier: "akanjs/signal" }));
+    return new GuardCatalog(
+      [...exports.filter((entry) => entry.kind === "Guard"), ...frameworkGuards],
+      exports.filter((entry) => entry.kind === "InternalArg"),
+      reachedLibs,
+    );
+  }
+
+  get names() {
+    return [...new Set(this.#guards.map((guard) => guard.name))];
+  }
+
+  resolve(name: string) {
+    const matches = this.#guards.filter((guard) => guard.name === name);
+    const specifiers = [...new Set(matches.map((guard) => guard.specifier))];
+    return { specifier: specifiers[0] ?? null, ambiguous: specifiers.length > 1 ? specifiers : null };
+  }
+
+  actingUserOf(guards: readonly string[]): ActingUser | null {
+    for (const guard of guards) {
+      const acting = GuardCatalog.#actingArgOf.get(guard);
+      const specifier = acting
+        ? this.#internalArgs.find((entry) => entry.name === acting.argName)?.specifier
+        : undefined;
+      if (acting && specifier) return { ...acting, specifier };
+    }
+    return null;
+  }
+
+  static async #reachedLibs(sys: Sys) {
+    const workspaceLibs = await sys.workspace.getLibs();
+    const depsOf = async (type: "app" | "lib", name: string) => {
+      const jsonPath = `${type}s/${name}/akan.${type}.json`;
+      if (!(await sys.workspace.exists(jsonPath))) return null;
+      const { libDeps } = (await sys.workspace.readJson(jsonPath)) as { libDeps?: unknown };
+      return Array.isArray(libDeps) ? libDeps.filter((lib): lib is string => workspaceLibs.includes(lib)) : [];
+    };
+    const direct = await depsOf(sys.type, sys.name);
+    if (!direct) return workspaceLibs.filter((lib) => sys.type !== "lib" || lib !== sys.name);
+    const reached = new Set<string>();
+    const queue = [...direct];
+    while (queue.length) {
+      const lib = queue.shift();
+      if (!lib || reached.has(lib) || (sys.type === "lib" && lib === sys.name)) continue;
+      reached.add(lib);
+      queue.push(...((await depsOf("lib", lib)) ?? []));
+    }
+    return [...reached];
+  }
+
+  static async #srvkitExports(sys: Sys, scope: { type: "app" | "lib"; name: string }) {
+    const dir = `${scope.type}s/${scope.name}/srvkit`;
+    const files = (await sys.workspace.readdir(dir)).filter(
+      (file) => /\.tsx?$/.test(file) && !/\.(test|spec)\.tsx?$/.test(file) && file !== "index.ts",
+    );
+    const specifier = `@${scope.type}s/${scope.name}/srvkit`;
+    const contents = await Promise.all(files.map((file) => sys.workspace.readFile(`${dir}/${file}`)));
+    return contents.flatMap((content) =>
+      [...content.matchAll(/export class ([A-Z][A-Za-z0-9_]*)\s+implements\s+([^{]+)\{/g)].flatMap((match) => {
+        const implemented = (match[2] ?? "").split(",").map((name) => name.replace(/<.*$/s, "").trim());
+        const kind = implemented.includes("Guard")
+          ? "Guard"
+          : implemented.includes("InternalArg")
+            ? "InternalArg"
+            : null;
+        return kind && match[1] ? [{ kind, name: match[1], specifier }] : [];
+      }),
+    );
+  }
+}

package/workflow/index.ts

@@ -1,6 +1,10 @@
 export * from "./artifacts";
 export * from "./executor";
+export * from "./guardCatalog";
+export * from "./interactionScaffold";
 export * from "./moduleIndex";
+export * from "./mutationScaffold";
+export * from "./mutationSource";
 export * from "./plan";
 export * from "./render";
 export * from "./rolloutGate";

package/workflow/interactionScaffold.ts

@@ -0,0 +1,122 @@
+import { capitalize, lowerlize } from "akanjs/common";
+import type { Sys } from "../commandDecorators";
+import type { ScaffoldFile, WorkflowDiagnostic } from "./types";
+
+export class InteractionScaffold {
+  readonly name: string;
+  readonly className: string;
+  readonly hookName: string;
+  readonly #commonSpecifier: string;
+
+  constructor(sys: Sys, name: string) {
+    this.name = name;
+    this.className = capitalize(name);
+    this.hookName = `use${this.className}`;
+    this.#commonSpecifier = `@${sys.type}s/${sys.name}/common`;
+  }
+
+  static nameOf(raw: string) {
+    const name = lowerlize(raw.replace(/^use(?=[A-Z])/, ""));
+    return /^[a-z][A-Za-z0-9]*$/.test(name) ? name : null;
+  }
+
+  static async build(sys: Sys, raw: string | null) {
+    const diagnostics: WorkflowDiagnostic[] = [];
+    const name = raw ? InteractionScaffold.nameOf(raw) : null;
+    if (!name) {
+      diagnostics.push({
+        severity: "error",
+        code: "create-interaction-name-invalid",
+        input: "interaction",
+        message: `Interaction name "${raw ?? ""}" must be camelCase (boardKeys), optionally prefixed with use.`,
+      });
+      return { diagnostics, files: [] as ScaffoldFile[] };
+    }
+    const scaffold = new InteractionScaffold(sys, name);
+    const files = scaffold.files;
+    const taken = (
+      await Promise.all(
+        scaffold.claimedPaths.map(async (path) =>
+          (await sys.exists(path)) ? `${sys.type}s/${sys.name}/${path}` : null,
+        ),
+      )
+    ).filter((path): path is string => !!path);
+    if (taken.length)
+      diagnostics.push({
+        severity: "error",
+        code: "create-interaction-exists",
+        input: "interaction",
+        message: `${taken.join(", ")} already exists; pick another interaction name or extend the existing files.`,
+      });
+    return { diagnostics, files: taken.length ? [] : files };
+  }
+
+  get claimedPaths() {
+    const { name, hookName } = this;
+    return [
+      `common/${name}.ts`,
+      `common/${name}.tsx`,
+      `common/${name}.test.ts`,
+      `webkit/${hookName}.tsx`,
+      `webkit/${hookName}.ts`,
+    ];
+  }
+
+  get files(): ScaffoldFile[] {
+    return [
+      {
+        path: `common/${this.name}.ts`,
+        content: this.logicSource,
+        action: "create",
+        reason: "Pure interaction logic.",
+      },
+      {
+        path: `common/${this.name}.test.ts`,
+        content: this.testSource,
+        action: "create",
+        reason: "Test of the pure interaction logic.",
+      },
+      { path: `webkit/${this.hookName}.tsx`, content: this.hookSource, action: "create", reason: "Client hook." },
+    ];
+  }
+
+  get logicSource() {
+    return [
+      `export class ${this.className} {`,
+      "  static next<State extends object>(state: State, input: Partial<State>) {",
+      "    return { ...state, ...input };",
+      "  }",
+      "}",
+      "",
+    ].join("\n");
+  }
+
+  get testSource() {
+    return [
+      'import { describe, expect, it } from "bun:test";',
+      `import { ${this.className} } from "./${this.name}";`,
+      "",
+      `describe(${JSON.stringify(this.className)}, () => {`,
+      '  it("applies an input over the state it is handed", () => {',
+      `    expect(${this.className}.next({ idx: 0, isOpen: false }, { idx: 1 })).toEqual({ idx: 1, isOpen: false });`,
+      "  });",
+      "});",
+      "",
+    ].join("\n");
+  }
+
+  get hookSource() {
+    return [
+      '"use client";',
+      `import { ${this.className} } from "${this.#commonSpecifier}";`,
+      "",
+      `export const ${this.hookName} = <State extends object>(state: State, commit: (next: State) => void) => {`,
+      "  const change = async (input: Partial<State>) => {",
+      `    commit(${this.className}.next(state, input));`,
+      "  };",
+      "  return { change };",
+      "};",
+      "",
+    ].join("\n");
+  }
+}