@akanjs/devkit 2.3.9-rc.0 → 2.3.9-rc.10

package/aiEditor.test.ts

@@ -1,8 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import {
-  parseTypescriptFileBlocks,
-  preserveTypescriptResponseContent,
-} from "./aiEditor";
+import { parseTypescriptFileBlocks, preserveTypescriptResponseContent } from "./aiEditor";
 
 describe("parseTypescriptFileBlocks", () => {
   test("parses TypeScript file blocks with common fence variants", () => {
@@ -39,12 +36,9 @@ export const CarUnit = () => null;
 export const car = "car";
 \`\`\`
 `;
-    const nextContent =
-      "The generated file meets all specified requirements. No rewrite is necessary.";
+    const nextContent = "The generated file meets all specified requirements. No rewrite is necessary.";
 
-    expect(
-      preserveTypescriptResponseContent(previousContent, nextContent),
-    ).toBe(previousContent);
+    expect(preserveTypescriptResponseContent(previousContent, nextContent)).toBe(previousContent);
   });
 
   test("uses next code response when validation rewrites with parseable files", () => {
@@ -61,8 +55,6 @@ export const car = "updated";
 \`\`\`
 `;
 
-    expect(
-      preserveTypescriptResponseContent(previousContent, nextContent),
-    ).toBe(nextContent);
+    expect(preserveTypescriptResponseContent(previousContent, nextContent)).toBe(nextContent);
   });
 });

package/akanContext.ts

@@ -4,6 +4,15 @@ import { capitalize } from "akanjs/common";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import type { PackageJson } from "./types";
+import {
+  type GeneratedSyncState,
+  type RepairAction,
+  type WorkflowApplyReport,
+  type WorkflowPlan,
+  type WorkflowRunArtifact,
+  workflowRunArtifactPath,
+  workflowSyncDir,
+} from "./workflow";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -59,14 +68,115 @@ export interface AkanDiagnostic {
   code: string;
   message: string;
   path?: string;
+  repairActions?: RepairAction[];
+  scope?: "baseline" | "workflow" | "unknown";
+  context?: {
+    workflow?: string;
+    planPath?: string;
+    runId?: string;
+    target?: string;
+    paths?: string[];
+  };
+}
+
+export interface GeneratedFilesFreshness {
+  status: "fresh" | "stale" | "missing" | "unknown";
+  message: string;
+  refreshCommand: string;
+  verifyingCommands: string[];
+  targets?: {
+    target: string;
+    status: "fresh" | "stale" | "missing" | "unknown";
+    lastSyncedAt?: string;
+    runId?: string;
+    generatedFiles: string[];
+    reason: string;
+  }[];
 }
 
 export interface AkanDoctorResult {
   schemaVersion: 1;
+  repoName: string;
+  root: string;
   strict: boolean;
+  status: "passed" | "failed";
   diagnostics: AkanDiagnostic[];
+  generatedFiles: string[];
+  generatedFilesFreshness: GeneratedFilesFreshness;
+  validationCommands: string[];
+  repairActions: RepairAction[];
+  baselineDiagnostics?: AkanDiagnostic[];
+  workflowDiagnostics?: AkanDiagnostic[];
 }
 
