@akanjs/devkit 3.0.0-alpha.7 → 3.0.0-alpha.70

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @akanjs/devkit
 
+## 2.4.2
+
+### Patch Changes
+
+- Updated dependencies [6d58c7e]
+- Updated dependencies [11aa655]
+- Updated dependencies [25d5b15]
+- Updated dependencies [11aa655]
+- Updated dependencies [11aa655]
+- Updated dependencies [25d5b15]
+- Updated dependencies [42cf7a2]
+- Updated dependencies [25d5b15]
+- Updated dependencies [04cb46d]
+  - akanjs@2.4.2
+
 ## 2.4.1
 
 ### Patch Changes

package/README.ko.md

@@ -56,7 +56,7 @@ await runner.build();
 
 ## 요구사항
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript
 - Optional peer는 Capacitor integration처럼 해당 기능을 사용할 때만 필요합니다.
 

package/README.md

@@ -60,7 +60,7 @@ defaults, the shares they derive from `AKAN_MEMORY_LIMIT`, and what a small cont
 
 ## Requirements
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript
 - Optional peers are only needed for the features that use them, such as Capacitor integration.
 

package/agentsIndex.test.ts

@@ -10,6 +10,7 @@ import {
   renderRecipeEntries,
   renderScopeAgentBlock,
   renderScopeAgentsMd,
+  renderScopeClaudeMd,
   upsertAgentBlock,
 } from "./agentsIndex";
 import type { RecipeInfo } from "./recipeScanner";
@@ -48,6 +49,15 @@ describe("renderScopeAgentBlock", () => {
   });
 });
 
