@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.80

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/akanApp/BackendImportGraph.test.ts

@@ -0,0 +1,120 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { App } from "../commandDecorators";
+import { BackendImportGraph } from "./BackendImportGraph";
+import { filesChangedSince } from "./devHostPolicy";
+
+describe("BackendImportGraph", () => {
+  const tempRoots: string[] = [];
+
+  const makeGraph = async (files: Record<string, string>) => {
+    // Realpath, not the mkdtemp path: `Bun.resolveSync` returns real paths, and on macOS `/var/folders`
+    // is a symlink, so an unresolved root makes every resolved import look like it escapes the workspace.
+    const workspaceRoot = await realpath(await mkdtemp(path.join(os.tmpdir(), "akan-devkit-graph-")));
+    tempRoots.push(workspaceRoot);
+    const cwdPath = path.join(workspaceRoot, "apps/demo");
+    for (const [rel, source] of Object.entries(files)) {
+      const filePath = path.join(cwdPath, rel);
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await writeFile(filePath, source);
+    }
+    const app = { cwdPath, workspace: { workspaceRoot } } as unknown as App;
+    return { graph: new BackendImportGraph(app, new Logger("test")), cwdPath };
+  };
+
+  afterEach(async () => {
+    await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  test("walks the backend entrypoints' import graph", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import { handler } from "./lib/handler";\nexport default handler;\n',
+      "lib/handler.ts": "export const handler = () => null;\n",
+      "lib/unreachable.ts": "export const nope = 1;\n",
+    });
+
+    expect(await graph.refresh()).toBe(true);
+    expect(graph.has(path.join(cwdPath, "lib/handler.ts"))).toBe(true);
+    expect(graph.has(path.join(cwdPath, "lib/unreachable.ts"))).toBe(false);
+  });
+
+  test("picks up an import added to an already-scanned file", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": "export default 1;\n",
+      "lib/added.ts": "export const added = 1;\n",
+    });
+    await graph.refresh();
+    expect(graph.has(path.join(cwdPath, "lib/added.ts"))).toBe(false);
+
+    // The scan cache is keyed on (mtimeMs, size), so the rewrite must invalidate it.
+    await writeFile(path.join(cwdPath, "server.ts"), 'import "./lib/added";\nexport default 1;\n');
+
+    await graph.refresh();
+    expect(graph.has(path.join(cwdPath, "lib/added.ts"))).toBe(true);
+  });
+
+  test("drops a file that left the graph", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import "./lib/leaving";\nexport default 1;\n',
+      "lib/leaving.ts": "export const leaving = 1;\n",
+    });
+    await graph.refresh();
+    expect(graph.has(path.join(cwdPath, "lib/leaving.ts"))).toBe(true);
+
+    await writeFile(path.join(cwdPath, "server.ts"), "export default 1;\n");
+    await graph.refresh();
+    expect(graph.has(path.join(cwdPath, "lib/leaving.ts"))).toBe(false);
+  });
+
+  test("reports which backend files moved while nobody was watching", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import "./lib/handler";\nexport default 1;\n',
+      "lib/handler.ts": "export const handler = () => null;\n",
+    });
+    await graph.refresh();
+    const before = await graph.fingerprint();
+
+    // The builder is gone here, so no watcher event exists for this save — which is the whole reason
+    // the stamps are taken. `mtimeMs` has a coarse clock on Linux, so the size has to move too.
+    await writeFile(path.join(cwdPath, "lib/handler.ts"), "export const handler = () => 'changed';\n");
+
+    expect(filesChangedSince(before, await graph.fingerprint())).toEqual([path.join(cwdPath, "lib/handler.ts")]);
+  });
+
+  test("says nothing when the tree is untouched, and names a deleted file", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import "./lib/handler";\nexport default 1;\n',
+      "lib/handler.ts": "export const handler = () => null;\n",
+    });
+    await graph.refresh();
+    const before = await graph.fingerprint();
+    // A recycle with no edit in it is the common case, and it must not cost a backend restart.
+    expect(filesChangedSince(before, await graph.fingerprint())).toEqual([]);
+
+    await rm(path.join(cwdPath, "lib/handler.ts"));
+    // Deleted counts as changed: the backend is still running what used to be there.
+    expect(filesChangedSince(before, await graph.fingerprint())).toEqual([path.join(cwdPath, "lib/handler.ts")]);
+  });
+
+  test("keeps the previous graph when a refresh finds no entrypoints", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./lib/kept";\n',
+      "lib/kept.ts": "export const kept = 1;\n",
+    });
+    await graph.refresh();
+    expect(graph.ready).toBe(true);
+
+    await rm(path.join(cwdPath, "main.ts"));
+    await graph.refresh();
+    // An empty scan is not a failure, so the graph legitimately empties out.
+    expect(graph.has(path.join(cwdPath, "lib/kept.ts"))).toBe(false);
+  });
+});