+export type JsonRpcRequest = {
+  jsonrpc?: "2.0";
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+export type McpFraming = "content-length" | "newline";
+export type AkanMcpMode = "readonly" | "plan" | "apply";
+
+export type CursorMcpConfig = {
+  mcpServers?: Record<string, unknown>;
+};
+
+export const resourceList = [
+  { uri: "akan://docs/framework", name: "Akan framework guide", mimeType: "text/markdown" },
+  { uri: "akan://guidelines/framework", name: "Framework guideline", mimeType: "text/markdown" },
+  { uri: "akan://guidelines/modelSignal", name: "Model signal guideline", mimeType: "text/markdown" },
+  { uri: "akan://workspace/summary", name: "Workspace summary", mimeType: "application/json" },
+  { uri: "akan://workspace/apps", name: "Workspace apps", mimeType: "application/json" },
+  { uri: "akan://workspace/modules", name: "Workspace modules", mimeType: "application/json" },
+];
+
+export const cursorMcpConfigPath = ".cursor/mcp.json";
+
+const cursorWorkspaceFolder = "$" + "{workspaceFolder}";
+
+export const createAkanCursorMcpServer = (mode: AkanMcpMode = "readonly") => ({
+  type: "stdio",
+  command: "bash",
+  args: ["-lc", `cd "${cursorWorkspaceFolder}" && akan mcp --mode ${mode}`],
+});
+
+export const akanCursorMcpServer = createAkanCursorMcpServer();
+
+export const renderDoctorText = (result: AkanDoctorResult) => {
+  const lines = [`Akan doctor status: ${result.status}`];
+  if (result.diagnostics.length === 0) {
+    lines.push("", "No Akan workspace diagnostics found.");
+  } else {
+    lines.push(
+      "",
+      ...result.diagnostics.map((diagnostic) =>
+        [
+          `[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`,
+          diagnostic.path ? `  ${diagnostic.path}` : "",
+        ]
+          .filter(Boolean)
+          .join("\n"),
+      ),
+    );
+  }
+  lines.push(
+    "",
+    "Generated file freshness:",
+    `Status: ${result.generatedFilesFreshness.status}`,
+    result.generatedFilesFreshness.message,
+    `Refresh: ${result.generatedFilesFreshness.refreshCommand}`,
+    "",
+    "Repair actions:",
+    ...(result.repairActions.length ? result.repairActions.map((action) => `- ${action.command}`) : ["- none"]),
+    "",
+    "Validation commands:",
+    ...result.validationCommands.map((command) => `- ${command}`),
+  );
+  return `${lines.join("\n")}\n`;
+};
+
 export interface AkanContextOptions {
   app?: string | null;
   module?: string | null;
@@ -74,17 +184,69 @@ export interface AkanContextOptions {
 }
 
 const generatedFiles = [
-  "cnst.ts",
-  "db.ts",
-  "dict.ts",
-  "option.ts",
-  "sig.ts",
-  "srv.ts",
-  "st.ts",
-  "useClient.ts",
-  "useServer.ts",
+  "apps/*/client.ts",
+  "apps/*/server.ts",
+  "*/lib/cnst.ts",
+  "*/lib/db.ts",
+  "*/lib/dict.ts",
+  "*/lib/option.ts",
+  "*/lib/sig.ts",
+  "*/lib/srv.ts",
+  "*/lib/st.ts",
+  "*/lib/useClient.ts",
+  "*/lib/useServer.ts",
+  "*/lib/**/index.ts",
+  "*/ui/index.ts",
+  "*/webkit/index.ts",
+  "*/srvkit/index.ts",
+  "*/common/index.ts",
+];
+
+const validationCommands = [
+  "akan sync <app-or-lib>",
+  "akan lint <app-or-lib-or-pkg>",
+  "akan typecheck <app-name>",
+  "akan test <app-or-lib-or-pkg>",
+  "akan build <app-name>",
+  "akan doctor --strict --format json",
 ];
 
+const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
+  status: "unknown" as const,
+  message: "Run sync before validation so generated Akan files match the current source conventions.",
+  refreshCommand: "akan sync <app-or-lib>",
+  verifyingCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>"],
+};
+
+const repairAction = (
+  kind: RepairAction["kind"],
+  command: string,
+  reason: string,
+  safeToRun: boolean,
+): RepairAction => ({
+  kind,
+  command,
+  reason,
+  safeToRun,
+});
+
+const moduleShapeFiles = (module: AkanModuleContext) => {
+  if (module.kind === "service") {
+    return [`${module.name}.dictionary.ts`, `${module.name}.service.ts`, `${module.name}.signal.ts`];
+  }
+  if (module.kind === "scalar") return [`${module.name}.constant.ts`, `${module.name}.dictionary.ts`];
+  return [
+    `${module.name}.constant.ts`,
+    `${module.name}.dictionary.ts`,
+    `${module.name}.service.ts`,
+    `${module.name}.store.ts`,
+    `${module.name}.signal.ts`,
+  ];
+};
+
+const constantFieldNames = (content: string) =>
+  [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
+
 const appRootAllowFiles = new Set([
   "akan.app.json",
   "akan.config.ts",
@@ -136,6 +298,135 @@ const safeReadJson = async <T>(filePath: string) => {
   }
 };
 
+const isWorkflowPlan = (value: unknown): value is WorkflowPlan =>
+  typeof value === "object" &&
+  value !== null &&
+  "schemaVersion" in value &&
+  value.schemaVersion === 1 &&
+  "mode" in value &&
+  value.mode === "plan";
+
+const isWorkflowApplyReport = (value: unknown): value is WorkflowApplyReport =>
+  typeof value === "object" &&
+  value !== null &&
+  "schemaVersion" in value &&
+  value.schemaVersion === 1 &&
+  "mode" in value &&
+  (value.mode === "apply" || value.mode === "dry-run");
+
+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)) {
+    return [
+      ...artifact.changedFiles.map((file) => file.path),
+      ...artifact.generatedFiles.map((file) => file.path),
+      ...workflowPathsForPlan(artifact.plan),
+    ];
+  }
+  if ("mode" in artifact && artifact.mode === "validate" && artifact.plan) return workflowPathsForPlan(artifact.plan);
+  return [];
+};
+
+const loadWorkflowContextPaths = async (
+  workspace: WorkspaceExecutor,
+  runIdOrPlan: string | null,
+  changedFiles: string[],
+) => {
+  const paths = [...changedFiles];
+  if (!runIdOrPlan) return paths;
+  const inputPath = path.isAbsolute(runIdOrPlan) ? runIdOrPlan : path.join(workspace.workspaceRoot, runIdOrPlan);
+  const artifact =
+    (await safeReadJson<WorkflowRunArtifact | WorkflowPlan>(inputPath)) ??
+    (await safeReadJson<WorkflowRunArtifact>(path.join(workspace.workspaceRoot, workflowRunArtifactPath(runIdOrPlan))));
+  if (artifact && isWorkflowRunArtifact(artifact)) paths.push(...workflowPathsForArtifact(artifact));
+  return [...new Set(paths.filter(Boolean))];
+};
+
+const pathKey = (value: string) =>
+  value
+    .replaceAll("\\", "/")
+    .replaceAll("*", "")
+    .replace(/<[^>]+>/g, "")
+    .replace(/\/+/g, "/")
+    .replace(/^\/|\/$/g, "");
+
+const isWorkflowRelatedDiagnostic = (diagnostic: AkanDiagnostic, workflowPaths: string[]) => {
+  if (!diagnostic.path) return false;
+  const diagnosticPath = pathKey(diagnostic.path);
+  return workflowPaths.some((workflowPath) => {
+    const candidate = pathKey(workflowPath);
+    if (!candidate) return false;
+    return (
+      diagnosticPath.startsWith(candidate) || candidate.startsWith(diagnosticPath) || diagnosticPath.includes(candidate)
+    );
+  });
+};
+
+const readGeneratedSyncStates = async (workspace: WorkspaceExecutor) => {
+  const syncDir = path.join(workspace.workspaceRoot, workflowSyncDir);
+  const entries = await safeReadDir(syncDir);
+  const states = await Promise.all(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => safeReadJson<GeneratedSyncState>(path.join(syncDir, entry.name))),
+  );
+  return states.filter(
+    (state): state is GeneratedSyncState =>
+      !!state && state.schemaVersion === 1 && typeof state.target === "string" && typeof state.syncedAt === "string",
+  );
+};
+
+const generatedFreshnessFromStates = async (workspace: WorkspaceExecutor): Promise<GeneratedFilesFreshness> => {
+  const states = await readGeneratedSyncStates(workspace);
+  if (states.length === 0) return unknownGeneratedFilesFreshness;
+  const targets = states
+    .sort((a, b) => a.target.localeCompare(b.target))
+    .map((state) => ({
+      target: state.target,
+      status: state.status === "passed" ? ("fresh" as const) : ("stale" as const),
+      lastSyncedAt: state.syncedAt,
+      runId: state.runId,
+      generatedFiles: state.generatedFiles.map((file) => file.path),
+      reason:
+        state.status === "passed"
+          ? `Generated files were refreshed by ${state.command}.`
+          : `Last generated repair command failed: ${state.command}.`,
+    }));
+  const lastFresh = targets
+    .filter((target) => target.status === "fresh" && target.lastSyncedAt)
+    .sort((a, b) => (b.lastSyncedAt ?? "").localeCompare(a.lastSyncedAt ?? ""))[0];
+  return {
+    status: targets.some((target) => target.status === "fresh") ? "fresh" : "stale",
+    message: lastFresh
+      ? `Generated files were refreshed for ${lastFresh.target} at ${lastFresh.lastSyncedAt}.`
+      : "Generated sync state exists, but the last recorded repair did not pass.",
+    refreshCommand: "akan sync <app-or-lib>",
+    verifyingCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>"],
+    targets,
+  };
+};
+
 const parseAbstractSummary = (
   relativePath: string,
   content: string | null,
@@ -283,28 +574,50 @@ export class AkanContextAnalyzer {
       libs,
       pkgs,
       generatedFiles,
-      validationCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>", "akan start <app-name>"],
+      validationCommands,
     };
   }
 
   static async doctor(
     workspace: WorkspaceExecutor,
-    { strict = false }: { strict?: boolean } = {},
+    {
+      strict = false,
+      runIdOrPlan = null,
+      changedFiles = [],
+    }: { strict?: boolean; runIdOrPlan?: string | null; changedFiles?: string[] } = {},
   ): Promise<AkanDoctorResult> {
     const context = await AkanContextAnalyzer.analyze(workspace);
+    const workflowPaths = await loadWorkflowContextPaths(workspace, runIdOrPlan, changedFiles);
     const diagnostics: AkanDiagnostic[] = [];
+    const repairActions: RepairAction[] = [
+      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,
+      ),
+    ];
 
     for (const app of context.apps) {
       const appPath = path.join(workspace.workspaceRoot, app.path);
       for (const entry of await safeReadDir(appPath)) {
         const allowed = entry.isDirectory() ? appRootAllowDirs.has(entry.name) : appRootAllowFiles.has(entry.name);
         if (!allowed) {
+          const action = repairAction(
+            "module-shape",
+            `akan repair module-shape --app ${app.name}`,
+            "Review app root shape and remove or move the unknown entry.",
+            false,
+          );
           diagnostics.push({
-            severity: "warning",
+            severity: "error",
             code: "app-root-unknown-entry",
             path: `${app.path}/${entry.name}`,
             message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in app root: ${app.path}/${entry.name}`,
+            repairActions: [action],
           });
+          repairActions.push(action);
         }
       }
     }
@@ -312,21 +625,102 @@ export class AkanContextAnalyzer {
     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({
             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,
+          );
+          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`);
+          const [constantContent, dictionaryContent] = await Promise.all([
+            safeReadText(constantPath),
+            safeReadText(dictionaryPath),
+          ]);
+          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,
+              );
+              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);
+            }
+          }
         }
       }
     }
 
