@akanjs/devkit 3.0.0-alpha.9 → 3.0.0-alpha.90

package/subspaceConfig.ts

@@ -0,0 +1,76 @@
+import path from "node:path";
+import type { SubspaceConfigInput, SubspaceDeclaration } from "akanjs";
+import type { WorkspaceExecutor } from "./executors";
+import { FileSys } from "./fileSys";
+
+export type { SubspaceConfigInput, SubspaceDeclaration };
+
+/**
+ * `akan.subspace.ts` at the workspace root: which customer repo each app is mirrored to.
+ *
+ * There is no branch field. The branch is whichever one the workspace is on, so the same declaration
+ * serves `develop` and `main`, and every subspace on one branch holds the same akanjs version and the
+ * same library source.
+ */
+export class SubspaceConfig {
+  static readonly fileName = "akan.subspace.ts";
+  static readonly defaultPushableBranches = ["main", "develop", "debug"];
+
+  static async from(workspace: WorkspaceExecutor): Promise<SubspaceConfig | null> {
+    const configPath = path.join(workspace.workspaceRoot, SubspaceConfig.fileName);
+    if (!(await FileSys.fileExists(configPath))) return null;
+    const input = await import(configPath).then((mod: { default: SubspaceConfigInput }) => mod.default);
+    return new SubspaceConfig(input);
+  }
+
+  readonly pushableBranches: string[];
+  readonly exclude: string[];
+  readonly subspaces: SubspaceDeclaration[];
+
+  constructor(input: SubspaceConfigInput) {
+    this.pushableBranches = input.pushableBranches ?? SubspaceConfig.defaultPushableBranches;
+    this.exclude = input.exclude ?? [];
+    this.subspaces = input.subspaces ?? [];
+    this.#assertValid();
+  }
+
+  #assertValid() {
+    const seenNames = new Set<string>();
+    const appOwners = new Map<string, string>();
+    for (const subspace of this.subspaces) {
+      if (!subspace.name || !subspace.repo)
+        throw new Error(`${SubspaceConfig.fileName}: every subspace needs a name and a repo`);
+      if (seenNames.has(subspace.name))
+        throw new Error(`${SubspaceConfig.fileName}: duplicate subspace "${subspace.name}"`);
+      seenNames.add(subspace.name);
+      if (!subspace.apps?.length)
+        throw new Error(`${SubspaceConfig.fileName}: subspace "${subspace.name}" declares no apps`);
+      for (const app of subspace.apps) {
+        const owner = appOwners.get(app);
+        //* One app never goes to two subspaces: the two would need per-subspace domains and ids, which
+        //* this declaration cannot express. Share code through a lib instead.
+        if (owner)
+          throw new Error(
+            `${SubspaceConfig.fileName}: app "${app}" is claimed by both "${owner}" and "${subspace.name}"`,
+          );
+        appOwners.set(app, subspace.name);
+      }
+    }
+  }
+
+  select(names: string[]) {
+    if (!names.length) return this.subspaces;
+    return names.map((name) => {
+      const subspace = this.subspaces.find((candidate) => candidate.name === name);
+      if (!subspace) throw new Error(`${SubspaceConfig.fileName}: unknown subspace "${name}"`);
+      return subspace;
+    });
+  }
+
+  assertPushable(branch: string) {
+    if (this.pushableBranches.includes(branch)) return;
+    throw new Error(
+      `Branch "${branch}" is not pushable. ${SubspaceConfig.fileName} allows: ${this.pushableBranches.join(", ")}`,
+    );
+  }
+}