+describe("renderScopeClaudeMd", () => {
+  test("points at AGENTS.md and restates only the comment rule", () => {
+    const claude = renderScopeClaudeMd({ type: "app", name: "minimal" });
+    expect(claude).toContain("@AGENTS.md");
+    expect(claude).toContain("## Comments — Overrides Your Default");
+    expect(claude).not.toContain("## Recipes In Scope");
+  });
+});
+
 describe("upsertAgentBlock / extractAgentBlock", () => {
   test("round-trips: fresh file → replace block → extract equals block", () => {
     const fresh = renderScopeAgentsMd({ type: "app", name: "minimal" }, "OLD");

package/agentsIndex.ts

@@ -19,6 +19,32 @@ const loadRecipeScanner = () => (recipeScannerLoad ??= import("./recipeScanner")
 export const AGENT_BLOCK_START = "<!-- akan:agent:start -->";
 export const AGENT_BLOCK_END = "<!-- akan:agent:end -->";
 
+const AGENT_VERSION_PREFIX = "<!-- akan:agent:version ";
+
+/**
+ * The generating release, stamped into the workspace block. Nothing re-runs `akan agent install` on its own, so
+ * without a stamp a workspace carrying conventions from four releases ago is indistinguishable from a current one —
+ * `akan doctor` compares this against the installed devkit and says so.
+ */
+export const stampBlockVersion = (block: string, version: string): string =>
+  `${AGENT_VERSION_PREFIX}${version} -->\n\n${block}`;
+
+/** The stamped version of a committed AGENTS.md, or null when it predates stamping or carries no block. */
+export const extractBlockVersion = (content: string): string | null =>
+  content.match(/<!-- akan:agent:version ([^\s]+) -->/)?.[1] ?? null;
+
+/** The running `@akanjs/devkit` version; null when its package.json is unreadable, which must not fail a doctor run. */
+export const readDevkitVersion = async (): Promise<string | null> => {
+  const { readFile } = await import("node:fs/promises");
+  const { getDirname } = await import("./getDirname");
+  try {
+    const raw = await readFile(`${getDirname(import.meta.url)}/package.json`, "utf-8");
+    return (JSON.parse(raw) as { version?: string }).version ?? null;
+  } catch {
+    return null;
+  }
+};
+
 export interface AgentsIndexScope {
   type: "app" | "lib";
   name: string;
@@ -139,8 +165,28 @@ ${block}
 ${AGENT_BLOCK_END}
 `;
 
-/** Claude Code reads nested CLAUDE.md files as it works under a directory; keep it a thin pointer. */
+export const CLAUDE_COMMENT_RULE = `## Comments — Overrides Your Default
+
+Write **no comments** unless the comment passes the test below. This is the rule agents break most often here, so it
+is repeated outside the guide: a diff that adds a comment the test rejects is a diff to redo.
+
+Before typing \`//\`, \`/*\`, or a doc block, ask — **does this sentence carry a fact that is nowhere in the code?**
+
+- Restates the identifier, the signature, or the line under it → delete it.
+- Labels a section (\`// helpers\`, \`// state\`) or narrates a step (\`// fetch the user\`, \`// then save\`) → delete it.
+- JSDoc on an ordinary function, or a why/how preamble on ordinary logic → delete it.
+- Explains the edit you just made, for whoever reads the diff → say it in your reply, not in the file.
+- Names a vendor or protocol quirk, an infrastructure constraint, a library gotcha, security reasoning, a math
+  derivation, a domain field's business meaning, a state transition, or why an obvious alternative was rejected →
+  keep it, one line.
+
+That keep-list is exact — \`Comments\` in the guide is the full version. "It aids readability" and "this logic is
+subtle" are not on it: rename or split the code instead. When you edit an existing file, match its density; if the
+surrounding code carries none, your diff carries none.`;
+
 export const renderScopeClaudeMd = (scope: AgentsIndexScope): string => `# ${scope.name} — Claude Code Guide
 
 @AGENTS.md
+
+${CLAUDE_COMMENT_RULE}
 `;

package/aiEditor.ts

@@ -19,7 +19,7 @@ import type { FileContent } from "./types";
 
 const MAX_ASK_TRY = 300;
 
-const deepSeekLlmModels = ["deepseek-chat", "deepseek-reasoner"] as const;
+const deepSeekLlmModels = ["deepseek-v4-flash", "deepseek-v4-pro"] as const;
 
 const openAiLlmModels = ["gpt-5.5"] as const;
 

package/akanConfig/akanConfig.test.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { AppExecutor, WorkspaceExecutor } from "../executors";
 import type { PackageJson } from "../types";
 import { AkanAppConfig, AkanLibConfig, deriveDefaultAppId } from "./akanConfig";
 import type { DeepPartial, LibConfigResult } from "./types";
@@ -19,7 +20,6 @@ const packageJson: PackageJson = {
     react: "19.0.0",
     "react-dom": "19.0.0",
     "react-server-dom-webpack": "19.0.0",
-    sharp: "1.0.0",
     "@external/runtime": "2.0.0",
   },
 };
@@ -64,7 +64,7 @@ describe("AkanAppConfig", () => {
     expect(config.barrelImports).toEqual(
       expect.arrayContaining(["@apps/portal/ui", "@libs/shared/server", "akanjs/common", "akanjs/server"]),
     );
-    expect(config.docker.content).toContain("ENV AKAN_PUBLIC_APP_NAME=portal");
+    expect(config.dockerfile).toContain("ENV AKAN_PUBLIC_APP_NAME=portal");
     expect(process.env.AKAN_PUBLIC_DEFAULT_LOCALE).toBe("en");
   });
 
@@ -128,9 +128,67 @@ describe("AkanAppConfig", () => {
     });
     expect(config.publicEnv).toEqual(["AKAN_PUBLIC_FEATURE"]);
     expect(config.optimizeImports).toContain("custom-icons");
-    expect(config.docker.content).toContain('CMD ["bun","server.js"]');
-    expect(config.docker.content).toContain("FROM oven/bun:amd64 AS amd64");
-    expect(config.docker.content).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+    expect(config.dockerfile).toContain('CMD ["bun","server.js"]');
+    expect(config.dockerfile).toContain("FROM oven/bun:amd64 AS amd64");
+    expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+  });
+
+  test("defaults both web surfaces on and keeps the image free of web env overrides", () => {
+    const config = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv);
+
+    expect(config.web).toEqual({ ssr: true, csr: true });
+    expect(config.dockerfile).not.toContain("AKAN_SSR");
+    expect(config.dockerfile).not.toContain("AKAN_CSR");
+  });
+
+  test("bakes the disabled surface into the image env so the default matches what was built", () => {
+    const ssrOnly = new AkanAppConfig(app, [], packageJson, { web: { csr: false } }, baseDevEnv);
+    expect(ssrOnly.web).toEqual({ ssr: true, csr: false });
+    expect(ssrOnly.dockerfile).toContain("ENV AKAN_CSR=false");
+    expect(ssrOnly.dockerfile).not.toContain("ENV AKAN_SSR=false");
+
+    const apiOnly = new AkanAppConfig(app, [], packageJson, { web: false }, baseDevEnv);
+    expect(apiOnly.web).toEqual({ ssr: false, csr: false });
+    expect(apiOnly.dockerfile).toContain("ENV AKAN_SSR=false");
+    expect(apiOnly.dockerfile).toContain("ENV AKAN_CSR=false");
+
+    expect(new AkanAppConfig(app, [], packageJson, { web: true }, baseDevEnv).web).toEqual({ ssr: true, csr: true });
+  });
+
+  test("refuses a csr-less build that ships a mobile app", () => {
+    expect(
+      () => new AkanAppConfig(app, [], packageJson, { web: { csr: false }, mobile: { appName: "portal" } }, baseDevEnv),
+    ).toThrow("the Capacitor build ships that bundle");
+  });
+
+  test("installs only ca-certificates and tzdata in the default image", () => {
+    const config = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv);
+
+    expect(config.dockerfile).toContain(
+      "RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*",
+    );
+    // The Chromium/ffmpeg toolchain moved to per-app `preRuns`; keeping it here paid for it in every image.
+    for (const dropped of ["libnss3", "ffmpeg", "build-essential", "redis", "xdg-utils"])
+      expect(config.dockerfile).not.toContain(dropped);
+  });
+
+  test("keeps a declared Dockerfile string verbatim", () => {
+    const dockerfile = 'FROM oven/bun:1-slim\nCOPY . .\nCMD ["bun","main.js"]';
+    const config = new AkanAppConfig(app, [], packageJson, { docker: dockerfile }, baseDevEnv);
+
+    expect(config.docker).toBe(dockerfile);
+    expect(config.dockerfile).toBe(dockerfile);
+  });
+
+  test("resolves the image parts, defaulting the base image and the command", () => {
+    const config = new AkanAppConfig(app, [], packageJson, { docker: { preRuns: ["echo hi"] } }, baseDevEnv);
+
+    expect(config.docker).toEqual({
+      image: "oven/bun:1-slim",
+      preRuns: ["echo hi"],
+      postRuns: [],
+      command: ["bun", "main.js"],
+    });
   });
 
   test("creates production package json and reports missing external versions", () => {
@@ -144,8 +202,6 @@ describe("AkanAppConfig", () => {
         react: "19.0.0",
         "react-dom": "19.0.0",
         "react-server-dom-webpack": "19.0.0",
-        croner: akanPackageJson.peerDependencies?.croner,
-        sharp: "1.0.0",
         "@external/runtime": "2.0.0",
       },
     });
@@ -184,8 +240,6 @@ describe("AkanAppConfig", () => {
       react: runtimeDependencies.react,
       "react-dom": runtimeDependencies["react-dom"],
       "react-server-dom-webpack": runtimeDependencies["react-server-dom-webpack"],
-      croner: runtimeDependencies.croner,
-      sharp: runtimeDependencies.sharp,
     });
   });
 
