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

package/akanContext.ts

@@ -1,6 +1,6 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
-import { capitalize } from "akanjs/common";
+import { capitalize, isRecord } from "akanjs/common";
 import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
@@ -12,6 +12,7 @@ import {
   type WorkflowApplyReport,
   type WorkflowPlan,
   type WorkflowRunArtifact,
+  workflowPathsForPlan,
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
@@ -122,8 +123,7 @@ export type JsonRpcRequest = {
 export type McpFraming = "content-length" | "newline";
 export type AkanMcpMode = "readonly" | "plan" | "apply";
 
-// Coding-agent tools that can host the Akan MCP server. Cursor and Claude Code both read a JSON
-// `mcpServers` map; Codex reads a TOML `[mcp_servers.<name>]` table.
+// Cursor and Claude Code read a JSON `mcpServers` map; Codex reads a TOML `[mcp_servers.<name>]` table.
 export type AkanMcpInstallTarget = "cursor" | "claude" | "codex";
 
 export type CursorMcpConfig = {
@@ -132,11 +132,6 @@ export type CursorMcpConfig = {
 
 export const guidelineResourceUri = (name: string) => `akan://guidelines/${name}`;
 
-/**
- * Resources that exist whatever the workspace holds. The guideline entries are **not** here: they are
- * one per directory under `cli/guidelines/`, and a hardcoded pair listed 2 of 31 while `readResource`
- * threw on the other 29. `buildResourceList` is the only place the two halves meet.
- */
 const staticResourceList = [
   { uri: "akan://docs/framework", name: "Akan framework guide", mimeType: "text/markdown" },
   { uri: "akan://workspace/summary", name: "Workspace summary", mimeType: "application/json" },
@@ -167,42 +162,35 @@ export const akanMcpInstallConfigPaths: Record<AkanMcpInstallTarget, string> = {
   codex: codexMcpConfigPath,
 };
 
-// `akan mcp` resolves the workspace from process.cwd(), so every launcher must run it from the
-// workspace root. Cursor expands its own ${workspaceFolder} variable. Claude Code does not guarantee
-// the server's cwd but sets CLAUDE_PROJECT_DIR in its environment, so we cd into that at runtime.
-// Codex inherits its own launch cwd (it also discovers .codex/config.toml from cwd), so it runs the
-// command directly and must be started from the workspace root.
+// `akan mcp` resolves the workspace from its cwd: Cursor expands ${workspaceFolder}, Claude Code only sets
+// CLAUDE_PROJECT_DIR (its cwd is not guaranteed), and Codex runs from its own launch cwd.
 const cursorWorkspaceFolder = "$" + "{workspaceFolder}";
 const claudeProjectDir = "$CLAUDE_PROJECT_DIR";
 
 const akanMcpCommand = (mode: AkanMcpMode, { cd }: { cd?: string } = {}) =>
   cd ? `cd "${cd}" && akan mcp --mode ${mode}` : `akan mcp --mode ${mode}`;
 
-export const createAkanCursorMcpServer = (mode: AkanMcpMode = "readonly") => ({
+const bashMcpServer = (mode: AkanMcpMode, cd: string) => ({
   type: "stdio",
   command: "bash",
-  args: ["-lc", akanMcpCommand(mode, { cd: cursorWorkspaceFolder })],
+  args: ["-lc", akanMcpCommand(mode, { cd })],
 });
 
-export const createAkanClaudeMcpServer = (mode: AkanMcpMode = "readonly") => ({
-  type: "stdio",
-  command: "bash",
-  args: ["-lc", akanMcpCommand(mode, { cd: claudeProjectDir })],
-});
+export const createAkanCursorMcpServer = (mode: AkanMcpMode = "readonly") => bashMcpServer(mode, cursorWorkspaceFolder);
+
+export const createAkanClaudeMcpServer = (mode: AkanMcpMode = "readonly") => bashMcpServer(mode, claudeProjectDir);
 
-// JSON-config targets (Cursor, Claude Code) share the same `mcpServers` entry shape.
 export const createAkanMcpServer = (target: "cursor" | "claude", mode: AkanMcpMode = "readonly") =>
   target === "cursor" ? createAkanCursorMcpServer(mode) : createAkanClaudeMcpServer(mode);
 
 export const akanCursorMcpServer = createAkanCursorMcpServer();
 
-// Codex config is TOML and we have no TOML serializer, so we build the `[mcp_servers.akan]` table as text.
+// No TOML serializer is bundled, so the `[mcp_servers.akan]` table is written as text.
 export const codexMcpServerTableHeader = "[mcp_servers.akan]";
 export const createAkanCodexMcpServerBlock = (mode: AkanMcpMode = "readonly") =>
   `${codexMcpServerTableHeader}\ncommand = "bash"\nargs = ["-lc", "${akanMcpCommand(mode)}"]\n`;
 
-// A TOML table runs from its header until the next top-level `[header]` or EOF. We upsert only the
-// akan table and preserve everything else in the file, mirroring the JSON merge behavior.
+// A TOML table runs from its header until the next top-level `[header]` or EOF.
 const codexAkanTablePattern = /^\[mcp_servers\.akan\][^\n]*\n(?:(?!\[)[^\n]*(?:\n|$))*/m;
 
 export const upsertCodexMcpServerBlock = (
@@ -331,29 +319,12 @@ const moduleShapeFiles = (module: AkanModuleContext) => {
 const constantFieldNames = (content: string) =>
   [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
 
-const safeReadDir = async (dirPath: string) => {
-  try {
-    return (await readdir(dirPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
-  } catch {
-    return [];
-  }
-};
+const safeReadDir = async (dirPath: string) =>
+  (await readdir(dirPath, { withFileTypes: true }).catch(() => [])).sort((a, b) => a.name.localeCompare(b.name));
 
-const safeReadText = async (filePath: string) => {
-  try {
-    return await FileSys.readText(filePath);
-  } catch {
-    return null;
-  }
-};
+const safeReadText = (filePath: string) => FileSys.readText(filePath).catch(() => null);
 
-const safeReadJson = async <T>(filePath: string) => {
-  try {
-    return await FileSys.readJson<T>(filePath);
-  } catch {
-    return null;
-  }
-};
+const safeReadJson = <T>(filePath: string) => FileSys.readJson<T>(filePath).catch(() => null);
 
 const isWorkflowPlan = (value: unknown): value is WorkflowPlan =>
   typeof value === "object" &&
@@ -361,7 +332,15 @@ const isWorkflowPlan = (value: unknown): value is WorkflowPlan =>
   "schemaVersion" in value &&
   value.schemaVersion === 1 &&
   "mode" in value &&
-  value.mode === "plan";
+  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");
+
+const isPathList = (value: unknown) =>
+  Array.isArray(value) && value.every((file) => isRecord(file) && typeof file.path === "string");
 
 const isWorkflowApplyReport = (value: unknown): value is WorkflowApplyReport =>
   typeof value === "object" &&
@@ -369,29 +348,17 @@ const isWorkflowApplyReport = (value: unknown): value is WorkflowApplyReport =>
   "schemaVersion" in value &&
   value.schemaVersion === 1 &&
   "mode" in value &&
-  (value.mode === "apply" || value.mode === "dry-run");
+  (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);
 
 const isWorkflowRunArtifact = (value: unknown): value is WorkflowRunArtifact =>
   typeof value === "object" && value !== null && "schemaVersion" in value && value.schemaVersion === 1;
 
-const planInputString = (plan: WorkflowPlan, key: string) => {
-  const value = plan.inputs[key];
-  return typeof value === "string" ? value : "";
-};
-
-const expandWorkflowTarget = (target: string, plan: WorkflowPlan) => {
-  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);
-};
-
-const workflowPathsForPlan = (plan: WorkflowPlan) =>
-  plan.predictedChanges.map((change) => expandWorkflowTarget(change.target, plan));
-
 const workflowPathsForArtifact = (artifact: WorkflowRunArtifact) => {
   if (isWorkflowPlan(artifact)) return workflowPathsForPlan(artifact);
   if (isWorkflowApplyReport(artifact)) {
@@ -401,7 +368,8 @@ const workflowPathsForArtifact = (artifact: WorkflowRunArtifact) => {
       ...workflowPathsForPlan(artifact.plan),
     ];
   }
-  if ("mode" in artifact && artifact.mode === "validate" && artifact.plan) return workflowPathsForPlan(artifact.plan);
+  if ("mode" in artifact && artifact.mode === "validate" && isWorkflowPlan(artifact.plan))
+    return workflowPathsForPlan(artifact.plan);
   return [];
 };
 
@@ -635,9 +603,7 @@ export class AkanContextAnalyzer {
     };
   }
 
-  // The conventions in AGENTS.md ship with the package, but nothing re-renders them on `bun update` — a workspace
-  // keeps whichever release wrote its block until someone re-runs the install. Comparing the stamp against the
-  // running devkit is the only signal that the guide an agent is reading is older than the framework it describes.
+  // Nothing re-renders the AGENTS.md block on `bun update`, so the version stamp is the only staleness signal.
   static async #agentGuideDrift(workspace: WorkspaceExecutor) {
     const installed = await readDevkitVersion();
     if (!installed) return null;
@@ -679,6 +645,10 @@ export class AkanContextAnalyzer {
         true,
       ),
     ];
+    const report = (diagnostic: AkanDiagnostic, action: RepairAction) => {
+      diagnostics.push({ ...diagnostic, repairActions: [action] });
+      repairActions.push(action);
+    };
 
     for (const sys of [...context.apps, ...context.libs]) {
       const sysPath = path.join(workspace.workspaceRoot, sys.path);
@@ -687,73 +657,60 @@ export class AkanContextAnalyzer {
         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,
+        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}`,
+            },
+            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({
-            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);
-        }
       }
     }
 
     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,
+        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}`,
+            },
+            repairAction(
+              "module-shape",
+              moduleShapeCommand,
+              "Create the missing module abstract or inspect required source files.",
+              false,
+            ),
           );
-          diagnostics.push({
-            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);
-        }
         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,
+        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(", ")}`,
+            },
+            repairAction("module-shape", moduleShapeCommand, "Review missing required module source files.", false),
           );
-          diagnostics.push({
-            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);
-        }
         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`);
@@ -764,28 +721,27 @@ export class AkanContextAnalyzer {
           if (constantContent && dictionaryContent) {
             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,
+              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.`,
+                },
+                repairAction(
+                  "dictionary",
+                  `akan repair dictionary --app ${sys.name} --module ${module.name}`,
+                  "Add missing dictionary labels for source constant fields.",
+                  false,
+                ),
               );
-              diagnostics.push({
-                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);
             }
           }
         }
       }
     }
 
-    // Recipe SSOT advisory (항상 warning — 차단하지 않음): recipe 지문이 인라인 className 으로 재작성된
-    // 곳의 추이를 보이게 한다. 유입이 실제로 재발하면 그때 lint 승격을 검토한다 — 증거 기반 에스컬레이션.
+    //* Advisory only (warning): promoted to lint only if inline re-authoring actually recurs.
     for (const sys of [...context.apps, ...context.libs]) {
       const sources = await collectRecipeSources(path.join(workspace.workspaceRoot, sys.path, "ui"), "ui");
       if (sources.length === 0) continue;
@@ -815,11 +771,7 @@ export class AkanContextAnalyzer {
       });
     }
 
-    // Recipe index freshness. The recipe indexes are generated and read as authoritative — a recipe missing
-    // from its index gets re-invented inline, and a name lingering in it gets imported and fails. The index is
-    // split by ownership: the root AGENTS.md `## Recipes` lists framework recipes only, and every app/lib lists
-    // what it may additionally import in its own AGENTS.md `## Recipes In Scope`. Doctor never writes, so this
-    // is the check that catches a *committed* stale index (lint/sync self-heal the working tree instead).
+    // Doctor never writes, so this is what catches a committed stale recipe index (lint and sync self-heal the tree).
     const scanNames = async (uiDirPath: string, basename?: string) =>
       new Set(scanRecipes(await collectRecipeSources(uiDirPath, "ui", basename)).map((info) => info.name));
     const declaredByImport = new Map<string, Set<string>>();
@@ -853,24 +805,19 @@ export class AkanContextAnalyzer {
     };
     const pushIndexDiagnostic = (indexPath: string, missing: string[], stale: string[], repairCommand: string) => {
       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({
-        severity: "error",
-        code: "recipe-index-stale",
-        path: indexPath,
-        message: `${indexPath} recipe index is out of date — ${parts.join("; ")}. Agents read this list as authoritative.`,
-        repairActions: [action],
-      });
-      repairActions.push(action);
+      report(
+        {
+          severity: "error",
+          code: "recipe-index-stale",
+          path: indexPath,
+          message: `${indexPath} recipe index is out of date — ${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<string>();
     if (frameworkDeclared.size > 0) {

package/akanMcpContract.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
-import { AkanContextAnalyzer, type AkanModuleContext } from "./akanContext";
+import { isRecord } from "akanjs/common";
+import { AkanContextAnalyzer, type AkanDiagnostic, type AkanModuleContext } from "./akanContext";
 import type { Workspace } from "./commandDecorators";
 import type {
   AkanContextEvidence,
@@ -107,9 +108,6 @@ const inspectAkanContextInputSchema = {
   required: ["question", "draft", "review", "request"],
 };
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
 const slugPart = (value: unknown) =>
   typeof value === "string"
     ? value
@@ -124,12 +122,6 @@ const optionalString = (args: Record<string, unknown>, key: string) => {
   return typeof value === "string" && value ? value : undefined;
 };
 
-const nestedStringArg = (args: Record<string, unknown>, key: string) => {
-  const value = args[key];
-  if (typeof value !== "string" || !value) throw new Error(`MCP tool argument "${key}" is required.`);
-  return value;
-};
-
 const isInspectAkanContextRequestType = (value: unknown): value is InspectAkanContextRequest["type"] =>
   typeof value === "string" && inspectAkanContextRequestTypes.includes(value as InspectAkanContextRequest["type"]);
 
@@ -192,49 +184,30 @@ export const inspectAkanContextPropsArg = (args: Record<string, unknown>): Inspe
   if (!isInspectAkanContextRequestType(args.request.type)) {
     throw new Error('MCP tool argument "request.type" must be a supported inspect_akan_context request type.');
   }
-  const draft = { reason: nestedStringArg(args.draft, "reason"), type: args.draft.type };
+  const base = { question, draft: { reason: stringArg(args.draft, "reason"), type: args.draft.type }, review };
   const request = args.request;
-  if (request.type === "workspaceOverview") return { question, draft, review, request: { type: request.type } };
+  if (request.type === "workspaceOverview") return { ...base, request: { type: request.type } };
   if (request.type === "moduleContext")
     return {
-      question,
-      draft,
-      review,
-      request: {
-        type: request.type,
-        app: nestedStringArg(request, "app"),
-        module: nestedStringArg(request, "module"),
-      },
+      ...base,
+      request: { type: request.type, app: stringArg(request, "app"), module: stringArg(request, "module") },
     };
   if (request.type === "fieldInsertionContext")
     return {
-      question,
-      draft,
-      review,
+      ...base,
       request: {
         type: request.type,
-        app: nestedStringArg(request, "app"),
-        module: nestedStringArg(request, "module"),
-        field: nestedStringArg(request, "field"),
-        fieldType: nestedStringArg(request, "fieldType"),
+        app: stringArg(request, "app"),
+        module: stringArg(request, "module"),
+        field: stringArg(request, "field"),
+        fieldType: stringArg(request, "fieldType"),
       },
     };
   if (request.type === "workflowDiagnostics")
-    return {
-      question,
-      draft,
-      review,
-      request: { type: request.type, runIdOrPlan: nestedStringArg(request, "runIdOrPlan") },
-    };
+    return { ...base, request: { type: request.type, runIdOrPlan: stringArg(request, "runIdOrPlan") } };
   return {
-    question,
-    draft,
-    review,
-    request: {
-      type: "escape",
-      reason: nestedStringArg(request, "reason"),
-      nextStep: optionalString(request, "nextStep"),
-    },
+    ...base,
+    request: { type: "escape", reason: stringArg(request, "reason"), nextStep: optionalString(request, "nextStep") },
   };
 };
 
@@ -391,11 +364,7 @@ export const applyMcpTools: McpToolDefinition[] = [
   },
 ];
 
-/**
- * `guidelineNames` fills the `get_guideline` enum. Without it the argument is a bare string and a model
- * has to guess one of the ~30 directory names, which it cannot see from here — the names are a
- * filesystem listing, so they can only arrive from a caller that already read it.
- */
+// `guidelineNames` fills the `get_guideline` enum; they are a filesystem listing only the caller has read.
 export const listAkanMcpTools = (
   mode: "readonly" | "plan" | "apply" = "readonly",
   { guidelineNames = [] }: { guidelineNames?: readonly string[] } = {},
@@ -523,29 +492,19 @@ export const inspectAkanContext = async (
       strict: true,
       runIdOrPlan: workspacePath(workspace, props.request.runIdOrPlan),
     });
+    const toWorkflowDiagnostic = (
+      { severity, code, message, scope }: AkanDiagnostic,
+      context: AkanDiagnostic["context"],
+    ): WorkflowDiagnostic => ({ severity, code, message, scope, context });
     const baselineSummary = createWorkflowBaselineSummary(
-      (doctor.baselineDiagnostics ?? []).map(
-        (diagnostic): WorkflowDiagnostic => ({
-          severity: diagnostic.severity,
-          code: diagnostic.code,
-          message: diagnostic.message,
-          scope: diagnostic.scope,
-          context: diagnostic.context,
-        }),
-      ),
+      (doctor.baselineDiagnostics ?? []).map((diagnostic) => toWorkflowDiagnostic(diagnostic, diagnostic.context)),
       { detailsIncluded: false },
     );
     diagnostics.push(
-      ...(doctor.workflowDiagnostics ?? doctor.diagnostics).map(
-        (diagnostic): WorkflowDiagnostic => ({
-          severity: diagnostic.severity,
-          code: diagnostic.code,
-          message: diagnostic.message,
-          scope: diagnostic.scope,
-          context: {
-            ...diagnostic.context,
-            ...(diagnostic.path ? { paths: [diagnostic.path] } : {}),
-          },
+      ...(doctor.workflowDiagnostics ?? doctor.diagnostics).map((diagnostic) =>
+        toWorkflowDiagnostic(diagnostic, {
+          ...diagnostic.context,
+          ...(diagnostic.path ? { paths: [diagnostic.path] } : {}),
         }),
       ),
     );
@@ -574,15 +533,11 @@ export const inspectAkanContext = async (
     );
   }
 
+  const moduleRequest =
+    props.request.type === "moduleContext" || props.request.type === "fieldInsertionContext" ? props.request : null;
   const context = await AkanContextAnalyzer.analyze(workspace, {
-    app:
-      props.request.type === "moduleContext" || props.request.type === "fieldInsertionContext"
-        ? props.request.app
-        : null,
-    module:
-      props.request.type === "moduleContext" || props.request.type === "fieldInsertionContext"
-        ? props.request.module
-        : null,
+    app: moduleRequest?.app ?? null,
+    module: moduleRequest?.module ?? null,
     includeAbstractContent: false,
   });
 

package/appSelectionMemory.ts

@@ -5,10 +5,7 @@ interface StoredSelection {
   apps: string[];
 }
 
-/**
- * The apps the last interactive pick chose, so `akan start` + Enter repeats a multi-app session instead
- * of re-ticking it. Advisory only: a missing, unreadable or stale file just means nothing is pre-ticked.
- */
+// Advisory only: a missing, unreadable or stale file just means nothing is pre-ticked.
 export class AppSelectionMemory {
   static pathIn(workspaceRoot: string) {
     return path.join(workspaceRoot, "local", ".akan", "lastStart.json");

package/applicationBuildReporter.ts

@@ -1,3 +1,5 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
 import { Logger } from "akanjs/common";
 
 export interface ApplicationBuildPhaseResult {
@@ -35,12 +37,12 @@ export class ApplicationBuildReporter {
     Logger.rawLog(`Done in ${ApplicationBuildReporter.formatDuration(result.durationMs)}`);
   }
 
-  static formatError(error: unknown): string {
+  static formatError(error: unknown, workspaceRoot = process.cwd()): string {
     if (error instanceof AggregateError) {
       const nestedMessages = error.errors
         .map(
           (nestedError, index) =>
-            ApplicationBuildReporter.formatError(nestedError).trim() || `Unknown error ${index + 1}`,
+            ApplicationBuildReporter.formatError(nestedError, workspaceRoot).trim() || `Unknown error ${index + 1}`,
         )
         .map((message) => message.replace(/^/gm, "  "))
         .join("\n");
@@ -48,13 +50,43 @@ export class ApplicationBuildReporter {
       return nestedMessages ? `${error.message}\n${nestedMessages}` : error.message;
     }
     if (error instanceof Error) {
-      const causeMessage = error.cause ? `\nCaused by: ${ApplicationBuildReporter.formatError(error.cause)}` : "";
-      return `${error.message}${causeMessage}`;
+      const causeMessage = error.cause
+        ? `\nCaused by: ${ApplicationBuildReporter.formatError(error.cause, workspaceRoot)}`
+        : "";
+      return `${ApplicationBuildReporter.#withLocation(error.message, error, workspaceRoot)}${causeMessage}`;
     }
-    if (typeof error === "object" && error !== null && "message" in error) return String(error.message);
+    if (typeof error === "object" && error !== null && "message" in error)
+      return ApplicationBuildReporter.#withLocation(String(error.message), error, workspaceRoot);
     return String(error);
   }
 
+  static #withLocation(message: string, error: object, workspaceRoot: string): string {
+    const { position } = error as { position?: { file: string; line: number; column: number } | null };
+    if (!position?.file) return message;
+    const file = ApplicationBuildReporter.#relativeToWorkspace(position.file, workspaceRoot);
+    const location = position.line > 0 ? `${file}:${position.line}:${position.column}` : file;
+    return message.includes(location) ? message : message.replace(/^.*/, (headline) => `${headline} (${location})`);
+  }
+
+  // Bun names the file by its realpath, so a workspace root reached through a symlink is matched by its own too.
+  static #relativeToWorkspace(file: string, workspaceRoot: string): string {
+    if (!path.isAbsolute(file)) return file;
+    for (const root of [workspaceRoot, ApplicationBuildReporter.#realpathOf(workspaceRoot)]) {
+      const relative = path.relative(root, file);
+      if (!relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+        return relative.replaceAll(path.sep, "/");
+    }
+    return file;
+  }
+
+  static #realpathOf(dir: string): string {
+    try {
+      return realpathSync(dir);
+    } catch {
+      return dir;
+    }
+  }
+
   static formatDuration(ms: number): string {
     if (ms < 1000) return `${ms}ms`;
     if (ms < 60_000) return `${Math.round(ms / 100) / 10}s`;