@akanjs/cli 3.0.0-beta.9 → 3.0.1

package/{index-d43r08tf.js → index-8b639zes.js}

@@ -1,23 +1,25 @@
 // @bun
 import {
   script
-} from "./index-0g7r8xz3.js";
+} from "./index-a37by9hn.js";
 import {
   AppExecutor,
   LibExecutor,
   ModuleExecutor
-} from "./index-2tv3fdx4.js";
+} from "./index-150s07n8.js";
 import {
+  workflowStatus,
   compactDiagnostics,
-  createPrimitiveWriteReport,
   sourceFile,
   moduleComponentName,
   moduleSourcePaths,
   generatedFilesForSync,
   validationCommandsForTarget,
   nextActionsForTarget,
-  lowerlize,
+  createPrimitiveWriteReport,
   normalizeFieldType,
+  ensureNamedImport,
+  ensureBaseImport,
   ensureBaseTypeImport,
   coerceFieldDefault,
   fieldExpression,
@@ -39,13 +41,13 @@ import {
   hasSignalFactoryEntry,
   insertSignalFactoryEntry,
   addFieldUiPolicyForType
-} from "./index-gyd220p2.js";
+} from "./index-mb59b8x0.js";
 import {
   ModuleScript
-} from "./index-5ystnsd5.js";
+} from "./index-rfcz04w9.js";
 
 // pkgs/@akanjs/cli/primitive/primitive.script.ts
-import { capitalize } from "akanjs/common";
+import { capitalize, lowerlize } from "akanjs/common";
 class PrimitiveScript extends script("primitive", [ModuleScript]) {
   async resolveSys(workspace, target) {
     if (!target)
@@ -59,28 +61,11 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
   }
   async createUi(workspace, input) {
     const sys = await this.resolveSys(workspace, input.app);
-    if (!sys || !input.module) {
-      return createPrimitiveWriteReport({
-        command: "create-ui",
-        changedFiles: [],
-        generatedFiles: [],
-        validationCommands: [],
-        diagnostics: compactDiagnostics([
-          !sys && {
-            severity: "error",
-            code: "primitive-target-missing",
-            message: "Target app or library was not found."
-          },
-          !input.module && {
-            severity: "error",
-            code: "primitive-input-missing",
-            message: "Module is required.",
-            input: "module"
-          }
-        ]),
-        nextActions: []
-      });
-    }
+    if (!sys || !input.module)
+      return PrimitiveScript.#refuse("create-ui", compactDiagnostics([
+        !sys && PrimitiveScript.#targetMissing(),
+        !input.module && PrimitiveScript.#inputMissing("module")
+      ]));
     const mod = ModuleExecutor.from(sys, input.module);
     if (input.surface === "view")
       return await this.moduleScript.createView(mod);