package/transforms/asyncDefaultExportDetector.ts

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import type ts from "typescript";
+
+type TypeScript = typeof ts;
+
+export class AsyncDefaultExportDetector {
+  static #typescriptLoad: Promise<TypeScript> | undefined;
+
+  // `typescript` costs ~70 MB resident and this detector is reached from the cli entry through the root
+  // layout generator, so the compiler loads on first use rather than at import (`entryModuleGraph.test.ts`).
+  static #loadTypescript(): Promise<TypeScript> {
+    AsyncDefaultExportDetector.#typescriptLoad ??= import("typescript").then(
+      (mod) => (mod.default ?? mod) as TypeScript,
+    );
+    return AsyncDefaultExportDetector.#typescriptLoad;
+  }
+
+  static async detect(moduleAbsPath: string): Promise<boolean> {
+    try {
+      const typescript = await AsyncDefaultExportDetector.#loadTypescript();
+      const source = fs.readFileSync(path.resolve(moduleAbsPath), "utf8");
+      const sourceFile = typescript.createSourceFile(
+        moduleAbsPath,
+        source,
+        typescript.ScriptTarget.Latest,
+        true,
+        AsyncDefaultExportDetector.#scriptKind(typescript, moduleAbsPath),
+      );
+      return new AsyncDefaultExportDetector(typescript).detectInSourceFile(sourceFile);
+    } catch {
+      return false;
+    }
+  }
+
+  #ts: TypeScript;
+
+  constructor(typescript: TypeScript) {
+    this.#ts = typescript;
+  }
+
+  detectInSourceFile(sourceFile: ts.SourceFile): boolean {
+    const ts = this.#ts;
+    const asyncBindings = new Map<string, boolean>();
+    let defaultIdentifier: string | null = null;
+
+    for (const statement of sourceFile.statements) {
+      if (ts.isFunctionDeclaration(statement)) {
+        if (this.#hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+          return this.#hasModifier(statement, ts.SyntaxKind.AsyncKeyword);
+        }
+        if (statement.name) {
+          asyncBindings.set(statement.name.text, this.#hasModifier(statement, ts.SyntaxKind.AsyncKeyword));
+        }
+        continue;
+      }
+
+      if (ts.isVariableStatement(statement)) {
+        for (const declaration of statement.declarationList.declarations) {
+          if (!ts.isIdentifier(declaration.name)) continue;
+          asyncBindings.set(declaration.name.text, this.#isAsyncFunctionExpression(declaration.initializer));
+        }
+        continue;
+      }
+
+      if (ts.isExportAssignment(statement)) {
+        if (this.#isAsyncFunctionExpression(statement.expression)) return true;
+        if (ts.isIdentifier(statement.expression)) defaultIdentifier = statement.expression.text;
+        continue;
+      }
+
+      if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+        const exportClause = statement.exportClause;
+        for (const specifier of exportClause.elements) {
+          if (specifier.name.text !== "default") continue;
+          defaultIdentifier = specifier.propertyName?.text ?? specifier.name.text;
+        }
+      }
+    }
+
+    return defaultIdentifier ? asyncBindings.get(defaultIdentifier) === true : false;
+  }
+
+  #hasModifier(node: ts.Node, kind: ts.SyntaxKind): boolean {
+    const ts = this.#ts;
+    return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) ?? false);
+  }
+
+  #isAsyncFunctionExpression(node?: ts.Expression): boolean {
+    const ts = this.#ts;
+    return Boolean(
+      node &&
+        (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
+        this.#hasModifier(node, ts.SyntaxKind.AsyncKeyword),
+    );
+  }
+
+  static #scriptKind(typescript: TypeScript, moduleAbsPath: string): ts.ScriptKind {
+    return moduleAbsPath.endsWith(".tsx") || moduleAbsPath.endsWith(".jsx")
+      ? typescript.ScriptKind.TSX
+      : typescript.ScriptKind.TS;
+  }
+}

package/transforms/barrelImportsPlugin.ts