@@ -198,9 +252,6 @@ describe("AkanAppConfig", () => {
     const multipleConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "multiple" }, baseDevEnv);
     const clusterConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "cluster" }, baseDevEnv);
 
-    expect(singleConfig.getProductionPackageJson().dependencies).toMatchObject({
-      croner: runtimeDependencies.croner,
-    });
     expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("ioredis");
     expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("bullmq");
     expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("@libsql/client");
@@ -210,7 +261,6 @@ describe("AkanAppConfig", () => {
     expect(multipleConfig.getProductionPackageJson().dependencies).toMatchObject({
       "@libsql/client": runtimeDependencies["@libsql/client"],
       bullmq: runtimeDependencies.bullmq,
-      croner: runtimeDependencies.croner,
       ioredis: runtimeDependencies.ioredis,
       protobufjs: runtimeDependencies.protobufjs,
     });
@@ -218,7 +268,6 @@ describe("AkanAppConfig", () => {
 
     expect(clusterConfig.getProductionPackageJson().dependencies).toMatchObject({
       bullmq: runtimeDependencies.bullmq,
-      croner: runtimeDependencies.croner,
       ioredis: runtimeDependencies.ioredis,
       postgres: runtimeDependencies.postgres,
       protobufjs: runtimeDependencies.protobufjs,
@@ -392,6 +441,115 @@ describe("deriveDefaultAppId", () => {
   });
 });
 
+describe("AkanAppConfig lib externalLibs", () => {
+  test("merges lib-declared external libs into the app's own, deduped", () => {
+    const libAwarePackageJson: PackageJson = {
+      ...packageJson,
+      dependencies: { ...packageJson.dependencies, puppeteer: "24.0.0" },
+    };
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      libAwarePackageJson,
+      { externalLibs: ["@external/runtime"] },
+      baseDevEnv,
+      [],
+      { externalLibs: ["@external/runtime", "puppeteer"], docker: { preRuns: [], postRuns: [] } },
+    );
+
+    expect(config.externalLibs).toEqual(["@external/runtime", "puppeteer"]);
+    expect(config.getProductionPackageJson().dependencies).toMatchObject({
+      "@external/runtime": "2.0.0",
+      puppeteer: "24.0.0",
+    });
+  });
+
+  test("reads them off every workspace lib config on load", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-libext-"));
+    try {
+      fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
+      fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
+      fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), "export default { externalLibs: ['shiki'] };\n");
+      fs.writeFileSync(
+        path.join(root, "libs/extlib/akan.config.ts"),
+        "export default { externalLibs: ['puppeteer'] };\n",
+      );
+      fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
+      fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
+
+      const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
+      const config = await AppExecutor.from(workspace, "extapp").getConfig();
+
+      expect(config.externalLibs).toEqual(["shiki", "puppeteer"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("AkanAppConfig lib docker runs", () => {
+  const libDocker = (preRuns: string[], postRuns: string[] = []) => ({
+    externalLibs: [],
+    docker: { preRuns, postRuns },
+  });
+
+  test("runs lib steps before the app's own, deduped", () => {
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      packageJson,
+      { docker: { preRuns: ["apt-get install -y ffmpeg", "echo app"], postRuns: ["echo app-post"] } },
+      baseDevEnv,
+      [],
+      libDocker(["apt-get install -y ffmpeg", "echo lib"], ["echo lib-post"]),
+    );
+
+    expect(config.docker).toMatchObject({
+      preRuns: ["apt-get install -y ffmpeg", "echo lib", "echo app"],
+      postRuns: ["echo lib-post", "echo app-post"],
+    });
+    expect(config.dockerfile).toContain("RUN echo lib\nRUN echo app\n");
+    expect(config.dockerfile.match(/RUN apt-get install -y ffmpeg/g)).toHaveLength(1);
+  });
+
+  test("drops them when the app hands over a whole Dockerfile", () => {
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      packageJson,
+      { docker: "FROM scratch" },
+      baseDevEnv,
+      [],
+      libDocker(["echo lib"]),
+    );
+
+    expect(config.dockerfile).toBe("FROM scratch");
+  });
+
+  test("reads them off every workspace lib config on load", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-libdocker-"));
+    try {
+      fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
+      fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
+      fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), "export default {};\n");
+      fs.writeFileSync(
+        path.join(root, "libs/extlib/akan.config.ts"),
+        "export default { docker: { preRuns: ['echo from-lib'], postRuns: [{ arm64: 'echo arm-only' }] } };\n",
+      );
+      fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
+      fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
+
+      const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
+      const config = await AppExecutor.from(workspace, "extapp").getConfig();
+
+      expect(config.dockerfile).toContain("RUN echo from-lib");
+      expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("AkanLibConfig", () => {
   test("uses empty external libs by default and preserves explicit libs", () => {
     const lib = { name: "shared" } as never;
@@ -402,6 +560,15 @@ describe("AkanLibConfig", () => {
     };
     expect(new AkanLibConfig(lib, config).externalLibs).toEqual(["firebase-admin"]);
   });
+
+  test("defaults docker runs to empty lists and preserves declared ones", () => {
+    const lib = { name: "shared" } as never;
+    expect(new AkanLibConfig(lib, {}).docker).toEqual({ preRuns: [], postRuns: [] });
+    expect(new AkanLibConfig(lib, { docker: { preRuns: ["echo lib"] } }).docker).toEqual({
+      preRuns: ["echo lib"],
+      postRuns: [],
+    });
+  });
 });
 
 describe("AkanAppConfig.importConfigModule", () => {