@@ -96,30 +81,16 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
     return await this.addFieldToSources(workspace, { ...input, type: `${capitalize(input.field ?? "")}` }, { enumValues: values });
   }
   async addFieldToSources(workspace, input, { enumValues }) {
+    const command = enumValues ? "add-enum-field" : "add-field";
     const sys = await this.resolveSys(workspace, input.app);
     const ambiguousNumberTypes = new Set(["number", "numeric"]);
     const normalizedType = input.type ? normalizeFieldType(input.type) : null;
     const diagnostics = compactDiagnostics([
-      !sys && { severity: "error", code: "primitive-target-missing", message: "Target app or library was not found." },
-      !input.module && {
-        severity: "error",
-        code: "primitive-input-missing",
-        message: "Module is required.",
-        input: "module"
-      },
-      !input.field && {
-        severity: "error",
-        code: "primitive-input-missing",
-        message: "Field is required.",
-        input: "field"
-      },
-      !input.type && {
-        severity: "error",
-        code: "primitive-input-missing",
-        message: "Type is required.",
-        input: "type"
-      },
-      enumValues && enumValues.length === 0 ? { severity: "error", code: "primitive-input-missing", message: "Enum values are required.", input: "values" } : null,
+      !sys && PrimitiveScript.#targetMissing(),
+      !input.module && PrimitiveScript.#inputMissing("module"),
+      !input.field && PrimitiveScript.#inputMissing("field"),
+      !input.type && PrimitiveScript.#inputMissing("type"),
+      enumValues?.length === 0 && PrimitiveScript.#inputMissing("values", "Enum values are required."),
       input.type && ambiguousNumberTypes.has(input.type.toLowerCase()) ? {
         severity: "error",
         code: "primitive-field-type-unsupported",
@@ -133,16 +104,8 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
         input: "type"
       } : null
     ]);
-    if (!sys || !input.module || !input.field || !input.type || diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
-      return createPrimitiveWriteReport({
-        command: enumValues ? "add-enum-field" : "add-field",
-        changedFiles: [],
-        generatedFiles: [],
-        validationCommands: [],
-        diagnostics,
-        nextActions: []
-      });
-    }
+    if (!sys || !input.module || !input.field || !input.type || workflowStatus(diagnostics) === "failed")
+      return PrimitiveScript.#refuse(command, diagnostics);
     const moduleClassName = moduleComponentName(input.module);
     const inputClassName = `${moduleClassName}Input`;
     const paths = moduleSourcePaths(input.module);
@@ -150,32 +113,13 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
     const dictionaryPath = paths.dictionary;
     const templatePath = paths.template;
     const changedFiles = [];
-    const generatedFiles = generatedFilesForSync(sys);
     const [hasConstant, hasDictionary] = await Promise.all([sys.exists(constantPath), sys.exists(dictionaryPath)]);
-    if (!hasConstant) {
-      diagnostics.push({
-        severity: "error",
-        code: "primitive-source-missing",
-        message: `Constant source file was not found: ${constantPath}.`
-      });
-    }
-    if (!hasDictionary) {
-      diagnostics.push({
-        severity: "error",
-        code: "primitive-source-missing",
-        message: `Dictionary source file was not found: ${dictionaryPath}.`
-      });
-    }
-    if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
-      return createPrimitiveWriteReport({
-        command: enumValues ? "add-enum-field" : "add-field",
-        changedFiles,
-        generatedFiles,
-        validationCommands: validationCommandsForTarget(sys.name),
-        diagnostics,
-        nextActions: nextActionsForTarget(sys.name)
-      });
-    }
+    if (!hasConstant)
+      diagnostics.push(PrimitiveScript.#sourceMissing("Constant", constantPath));
+    if (!hasDictionary)
+      diagnostics.push(PrimitiveScript.#sourceMissing("Dictionary", dictionaryPath));
+    if (workflowStatus(diagnostics) === "failed")
+      return PrimitiveScript.#report(command, sys, changedFiles, diagnostics);
     let constantContent = await sys.readFile(constantPath);
     let dictionaryContent = await sys.readFile(dictionaryPath);
     const fieldBuilderName = viaBuilderParameterName(constantContent, inputClassName) ?? "field";
@@ -210,6 +154,8 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
       if (defaultCoercion.diagnostic)
         diagnostics.push(defaultCoercion.diagnostic);
       constantContent = ensureBaseTypeImport(constantContent, input.type);
+      if (input.type === "Date" && defaultCoercion.expression)
+        constantContent = ensureBaseImport(constantContent, "dayjs");
     }
     if (enumValues) {
       const defaultCoercion = coerceFieldDefault("enum", input.defaultValue, { enumValues });
@@ -311,7 +257,7 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
         }
       }
     }
