@akanjs/devkit 3.0.0-alpha.5 → 3.0.0-alpha.51

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",
   },
 };
@@ -144,8 +144,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 +182,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 +194,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 +203,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 +210,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 +383,52 @@ 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,
+      [],
+      ["@external/runtime", "puppeteer"],
+    );
+
+    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("AkanLibConfig", () => {
   test("uses empty external libs by default and preserves explicit libs", () => {
     const lib = { name: "shared" } as never;

package/akanConfig/akanConfig.ts

@@ -5,7 +5,7 @@ import type { AkanPlugin } from "akanjs";
 import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
-import { WorkspaceExecutor } from "../executors";
+import { LibExecutor, WorkspaceExecutor } from "../executors";
 import type { BaseDevEnv, PackageJson } from "../types";
 import {
   type AkanMobileConfig,
@@ -50,8 +50,6 @@ const DEFAULT_OPTIMIZE_IMPORTS = [
 ];
 const WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"] as const;
 const SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"] as const;
-const NATIVE_RUNTIME_PACKAGES = ["sharp"] as const;
-const DEFAULT_BACKEND_RUNTIME_PACKAGES = ["croner"] as const;
 // The firebase client (push tokens) and the Capacitor toolchain — `@capacitor/cli` (`npx cap`),
 // `@capacitor/assets` (`npx @capacitor/assets`) plus the `@capacitor/core`/`ios`/`android` runtime
 // and native-platform packages that `npx cap add`/`sync` resolve from the workspace node_modules.
@@ -92,8 +90,6 @@ const DATABASE_MODE_RUNTIME_PACKAGES = {
 } satisfies Record<DatabaseMode, readonly string[]>;
 const AKAN_RUNTIME_PACKAGES = new Set<string>([
   ...SSR_RUNTIME_PACKAGES,
-  ...NATIVE_RUNTIME_PACKAGES,
-  ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
   ...MOBILE_RUNTIME_PACKAGES,
   ...Object.values(DATABASE_MODE_RUNTIME_PACKAGES).flat(),
 ]);
@@ -199,6 +195,7 @@ export class AkanAppConfig implements AppConfigResult {
     config: DeepPartial<AppConfigResult>,
     baseDevEnv: BaseDevEnv,
     plugins: AkanPlugin[] = [],
+    libExternalLibs: readonly string[] = [],
   ) {
     this.app = app;
     this.rootPackageJson = rootPackageJson;
@@ -207,7 +204,7 @@ export class AkanAppConfig implements AppConfigResult {
     this.plugins = plugins;
     this.#applyRoutes(config?.routes);
     this.defaultDatabaseMode = config?.defaultDatabaseMode ?? "single";
-    this.externalLibs = config?.externalLibs ?? [];
+    this.externalLibs = [...new Set([...(config?.externalLibs ?? []), ...libExternalLibs])];
     this.barrelImports = [
       ...DEFAULT_BARREL_IMPORTS,
       ...WORKSPACE_BARREL_FACETS.map((facet) => `@apps/${app.name}/${facet}`),
@@ -416,7 +413,23 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     ]);
     const resolved = typeof configImp === "function" ? configImp(app) : configImp;
     const { plugins, ...config } = (resolved ?? {}) as DeepPartial<AppConfigResult> & { plugins?: AkanPlugin[] };
-    return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? []);
+    const libExternalLibs = await AkanAppConfig.#collectLibExternalLibs(app, libs, bustImportCache);
+    return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? [], libExternalLibs);
+  }
+  //* Every workspace lib is read, not just this app's lib deps: narrowing the set needs the dependency
+  //* scan, and the incremental page rebundle re-reads this config on every file change.
+  static async #collectLibExternalLibs(app: App, libs: string[], bustImportCache: boolean): Promise<string[]> {
+    const libConfigs = await Promise.all(
+      libs.map(async (libName) =>
+        LibExecutor.from(app, libName)
+          .getConfig({ refresh: bustImportCache })
+          .catch((error: unknown) => {
+            app.logger.warn(`Skipped libs/${libName}/akan.config.ts externalLibs: ${String(error)}`);
+            return null;
+          }),
+      ),
+    );
+    return libConfigs.flatMap((libConfig) => libConfig?.externalLibs ?? []);
   }
   #resolveProductionDependencyVersion(lib: string) {
     const rootVersion = this.rootPackageJson.dependencies?.[lib] ?? this.rootPackageJson.devDependencies?.[lib];
@@ -428,13 +441,7 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     return akanPackageJson.dependencies?.[lib] ?? akanPackageJson.peerDependencies?.[lib];
   }
   #getProductionRuntimePackages() {
-    return [
-      ...this.externalLibs,
-      ...SSR_RUNTIME_PACKAGES,
-      ...NATIVE_RUNTIME_PACKAGES,
-      ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
-      ...this.getDatabaseModeRuntimePackages(),
-    ];
+    return [...this.externalLibs, ...SSR_RUNTIME_PACKAGES, ...this.getDatabaseModeRuntimePackages()];
   }
   getDatabaseModeRuntimePackages(databaseMode: DatabaseMode = this.defaultDatabaseMode) {
     return [...DATABASE_MODE_RUNTIME_PACKAGES[databaseMode]];
@@ -539,8 +546,8 @@ export class AkanLibConfig implements LibConfigResult {
     this.externalLibs = config?.externalLibs ?? [];
     this.plugins = plugins;
   }
-  static async from(lib: Lib) {
-    const [configImp] = await Promise.all([import(`${lib.cwdPath}/akan.config.ts`).then((mod) => mod.default)]);
+  static async from(lib: Lib, { bustImportCache = false }: { bustImportCache?: boolean } = {}) {
+    const configImp = await AkanAppConfig.importConfigModule(lib.cwdPath, { bustImportCache });
     const resolved = typeof configImp === "function" ? configImp(lib) : configImp;
     const { plugins, ...config } = (resolved ?? {}) as DeepPartial<LibConfigResult> & { plugins?: AkanPlugin[] };
     return new AkanLibConfig(lib, config, plugins ?? []);

package/akanContext.ts

@@ -1,6 +1,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { capitalize } from "akanjs/common";
+import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import { collectRecipeSources, findInlineRecipeDuplicates, scanRecipes } from "./recipeScanner";
@@ -14,7 +15,7 @@ import {
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
-import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+import { isScannedRootEntry, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -276,6 +277,8 @@ const validationCommands = [
   "akan test <app-or-lib-or-pkg>",
   "akan build <app-name>",
   "akan doctor --strict --format json",
+  "akan quality scan [--format json]",
+  "akan quality ssr [--format json]",
 ];
 
 const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
@@ -618,6 +621,30 @@ 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.
+  static async #agentGuideDrift(workspace: WorkspaceExecutor) {
+    const installed = await readDevkitVersion();
+    if (!installed) return null;
+    const content = await safeReadText(path.join(workspace.workspaceRoot, "AGENTS.md"));
+    if (content === null) return null;
+    const stamped = extractBlockVersion(content);
+    if (stamped === installed) return null;
+    const hint = "Re-render the AGENTS.md managed block from the installed framework release.";
+    if (!stamped)
+      return {
+        code: "agent-guide-unstamped",
+        message: `AGENTS.md carries no generated-version stamp, so its conventions may predate @akanjs/devkit ${installed}`,
+        hint,
+      };
+    return {
+      code: "agent-guide-stale",
+      message: `AGENTS.md was generated by @akanjs/devkit ${stamped}, but ${installed} is installed`,
+      hint,
+    };
+  }
+
   static async doctor(
     workspace: WorkspaceExecutor,
     {
@@ -639,23 +666,25 @@ export class AkanContextAnalyzer {
       ),
     ];
 
-    for (const app of context.apps) {
-      const appPath = path.join(workspace.workspaceRoot, app.path);
-      for (const entry of await safeReadDir(appPath)) {
-        if (!isScannedAppRootEntry(entry.name)) continue;
-        const allowed = entry.isDirectory() ? appRootAllowedDirs.has(entry.name) : appRootAllowedFiles.has(entry.name);
+    for (const sys of [...context.apps, ...context.libs]) {
+      const sysPath = path.join(workspace.workspaceRoot, sys.path);
+      for (const entry of await safeReadDir(sysPath)) {
+        if (!isScannedRootEntry(sys.type, entry.name)) continue;
+        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 ${app.name}`,
-            "Review app root shape and remove or move the unknown entry.",
+            `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: "app-root-unknown-entry",
-            path: `${app.path}/${entry.name}`,
-            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in app root: ${app.path}/${entry.name}`,
+            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);
@@ -663,6 +692,19 @@ export class AkanContextAnalyzer {
       }
     }
 
+    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);
+    }
+
     for (const sys of [...context.apps, ...context.libs]) {
       for (const module of sys.modules) {
         if (!module.abstract.exists) {

package/applicationBuildRunner.test.ts

@@ -4,7 +4,7 @@ import { AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
     expect(AKAN_OPTIONAL_BACKEND_EXTERNALS).toEqual(
-      expect.arrayContaining(["@libsql/client", "bullmq", "croner", "ioredis", "postgres", "protobufjs"]),
+      expect.arrayContaining(["@libsql/client", "bullmq", "ioredis", "postgres", "protobufjs"]),
     );
   });
 });

package/applicationBuildRunner.ts

@@ -56,7 +56,6 @@ const SSR_RENDER_EXTERNALS = [
 export const AKAN_OPTIONAL_BACKEND_EXTERNALS = [
   "@libsql/client",
   "bullmq",
-  "croner",
   "ioredis",
   "postgres",
   "protobufjs",