@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/transforms/transforms.test.ts

@@ -1,27 +1,16 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
-import { BarrelAnalyzer } from "./barrelAnalyzer";
+import { ApplicationBuildReporter } from "../applicationBuildReporter";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { BarrelAnalyzer, type BarrelExportTarget } from "./barrelAnalyzer";
 import { rewriteBarrelImports } from "./barrelImportsPlugin";
-import { toClientReferencePath, transformUseClient } from "./rscUseClientTransform";
+import { scanUseClientExports, toClientReferencePath, transformUseClient } from "./rscUseClientTransform";
+import { createUseClientBundlePlugin } from "./useClientBundlePlugin";
 
-const tempRoots: string[] = [];
+const makeTempRoot = tempDirs("akan-devkit-transform-");
 
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-transform-"));
-  tempRoots.push(root);
-  return root;
-};
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+const fakeAnalyzer = (entries: [string, BarrelExportTarget][]) =>
+  ({ analyze: async () => new Map(entries) }) as unknown as BarrelAnalyzer;
 
 describe("transformUseClient", () => {
   test("returns null for non-client modules and generated root layouts", () => {
@@ -38,6 +27,19 @@ describe("transformUseClient", () => {
     ).toBeNull();
   });
 
+  test("a client module with no exports stays server code and is not reported as a client module", () => {
+    const reported: string[] = [];
+    const onClientModule = (file: string) => reported.push(file);
+    expect(
+      transformUseClient('"use client";\nimport "./side-effect";\n', { path: "/repo/ui/Fx.tsx", onClientModule }),
+    ).toBeNull();
+    expect(reported).toEqual([]);
+    expect(
+      transformUseClient('"use client"; export const value = 1;', { path: "/repo/ui/V.tsx", onClientModule }),
+    ).not.toBeNull();
+    expect(reported).toEqual(["/repo/ui/V.tsx"]);
+  });
+
   test("stubs named and default exports as RSC client references", () => {
     const source = [
       "// comment before directive",
@@ -62,6 +64,65 @@ describe("transformUseClient", () => {
   });
 });
 
+describe('export * in a "use client" module', () => {
+  test("is refused with the file, the specifier and the fix, since the server would see none of its names", () => {
+    const source = [
+      '"use client";',
+      'export * from "../../ui/UserLeave";',
+      "export const General = () => null;",
+      "",
+    ].join("\n");
+    expect(() =>
+      transformUseClient(source, { path: "/repo/libs/shared/lib/user/User.Template.tsx", workspaceRoot: "/repo" }),
+    ).toThrow(
+      'libs/shared/lib/user/User.Template.tsx is a "use client" module, so it cannot `export * from "../../ui/UserLeave"`',
+    );
+    expect(() => scanUseClientExports('"use client";\nexport * from "./a";\n', "/repo/ui/Barrel.ts")).toThrow(
+      "Re-export them by name",
+    );
+  });
+
+  test("leaves every other export shape alone, and a module that is not a client boundary", () => {
+    const file = "/repo/ui/Barrel.tsx";
+    const shapes = [
+      '"use client";',
+      'export type * from "./types";',
+      'export * as ns from "./namespace";',
+      'export { LeaveInfo, Voc } from "./leave";',
+      "// export * from './commented';",
+      "export const text = \"export * from './a string'\";",
+      "",
+    ].join("\n");
+    expect(scanUseClientExports(shapes, file).sort()).toEqual(["LeaveInfo", "Voc", "ns", "text"]);
+    expect(scanUseClientExports('export * from "./a";\nexport const X = 1;\n', file)).toEqual(["X"]);
+    const stub = transformUseClient(shapes, { path: file, workspaceRoot: "/repo" });
+    expect(stub).toContain("export const LeaveInfo = registerClientReference");
+    expect(stub).toContain("export const Voc = registerClientReference");
+  });
+
+  test("fails the server bundle, and the build report carries the reason out of the bundler's error", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "Leave.tsx"), '"use client";\nexport const LeaveInfo = () => null;\n');
+    await write(
+      path.join(root, "Template.tsx"),
+      '"use client";\nexport * from "./Leave";\nexport const General = () => null;\n',
+    );
+    await write(path.join(root, "page.tsx"), 'import * as Template from "./Template";\nexport const T = Template;\n');
+    const failure = await Bun.build({
+      entrypoints: [path.join(root, "page.tsx")],
+      target: "bun",
+      external: ["react-server-dom-webpack/server.node"],
+      plugins: [createUseClientBundlePlugin({ workspaceRoot: root })],
+    }).then(
+      () => null,
+      (error: unknown) => error,
+    );
+    expect(ApplicationBuildReporter.formatError(failure)).toContain(
+      'Template.tsx is a "use client" module, so it cannot `export * from "./Leave"`',
+    );
+  });
+});
+
 describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   test("analyzes local, named, aliased, and star re-exports while skipping type and namespace exports", async () => {
     const root = await makeTempRoot();
@@ -97,14 +158,83 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(map?.has("ns")).toBe(false);
   });
 
+  test("a name a module exports itself wins over the same name its star re-exports bring, as ES decides", async () => {
+    const root = await makeTempRoot();
+    const pkgDir = path.join(root, "pkg");
+    await write(
+      path.join(pkgDir, "index.ts"),
+      [
+        'export * from "./a";',
+        'export { X } from "./c";',
+        'export * from "./nested";',
+        "export const Local = 1;",
+        "",
+      ].join("\n"),
+    );
+    await write(path.join(pkgDir, "a.ts"), "export const X = 2;\nexport const Local = 2;\nexport const OnlyA = 2;\n");
+    await write(path.join(pkgDir, "c.ts"), "export const X = 1;\n");
+    await write(path.join(pkgDir, "nested", "index.ts"), 'export * from "./deep";\nexport { Y } from "./y";\n');
+    await write(path.join(pkgDir, "nested", "deep.ts"), "export const Y = 2;\n");
+    await write(path.join(pkgDir, "nested", "y.ts"), "export const Y = 1;\n");
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({ pkgName: "@scope/pkg", entryFile: path.join(pkgDir, "index.ts"), pkgDir }),
+    });
+
+    const runtime = (await import(path.join(pkgDir, "index.ts"))) as Record<string, number>;
+    expect([runtime.X, runtime.Local, runtime.Y, runtime.OnlyA]).toEqual([1, 1, 1, 2]);
+    const map = await analyzer.analyze("@scope/pkg");
+    expect(map?.get("X")).toEqual({ subpath: "@scope/pkg/c", originalName: "X" });
+    expect(map?.get("Local")).toEqual({ subpath: "@scope/pkg", originalName: "Local" });
+    expect(map?.get("Y")).toEqual({ subpath: "@scope/pkg/nested/y", originalName: "Y" });
+    expect(map?.get("OnlyA")).toEqual({ subpath: "@scope/pkg/a", originalName: "OnlyA" });
+  });
+
+  test("two analyses that interleave each keep their own place in their barrel", async () => {
+    const root = await makeTempRoot();
+    const barrels = { first: ["a1", "a2", "a3"], second: ["b1", "b2"] } as const;
+    for (const [pkgName, names] of Object.entries(barrels)) {
+      const lines = names.map((name) => `export { ${name} } from "./${name}";`);
+      // Parks the second walk past the end of the first barrel, so a shared regex position would end the first early.
+      const padding = pkgName === "second" ? [`// ${"-".repeat(200)}`] : [];
+      await write(path.join(root, pkgName, "index.ts"), [...padding, ...lines, ""].join("\n"));
+      for (const name of names) await write(path.join(root, pkgName, `${name}.ts`), `export const ${name} = 1;\n`);
+    }
+    const parked = { first: Promise.withResolvers<void>(), second: Promise.withResolvers<void>() };
+    const released = { first: Promise.withResolvers<void>(), second: Promise.withResolvers<void>() };
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async (pkgName) => ({
+        pkgName,
+        entryFile: path.join(root, pkgName, "index.ts"),
+        pkgDir: path.join(root, pkgName),
+      }),
+      resolveRelative: async (fromFile, relSpec) => {
+        const pkgName = path.basename(path.dirname(fromFile)) as keyof typeof barrels;
+        if (relSpec === `./${barrels[pkgName][0]}`) {
+          parked[pkgName].resolve();
+          await released[pkgName].promise;
+        }
+        return path.join(path.dirname(fromFile), `${relSpec.slice(2)}.ts`);
+      },
+    });
+
+    const first = analyzer.analyze("first");
+    await parked.first.promise;
+    const second = analyzer.analyze("second");
+    await parked.second.promise;
+    released.first.resolve();
+    const firstMap = await first;
+    released.second.resolve();
+    const secondMap = await second;
+
+    expect(firstMap?.get("a3")).toEqual({ subpath: "first/a3", originalName: "a3" });
+    expect(secondMap?.get("b2")).toEqual({ subpath: "second/b2", originalName: "b2" });
+  });
+
   test("rewrites flattenable named imports and preserves default, type, and unknown imports", async () => {
-    const analyzer = {
-      analyze: async () =>
-        new Map([
-          ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
-          ["Bee", { subpath: "@scope/pkg/leaf", originalName: "B" }],
-        ]),
-    } as unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([
+      ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+      ["Bee", { subpath: "@scope/pkg/leaf", originalName: "B" }],
+    ]);
 
     const rewritten = await rewriteBarrelImports(
       'import DefaultExport, { A, Bee as LocalBee, type Shape, Missing } from "@scope/pkg";\nconsole.log(A);',
@@ -126,9 +256,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 unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([["st", { subpath: "@apps/demo/lib/st", originalName: "st" }]]);
 
     const rewritten = await rewriteBarrelImports(
       'import { st } from "@apps/demo/client";\nvoid st;\n',
@@ -142,9 +270,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 unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([["AkanApp", { subpath: "akanjs/server/akanApp", originalName: "AkanApp" }]]);
 
     const source = [
       'import { Code } from "@apps/docs/ui";',
@@ -164,13 +290,10 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   });
 
   test("rewrites akanjs/server value imports to leaf subpaths", async () => {
-    const analyzer = {
-      analyze: async () =>
-        new Map([
-          ["AkanOption", { subpath: "akanjs/server/akanOption", originalName: "AkanOption" }],
-          ["Try", { subpath: "akanjs/server/decorators", originalName: "Try" }],
-        ]),
-    } as unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([
+      ["AkanOption", { subpath: "akanjs/server/akanOption", originalName: "AkanOption" }],
+      ["Try", { subpath: "akanjs/server/decorators", originalName: "Try" }],
+    ]);
 
     const rewritten = await rewriteBarrelImports(
       'import { AkanOption, Try } from "akanjs/server";\nexport const option = new AkanOption();\n',
@@ -188,10 +311,9 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   });
 
   test("rewrites single-package Akan facet barrels to leaf subpaths", async () => {
-    const analyzer = {
-      analyze: async () =>
-        new Map([["BottomInset", { subpath: "akanjs/ui/Layout/BottomInset", originalName: "BottomInset" }]]),
-    } as unknown as BarrelAnalyzer;
+    const analyzer = fakeAnalyzer([
+      ["BottomInset", { subpath: "akanjs/ui/Layout/BottomInset", originalName: "BottomInset" }],
+    ]);
 
     const rewritten = await rewriteBarrelImports('import { BottomInset } from "akanjs/ui";\n', ["akanjs/ui"], analyzer);
 

package/transforms/tsconfigPackageResolver.test.ts

@@ -1,16 +1,10 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { tempDirs } from "../testHelpers";
 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 makeTempRoot = tempDirs("akan-devkit-resolver-");
 
 const write = async (root: string, relPath: string, content = "export const value = 1;\n") => {
   const filePath = path.join(root, relPath);
@@ -25,10 +19,6 @@ const resolverFor = async (root: string, paths: Record<string, string[]>) =>
     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();
@@ -43,9 +33,6 @@ describe("createTsconfigPackageResolver — exact tsconfig mapping", () => {
   });
 
   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"] });
@@ -134,8 +121,6 @@ describe("createTsconfigPackageResolver — wildcard tsconfig mapping", () => {
   });
 
   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, {
@@ -183,9 +168,7 @@ describe("createTsconfigPackageResolver — node_modules fallback", () => {
   });
 
   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.
+    // Vendor-neutral on purpose: `packageExports.test.ts` reads every `"@akanjs/devkit/<x>"` literal here as an import.
     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");
@@ -195,8 +178,7 @@ describe("createTsconfigPackageResolver — node_modules fallback", () => {
   });
 
   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.
+    // `main` without a leading `./` is declined by the exports resolver, so only the last fallback resolves it.
     const root = await makeTempRoot();
     await writePackageJson(root, "plainpkg", { main: "index.js" });
     const entryFile = await write(root, "node_modules/plainpkg/index.js");

package/transforms/useClientBundlePlugin.ts

@@ -1,22 +1,11 @@
 import type { BunPlugin } from "bun";
+import { loaderFor } from "./moduleSyntax";
 import { transformUseClient } from "./rscUseClientTransform";
 
-/**
- * BunPlugin that stubs `"use client"` modules so the server bundle sees
- * `registerClientReference(proxy, absPath, name)` stubs instead of the
- * original client code.
- *
- * The bundle produced by `PagesBundleBuilder` is loaded in the RSC worker
- * with `--conditions react-server`; client components are never supposed
- * to execute there. The resulting stub references keep the client
- * component manifest lookups working at render time while ensuring the
- * server bundle never drags the real client source graph in.
- *
- * Important: the second argument to `registerClientReference` must match the
- * key the client manifest uses. When `workspaceRoot` is provided, both sides
- * use workspace-relative keys so production artifacts are portable.
- */
-export function createUseClientBundlePlugin(options: { workspaceRoot?: string } = {}): BunPlugin {
+/** `workspaceRoot` makes reference keys workspace-relative; they must match the client manifest's keys. */
+export function createUseClientBundlePlugin(
+  options: { workspaceRoot?: string; onClientModule?: (path: string, exports: string[]) => void } = {},
+): BunPlugin {
   return {
     name: "akan-use-client-bundle",
     setup(build) {
@@ -31,6 +20,7 @@ export function createUseClientBundlePlugin(options: { workspaceRoot?: string }
         const stubbed = transformUseClient(source, {
           path: args.path,
           workspaceRoot: options.workspaceRoot,
+          onClientModule: options.onClientModule,
         });
         if (stubbed === null) return undefined;
         return { contents: stubbed, loader: loaderFor(args.path) };
@@ -38,10 +28,3 @@ export function createUseClientBundlePlugin(options: { workspaceRoot?: string }
     },
   };
 }
-
-function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-  if (absPath.endsWith(".tsx")) return "tsx";
-  if (absPath.endsWith(".jsx")) return "jsx";
-  if (absPath.endsWith(".ts")) return "ts";
-  return "js";
-}

package/typeChecker.ts

@@ -38,31 +38,15 @@ export class TypeChecker {
     }
     this.config = parsedConfig;
   }
-  /**
-   * Find tsconfig.json by walking up the directory tree
-   */
   #findConfigFile(searchPath: string): string | undefined {
     return ts.findConfigFile(searchPath, (fileName) => ts.sys.fileExists(fileName), "tsconfig.json");
   }
 
-  /**
-   * Type-check a single TypeScript file
-   * @param filePath - Path to the TypeScript file to check
-   * @returns Array of diagnostic messages
-   */
-  check(filePath: string): {
-    diagnostics: ts.Diagnostic[];
-    errors: ts.Diagnostic[];
-    warnings: ts.Diagnostic[];
-    fileDiagnostics: ts.Diagnostic[];
-    fileErrors: ts.Diagnostic[];
-    fileWarnings: ts.Diagnostic[];
-  } {
+  check(filePath: string) {
     const program = ts.createProgram([filePath], this.config.options);
     const diagnostics = [
       ...program.getSemanticDiagnostics(),
       ...program.getSyntacticDiagnostics(),
-      // Only check declaration diagnostics when declaration emit is enabled
       ...(this.config.options.declaration ? program.getDeclarationDiagnostics() : []),
     ];
     const errors = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
@@ -73,11 +57,6 @@ export class TypeChecker {
     return { diagnostics, errors, warnings, fileDiagnostics, fileErrors, fileWarnings };
   }
 
-  /**
-   * Format diagnostics for console output
-   * @param diagnostics - Array of TypeScript diagnostics
-   * @returns Formatted string
-   */
   formatDiagnostics(diagnostics: ts.Diagnostic[]): string {
     if (diagnostics.length === 0) return chalk.bold("✅ No type errors found");
 
@@ -86,48 +65,24 @@ export class TypeChecker {
     let warningCount = 0;
     let suggestionCount = 0;
 
-    // Group diagnostics by file
     const diagnosticsByFile = new Map<string, ts.Diagnostic[]>();
     diagnostics.forEach((diagnostic) => {
       if (diagnostic.category === ts.DiagnosticCategory.Error) errorCount++;
       else if (diagnostic.category === ts.DiagnosticCategory.Warning) warningCount++;
       else if (diagnostic.category === ts.DiagnosticCategory.Suggestion) suggestionCount++;
-
-      if (diagnostic.file) {
-        const fileName = diagnostic.file.fileName;
-        if (!diagnosticsByFile.has(fileName)) diagnosticsByFile.set(fileName, []);
-        const fileDiagnostics = diagnosticsByFile.get(fileName);
-        if (fileDiagnostics) fileDiagnostics.push(diagnostic);
-      } else {
-        if (!diagnosticsByFile.has("")) diagnosticsByFile.set("", []);
-        const fileDiagnostics = diagnosticsByFile.get("");
-        if (fileDiagnostics) fileDiagnostics.push(diagnostic);
-      }
+      diagnosticsByFile.getOrInsert(diagnostic.file?.fileName ?? "", []).push(diagnostic);
     });
 
-    // Format diagnostics by file
     diagnosticsByFile.forEach((fileDiagnostics, fileName) => {
       if (fileName) output.push(`\n${chalk.cyan(fileName)}`);
 
       fileDiagnostics.forEach((diagnostic) => {
-        const categoryText =
-          diagnostic.category === ts.DiagnosticCategory.Error
-            ? "error"
-            : diagnostic.category === ts.DiagnosticCategory.Warning
-              ? "warning"
-              : "suggestion";
-        const categoryColor =
-          diagnostic.category === ts.DiagnosticCategory.Error
-            ? chalk.red
-            : diagnostic.category === ts.DiagnosticCategory.Warning
-              ? chalk.yellow
-              : chalk.blue;
-        const icon =
+        const [categoryText, categoryColor, icon] =
           diagnostic.category === ts.DiagnosticCategory.Error
-            ? "❌"
+            ? (["error", chalk.red, "❌"] as const)
             : diagnostic.category === ts.DiagnosticCategory.Warning
-              ? "⚠️"
-              : "💡";
+              ? (["warning", chalk.yellow, "⚠️"] as const)
+              : (["suggestion", chalk.blue, "💡"] as const);
         const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
         const tsCode = chalk.dim(`(TS${diagnostic.code})`);
 
@@ -137,7 +92,6 @@ export class TypeChecker {
           output.push(`\n  ${icon} ${categoryColor(categoryText)}: ${message} ${tsCode}`);
           output.push(`     ${chalk.gray("at")} ${fileName}:${chalk.bold(`${line + 1}:${character + 1}`)}`);
 
-          // Show source line with underline
           const sourceLines = diagnostic.file.text.split("\n");
           if (line < sourceLines.length) {
             const sourceLine = sourceLines[line];
@@ -145,7 +99,6 @@ export class TypeChecker {
 
             output.push(`\n${chalk.dim(`${lineNumber} |`)} ${sourceLine}`);
 
-            // Create underline with squiggly for TypeScript
             const underlinePrefix = " ".repeat(character);
             const length = diagnostic.length ?? 1;
             const underline = "~".repeat(Math.max(1, length));
@@ -166,11 +119,6 @@ export class TypeChecker {
     return `\n${summary.join(", ")} found${output.join("\n")}`;
   }
 
-  /**
-   * Get detailed diagnostic information with code snippet
-   * @param filePath - Path to the TypeScript file to check
-   * @returns Object containing diagnostics and detailed information
-   */
   getDetailedDiagnostics(filePath: string): {
     diagnostics: ts.Diagnostic[];
     details: { line: number; column: number; message: string; code: number; codeSnippet?: string }[];
@@ -199,11 +147,7 @@ export class TypeChecker {
     return { diagnostics, details };
   }
 
-  /**
-   * Check if a file has type errors
-   * @param filePath - Path to the TypeScript file to check
-   * @returns true if there are no type errors, false otherwise
-   */
+  /** Also false when the check itself throws. */
   hasNoTypeErrors(filePath: string): boolean {
     try {
       const { diagnostics } = this.check(filePath);

package/types.ts

@@ -10,6 +10,8 @@ export interface PackageJson {
   peerDependencies?: Record<string, string>;
   peerDependenciesMeta?: Record<string, { optional?: boolean }>;
   optionalDependencies?: Record<string, string>;
+  trustedDependencies?: string[];
+  overrides?: Record<string, string>;
   engines?: Record<string, string>;
   exports?: Record<string, string | Record<string, string>>;
   bun?: {

package/uploadRelease.ts

@@ -2,10 +2,8 @@ import { Logger, RestClient } from "akanjs/common";
 
 import { Spinner } from "./spinner";
 
-const spinning = (message: string) => {
-  const spinner = new Spinner(message, { prefix: message, enableSpin: true }).start();
-  return spinner;
-};
+const spinning = (message: string) => new Spinner(message, { prefix: message, enableSpin: true }).start();
+
 export const uploadRelease = async (
   appName: string,
   {
@@ -27,33 +25,20 @@ export const uploadRelease = async (
   const logger = new Logger("uploadRelease");
   const basePath = local ? "http://localhost:8282/backend" : "https://cloud.akanjs.com/backend";
   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`;
-
   const readingFilesSpinner = spinning("Reading files...");
   try {
-    const buildFile = Bun.file(buildPath);
-    const sourceFile = Bun.file(sourcePath);
-    const appBuildFile = Bun.file(appBuildPath);
-    const buildStat = { mtime: new Date(buildFile.lastModified), size: buildFile.size };
-    const sourceStat = { mtime: new Date(sourceFile.lastModified), size: sourceFile.size };
-    const appBuildStat = { mtime: new Date(appBuildFile.lastModified), size: appBuildFile.size };
+    const uploads = [
+      [`builds/${appName}-release.tar.gz`, `${appName}-release.tar.gz`],
+      [`sources/${appName}-source.tar.gz`, `${appName}-source.tar.gz`],
+      [`builds/${appName}-appBuild.zip`, `${appName}-appBuild.zip`],
+    ].map(([relativePath, name]) => ({ file: Bun.file(`${workspaceRoot}/releases/${relativePath}`), name }));
+    const metas = uploads.map(({ file }) => ({ lastModifiedAt: new Date(file.lastModified), size: file.size }));
     readingFilesSpinner.succeed("Reading files... done");
 
     const preparingFormSpinner = spinning("Preparing form data...");
     const formData = new FormData();
-    formData.append("files", buildFile, `${appName}-release.tar.gz`);
-    formData.append("files", sourceFile, `${appName}-source.tar.gz`);
-    formData.append("files", appBuildFile, `${appName}-appBuild.zip`);
-    formData.append(
-      "metas",
-      JSON.stringify([
-        { lastModifiedAt: buildStat.mtime, size: buildStat.size },
-        { lastModifiedAt: sourceStat.mtime, size: sourceStat.size },
-        { lastModifiedAt: appBuildStat.mtime, size: appBuildStat.size },
-      ]),
-    );
+    for (const { file, name } of uploads) formData.append("files", file, name);
+    formData.append("metas", JSON.stringify(metas));
     formData.append("type", "release");
     preparingFormSpinner.succeed("Preparing form data... done");
 

package/workflow/artifacts.ts

@@ -1,3 +1,4 @@
+import { capitalize } from "akanjs/common";
 import type { Workspace } from "../commandDecorators";
 import type {
   GeneratedSyncState,
@@ -146,6 +147,23 @@ export const workflowCommandsForPlan = (plan: WorkflowPlan) =>
     kind: validation.kind,
   })) satisfies WorkflowApplyCommand[];
 
+const planInputString = (plan: WorkflowPlan, key: string) => {
+  const value = plan.inputs[key];
+  return typeof value === "string" ? value : "";
+};
+
+export const workflowPathsForPlan = (plan: WorkflowPlan) => {
+  const app = planInputString(plan, "app");
+  const module = planInputString(plan, "module");
+  const moduleClass = module ? capitalize(module) : "<Module>";
+  return plan.predictedChanges.map((change) =>
+    change.target
+      .replace(/^\*\//, app ? `apps/${app}/` : "")
+      .replaceAll("<module>", module || "<module>")
+      .replaceAll("<Module>", moduleClass),
+  );
+};
+
 export const workflowRunsDir = ".akan/workflows/runs";
 
 export const createWorkflowRunId = (prefix = "run") =>

package/workflow/executor.test.ts

@@ -9,11 +9,6 @@ import type {
   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,
@@ -21,8 +16,7 @@ const step = (id: string, tool = `tool:${id}`): WorkflowStep => ({
   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.
+// Not a cast partial: `apply` reads `validation` before the first step, so a missing field fails only at runtime.
 const planOf = (steps: WorkflowStep[], diagnostics: WorkflowDiagnostic[] = []): WorkflowPlan => ({
   schemaVersion: 1,
   workflow: "add-field",
@@ -37,10 +31,6 @@ const planOf = (steps: WorkflowStep[], diagnostics: WorkflowDiagnostic[] = []):
   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> = {}) => {
@@ -79,7 +69,6 @@ describe("WorkflowExecutor.apply", () => {
 
   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");