@akanjs/devkit 3.0.0-alpha.13 → 3.0.0-alpha.15

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

@@ -165,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/executors.test.ts

@@ -760,6 +760,29 @@ describe("Workspace and app executor environment contracts", () => {
     expect(offsetMinimalStart.env.AKAN_PUBLIC_CLIENT_PORT).toBe("8286");
     expect(offsetMinimalStart.env.AKAN_PUBLIC_SERVER_PORT).toBe("8286");
   });
+
+  test("pins the start command to development so an ambient NODE_ENV cannot pick the production router", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/ambient"), { recursive: true });
+    await writeFile(path.join(root, "apps/ambient/akan.config.ts"), "export default {};\n");
+
+    const originalNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+    try {
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      const started = await AppExecutor.from(workspace, "ambient").prepareCommand("start");
+      expect(started.env.NODE_ENV).toBe("development");
+      // The builder runs in this process and bakes NODE_ENV into the dev bundles it emits.
+      expect(process.env.NODE_ENV).toBe("development");
+    } finally {
+      if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
+      else process.env.NODE_ENV = originalNodeEnv;
+    }
+  });
 });
 
 describe("PkgExecutor package generation", () => {

package/executors.ts

@@ -233,7 +233,7 @@ export class Executor {
         );
       });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal)
+        if (code || signal)
           reject(
             new CommandExecutionError({
               command,
@@ -342,7 +342,7 @@ export class Executor {
         );
       });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal)
+        if (code || signal)
           reject(
             new CommandExecutionError({
               command: modulePath,
@@ -1364,6 +1364,12 @@ export class AppExecutor extends SysExecutor {
         this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true }),
       ]);
     } else await this.removeDir(".akan");
+    //? `akan start` is the dev server, and it must say so rather than inherit an answer. Bun auto-loads the
+    //? workspace `.env`, so NODE_ENV=production can reach this process without ever being exported in a shell —
+    //? and a dev server that believes it is production serves from the production route cache, whose every
+    //? route throws because a dev artifact carries no routes manifest. Written into `process.env` and not only
+    //? into the child env because the builder runs here and bakes NODE_ENV into the bundles it emits.
+    if (type === "start") process.env.NODE_ENV = "development";
     const devPort = type === "start" ? (await this.getDevPort()).toString() : undefined;
     const env = this.getCommandEnv({
       AKAN_COMMAND_TYPE: type,

package/incrementalBuilder/devWatchBatch.test.ts

@@ -22,27 +22,25 @@ describe("prepareDevWatchBatch", () => {
     expect(prepared.event.devPlan?.files).toEqual(prepared.files);
   });
 
-  test.each([
-    "common",
-    "srvkit",
-    "ui",
-    "webkit",
-  ])("keeps %s facet add/delete generated index in the same generation", (facet) => {
-    const root = "/repo";
-    const changedFile = `${root}/libs/shared/${facet}/tmpExample.ts`;
-    const generatedIndex = `${root}/libs/shared/${facet}/index.ts`;
-    const prepared = prepareDevWatchBatch({
-      generation: 20,
-      batch: { files: [changedFile], kinds: new Set(["code"]) },
-      indexSync: { changedFiles: [generatedIndex], errors: [] },
-      changePlanner: new DevChangePlanner({ workspaceRoot: root }),
-    });
+  test.each(["common", "srvkit", "ui", "webkit"])(
+    "keeps %s facet add/delete generated index in the same generation",
+    (facet) => {
+      const root = "/repo";
+      const changedFile = `${root}/libs/shared/${facet}/tmpExample.ts`;
+      const generatedIndex = `${root}/libs/shared/${facet}/index.ts`;
+      const prepared = prepareDevWatchBatch({
+        generation: 20,
+        batch: { files: [changedFile], kinds: new Set(["code"]) },
+        indexSync: { changedFiles: [generatedIndex], errors: [] },
+        changePlanner: new DevChangePlanner({ workspaceRoot: root }),
+      });
 
-    expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
-    expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
-    expect(prepared.event.devPlan?.roles).toContain("barrel");
-    expect(prepared.event.devPlan?.actions).toContain("sync-generated");
-  });
+      expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
+      expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
+      expect(prepared.event.devPlan?.roles).toContain("barrel");
+      expect(prepared.event.devPlan?.actions).toContain("sync-generated");
+    },
+  );
 
   test("marks failed generated index sync as an error generation", () => {
     const root = "/repo";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.13",
+  "version": "3.0.0-alpha.15",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.13",
+    "akanjs": "3.0.0-alpha.15",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",