-    if (!diagnostics.some((diagnostic) => diagnostic.severity === "error") && nextConstantContentWithLight && nextDictionaryContent) {
+    if (workflowStatus(diagnostics) === "passed" && nextConstantContentWithLight && nextDictionaryContent) {
       await sys.writeFile(constantPath, nextConstantContentWithLight);
       await sys.writeFile(dictionaryPath, nextDictionaryContent);
       changedFiles.push(sourceFile(sys, constantPath, "modify", "Field source shape was updated."), sourceFile(sys, dictionaryPath, "modify", "Field dictionary labels were updated."));
@@ -320,14 +266,7 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
         changedFiles.push(sourceFile(sys, templatePath, "modify", "Template field surface was updated."));
       }
     }
-    return createPrimitiveWriteReport({
-      command: enumValues ? "add-enum-field" : "add-field",
-      changedFiles,
-      generatedFiles,
-      validationCommands: validationCommandsForTarget(sys.name),
-      diagnostics,
-      nextActions: nextActionsForTarget(sys.name)
-    });
+    return PrimitiveScript.#report(command, sys, changedFiles, diagnostics);
   }
   async addMutation(workspace, input) {
     const moduleClassName = input.module ? moduleComponentName(input.module) : "";
@@ -353,7 +292,7 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
       signal: name ? {
         className: `${moduleClassName}Endpoint`,
         entryLine: [
-          `${name}: mutation(Boolean)`,
+          `${name}: mutation(Boolean, { guards: [None] })`,
           `    .exec(async function () {`,
           `      return await this.${serviceRef}Service.${name}();`,
           `    }),`
@@ -388,7 +327,7 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
       signal: name && queryName ? {
         className: `${moduleClassName}Slice`,
         entryLine: [
-          `${name}: init()`,
+          `${name}: init({ guards: [None] })`,
           `    .exec(function () {`,
           `      return this.${serviceRef}Service.${queryName}();`,
           `    }),`
@@ -401,60 +340,21 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
   async#writeServiceSignalEntry(workspace, spec) {
     const sys = await this.resolveSys(workspace, spec.app);
     const diagnostics = compactDiagnostics([
-      !sys && { severity: "error", code: "primitive-target-missing", message: "Target app or library was not found." },
-      !spec.module && {
-        severity: "error",
-        code: "primitive-input-missing",
-        message: "Module is required.",
-        input: "module"
-      },
-      !spec.entryName && {
-        severity: "error",
-        code: "primitive-input-missing",
-        message: `${capitalize(spec.requiredInput)} name is required.`,
-        input: spec.requiredInput
-      }
+      !sys && PrimitiveScript.#targetMissing(),
+      !spec.module && PrimitiveScript.#inputMissing("module"),
+      !spec.entryName && PrimitiveScript.#inputMissing(spec.requiredInput, `${capitalize(spec.requiredInput)} name is required.`)
     ]);
-    if (!sys || !spec.module || !spec.entryName || !spec.serviceMethod || !spec.signal) {
-      return createPrimitiveWriteReport({
-        command: spec.command,
-        changedFiles: [],
-        generatedFiles: [],
-        validationCommands: [],
-        diagnostics,
-        nextActions: []
-      });
-    }
-    const paths = moduleSourcePaths(spec.module);
-    const servicePath = paths.service;
-    const signalPath = paths.signal;
+    if (!sys || !spec.module || !spec.entryName || !spec.serviceMethod || !spec.signal)
+      return PrimitiveScript.#refuse(spec.command, diagnostics);
+    const { service: servicePath, signal: signalPath } = moduleSourcePaths(spec.module);
     const changedFiles = [];
-    const generatedFiles = generatedFilesForSync(sys);
     const [hasServiceFile, hasSignalFile] = await Promise.all([sys.exists(servicePath), sys.exists(signalPath)]);
-    if (!hasServiceFile) {
-      diagnostics.push({
-        severity: "error",
-        code: "primitive-source-missing",
-        message: `Service source file was not found: ${servicePath}.`
-      });
-    }
-    if (!hasSignalFile) {
-      diagnostics.push({
-        severity: "error",
-        code: "primitive-source-missing",
-        message: `Signal source file was not found: ${signalPath}.`
-      });
-    }
-    if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
-      return createPrimitiveWriteReport({
-        command: spec.command,
-        changedFiles,
-        generatedFiles,
-        validationCommands: validationCommandsForTarget(sys.name),
-        diagnostics,
-        nextActions: nextActionsForTarget(sys.name)
-      });
-    }
+    if (!hasServiceFile)
+      diagnostics.push(PrimitiveScript.#sourceMissing("Service", servicePath));
+    if (!hasSignalFile)
+      diagnostics.push(PrimitiveScript.#sourceMissing("Signal", signalPath));
+    if (workflowStatus(diagnostics) === "failed")
+      return PrimitiveScript.#report(spec.command, sys, changedFiles, diagnostics);
     const serviceClassName = `${moduleComponentName(spec.module)}Service`;
     const serviceContent = await sys.readFile(servicePath);
     const signalContent = await sys.readFile(signalPath);
@@ -476,7 +376,8 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
       });
     }
     const nextServiceContent = serviceMethodExists ? serviceContent : insertClassMethod(serviceContent, serviceClassName, spec.serviceMethod.block);
-    const nextSignalContent = insertSignalFactoryEntry(signalContent, spec.signal.className, spec.entryName, spec.signal.entryLine, spec.signal.param);
+    const insertedSignalContent = insertSignalFactoryEntry(signalContent, spec.signal.className, spec.entryName, spec.signal.entryLine, spec.signal.param);
+    const nextSignalContent = insertedSignalContent ? ensureNamedImport(insertedSignalContent, "akanjs/signal", "None") : insertedSignalContent;
     if (!nextServiceContent) {
       diagnostics.push({
         severity: "error",
@@ -515,20 +416,46 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
         message: `Edited ${signalPath} did not contain entry "${spec.entryName}" in ${spec.signal.className}.`
       });
     }
-    if (!diagnostics.some((diagnostic) => diagnostic.severity === "error") && nextServiceContent && nextSignalContent) {
+    if (workflowStatus(diagnostics) === "passed" && nextServiceContent && nextSignalContent) {
       await sys.writeFile(servicePath, nextServiceContent);
       await sys.writeFile(signalPath, nextSignalContent);
       changedFiles.push(sourceFile(sys, servicePath, "modify", `Service ${spec.entryKind} was added.`), sourceFile(sys, signalPath, "modify", `Signal ${spec.entryKind} was added.`));
     }
+    return PrimitiveScript.#report(spec.command, sys, changedFiles, diagnostics);
+  }
+  static #refuse(command, diagnostics) {
+    return createPrimitiveWriteReport({
+      command,
+      changedFiles: [],
+      generatedFiles: [],
+      validationCommands: [],
+      diagnostics,
+      nextActions: []
+    });
+  }
+  static #report(command, sys, changedFiles, diagnostics) {
     return createPrimitiveWriteReport({
-      command: spec.command,
+      command,
       changedFiles,
-      generatedFiles,
+      generatedFiles: generatedFilesForSync(sys),
       validationCommands: validationCommandsForTarget(sys.name),
       diagnostics,
       nextActions: nextActionsForTarget(sys.name)
     });
   }
+  static #targetMissing() {
+    return { severity: "error", code: "primitive-target-missing", message: "Target app or library was not found." };
+  }
+  static #inputMissing(input, message = `${capitalize(input)} is required.`) {
+    return { severity: "error", code: "primitive-input-missing", message, input };
+  }
+  static #sourceMissing(kind, path) {
+    return {
+      severity: "error",
+      code: "primitive-source-missing",
+      message: `${kind} source file was not found: ${path}.`
+    };
+  }
 }
 
 export { PrimitiveScript };