-    return { schemaVersion: 1, strict, diagnostics };
+    const scopedDiagnostics = diagnostics.map((diagnostic) => ({
+      ...diagnostic,
+      scope: workflowPaths.length
+        ? isWorkflowRelatedDiagnostic(diagnostic, workflowPaths)
+          ? ("workflow" as const)
+          : ("baseline" as const)
+        : diagnostic.scope,
+      context: workflowPaths.length ? { ...diagnostic.context, paths: workflowPaths } : diagnostic.context,
+    }));
+    const workflowDiagnostics = scopedDiagnostics.filter((diagnostic) => diagnostic.scope === "workflow");
+    const baselineDiagnostics = scopedDiagnostics.filter((diagnostic) => diagnostic.scope === "baseline");
+    return {
+      schemaVersion: 1,
+      repoName: context.repoName,
+      root: context.root,
+      strict,
+      status: scopedDiagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed",
+      diagnostics: scopedDiagnostics,
+      generatedFiles: context.generatedFiles,
+      generatedFilesFreshness: await generatedFreshnessFromStates(workspace),
+      validationCommands: context.validationCommands,
+      repairActions,
+      ...(workflowPaths.length ? { baselineDiagnostics, workflowDiagnostics } : {}),
+    };
   }
 
-  static findModules(context: AkanWorkspaceContext, moduleName?: string | null) {
-    const modules = [...context.apps, ...context.libs].flatMap((sys) => sys.modules);
+  static findModules(
+    context: AkanWorkspaceContext,
+    moduleName?: string | null,
+    { app = null }: { app?: string | null } = {},
+  ) {
+    const modules = [...context.apps, ...context.libs]
+      .filter((sys) => !app || sys.name === app)
+      .flatMap((sys) => sys.modules);
     return moduleName
       ? modules.filter((module) => module.name === moduleName || module.folderName === moduleName)
       : modules;

package/akanMcpContract.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { createAkanValidationContract } from "./akanMcpContract";
+
+describe("createAkanValidationContract", () => {
+  test("exposes reference-first tooling rollout gate semantics", () => {
+    const contract = createAkanValidationContract();
+
+    expect(contract.toolingRolloutGate).toMatchObject({
+      schemaVersion: 1,
+      strategy: "reference-first-dependency-later",
+    });
+    expect(contract.toolingRolloutGate.candidates).toContainEqual(
+      expect.objectContaining({
+        packageName: "typescript",
+        status: "allowed",
+      }),
+    );
+    expect(contract.toolingRolloutGate.candidates).toContainEqual(
+      expect.objectContaining({
+        packageName: "@ttsc/graph",
+        status: "reference-only",
+      }),
+    );
+  });
+
+  test("keeps dependency adoption gated by package and source-body constraints", () => {
+    const contract = createAkanValidationContract();
+
+    expect(contract.toolingRolloutGate.gateConditions).toContain(
+      "Works in Bun runtime and published package artifacts.",
+    );
+    expect(contract.toolingRolloutGate.gateConditions).toContain("Does not break dist/pkgs package verification.");
+    expect(contract.toolingRolloutGate.gateConditions).toContain(
+      "Does not move MCP responses toward returning source bodies.",
+    );
+  });
+});