@akanjs/devkit 2.3.11-rc.5 → 2.3.11-rc.7

package/akanContext.ts

@@ -119,6 +119,10 @@ 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.
+export type AkanMcpInstallTarget = "cursor" | "claude" | "codex";
+
 export type CursorMcpConfig = {
   mcpServers?: Record<string, unknown>;
 };
@@ -133,17 +137,79 @@ export const resourceList = [
 ];
 
 export const cursorMcpConfigPath = ".cursor/mcp.json";
+// Claude Code reads project-scoped MCP servers from `.mcp.json` at the workspace root.
+export const claudeMcpConfigPath = ".mcp.json";
+// Codex reads project-scoped config (trusted projects) from `.codex/config.toml`.
+export const codexMcpConfigPath = ".codex/config.toml";
+
+export const akanMcpInstallTargets: AkanMcpInstallTarget[] = ["cursor", "claude", "codex"];
+
+export const akanMcpInstallConfigPaths: Record<AkanMcpInstallTarget, string> = {
+  cursor: cursorMcpConfigPath,
+  claude: claudeMcpConfigPath,
+  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.
 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") => ({
   type: "stdio",
   command: "bash",
-  args: ["-lc", `cd "${cursorWorkspaceFolder}" && akan mcp --mode ${mode}`],
+  args: ["-lc", akanMcpCommand(mode, { cd: cursorWorkspaceFolder })],
+});
+
+export const createAkanClaudeMcpServer = (mode: AkanMcpMode = "readonly") => ({
+  type: "stdio",
+  command: "bash",
+  args: ["-lc", akanMcpCommand(mode, { cd: 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.
+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.
+const codexAkanTablePattern = /^\[mcp_servers\.akan\][^\n]*\n(?:(?!\[)[^\n]*(?:\n|$))*/m;
+
+export const upsertCodexMcpServerBlock = (
+  existing: string,
+  block: string,
+  { force = false }: { force?: boolean } = {},
+) => {
+  const nextBlock = block.endsWith("\n") ? block : `${block}\n`;
+  const match = existing.match(codexAkanTablePattern);
+  if (!match) {
+    if (!existing.trim()) return nextBlock;
+    return `${existing.replace(/\s*$/, "")}\n\n${nextBlock}`;
+  }
+  if (match[0].trim() === nextBlock.trim()) return existing;
+  if (!force)
+    throw new Error(`${codexMcpConfigPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
+  const start = match.index ?? 0;
+  const before = existing.slice(0, start);
+  const after = existing.slice(start + match[0].length);
+  // The matched table absorbed its trailing blank line, so re-insert one before any following table.
+  const separator = after && !after.startsWith("\n") ? "\n" : "";
+  return `${before}${nextBlock}${separator}${after}`;
+};
+
 export const renderDoctorText = (result: AkanDoctorResult) => {
   const lines = [`Akan doctor status: ${result.status}`];
   if (result.diagnostics.length === 0) {
@@ -189,7 +255,6 @@ const generatedFiles = [
   "*/lib/cnst.ts",
   "*/lib/db.ts",
   "*/lib/dict.ts",
-  "*/lib/option.ts",
   "*/lib/sig.ts",
   "*/lib/srv.ts",
   "*/lib/st.ts",

package/executors.ts

@@ -1392,6 +1392,12 @@ export class AppExecutor extends SysExecutor {
       ...routeEnv,
       ...(devPort ? { PORT: devPort, AKAN_PUBLIC_CLIENT_PORT: devPort, AKAN_PUBLIC_SERVER_PORT: devPort } : {}),
     });
+    // `start` spawns subprocesses that carry `env`, but `build` runs its phases in this same process and
+    // reads `process.env` directly. Publish the resolved env here so SSR/CSR bundling (fed by getPublicEnv,
+    // which filters to AKAN_PUBLIC_*) sees AKAN_PUBLIC_APP_NAME — otherwise SSR throws
+    // "environment variable AKAN_PUBLIC_APP_NAME is required". Only AKAN_PUBLIC_* is baked into bundles, so
+    // this does not leak non-public env.
+    if (type === "build") Object.assign(process.env, env);
     return { env };
   }
   #publicEnv: Record<string, string> | null = null;

package/lint/no-redeclare-predefined-endpoint.grit

@@ -2,8 +2,10 @@ engine biome(1.0)
 language js(typescript, jsx)
 
 // Every model already gets auto-generated CRUD endpoints in its slice fetch
-// contract (see pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts):
-//   <refName>, light<Model>, create<Model>, update<Model>, remove<Model>.
+// contract (see pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts and
+// pkgs/akanjs/fetch/client/fetchClient.ts):
+//   <refName>, light<Model>, create<Model>, update<Model>, remove<Model>,
+//   view<Model>, edit<Model>, merge<Model>.
 // Re-declaring one of them inside the `endpoint(...)` block of a
 // `<model>.signal.ts` file shadows the framework contract and can pass
 // sync/typecheck/build while failing at runtime, so flag it here.
@@ -15,12 +17,12 @@ language js(typescript, jsx)
   $filename <: r".*/([a-z][a-zA-Z0-9]*)\.signal\.ts"($model),
   or {
     $key <: $model,
-    $key <: r"(?:light|create|update|remove)([A-Z][a-zA-Z0-9]*)"($keyCap) where {
+    $key <: r"(?:light|create|update|remove|view|edit|merge)([A-Z][a-zA-Z0-9]*)"($keyCap) where {
       $keyCap <: $Cap
     }
   },
   register_diagnostic(
     span = $key,
-    message = "This endpoint name collides with an auto-generated CRUD endpoint (<model>, light/create/update/remove<Model>). Rename it or move the logic into the service; do not re-declare predefined endpoints."
+    message = "This endpoint name collides with an auto-generated CRUD endpoint (<model>, light/create/update/remove/view/edit/merge<Model>). Rename it or move the logic into the service; do not re-declare predefined endpoints."
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.11-rc.5",
+  "version": "2.3.11-rc.7",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.11-rc.5",
+    "akanjs": "2.3.11-rc.7",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/qualityScanner.ts

@@ -37,6 +37,7 @@ interface ExportedFunctionLike {
   file: string;
   line: number;
   bodyFingerprint?: string;
+  duplicateNameExempt: boolean;
 }
 
 interface TopLevelDeclaration {
@@ -177,7 +178,8 @@ export class AkanQualityScanner {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
     const warnings: QualityWarning[] = [];
 
-    for (const [name, declarations] of groupBy(exportedFunctionLikes, (declaration) => declaration.name)) {
+    const nameCheckedDeclarations = exportedFunctionLikes.filter((declaration) => !declaration.duplicateNameExempt);
+    for (const [name, declarations] of groupBy(nameCheckedDeclarations, (declaration) => declaration.name)) {
       if (declarations.length < 2) continue;
       warnings.push({
         rule: "akan.global.duplicate-exported-function-name",
@@ -345,6 +347,7 @@ function formatQualityLocation(file: string | undefined, line: number | undefine
 
 function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionLike[] {
   const declarations: ExportedFunctionLike[] = [];
+  const pageExempt = isPageRouteFile(sourceFile.file);
   for (const statement of sourceFile.sourceFile.statements) {
     if (ts.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
@@ -353,6 +356,7 @@ function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionL
         file: sourceFile.file,
         line: getLine(sourceFile.sourceFile, statement),
         bodyFingerprint: getBodyFingerprint(sourceFile.sourceFile, statement.body),
+        duplicateNameExempt: pageExempt || isConventionDuplicateNameExempt(sourceFile.file, false),
       });
     }
     if (ts.isClassDeclaration(statement) && statement.name && isExported(statement)) {
@@ -362,6 +366,9 @@ function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionL
         file: sourceFile.file,
         line: getLine(sourceFile.sourceFile, statement),
         bodyFingerprint: getBodyFingerprint(sourceFile.sourceFile, statement),
+        duplicateNameExempt:
+          pageExempt ||
+          isConventionDuplicateNameExempt(sourceFile.file, isEnumClassStatement(sourceFile.sourceFile, statement)),
       });
     }
     if (ts.isVariableStatement(statement) && isExported(statement)) {
@@ -373,6 +380,7 @@ function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionL
           file: sourceFile.file,
           line: getLine(sourceFile.sourceFile, declaration),
           bodyFingerprint: getBodyFingerprint(sourceFile.sourceFile, declaration.initializer),
+          duplicateNameExempt: pageExempt || isConventionDuplicateNameExempt(sourceFile.file, false),
         });
       }
     }
@@ -380,6 +388,38 @@ function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionL
   return declarations;
 }
 
+function isPageRouteFile(file: string) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "page";
+}
+
+function isConventionDuplicateNameExempt(file: string, isEnumClass: boolean) {
+  if (!isInLibModule(file)) return false;
+  if (file.endsWith(".tsx")) return true;
+  if (
+    file.endsWith(".document.ts") ||
+    file.endsWith(".service.ts") ||
+    file.endsWith(".signal.ts") ||
+    file.endsWith(".store.ts")
+  )
+    return true;
+  // Model view classes may repeat across modules; enum classes must stay uniquely named.
+  if (file.endsWith(".constant.ts")) return !isEnumClass;
+  return false;
+}
+
+function isInLibModule(file: string) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
+}
+
+function isEnumClassStatement(sourceFile: ts.SourceFile, statement: ts.Statement) {
+  if (!ts.isClassDeclaration(statement)) return false;
+  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword);
+  const expression = heritageClause?.types[0]?.expression;
+  return !!expression && expression.getText(sourceFile).startsWith("enumOf(");
+}
+
 function getExportedClassNames(sourceFile: ts.SourceFile) {
   return sourceFile.statements
     .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement) && !!statement.name)
@@ -403,11 +443,7 @@ function getPlaceholderExportWarnings(sourceFile: SourceFileInfo): QualityWarnin
 
 function getDictionaryTextWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
   if (!sourceFile.file.endsWith(".dictionary.ts")) return [];
-  const stalePatterns = [
-    { pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" },
-    { pattern: /settting/, label: "misspelling: settting" },
-    { pattern: /배너 수/, label: "stale copied Korean domain noun: 배너 수" },
-  ];
+  const stalePatterns = [{ pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" }];
   return stalePatterns.flatMap(({ pattern, label }) =>
     findPatternLines(sourceFile.content, pattern).map((line) => ({
       rule: "akan.file.dictionary-stale-text",

package/workflow/artifacts.ts

@@ -196,7 +196,6 @@ export const generatedFilePathsForTarget = (targetRoot: string, reason = "Genera
   [
     { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
     { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
-    { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
     { path: `${targetRoot}/lib/index.ts`, action: "sync", reason },
   ] satisfies PrimitiveGeneratedFile[];