package/{index-ktb5njgy.js → index-8kvy8qb4.js}

@@ -4,27 +4,29 @@ import {
   readDevkitVersion,
   rootAllowedFiles,
   rootAllowedDirs,
+  rootEntryHintOf,
   isScannedRootEntry,
   AppExecutor,
   LibExecutor
-} from "./index-2tv3fdx4.js";
+} from "./index-150s07n8.js";
 import {
-  FileSys
-} from "./index-q0y2jq9j.js";
+  FileSys2
+} from "./index-52w0fvh8.js";
 import {
   collectRecipeSources2,
   scanRecipes2,
   findInlineRecipeDuplicates2
-} from "./index-by5gpp8x.js";
+} from "./index-hj6w4ka1.js";
 import {
+  workflowPathsForPlan,
   workflowRunArtifactPath,
   workflowSyncDir
-} from "./index-gyd220p2.js";
+} from "./index-mb59b8x0.js";
 
 // pkgs/@akanjs/devkit/akanContext.ts
 import { readdir } from "fs/promises";
 import path from "path";
-import { capitalize } from "akanjs/common";
+import { capitalize, isRecord } from "akanjs/common";
 var guidelineResourceUri = (name) => `akan://guidelines/${name}`;
 var staticResourceList = [
   { uri: "akan://docs/framework", name: "Akan framework guide", mimeType: "text/markdown" },
@@ -52,16 +54,13 @@ var akanMcpInstallConfigPaths = {
 var cursorWorkspaceFolder = "$" + "{workspaceFolder}";
 var claudeProjectDir = "$CLAUDE_PROJECT_DIR";
 var akanMcpCommand = (mode, { cd } = {}) => cd ? `cd "${cd}" && akan mcp --mode ${mode}` : `akan mcp --mode ${mode}`;
-var createAkanCursorMcpServer = (mode = "readonly") => ({
+var bashMcpServer = (mode, cd) => ({
   type: "stdio",
   command: "bash",
-  args: ["-lc", akanMcpCommand(mode, { cd: cursorWorkspaceFolder })]
-});
-var createAkanClaudeMcpServer = (mode = "readonly") => ({
-  type: "stdio",
-  command: "bash",
-  args: ["-lc", akanMcpCommand(mode, { cd: claudeProjectDir })]
+  args: ["-lc", akanMcpCommand(mode, { cd })]
 });
+var createAkanCursorMcpServer = (mode = "readonly") => bashMcpServer(mode, cursorWorkspaceFolder);
+var createAkanClaudeMcpServer = (mode = "readonly") => bashMcpServer(mode, claudeProjectDir);
 var createAkanMcpServer = (target, mode = "readonly") => target === "cursor" ? createAkanCursorMcpServer(mode) : createAkanClaudeMcpServer(mode);
 var akanCursorMcpServer = createAkanCursorMcpServer();
 var codexMcpServerTableHeader = "[mcp_servers.akan]";
@@ -164,41 +163,13 @@ var moduleShapeFiles = (module) => {
   ];
 };
 var constantFieldNames = (content) => [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
-var safeReadDir = async (dirPath) => {
-  try {
-    return (await readdir(dirPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
-  } catch {
-    return [];
-  }
-};
-var safeReadText = async (filePath) => {
-  try {
-    return await FileSys.readText(filePath);
-  } catch {
-    return null;
-  }
-};
-var safeReadJson = async (filePath) => {
-  try {
-    return await FileSys.readJson(filePath);
-  } catch {
-    return null;
-  }
-};
-var isWorkflowPlan = (value) => typeof value === "object" && value !== null && ("schemaVersion" in value) && value.schemaVersion === 1 && ("mode" in value) && value.mode === "plan";
-var isWorkflowApplyReport = (value) => typeof value === "object" && value !== null && ("schemaVersion" in value) && value.schemaVersion === 1 && ("mode" in value) && (value.mode === "apply" || value.mode === "dry-run");
+var safeReadDir = async (dirPath) => (await readdir(dirPath, { withFileTypes: true }).catch(() => [])).sort((a, b) => a.name.localeCompare(b.name));
+var safeReadText = (filePath) => FileSys2.readText(filePath).catch(() => null);
+var safeReadJson = (filePath) => FileSys2.readJson(filePath).catch(() => null);
+var isWorkflowPlan = (value) => typeof value === "object" && value !== null && ("schemaVersion" in value) && value.schemaVersion === 1 && ("mode" in value) && value.mode === "plan" && ("inputs" in value) && isRecord(value.inputs) && ("predictedChanges" in value) && Array.isArray(value.predictedChanges) && value.predictedChanges.every((change) => isRecord(change) && typeof change.target === "string");
+var isPathList = (value) => Array.isArray(value) && value.every((file) => isRecord(file) && typeof file.path === "string");
+var isWorkflowApplyReport = (value) => typeof value === "object" && value !== null && ("schemaVersion" in value) && value.schemaVersion === 1 && ("mode" in value) && (value.mode === "apply" || value.mode === "dry-run") && ("changedFiles" in value) && isPathList(value.changedFiles) && ("generatedFiles" in value) && isPathList(value.generatedFiles) && ("plan" in value) && isWorkflowPlan(value.plan);
 var isWorkflowRunArtifact = (value) => typeof value === "object" && value !== null && ("schemaVersion" in value) && value.schemaVersion === 1;
-var planInputString = (plan, key) => {
-  const value = plan.inputs[key];
-  return typeof value === "string" ? value : "";
-};
-var expandWorkflowTarget = (target, plan) => {
-  const app = planInputString(plan, "app");
-  const module = planInputString(plan, "module");
-  const moduleClass = module ? capitalize(module) : "<Module>";
-  return target.replace(/^\*\//, app ? `apps/${app}/` : "").replaceAll("<module>", module || "<module>").replaceAll("<Module>", moduleClass);
-};
-var workflowPathsForPlan = (plan) => plan.predictedChanges.map((change) => expandWorkflowTarget(change.target, plan));
 var workflowPathsForArtifact = (artifact) => {
   if (isWorkflowPlan(artifact))
     return workflowPathsForPlan(artifact);
@@ -209,7 +180,7 @@ var workflowPathsForArtifact = (artifact) => {
       ...workflowPathsForPlan(artifact.plan)
     ];
   }
-  if ("mode" in artifact && artifact.mode === "validate" && artifact.plan)
+  if ("mode" in artifact && artifact.mode === "validate" && isWorkflowPlan(artifact.plan))
     return workflowPathsForPlan(artifact.plan);
   return [];
 };
@@ -310,13 +281,13 @@ var getSysModules = async (workspace, sys, {
       const serviceName = entry.name.replace(/^_+/, "");
       if (moduleFilter && moduleFilter !== serviceName && moduleFilter !== entry.name)
         continue;
-      if (!await FileSys.fileExists(path.join(libPath, entry.name, `${serviceName}.service.ts`)))
+      if (!await FileSys2.fileExists(path.join(libPath, entry.name, `${serviceName}.service.ts`)))
         continue;
       modules.push(await createModuleContext(workspace, sys, "service", entry.name, serviceName, includeAbstractContent));
     } else {
       if (moduleFilter && moduleFilter !== entry.name)
         continue;
-      if (!await FileSys.fileExists(path.join(libPath, entry.name, `${entry.name}.constant.ts`)))
+      if (!await FileSys2.fileExists(path.join(libPath, entry.name, `${entry.name}.constant.ts`)))
         continue;
       modules.push(await createModuleContext(workspace, sys, "domain", entry.name, entry.name, includeAbstractContent));
     }
@@ -327,7 +298,7 @@ var getSysModules = async (workspace, sys, {
       continue;
     if (moduleFilter && moduleFilter !== entry.name)
       continue;
-    if (!await FileSys.fileExists(path.join(scalarRoot, entry.name, `${entry.name}.constant.ts`)))
+    if (!await FileSys2.fileExists(path.join(scalarRoot, entry.name, `${entry.name}.constant.ts`)))
       continue;
     modules.push(await createModuleContext(workspace, sys, "scalar", entry.name, entry.name, includeAbstractContent));
   }
@@ -339,7 +310,7 @@ var getSysContext = async (workspace, type, name, options) => {
     type,
     name,
     path: `${type}s/${name}`,
-    hasConfig: await FileSys.fileExists(path.join(sys.cwdPath, "akan.config.ts")),
+    hasConfig: await FileSys2.fileExists(path.join(sys.cwdPath, "akan.config.ts")),
     modules: await getSysModules(workspace, sys, {
       includeAbstractContent: options.includeAbstractContent,
       module: options.module
@@ -411,62 +382,47 @@ class AkanContextAnalyzer {
       repairAction("generated", "akan repair generated --app <app-or-lib>", "Refresh generated Akan files.", true),
       repairAction("format", "akan repair format --target <app-or-lib-or-pkg>", "Run the formatter/linter repair path.", true)
     ];
+    const report = (diagnostic, action) => {
+      diagnostics.push({ ...diagnostic, repairActions: [action] });
+      repairActions.push(action);
+    };
     for (const sys of [...context.apps, ...context.libs]) {
       const sysPath = path.join(workspace.workspaceRoot, sys.path);
       for (const entry of await safeReadDir(sysPath)) {
         if (!isScannedRootEntry(sys.type, entry.name))
           continue;
         const allowed = entry.isDirectory() ? rootAllowedDirs[sys.type].has(entry.name) : rootAllowedFiles[sys.type].has(entry.name);
-        if (!allowed) {
-          const action = repairAction("module-shape", `akan repair module-shape --app ${sys.name}`, `Review ${sys.type} root shape and remove or move the unknown entry.`, false);
-          diagnostics.push({
+        const rootEntryHint = rootEntryHintOf(sys.type, entry.name);
+        if (!allowed)
+          report({
             severity: "error",
             code: `${sys.type}-root-unknown-entry`,
             path: `${sys.path}/${entry.name}`,
-            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in ${sys.type} root: ${sys.path}/${entry.name}`,
-            repairActions: [action]
-          });
-          repairActions.push(action);
-        }
+            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in ${sys.type} root: ${sys.path}/${entry.name}${rootEntryHint ? ` (${rootEntryHint})` : ""}`
+          }, repairAction("module-shape", `akan repair module-shape --app ${sys.name}`, `Review ${sys.type} root shape and remove or move the unknown entry.`, false));
       }
     }
     const agentDrift = await AkanContextAnalyzer.#agentGuideDrift(workspace);
-    if (agentDrift) {
-      const action = repairAction("generated", "akan agent install agents-md", agentDrift.hint, true);
-      diagnostics.push({
-        severity: "warning",
-        code: agentDrift.code,
-        path: "AGENTS.md",
-        message: agentDrift.message,
-        repairActions: [action]
-      });
-      repairActions.push(action);
-    }
+    if (agentDrift)
+      report({ severity: "warning", code: agentDrift.code, path: "AGENTS.md", message: agentDrift.message }, repairAction("generated", "akan agent install agents-md", agentDrift.hint, true));
     for (const sys of [...context.apps, ...context.libs]) {
       for (const module of sys.modules) {
-        if (!module.abstract.exists) {
-          const action = repairAction("module-shape", `akan repair module-shape --app ${sys.name} --module ${module.name}`, "Create the missing module abstract or inspect required source files.", false);
-          diagnostics.push({
+        const moduleShapeCommand = `akan repair module-shape --app ${sys.name} --module ${module.name}`;
+        if (!module.abstract.exists)
+          report({
             severity: strict ? "error" : "warning",
             code: "module-abstract-missing",
             path: module.abstract.path,
-            message: `${capitalize(module.kind)} module ${sys.name}:${module.name} should include ${module.abstract.path}`,
-            repairActions: [action]
-          });
-          repairActions.push(action);
-        }
+            message: `${capitalize(module.kind)} module ${sys.name}:${module.name} should include ${module.abstract.path}`
+          }, repairAction("module-shape", moduleShapeCommand, "Create the missing module abstract or inspect required source files.", false));
         const missingFiles = moduleShapeFiles(module).filter((filename) => !module.files.includes(filename));
-        if (missingFiles.length) {
-          const action = repairAction("module-shape", `akan repair module-shape --app ${sys.name} --module ${module.name}`, "Review missing required module source files.", false);
-          diagnostics.push({
+        if (missingFiles.length)
+          report({
             severity: "error",
             code: "module-shape-invalid",
             path: module.path,
-            message: `${capitalize(module.kind)} module ${sys.name}:${module.name} is missing required files: ${missingFiles.join(", ")}`,
-            repairActions: [action]
-          });
-          repairActions.push(action);
-        }
+            message: `${capitalize(module.kind)} module ${sys.name}:${module.name} is missing required files: ${missingFiles.join(", ")}`
+          }, repairAction("module-shape", moduleShapeCommand, "Review missing required module source files.", false));
         if (module.kind !== "service" && module.files.includes(`${module.name}.dictionary.ts`)) {
           const constantPath = path.join(workspace.workspaceRoot, module.path, `${module.name}.constant.ts`);
           const dictionaryPath = path.join(workspace.workspaceRoot, module.path, `${module.name}.dictionary.ts`);
@@ -478,15 +434,12 @@ class AkanContextAnalyzer {
             for (const fieldName of constantFieldNames(constantContent)) {
               if (new RegExp(`\\b${fieldName}\\s*:`).test(dictionaryContent))
                 continue;
-              const action = repairAction("dictionary", `akan repair dictionary --app ${sys.name} --module ${module.name}`, "Add missing dictionary labels for source constant fields.", false);
-              diagnostics.push({
+              report({
                 severity: "warning",
                 code: "dictionary-label-missing",
                 path: `${module.path}/${module.name}.dictionary.ts`,
-                message: `Dictionary labels for ${sys.name}:${module.name}.${fieldName} were not found.`,
-                repairActions: [action]
-              });
-              repairActions.push(action);
+                message: `Dictionary labels for ${sys.name}:${module.name}.${fieldName} were not found.`
+              }, repairAction("dictionary", `akan repair dictionary --app ${sys.name} --module ${module.name}`, "Add missing dictionary labels for source constant fields.", false));
             }
           }
         }
@@ -554,19 +507,16 @@ class AkanContextAnalyzer {
     const pushIndexDiagnostic = (indexPath, missing, stale, repairCommand) => {
       if (missing.length === 0 && stale.length === 0)
         return;
-      const action = repairAction("generated", repairCommand, "Regenerate the recipe index from the scanned recipes.", true);
       const parts = [
         missing.length > 0 ? `${missing.length} declared but unlisted (${missing.slice(0, 5).join(", ")})` : "",
         stale.length > 0 ? `${stale.length} listed but gone (${stale.slice(0, 5).join(", ")})` : ""
       ].filter(Boolean);
-      diagnostics.push({
+      report({
         severity: "error",
         code: "recipe-index-stale",
         path: indexPath,
-        message: `${indexPath} recipe index is out of date \u2014 ${parts.join("; ")}. Agents read this list as authoritative.`,
-        repairActions: [action]
-      });
-      repairActions.push(action);
+        message: `${indexPath} recipe index is out of date \u2014 ${parts.join("; ")}. Agents read this list as authoritative.`
+      }, repairAction("generated", repairCommand, "Regenerate the recipe index from the scanned recipes.", true));
     };
     const frameworkDeclared = declaredByImport.get("akanjs/ui") ?? new Set;
     if (frameworkDeclared.size > 0) {