@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

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/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");

package/workflow/executor.ts

@@ -48,16 +48,13 @@ const workflowStringListInput = (value: WorkflowInputValue | undefined) =>
 const workflowStringArrayInput = (value: WorkflowInputValue | undefined) => (Array.isArray(value) ? value : null);
 const workflowBooleanInput = (value: WorkflowInputValue | undefined) => (typeof value === "boolean" ? value : null);
 
-const postApplyDiagnostic = (code: string, message: string, target: string): WorkflowDiagnostic => ({
-  severity: "error",
-  code,
-  message,
-  failureScope: "source-change",
-  context: { target },
-});
-
-const postApplyWarning = (code: string, message: string, target: string): WorkflowDiagnostic => ({
-  severity: "warning",
+const postApplyDiagnostic = (
+  code: string,
+  message: string,
+  target: string,
+  severity: WorkflowDiagnostic["severity"] = "error",
+): WorkflowDiagnostic => ({
+  severity,
   code,
   message,
   failureScope: "source-change",
@@ -114,27 +111,23 @@ const checkTypeScriptSyntax = async (workspace: Workspace, filePath: string) =>
 
 const checkChangedFile = async (workspace: Workspace, file: PrimitiveChangedFile): Promise<WorkflowStepResult> => {
   if (file.action === "remove") return { postApplyChecks: [] };
-  const diagnostics: WorkflowDiagnostic[] = [];
-  const checks: WorkflowPostApplyCheck[] = [];
-  const pathIssue = await checkPathCasing(workspace, file.path);
-  if (pathIssue) {
-    diagnostics.push(postApplyDiagnostic(pathIssue.code, pathIssue.message, file.path));
-    checks.push({ ...pathIssue, target: file.path, status: "failed" });
-    return { diagnostics, postApplyChecks: checks };
-  }
-  const syntaxIssue = await checkTypeScriptSyntax(workspace, file.path);
-  if (syntaxIssue) {
-    diagnostics.push(postApplyDiagnostic(syntaxIssue.code, syntaxIssue.message, file.path));
-    checks.push({ ...syntaxIssue, target: file.path, status: "failed" });
-    return { diagnostics, postApplyChecks: checks };
+  const issue = (await checkPathCasing(workspace, file.path)) ?? (await checkTypeScriptSyntax(workspace, file.path));
+  if (issue) {
+    return {
+      diagnostics: [postApplyDiagnostic(issue.code, issue.message, file.path)],
+      postApplyChecks: [{ ...issue, target: file.path, status: "failed" }],
+    };
   }
-  checks.push({
-    code: "workflow-post-apply-file-valid",
-    target: file.path,
-    status: "passed",
-    message: "Changed file exists with exact casing and parses as source when applicable.",
-  });
-  return { postApplyChecks: checks };
+  return {
+    postApplyChecks: [
+      {
+        code: "workflow-post-apply-file-valid",
+        target: file.path,
+        status: "passed",
+        message: "Changed file exists with exact casing and parses as source when applicable.",
+      },
+    ],
+  };
 };
 
 const checkRecommendationPath = async (
@@ -199,18 +192,6 @@ const workflowModuleContext = async (workspace: Workspace, plan: WorkflowPlan):
   };
 };
 
-const structureCheck = (
-  code: string,
-  target: string,
-  status: WorkflowPostApplyCheck["status"],
-  message: string,
-): WorkflowPostApplyCheck => ({
-  code,
-  target,
-  status,
-  message,
-});
-
 const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowStepResult> => {
   if (plan.workflow !== "add-field" && plan.workflow !== "add-enum-field") return {};
   const app = workflowStringInput(plan.inputs.app);
@@ -260,16 +241,14 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
       .map((diagnostic) => diagnostic.message),
   ].filter((failure): failure is string => failure !== null);
   const constantValid = constantFailures.length === 0;
-  postApplyChecks.push(
-    structureCheck(
-      constantValid ? "workflow-post-apply-constant-shape-valid" : "workflow-post-apply-structure-invalid",
-      constantPath,
-      constantValid ? "passed" : "failed",
-      constantValid
-        ? `${inputClassName} keeps via structure, builder usage, imports, and requested field presence.`
-        : constantFailures.join(" "),
-    ),
-  );
+  postApplyChecks.push({
+    code: constantValid ? "workflow-post-apply-constant-shape-valid" : "workflow-post-apply-structure-invalid",
+    target: constantPath,
+    status: constantValid ? "passed" : "failed",
+    message: constantValid
+      ? `${inputClassName} keeps via structure, builder usage, imports, and requested field presence.`
+      : constantFailures.join(" "),
+  });
   if (!constantValid) {
     diagnostics.push(
       postApplyDiagnostic("workflow-post-apply-structure-invalid", constantFailures.join(" "), constantPath),
@@ -294,16 +273,14 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
       .map((diagnostic) => diagnostic.message),
   ].filter((failure): failure is string => failure !== null);
   const dictionaryValid = dictionaryFailures.length === 0;
-  postApplyChecks.push(
-    structureCheck(
-      dictionaryValid ? "workflow-post-apply-dictionary-shape-valid" : "workflow-post-apply-structure-invalid",
-      dictionaryPath,
-      dictionaryValid ? "passed" : "failed",
-      dictionaryValid
-        ? `.model<${moduleClassName}> keeps the requested field inside the model object and preserves dictionary chain order.`
-        : dictionaryFailures.join(" "),
-    ),
-  );
+  postApplyChecks.push({
+    code: dictionaryValid ? "workflow-post-apply-dictionary-shape-valid" : "workflow-post-apply-structure-invalid",
+    target: dictionaryPath,
+    status: dictionaryValid ? "passed" : "failed",
+    message: dictionaryValid
+      ? `.model<${moduleClassName}> keeps the requested field inside the model object and preserves dictionary chain order.`
+      : dictionaryFailures.join(" "),
+  });
   if (!dictionaryValid) {
     diagnostics.push(
       postApplyDiagnostic("workflow-post-apply-structure-invalid", dictionaryFailures.join(" "), dictionaryPath),
@@ -313,22 +290,21 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
   const constantOrderValid = fieldOrderValid(constantNames, fieldName);
   const dictionaryOrderValid = fieldOrderValid(dictionaryStructure.fields, fieldName);
   const orderValid = constantOrderValid && dictionaryOrderValid;
-  postApplyChecks.push(
-    structureCheck(
-      "workflow-post-apply-field-order-valid",
-      `${constantPath}, ${dictionaryPath}`,
-      orderValid ? "passed" : "failed",
-      orderValid
-        ? `Field "${fieldName}" follows the shared priority ordering policy.`
-        : `Field "${fieldName}" is present but does not match the shared priority ordering policy.`,
-    ),
-  );
+  postApplyChecks.push({
+    code: "workflow-post-apply-field-order-valid",
+    target: `${constantPath}, ${dictionaryPath}`,
+    status: orderValid ? "passed" : "failed",
+    message: orderValid
+      ? `Field "${fieldName}" follows the shared priority ordering policy.`
+      : `Field "${fieldName}" is present but does not match the shared priority ordering policy.`,
+  });
   if (!orderValid) {
     diagnostics.push(
-      postApplyWarning(
+      postApplyDiagnostic(
         "workflow-post-apply-field-order-mismatch",
         `Field "${fieldName}" is present but does not match the shared priority ordering policy.`,
         `${constantPath}, ${dictionaryPath}`,
+        "warning",
       ),
     );
   }
@@ -365,6 +341,14 @@ const unsupportedInput = (input: string, message: string): WorkflowDiagnostic =>
   message,
 });
 
+const surfaceReview = (
+  plan: WorkflowPlan,
+  { code, target, action, message, reason }: Record<"code" | "target" | "action" | "message" | "reason", string>,
+): WorkflowStepResult => ({
+  recommendations: [{ code, kind: "manual-action", target, action, confidence: "medium", message }],
+  nextActions: [{ command: `akan workflow explain ${plan.workflow}`, reason }],
+});
+
 const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
   const app = workflowStringInput(plan.inputs.app);
   const module = workflowStringInput(plan.inputs.module) ?? "<module>";
@@ -374,75 +358,41 @@ const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult =>
   const surfaces = workflowStringArrayInput(plan.inputs.surfaces);
   const templateRequested = surfaces?.includes("template") ?? false;
   const moduleClassName = moduleComponentName(module);
-  const target = `${app ? `apps/${app}` : "*"}/${moduleSourcePaths(module).template}`;
-  return {
-    recommendations: [
-      {
-        code: "add-field-ui-surface-review",
-        kind: "manual-action",
-        target,
-        action: templateRequested
-          ? `Template was requested for ${field}. If no Template file changed, users will not see the field in the form yet because the file was missing, the generated ${module}Form/Layout.Template pattern was not found, or ${policy.component} needs option binding. Add it inside Layout.Template near existing Field components.`
-          : `Template was not selected, so users will not see ${field} in the form from this apply. If list/card display is needed, include ${field} in Light${moduleClassName} projection data and place it in the local Unit/View card layout.`,
-        confidence: "medium",
-        message: `Review user-visible UI for ${module}.${field}; recommended component is ${policy.component}.`,
-      },
-    ],
-    nextActions: [
-      {
-        command: `akan workflow explain ${plan.workflow}`,
-        reason: "Review UI surface guidance before manually editing ambiguous UI files.",
-      },
-    ],
-  };
+  return surfaceReview(plan, {
+    code: "add-field-ui-surface-review",
+    target: `${app ? `apps/${app}` : "*"}/${moduleSourcePaths(module).template}`,
+    action: templateRequested
+      ? `Template was requested for ${field}. If no Template file changed, users will not see the field in the form yet because the file was missing, the generated ${module}Form/Layout.Template pattern was not found, or ${policy.component} needs option binding. Add it inside Layout.Template near existing Field components.`
+      : `Template was not selected, so users will not see ${field} in the form from this apply. If list/card display is needed, include ${field} in Light${moduleClassName} projection data and place it in the local Unit/View card layout.`,
+    message: `Review user-visible UI for ${module}.${field}; recommended component is ${policy.component}.`,
+    reason: "Review UI surface guidance before manually editing ambiguous UI files.",
+  });
 };
 
 const addMutationActionSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
   const module = workflowStringInput(plan.inputs.module) ?? "<module>";
   const mutation = workflowStringInput(plan.inputs.mutation) ?? "<mutation>";
   const moduleClassName = moduleComponentName(module);
-  return {
-    recommendations: [
-      {
-        code: "add-mutation-action-surface-review",
-        kind: "manual-action",
-        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.`,
-        confidence: "medium",
-        message: `Workflow apply does not write store or UI code for ${module}.${mutation}; review whether a screen should call it.`,
-      },
-    ],
-    nextActions: [
-      {
-        command: `akan workflow explain ${plan.workflow}`,
-        reason: "Review action surface guidance before manually editing store or UI files.",
-      },
-    ],
-  };
+  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.",
+  });
 };
 
 const addSliceViewSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
   const module = workflowStringInput(plan.inputs.module) ?? "<module>";
   const slice = workflowStringInput(plan.inputs.slice) ?? "<slice>";
   const moduleClassName = moduleComponentName(module);
-  return {
-    recommendations: [
-      {
-        code: "add-slice-view-surface-review",
-        kind: "manual-action",
-        target: `*/${moduleSourcePaths(module).zone}`,
-        action: `Fill in the service query stub and add the dictionary .slice() entry. After sync, load fetch.init${moduleClassName}${capitalize(slice)}() in the page and pass the result to a ${moduleClassName}.Zone as an init prop.`,
-        confidence: "medium",
-        message: `Workflow apply does not write page or Zone code for ${module}.${slice}; review where the list should render.`,
-      },
-    ],
-    nextActions: [
-      {
-        command: `akan workflow explain ${plan.workflow}`,
-        reason: "Review view surface guidance before manually editing Zone or page files.",
-      },
-    ],
-  };
+  return surfaceReview(plan, {
+    code: "add-slice-view-surface-review",
+    target: `*/${moduleSourcePaths(module).zone}`,
+    action: `Fill in the service query stub and add the dictionary .slice() entry. After sync, load fetch.init${moduleClassName}${capitalize(slice)}() in the page and pass the result to a ${moduleClassName}.Zone as an init prop.`,
+    message: `Workflow apply does not write page or Zone code for ${module}.${slice}; review where the list should render.`,
+    reason: "Review view surface guidance before manually editing Zone or page files.",
+  });
 };
 
 export const createWorkflowStepRegistry = ({
@@ -581,9 +531,8 @@ export class WorkflowExecutor {
     const postApplyChecks: WorkflowPostApplyCheck[] = [];
     const recommendations = [...plan.recommendations];
     const nextActions: PrimitiveNextAction[] = [];
-
-    if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
-      return createWorkflowApplyReport({
+    const report = () =>
+      createWorkflowApplyReport({
         workflow: plan.workflow,
         mode: "apply",
         changedFiles,
@@ -595,7 +544,8 @@ export class WorkflowExecutor {
         nextActions,
         plan,
       });
-    }
+
+    if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) return report();
 
     recommendedValidationCommands.push(...workflowCommandsForPlan(plan));
     nextActions.push(...workflowCommandsForPlan(plan));
@@ -646,17 +596,6 @@ export class WorkflowExecutor {
       );
     }
 
-    return createWorkflowApplyReport({
-      workflow: plan.workflow,
-      mode: "apply",
-      changedFiles,
-      generatedFiles,
-      recommendedValidationCommands,
-      diagnostics,
-      postApplyChecks,
-      recommendations,
-      nextActions,
-      plan,
-    });
+    return report();
   }
 }

package/workflow/index.ts

@@ -2,7 +2,6 @@ export * from "./artifacts";
 export * from "./executor";
 export * from "./moduleIndex";
 export * from "./plan";
-export * from "./primitive";
 export * from "./render";
 export * from "./rolloutGate";
 export * from "./source";

package/workflow/moduleIndex.test.ts

@@ -1,31 +1,20 @@
-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 type { AkanModuleContext } from "../akanContext";
 import type { Workspace } from "../commandDecorators";
+import { tempDirs, writeText } from "../testHelpers";
 import { buildAkanModuleContextIndex } from "./moduleIndex";
 
-const tempRoots: string[] = [];
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+const tempRoot = tempDirs("akan-module-index-");
 
 const makeWorkspace = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-module-index-"));
-  tempRoots.push(root);
+  const root = await tempRoot();
   return {
     root,
     workspace: { workspaceRoot: root } as Workspace,
   };
 };
 
-const writeText = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
-
 const moduleContext = (files: string[], name = "post"): AkanModuleContext => ({
   kind: "domain",
   name,