package/akanApp/BackendImportGraph.ts

@@ -0,0 +1,167 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import type { Logger } from "akanjs/common";
+import type { App } from "../commandDecorators";
+import { SOURCE_EXTS, type SourceFingerprints } from "./devHostPolicy";
+
+const NON_SOURCE_EXT_RE =
+  /\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
+
+const GRAPH_IMPORT_KINDS = new Set<Bun.ImportKind>([
+  "import-statement",
+  "require-call",
+  "require-resolve",
+  "dynamic-import",
+]);
+
+export class BackendImportGraph {
+  readonly #app: App;
+  readonly #logger: Logger;
+  readonly #tsTranspiler = new Bun.Transpiler({ loader: "ts" });
+  readonly #tsxTranspiler = new Bun.Transpiler({ loader: "tsx" });
+  readonly #jsTranspiler = new Bun.Transpiler({ loader: "js" });
+  readonly #jsxTranspiler = new Bun.Transpiler({ loader: "jsx" });
+  #files = new Set<string>();
+  /**
+   * `refresh()` runs on every server-side save and on every dev-host recycle, and re-reading plus
+   * re-parsing files that did not change is the whole cost of it. Keyed on (mtimeMs, size).
+   *
+   * Specifiers are cached, not resolved paths: creating a file can change what an *unchanged* importer's
+   * specifier resolves to, and `Bun.resolveSync` is cheap next to a read plus a transpiler scan. Only
+   * the scan result is retained — never the source text.
+   */
+  #scanCache = new Map<string, { mtimeMs: number; size: number; specifiers: Bun.Import[] }>();
+  #ready = false;
+  #lastRefreshSucceeded = false;
+
+  constructor(app: App, logger: Logger) {
+    this.#app = app;
+    this.#logger = logger;
+  }
+
+  get ready() {
+    return this.#ready;
+  }
+
+  get lastRefreshSucceeded() {
+    return this.#lastRefreshSucceeded;
+  }
+
+  has(file: string) {
+    return this.#files.has(path.resolve(file));
+  }
+
+  /**
+   * Stamp every file the backend runs, so a caller can ask later what moved.
+   *
+   * Taken when the builder goes away and compared when its replacement is up, because nothing watches
+   * the tree in between: the departing builder's watcher left with it, and the replacement's index
+   * primes from the disk it finds, so an edit that lands in the gap is *baseline* to it and is never
+   * reported at all. The client half of such an edit is rescued by the replacement's boot build; the
+   * backend half is a server left running code that no longer exists, with nothing on screen to say so.
+   *
+   * One `stat` per graph file, against a gap that costs a whole boot build anyway.
+   */
+  async fingerprint(): Promise<SourceFingerprints> {
+    const stamps = await Promise.all(
+      [...this.#files].map(async (file) => {
+        const stats = await stat(file).catch(() => null);
+        return [file, stats ? `${Math.round(stats.mtimeMs)}:${stats.size}` : "(gone)"] as const;
+      }),
+    );
+    return new Map(stamps);
+  }
+
+  async refresh(): Promise<boolean> {
+    try {
+      const files = await this.#build();
+      this.#files = files;
+      this.#ready = true;
+      this.#lastRefreshSucceeded = true;
+      this.#logger.verbose(`[backend-graph] scanned ${files.size} files`);
+      return true;
+    } catch (err) {
+      this.#ready = this.#files.size > 0;
+      this.#lastRefreshSucceeded = false;
+      this.#logger.warn(
+        `[backend-graph] scan failed; ${this.#ready ? "using previous graph" : "using fallback rules"}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return this.#ready;
+    }
+  }
+
+  async #build(): Promise<Set<string>> {
+    const roots = await this.#entrypoints();
+    const files = new Set<string>();
+    const queue = [...roots];
+    const workspaceRoot = path.resolve(this.#app.workspace.workspaceRoot);
+
+    while (queue.length > 0) {
+      const current = path.resolve(queue.pop() as string);
+      if (files.has(current)) continue;
+      if (!this.#isWorkspaceSource(current, workspaceRoot)) continue;
+      const imports = await this.#importsOf(current);
+      if (!imports) continue;
+
+      files.add(current);
+      const importerDir = path.dirname(current);
+      for (const imp of imports) {
+        if (!GRAPH_IMPORT_KINDS.has(imp.kind) || !imp.path || NON_SOURCE_EXT_RE.test(imp.path)) continue;
+        const resolved = this.#resolve(imp.path, importerDir);
+        if (!resolved || files.has(resolved)) continue;
+        queue.push(resolved);
+      }
+    }
+    // Files that dropped out of the graph would otherwise be cached for the life of the dev session.
+    for (const cached of this.#scanCache.keys()) if (!files.has(cached)) this.#scanCache.delete(cached);
+    return files;
+  }
+
+  /** Null when the file is gone, which is the existence check the walk used to make separately. */
+  async #importsOf(file: string): Promise<Bun.Import[] | null> {
+    const stats = await stat(file).catch(() => null);
+    if (!stats?.isFile()) return null;
+    const mtimeMs = Math.round(stats.mtimeMs);
+    const cached = this.#scanCache.get(file);
+    if (cached && cached.mtimeMs === mtimeMs && cached.size === stats.size) return cached.specifiers;
+    const specifiers = this.#scanImports(file, await Bun.file(file).text());
+    this.#scanCache.set(file, { mtimeMs, size: stats.size, specifiers });
+    return specifiers;
+  }
+
+  async #entrypoints(): Promise<string[]> {
+    const roots = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
+    const existing: string[] = [];
+    for (const root of roots) {
+      const abs = path.resolve(root);
+      if (await Bun.file(abs).exists()) existing.push(abs);
+    }
+    return existing;
+  }
+
+  #resolve(specifier: string, importerDir: string): string | null {
+    try {
+      const resolved = Bun.resolveSync(specifier, importerDir);
+      if (!path.isAbsolute(resolved)) return null;
+      if (!SOURCE_EXTS.has(path.extname(resolved).toLowerCase())) return null;
+      return path.resolve(resolved);
+    } catch {
+      return null;
+    }
+  }
+
+  #isWorkspaceSource(file: string, workspaceRoot: string): boolean {
+    const rel = path.relative(workspaceRoot, file);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) return false;
+    if (rel.includes(`${path.sep}node_modules${path.sep}`) || rel.includes(`${path.sep}.akan${path.sep}`)) return false;
+    return SOURCE_EXTS.has(path.extname(file).toLowerCase());
+  }
+
+  #scanImports(file: string, source: string): Bun.Import[] {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === ".tsx") return this.#tsxTranspiler.scanImports(source);
+    if (ext === ".jsx") return this.#jsxTranspiler.scanImports(source);
+    if (ext === ".js" || ext === ".mjs" || ext === ".cjs") return this.#jsTranspiler.scanImports(source);
+    return this.#tsTranspiler.scanImports(source);
+  }
+}