@@ -223,7 +223,7 @@ const resolveNodePackageExport = async (workspaceRoot: string, specifier: string
     const subpath = specifier === packageName ? "." : `.${specifier.slice(packageName.length)}`;
     const exported = resolvePackageExport(pkgJson.exports, subpath);
     const rel = exported ?? (subpath === "." ? (pkgJson.module ?? pkgJson.main ?? "index.js") : null);
-    if (!rel || !rel.startsWith(".")) return null;
+    if (!rel?.startsWith(".")) return null;
     const entryFile = await resolveFileCandidate(path.resolve(pkgDir, rel));
     if (!entryFile) return null;
     const pkgEntryName = specifier;

package/transforms/externalizeFrameworkPlugin.ts

@@ -65,7 +65,6 @@ const DEFAULT_EXCLUDE_PREFIX = ["@akanjs/cli/", "@akanjs/devkit/"];
 const OPTIONAL_BACKEND_EXTERNAL_EXACT = new Set<string>([
   "@libsql/client",
   "bullmq",
-  "croner",
   "ioredis",
   "postgres",
   "protobufjs",

package/transforms/transforms.test.ts

@@ -104,7 +104,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
           ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
           ["Bee", { subpath: "@scope/pkg/leaf", originalName: "B" }],
         ]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const rewritten = await rewriteBarrelImports(
       'import DefaultExport, { A, Bee as LocalBee, type Shape, Missing } from "@scope/pkg";\nconsole.log(A);',
@@ -128,7 +128,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   test("preserves generated client barrel side effects when flattening app client imports", async () => {
     const analyzer = {
       analyze: async () => new Map([["st", { subpath: "@apps/demo/lib/st", originalName: "st" }]]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const rewritten = await rewriteBarrelImports(
       'import { st } from "@apps/demo/client";\nvoid st;\n',
@@ -144,7 +144,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   test("does not rewrite import-looking code inside template literals", async () => {
     const analyzer = {
       analyze: async () => new Map([["AkanApp", { subpath: "akanjs/server/akanApp", originalName: "AkanApp" }]]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const source = [
       'import { Code } from "@apps/docs/ui";',
@@ -170,7 +170,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
           ["AkanOption", { subpath: "akanjs/server/akanOption", originalName: "AkanOption" }],
           ["Try", { subpath: "akanjs/server/decorators", originalName: "Try" }],
         ]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const rewritten = await rewriteBarrelImports(
       'import { AkanOption, Try } from "akanjs/server";\nexport const option = new AkanOption();\n',
@@ -191,7 +191,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     const analyzer = {
       analyze: async () =>
         new Map([["BottomInset", { subpath: "akanjs/ui/Layout/BottomInset", originalName: "BottomInset" }]]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const rewritten = await rewriteBarrelImports('import { BottomInset } from "akanjs/ui";\n', ["akanjs/ui"], analyzer);
 

package/transforms/tsconfigPackageResolver.test.ts

@@ -0,0 +1,230 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createTsconfigPackageResolver } from "./barrelImportsPlugin";
+
+const tempRoots: string[] = [];
+
+const makeTempRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-resolver-"));
+  tempRoots.push(root);
+  return root;
+};
+
+const write = async (root: string, relPath: string, content = "export const value = 1;\n") => {
+  const filePath = path.join(root, relPath);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+  return filePath;
+};
+
+const resolverFor = async (root: string, paths: Record<string, string[]>) =>
+  await createTsconfigPackageResolver({
+    workspace: { workspaceRoot: root },
+    getTsConfig: async () => ({ compilerOptions: { paths } }),
+  } as never);
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("createTsconfigPackageResolver — exact tsconfig mapping", () => {
+  test("resolves a package barrel and keeps the specifier", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "libs/util/index.ts");
+    const resolve = await resolverFor(root, { "@libs/util": ["./libs/util/index.ts"] });
+
+    expect(await resolve("@libs/util")).toEqual({
+      pkgName: "@libs/util",
+      entryFile,
+      pkgDir: path.join(root, "libs/util"),
+    });
+  });
+
+  test("collapses a facet specifier to its parent package", async () => {
+    // `@libs/util/server` maps to the sibling file `libs/util/server.ts`, not to a package directory, so a
+    // leaf rewritten under the raw specifier would become `@libs/util/server/lib/sig` — a path that does
+    // not exist. The parent specifier is what the `@libs/*` wildcard can actually resolve.
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "libs/util/server.ts");
+    const resolve = await resolverFor(root, { "@libs/util/server": ["./libs/util/server.ts"] });
+
+    expect(await resolve("@libs/util/server")).toEqual({
+      pkgName: "@libs/util",
+      entryFile,
+      pkgDir: path.join(root, "libs/util"),
+    });
+  });
+
+  test("keeps the specifier when the entry file name does not match the facet", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "libs/util/clientEntry.ts");
+    const resolve = await resolverFor(root, { "@libs/util/client": ["./libs/util/clientEntry.ts"] });
+
+    expect(await resolve("@libs/util/client")).toEqual({
+      pkgName: "@libs/util/client",
+      entryFile,
+      pkgDir: path.join(root, "libs/util"),
+    });
+  });
+
+  test("returns null when the mapped file is missing", async () => {
+    const root = await makeTempRoot();
+    const resolve = await resolverFor(root, { "@libs/util": ["./libs/util/index.ts"] });
+    expect(await resolve("@libs/util")).toBeNull();
+  });
+
+  test("returns null for an empty mapping", async () => {
+    const root = await makeTempRoot();
+    await write(root, "libs/util/index.ts");
+    const resolve = await resolverFor(root, { "@libs/util": [""] });
+    expect(await resolve("@libs/util")).toBeNull();
+  });
+});
+
+describe("createTsconfigPackageResolver — wildcard tsconfig mapping", () => {
+  test("prefers the longer prefix", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "custom/ui/index.ts");
+    await write(root, "libs/util/ui/index.ts");
+    const resolve = await resolverFor(root, {
+      "@libs/*": ["./libs/*"],
+      "@libs/util/*": ["./custom/*"],
+    });
+
+    expect(await resolve("@libs/util/ui")).toEqual({
+      pkgName: "@libs/util/ui",
+      entryFile,
+      pkgDir: path.join(root, "custom/ui"),
+    });
+  });
+
+  test("collapses a sibling facet file to its parent package", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "apps/minimal/client.ts");
+    const resolve = await resolverFor(root, { "@apps/*": ["./apps/*"] });
+
+    expect(await resolve("@apps/minimal/client")).toEqual({
+      pkgName: "@apps/minimal",
+      entryFile,
+      pkgDir: path.join(root, "apps/minimal"),
+    });
+  });
+
+  test("resolves a directory barrel and keeps the specifier", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "apps/minimal/index.tsx");
+    const resolve = await resolverFor(root, { "@apps/*": ["./apps/*"] });
+
+    expect(await resolve("@apps/minimal")).toEqual({
+      pkgName: "@apps/minimal",
+      entryFile,
+      pkgDir: path.join(root, "apps/minimal"),
+    });
+  });
+
+  test("prefers a sibling facet file over a same-named directory barrel", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "apps/minimal/client.ts");
+    await write(root, "apps/minimal/client/index.ts");
+    const resolve = await resolverFor(root, { "@apps/*": ["./apps/*"] });
+
+    expect((await resolve("@apps/minimal/client"))?.entryFile).toBe(entryFile);
+  });
+
+  test("stops at the matched prefix instead of falling through to a shorter one", async () => {
+    // Falling through would resolve `@libs/util/ui` against `./libs/*`, silently loading an unrelated
+    // directory that happens to sit at the same subpath under a different root.
+    const root = await makeTempRoot();
+    await write(root, "libs/util/ui/index.ts");
+    const resolve = await resolverFor(root, {
+      "@libs/*": ["./libs/*"],
+      "@libs/util/*": ["./custom/*"],
+    });
+
+    expect(await resolve("@libs/util/ui")).toBeNull();
+  });
+
+  test("tries every replacement of a matched prefix", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "second/util/index.ts");
+    const resolve = await resolverFor(root, { "@libs/*": ["./first/*", "./second/*"] });
+
+    expect((await resolve("@libs/util"))?.entryFile).toBe(entryFile);
+  });
+});
+
+describe("createTsconfigPackageResolver — node_modules fallback", () => {
+  const writePackageJson = async (root: string, pkgName: string, pkgJson: unknown) =>
+    await write(root, `node_modules/${pkgName}/package.json`, JSON.stringify(pkgJson));
+
+  test("resolves an exports subpath and preserves the file path", async () => {
+    const root = await makeTempRoot();
+    await writePackageJson(root, "akanjs", { exports: { "./ui": { source: "./ui/index.ts" } } });
+    const entryFile = await write(root, "node_modules/akanjs/ui/index.ts");
+    const resolve = await resolverFor(root, {});
+
+    expect(await resolve("akanjs/ui")).toEqual({
+      pkgName: "akanjs/ui",
+      entryFile,
+      pkgDir: path.join(root, "node_modules/akanjs/ui"),
+      preserveFilePath: true,
+    });
+  });
+
+  test("resolves an exports wildcard subpath", async () => {
+    const root = await makeTempRoot();
+    await writePackageJson(root, "akanjs", { exports: { "./*": "./dist/*.js" } });
+    const entryFile = await write(root, "node_modules/akanjs/dist/signal.js");
+    const resolve = await resolverFor(root, {});
+
+    expect((await resolve("akanjs/signal"))?.entryFile).toBe(entryFile);
+  });
+
+  test("resolves a scoped package subpath", async () => {
+    // A scoped name is two path segments, so the package boundary cannot be found by splitting on the
+    // first slash. Kept vendor-neutral on purpose: `packageExports.test.ts` reads every
+    // `"@akanjs/devkit/<x>"` literal under this package as a subpath the monorepo imports.
+    const root = await makeTempRoot();
+    await writePackageJson(root, "@vendor/kit", { exports: { "./lint": "./lint/index.ts" } });
+    const entryFile = await write(root, "node_modules/@vendor/kit/lint/index.ts");
+    const resolve = await resolverFor(root, {});
+
+    expect((await resolve("@vendor/kit/lint"))?.entryFile).toBe(entryFile);
+  });
+
+  test("falls back to module/main when exports resolution declines the specifier", async () => {
+    // `main: "index.js"` has no leading `./`, which the exports resolver rejects — the last fallback
+    // resolves it against the package directory, and it is the one path that does not preserve the file.
+    const root = await makeTempRoot();
+    await writePackageJson(root, "plainpkg", { main: "index.js" });
+    const entryFile = await write(root, "node_modules/plainpkg/index.js");
+    const resolve = await resolverFor(root, {});
+
+    expect(await resolve("plainpkg")).toEqual({
+      pkgName: "plainpkg",
+      entryFile,
+      pkgDir: path.join(root, "node_modules/plainpkg"),
+    });
+  });
+
+  test("returns null when the package is not installed", async () => {
+    const root = await makeTempRoot();
+    expect(await resolverFor(root, {}).then((resolve) => resolve("missingpkg"))).toBeNull();
+  });
+
+  test("returns null when the package.json is unparseable", async () => {
+    const root = await makeTempRoot();
+    await write(root, "node_modules/brokenpkg/package.json", "{ not json");
+    const resolve = await resolverFor(root, {});
+    expect(await resolve("brokenpkg")).toBeNull();
+  });
+
+  test("returns null when the resolved entry file is missing", async () => {
+    const root = await makeTempRoot();
+    await writePackageJson(root, "ghostpkg", { module: "./dist/index.js" });
+    const resolve = await resolverFor(root, {});
+    expect(await resolve("ghostpkg")).toBeNull();
+  });
+});

