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

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,7 @@ 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 { RepairAction } from "./workflow";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -59,14 +60,94 @@ export interface AkanDiagnostic {
   code: string;
   message: string;
   path?: string;
+  repairActions?: RepairAction[];
 }
 
 export interface AkanDoctorResult {
   schemaVersion: 1;
+  repoName: string;
+  root: string;
   strict: boolean;
+  status: "passed" | "failed";
   diagnostics: AkanDiagnostic[];
+  generatedFiles: string[];
+  generatedFilesFreshness: {
+    status: "unknown";
+    message: string;
+    refreshCommand: string;
+    verifyingCommands: string[];
+  };
+  validationCommands: string[];
+  repairActions: RepairAction[];
 }
 
+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:",
+    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 +155,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 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",
@@ -283,7 +416,7 @@ export class AkanContextAnalyzer {
       libs,
       pkgs,
       generatedFiles,
-      validationCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>", "akan start <app-name>"],
+      validationCommands,
     };
   }
 
@@ -293,18 +426,35 @@ export class AkanContextAnalyzer {
   ): Promise<AkanDoctorResult> {
     const context = await AkanContextAnalyzer.analyze(workspace);
     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,17 +462,80 @@ 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 };
+    return {
+      schemaVersion: 1,
+      repoName: context.repoName,
+      root: context.root,
+      strict,
+      status: diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed",
+      diagnostics,
+      generatedFiles: context.generatedFiles,
+      generatedFilesFreshness,
+      validationCommands: context.validationCommands,
+      repairActions,
+    };
   }
 
   static findModules(context: AkanWorkspaceContext, moduleName?: string | null) {

package/capacitorApp.test.ts

@@ -130,16 +130,14 @@ describe("materializeCapacitorConfig", () => {
 describe("root capacitor config helpers", () => {
   test("clears root configs before writing the temporary json config", async () => {
     const root = await makeTempRoot();
-    await Promise.all(
-      rootCapacitorConfigFilenames.map((file) => writeFile(path.join(root, file), `old ${file}\n`)),
-    );
+    await Promise.all(rootCapacitorConfigFilenames.map((file) => writeFile(path.join(root, file), `old ${file}\n`)));
 
-    await writeRootCapacitorConfig(root, "{\n  \"appId\": \"com.minimal.app\"\n}\n");
+    await writeRootCapacitorConfig(root, '{\n  "appId": "com.minimal.app"\n}\n');
 
     expect(await Bun.file(path.join(root, "capacitor.config.ts")).exists()).toBe(false);
     expect(await Bun.file(path.join(root, "capacitor.config.js")).exists()).toBe(false);
     expect(await Bun.file(path.join(root, "capacitor.config.json")).text()).toBe(
-      "{\n  \"appId\": \"com.minimal.app\"\n}\n",
+      '{\n  "appId": "com.minimal.app"\n}\n',
     );
 
     await clearRootCapacitorConfigs(root);
@@ -186,7 +184,9 @@ describe("iOS native run helpers", () => {
           },
         }),
       ),
-    ).toEqual([{ id: "11111111-2222-3333-4444-555555555555", name: "iPhone 16", kind: "simulator", state: "Shutdown" }]);
+    ).toEqual([
+      { id: "11111111-2222-3333-4444-555555555555", name: "iPhone 16", kind: "simulator", state: "Shutdown" },
+    ]);
   });
 
   test("builds xcodebuild destinations and output paths by target kind", () => {
@@ -198,7 +198,9 @@ describe("iOS native run helpers", () => {
     });
     expect(deviceCommand.xcodebuildArgs).toContain("id=device-1");
     expect(deviceCommand.xcodebuildArgs).toContain("App QA");
-    expect(deviceCommand.appPath).toBe("/repo/apps/minimal/ios/DerivedData/device-1/Build/Products/Debug-iphoneos/App.app");
+    expect(deviceCommand.appPath).toBe(
+      "/repo/apps/minimal/ios/DerivedData/device-1/Build/Products/Debug-iphoneos/App.app",
+    );
 
     const simulatorCommand = buildIosNativeRunCommand({
       appRoot: "/repo/apps/minimal",
@@ -212,7 +214,11 @@ describe("iOS native run helpers", () => {
 
   test("classifies iOS signing and device-state failures", () => {
     expect(classifyIosRunFailure("There are no accounts registered with Xcode").kind).toBe("apple-account");
-    expect(classifyIosRunFailure('Failed Registering Bundle Identifier: The app identifier "com.minimal.app" cannot be registered to your development team').kind).toBe("bundle-identifier");
+    expect(
+      classifyIosRunFailure(
+        'Failed Registering Bundle Identifier: The app identifier "com.minimal.app" cannot be registered to your development team',
+      ).kind,
+    ).toBe("bundle-identifier");
     expect(classifyIosRunFailure("No profiles for 'com.minimal.app' were found").kind).toBe("provisioning-profile");
     expect(classifyIosRunFailure("Developer Mode is disabled on this device").kind).toBe("device-state");
     expect(classifyIosRunFailure("arm64-apple-darwin20.0: error: unknown argument: '-index-store-path'").kind).toBe(

package/commandDecorators/command.ts

@@ -165,7 +165,7 @@ const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   );
 };
 
-const getInternalArgumentValue = async (
+export const getInternalArgumentValue = async (
   argMeta: InternalArgMeta,
   value: string | undefined,
   workspace: WorkspaceExecutor,
@@ -201,6 +201,7 @@ const getInternalArgumentValue = async (
     }
   } else if (sysType === "app") {
     if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
+    if (!value && appNames.length === 1 && appNames[0]) return AppExecutor.from(workspace, appNames[0]);
     const appName = await select<string>({ message: `Select the ${sysType} name`, choices: appNames });
     return AppExecutor.from(workspace, appName);
   } else if (sysType === "lib") {

package/commandDecorators/commandDecorators.test.ts

@@ -1,5 +1,7 @@
 import { afterEach, describe, expect, test } from "bun:test";
+import { AppExecutor, WorkspaceExecutor } from "../executors";
 import { App, getArgMetas, Lib, Module, Pkg, Sys, Workspace } from "./argMeta";
+import { getInternalArgumentValue } from "./command";
 import { command } from "./commandBuilder";
 import {
   assertUniqueDependencies,
@@ -127,6 +129,17 @@ describe("command helper metadata", () => {
     expect(commandHelp).toContain("[default: true]");
     expect(commandHelp).toContain("Fast, Full");
   });
+
+  test("resolves the only app without prompting for selection", async () => {
+    const workspace = new WorkspaceExecutor({ workspaceRoot: "/workspace", repoName: "repo" });
+    workspace.getExecs = async () => [["single-command-test-app"], [], []];
+
+    const app = await getInternalArgumentValue({ key: "", idx: 0, type: "App" }, undefined, workspace);
+
+    expect(app).toBeInstanceOf(AppExecutor);
+    expect(app.name).toBe("single-command-test-app");
+    expect(app.workspace).toBe(workspace);
+  });
 });
 
 describe("command helper dependency injection", () => {

package/executors.test.ts

@@ -143,11 +143,32 @@ describe("Executor filesystem helpers", () => {
       "Akan.js Workspace Rules",
     );
     expect(await readFile(path.join(root, "workspace/AGENTS.md"), "utf8")).toContain("sample Agent Guide");
+    expect(await readFile(path.join(root, "workspace/docs/AI-DEVELOPMENT.md"), "utf8")).toContain(
+      "AI Development Guide",
+    );
+    expect(await readFile(path.join(root, "workspace/docs/GENERATED.md"), "utf8")).toContain("Generated Akan Files");
     expect(await readFile(path.join(root, "workspace/biome.json"), "utf8")).toContain(
       "./node_modules/@akanjs/devkit/lint/no-import-client-functions.grit",
     );
   });
 
+  test("applies app sample signal test helpers", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+
+    await exec.applyTemplate({
+      basePath: "app",
+      template: "appSample",
+      dict: { appName: "demo" },
+      options: { libs: [] },
+    });
+
+    await expect(readFile(path.join(root, "app/lib/task/task.service.test.ts"), "utf8")).rejects.toThrow();
+    expect(await readFile(path.join(root, "app/lib/task/task.signal.spec.ts"), "utf8")).toContain("getCompletedTask");
+    expect(await readFile(path.join(root, "app/lib/task/task.signal.test.ts"), "utf8")).toContain("Task signal smoke");
+    expect(await readFile(path.join(root, "app/lib/task/task.document.ts"), "utf8")).toContain('action: "started"');
+  });
+
   test("copies static files from CLI templates", async () => {
     const root = await makeTempRoot();
     const exec = new Executor("fixture", root);

package/executors.ts

@@ -503,7 +503,7 @@ export class Executor {
   async writeFile(
     filePath: string,
     content: string | object,
-    { overwrite = true }: { overwrite?: boolean } = {},
+    { overwrite = true, silent = false }: { overwrite?: boolean; silent?: boolean } = {},
   ): Promise<FileContent> {
     const writePath = this.getPath(filePath);
     const dir = path.dirname(writePath);
@@ -521,7 +521,7 @@ export class Executor {
       }
     } else {
       await FileSys.writeText(writePath, contentStr);
-      this.logger.rawLog(chalk.green(`File Create: ${filePath}`));
+      if (!silent) this.logger.rawLog(chalk.green(`File Create: ${filePath}`));
     }
     return { filePath: writePath, content: contentStr };
   }
@@ -1357,14 +1357,15 @@ export class AppExecutor extends SysExecutor {
   getCommandEnv(env: Record<string, string> = {}): Record<string, string> {
     const basePort = 8282;
     const portOffset = WorkspaceExecutor.getBaseDevEnv().portOffset;
-    const PORT = basePort ? (basePort + portOffset).toString() : undefined;
+    const PORT = (basePort + portOffset).toString();
     const AKAN_PUBLIC_SERVER_PORT = portOffset ? (8282 + portOffset).toString() : undefined;
     return {
       ...process.env,
       AKAN_PUBLIC_APP_NAME: this.name,
       AKAN_WORKSPACE_ROOT: this.workspace.workspaceRoot,
       NODE_NO_WARNINGS: "1",
-      ...(PORT ? { PORT, AKAN_PUBLIC_CLIENT_PORT: PORT } : {}),
+      PORT,
+      AKAN_PUBLIC_CLIENT_PORT: PORT,
       ...(AKAN_PUBLIC_SERVER_PORT ? { AKAN_PUBLIC_SERVER_PORT } : {}),
       ...env,
     };

package/index.ts

@@ -36,3 +36,4 @@ export * from "./types";
 export * from "./ui";
 export * from "./uploadRelease";
 export * from "./useStdoutDimensions";
+export * from "./workflow";