package/tsconfig.json

@@ -32,6 +32,10 @@
   "files": [],
   "include": [
     "**/*.ts",
-    "**/*.tsx"
+    "**/*.tsx",
+    "../../akanjs/server/types/*.d.ts"
+  ],
+  "exclude": [
+    "lint/__fixtures__"
   ]
-}
+}

package/typeChecker.ts

@@ -208,7 +208,7 @@ export class TypeChecker {
     try {
       const { diagnostics } = this.check(filePath);
       return diagnostics.length === 0;
-    } catch (error) {
+    } catch (_error) {
       return false;
     }
   }

package/types.ts

@@ -15,6 +15,7 @@ export interface PackageJson {
   bun?: {
     platform?: "node" | "browser" | "bun";
   };
+  publishConfig?: { access?: "public" | "restricted"; registry?: string; tag?: string };
   [key: string]: unknown;
 }
 

package/uploadRelease.ts

@@ -1,4 +1,4 @@
-import { HttpClient, Logger } from "akanjs/common";
+import { Logger, RestClient } from "akanjs/common";
 
 import { Spinner } from "./spinner";
 
@@ -26,7 +26,7 @@ export const uploadRelease = async (
 ) => {
   const logger = new Logger("uploadRelease");
   const basePath = local ? "http://localhost:8282/backend" : "https://cloud.akanjs.com/backend";
-  const httpClient = new HttpClient(basePath);
+  const httpClient = new RestClient(basePath);
   const buildPath = `${workspaceRoot}/releases/builds/${appName}-release.tar.gz`;
   const appBuildPath = `${workspaceRoot}/releases/builds/${appName}-appBuild.zip`;
   const sourcePath = `${workspaceRoot}/releases/sources/${appName}-source.tar.gz`;

package/workflow/executor.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "bun:test";
+import { WorkflowExecutor, workflowStepKey } from "./executor";
+import type {
+  PrimitiveChangedFile,
+  WorkflowDiagnostic,
+  WorkflowPlan,
+  WorkflowStep,
+  WorkflowStepRegistry,
+  WorkflowStepResult,
+} from "./types";
+
+/**
+ * `WorkflowExecutor` takes its registry by constructor injection and its plan as data, so `apply` runs with
+ * no filesystem and no workspace — the `workspace` argument is what gates every post-apply check. These
+ * cover the ordering rules that `cli/workflow/workflow.test.ts` can only reach through a real scaffold.
+ */
+const step = (id: string, tool = `tool:${id}`): WorkflowStep => ({
+  id,
+  tool,
+  title: id,
+  description: id,
+});
+
+// Every field spelled out rather than cast through `unknown`: `apply` reads `validation` before the first
+// step runs, so a partial literal fails at runtime instead of at the type level.
+const planOf = (steps: WorkflowStep[], diagnostics: WorkflowDiagnostic[] = []): WorkflowPlan => ({
+  schemaVersion: 1,
+  workflow: "add-field",
+  mode: "plan",
+  inputs: {},
+  optionalSurfaces: {},
+  steps,
+  predictedChanges: [],
+  validation: [],
+  diagnostics,
+  recommendations: [],
+  requiresApproval: true,
+});
+
+/**
+ * A registry that records **which key** each call resolved through, not just that a step ran — the
+ * resolution order is the thing under test, and every candidate key would otherwise record the same step id.
+ */
+const changed = (path: string): PrimitiveChangedFile => ({ path, action: "modify", reason: "test" });
+
+const recordingRegistry = (results: Record<string, WorkflowStepResult | undefined> = {}) => {
+  const calls: string[] = [];
+  const registry: WorkflowStepRegistry = {};
+  const on = (key: string) => {
+    registry[key] = async () => {
+      calls.push(key);
+      return results[key];
+    };
+  };
+  return { calls, registry, on };
+};
+
+describe("WorkflowExecutor.apply", () => {
+  test("runs no step when the plan already carries an error diagnostic", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "one"));
+    const plan = planOf([step("one")], [{ severity: "error", code: "plan-invalid", message: "bad inputs" }]);
+
+    const report = await new WorkflowExecutor(registry).apply(plan);
+
+    expect(calls).toEqual([]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("plan-invalid");
+  });
+
+  test("a warning in the plan does not stop the steps", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "one"));
+    const plan = planOf([step("one")], [{ severity: "warning", code: "plan-note", message: "heads up" }]);
+
+    await new WorkflowExecutor(registry).apply(plan);
+
+    expect(calls).toEqual([workflowStepKey("add-field", "one")]);
+  });
+
+  test("resolves a runner by workflow-scoped key first, then tool, then bare step id", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    // All three keys are registered for the same step, so only the winner records a call.
+    on(workflowStepKey("add-field", "scoped"));
+    on("tool:scoped");
+    on("scoped");
+    await new WorkflowExecutor(registry).apply(planOf([step("scoped")]));
+    expect(calls).toEqual([workflowStepKey("add-field", "scoped")]);
+
+    const byTool = recordingRegistry();
+    byTool.on("tool:viaTool");
+    byTool.on("viaTool");
+    await new WorkflowExecutor(byTool.registry).apply(planOf([step("viaTool")]));
+    expect(byTool.calls).toEqual(["tool:viaTool"]);
+
+    const byId = recordingRegistry();
+    byId.on("viaId");
+    await new WorkflowExecutor(byId.registry).apply(planOf([step("viaId")]));
+    expect(byId.calls).toEqual(["viaId"]);
+  });
+
+  test("an unsupported step is reported and abandons the rest of the plan", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "first"));
+    on(workflowStepKey("add-field", "third"));
+
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("first"), step("second"), step("third")]));
+
+    expect(calls).toEqual([workflowStepKey("add-field", "first")]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("workflow-step-unsupported");
+    expect(report.nextActions.map((action) => action.command)).toContain("akan workflow explain add-field");
+  });
+
+  test("accumulates changed files and diagnostics across steps, and stops at the first error", async () => {
+    const key = (id: string) => workflowStepKey("add-field", id);
+    const { calls, registry, on } = recordingRegistry({
+      [key("a")]: { changedFiles: [changed("apps/demo/lib/task/task.constant.ts")] },
+      [key("b")]: {
+        changedFiles: [changed("apps/demo/lib/task/task.dictionary.ts")],
+        diagnostics: [{ severity: "error", code: "step-failed", message: "no such module" }],
+      },
+      [key("c")]: { changedFiles: [changed("never-reached.ts")] },
+    });
+    on(key("a"));
+    on(key("b"));
+    on(key("c"));
+
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("a"), step("b"), step("c")]));
+
+    expect(calls).toEqual([key("a"), key("b")]);
+    expect(report.changedFiles.map((file) => file.path)).toEqual([
+      "apps/demo/lib/task/task.constant.ts",
+      "apps/demo/lib/task/task.dictionary.ts",
+    ]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("step-failed");
+  });
+
+  test("a runner that answers nothing is not an error", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "silent"));
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("silent")]));
+
+    expect(calls).toEqual([workflowStepKey("add-field", "silent")]);
+    expect(report.diagnostics.filter((diagnostic) => diagnostic.severity === "error")).toEqual([]);
+    expect(report.changedFiles).toEqual([]);
+  });
+});