@akanjs/devkit 3.0.0-beta.16 → 3.0.0-beta.18

package/executors.test.ts

@@ -727,7 +727,7 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
-  test("accepts metadata route exports during page key discovery", async () => {
+  test("accepts head route exports during page key discovery", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
@@ -737,24 +737,19 @@ describe("Workspace and app executor environment contracts", () => {
     await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
     await writeFile(
       path.join(root, "apps/demo/page/_layout.tsx"),
-      [
-        "export const head = null;",
-        "export const metadata = { title: 'Root' };",
-        "export default function Layout({ children }) { return children; }",
-        "",
-      ].join("\n"),
+      ["export const head = null;", "export default function Layout({ children }) { return children; }", ""].join("\n"),
     );
     await writeFile(
       path.join(root, "apps/demo/page/docs/_layout.tsx"),
       [
-        "export async function generateMetadata() { return { title: 'Docs' }; }",
+        "export async function generateHead() { return null; }",
         "export default function Layout({ children }) { return children; }",
         "",
       ].join("\n"),
     );
     await writeFile(
       path.join(root, "apps/demo/page/docs/intro.tsx"),
-      ["export const metadata = { title: 'Intro' };", "export default function Page() { return null; }", ""].join("\n"),
+      ["export const head = null;", "export default function Page() { return null; }", ""].join("\n"),
     );
 
     const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
@@ -767,7 +762,7 @@ describe("Workspace and app executor environment contracts", () => {
     ]);
   });
 
-  test("rejects conflicting metadata route exports during page key discovery", async () => {
+  test("rejects a metadata route export during page key discovery", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
@@ -776,47 +771,16 @@ describe("Workspace and app executor environment contracts", () => {
     await mkdir(path.join(root, "apps/demo/page"), { recursive: true });
     await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
     await writeFile(
-      path.join(root, "apps/demo/page/conflict.tsx"),
-      [
-        "export const metadata = { title: 'Conflict' };",
-        "export function generateMetadata() { return { title: 'Conflict' }; }",
-        "export default function Page() { return null; }",
-        "",
-      ].join("\n"),
+      path.join(root, "apps/demo/page/legacy.tsx"),
+      ["export const metadata = { title: 'Legacy' };", "export default function Page() { return null; }", ""].join(
+        "\n",
+      ),
     );
 
     const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
     const app = AppExecutor.from(workspace, "demo");
 
-    await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
-      "metadata and generateMetadata cannot both be exported",
-    );
-  });
-
-  test("rejects mixed head and metadata route export channels during page key discovery", 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/demo/page"), { recursive: true });
-    await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
-    await writeFile(
-      path.join(root, "apps/demo/page/mixed.tsx"),
-      [
-        "export const head = null;",
-        "export const metadata = { title: 'Mixed' };",
-        "export default function Page() { return null; }",
-        "",
-      ].join("\n"),
-    );
-
-    const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
-    const app = AppExecutor.from(workspace, "demo");
-
-    await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
-      "head/generateHead and metadata/generateMetadata cannot both be exported",
-    );
+    await expect(app.getPageKeys({ refresh: true })).rejects.toThrow('unsupported export "metadata"');
   });
 
   test("assigns start command ports from sorted app order", async () => {

package/index.ts

@@ -32,7 +32,6 @@ export type * from "./fileSys";
 export type * from "./frontendBuild";
 export type * from "./getDirname";
 export type * from "./getRelatedCnsts";
-export type * from "./guideline";
 export type * from "./incrementalBuilder";
 export type * from "./mobile";
 export type * from "./packageExportsMap";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.16",
+  "version": "3.0.0-beta.18",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -39,14 +39,16 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@earendil-works/pi-agent-core": "0.80.6",
-    "@earendil-works/pi-ai": "0.80.6",
-    "@earendil-works/pi-coding-agent": "0.80.6",
-    "@earendil-works/pi-tui": "0.80.6",
+    "@earendil-works/chord": "0.86.1",
+    "@earendil-works/pi-agent-core": "0.86.1",
+    "@earendil-works/pi-ai": "0.86.1",
+    "@earendil-works/pi-coding-agent": "0.86.1",
+    "@earendil-works/pi-telemetry": "0.86.1",
+    "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-beta.16",
+    "akanjs": "3.0.0-beta.18",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/piDependencyPins.test.ts

@@ -28,9 +28,11 @@ const readJson = async <T>(file: string) => (await Bun.file(file).json()) as T;
 
 const shrinkwrappedPins = async () => {
   const { packages } = await readJson<Shrinkwrap>(`${piDir}/npm-shrinkwrap.json`);
+  // Top-level entries only: a key with a second `node_modules/` in it is a *nested placement* of some other
+  // package's dependency, which a consumer's resolver reaches on its own and we have no business pinning.
   const entries = Object.entries(packages)
-    .map(([key, entry]) => [key.replace(/^node_modules\//, ""), entry.version ?? ""] as const)
-    .filter(([name]) => name.startsWith("@earendil-works/"));
+    .filter(([key]) => /^node_modules\/@earendil-works\/[^/]+$/.test(key))
+    .map(([key, entry]) => [key.replace(/^node_modules\//, ""), entry.version ?? ""] as const);
   return Object.fromEntries(entries);
 };
 

package/prompter.ts

@@ -2,7 +2,6 @@ import fsPromise from "node:fs/promises";
 import { input, select } from "@inquirer/prompts";
 
 import { getDirname } from "./getDirname";
-import type { GuideGenerateJson } from "./guideline";
 
 interface FileUpdateRequestProps {
   context: string;
@@ -34,12 +33,6 @@ export class Prompter {
     const guidelineRoot = await Prompter.#getGuidelineRoot();
     return (await fsPromise.readdir(guidelineRoot)).filter((name) => !name.startsWith("_")).sort();
   }
-  static async getGuideJson(guideName: string): Promise<GuideGenerateJson> {
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
-    const filePath = `${guidelineRoot}/${guideName}/${guideName}.generate.json`;
-    const guideJson = await fsPromise.readFile(filePath, "utf-8");
-    return JSON.parse(guideJson) as GuideGenerateJson;
-  }
   /**
    * The name is checked against the directory listing rather than interpolated straight into a path:
    * it arrives from an MCP tool argument, and an unknown one has to name the valid set instead of

package/qualityScanner.test.ts

@@ -26,7 +26,7 @@ afterEach(async () => {
 });
 
 describe("AkanQualityScanner abstract rule", () => {
-  test("warns on an abstract over the line limit and points at akan compact", async () => {
+  test("warns on an abstract over the line limit and says how to trim it", async () => {
     const root = await makeWorkspace({
       "apps/demo/lib/post/post.abstract.md": abstractOf(AbstractDoc.maxLines + 1),
       "apps/demo/lib/post/post.constant.ts": "export class Post {}\n",
@@ -41,7 +41,8 @@ describe("AkanQualityScanner abstract rule", () => {
     expect(warnings).toHaveLength(1);
     expect(warnings[0]?.file).toBe("apps/demo/lib/post/post.abstract.md");
     expect(warnings[0]?.message).toContain(`${AbstractDoc.maxLines + 1} lines`);
-    expect(warnings[0]?.fix).toContain("akan compact");
+    expect(warnings[0]?.fix).toContain("## Rules");
+    expect(warnings[0]?.fix).not.toContain("akan compact");
   });
 });
 

package/qualityScanner.ts

@@ -114,7 +114,7 @@ const RULE_FIXES: Record<string, string> = {
     "Split the file by responsibility — move Zones, Utils, or subcomponents into sibling files.",
   "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
   "akan.file.abstract-max-lines":
-    "Run `akan compact <app-or-lib>` to rewrite the abstract with the AI editor, keeping only the invariants and workflows the source files cannot show.",
+    "Trim the abstract by hand to a title, one sentence naming what the module owns, a `## Rules` list of the invariants the source cannot show, and an optional workflow chain.",
   "akan.file.placeholder-export":
     "Remove the placeholder export; generated indexes should only re-export real modules.",
   "akan.file.bang-comment-in-client":

package/routeSourceValidator.test.ts

@@ -15,7 +15,6 @@ describe("RouteSourceValidator", () => {
       "export const reconnect = true;",
       "export const wsConnect = true;",
       "export const layoutStyle = {};",
-      'export const gaTrackingId = "G-1";',
     ].join("\n");
 
     expect(() => validate(source, "layout", true)).not.toThrow();

package/routeSourceValidator.ts

@@ -86,18 +86,6 @@ export class RouteSourceValidator {
     if (exported.has("head") && exported.has("generateHead")) {
       throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
     }
-    if (
-      !options.rootLayout &&
-      (exported.has("head") || exported.has("generateHead")) &&
-      (exported.has("metadata") || exported.has("generateMetadata"))
-    ) {
-      throw new Error(
-        `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`,
-      );
-    }
-    if (exported.has("metadata") && exported.has("generateMetadata")) {
-      throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
-    }
     const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
     if (!chain) return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
     const named = [...exported].filter((name) => name !== "default");

package/scanInfo.ts

@@ -524,16 +524,19 @@ export class PkgInfo {
     const [tsconfig, rootPackageJson] = await Promise.all([exec.getTsConfig(), exec.workspace.getPackageJson()]);
     const scanner = await createDependencyScanner(exec);
     const npmSet = new Set(Object.keys({ ...rootPackageJson.dependencies, ...rootPackageJson.devDependencies }));
+    const workspacePathOf = (resolve: string) => resolve.replace(/^\.\//, "");
     const pkgPathSet = new Set(
       Object.keys(tsconfig.compilerOptions.paths ?? {})
-        .filter((path) => tsconfig.compilerOptions.paths?.[path]?.some((resolve) => resolve.startsWith("pkgs/")))
+        .filter((path) =>
+          tsconfig.compilerOptions.paths?.[path]?.some((resolve) => workspacePathOf(resolve).startsWith("pkgs/")),
+        )
         .map((path) => path.replace("/*", "")),
     );
     const [npmDepSet, pkgPathDepSet] = await scanner.getImportSets([npmSet, pkgPathSet]);
     const pkgDeps = [...pkgPathDepSet]
       .map((path) => {
         const pathSplitLength = path.split("/").length;
-        return (tsconfig.compilerOptions.paths?.[path]?.[0] ?? "*")
+        return workspacePathOf(tsconfig.compilerOptions.paths?.[path]?.[0] ?? "*")
           .split("/")
           .slice(1, 1 + pathSplitLength)
           .join("/");

package/workflow/executor.ts

@@ -1,3 +1,4 @@
+import { capitalize } from "akanjs/common";
 import ts from "typescript";
 import type { AkanModuleContext } from "../akanContext";
 import type { Sys, Workspace } from "../commandDecorators";
@@ -396,6 +397,54 @@ const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult =>
   };
 };
 
+const addMutationActionSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
+  const module = workflowStringInput(plan.inputs.module) ?? "<module>";
+  const mutation = workflowStringInput(plan.inputs.mutation) ?? "<mutation>";
+  const moduleClassName = moduleComponentName(module);
+  return {
+    recommendations: [
+      {
+        code: "add-mutation-action-surface-review",
+        kind: "manual-action",
+        target: `*/${moduleSourcePaths(module).store}`,
+        action: `Name the endpoint's guards and add its dictionary .endpoint() entry with a .desc(). After sync, fetch.${mutation} exists; write a store action only for a toast, an optimistic update, or a multi-field write, and put the control that calls it in ${moduleClassName}.Util.tsx.`,
+        confidence: "medium",
+        message: `Workflow apply does not write store or UI code for ${module}.${mutation}; review whether a screen should call it.`,
+      },
+    ],
+    nextActions: [
+      {
+        command: `akan workflow explain ${plan.workflow}`,
+        reason: "Review action surface guidance before manually editing store or UI files.",
+      },
+    ],
+  };
+};
+
+const addSliceViewSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
+  const module = workflowStringInput(plan.inputs.module) ?? "<module>";
+  const slice = workflowStringInput(plan.inputs.slice) ?? "<slice>";
+  const moduleClassName = moduleComponentName(module);
+  return {
+    recommendations: [
+      {
+        code: "add-slice-view-surface-review",
+        kind: "manual-action",
+        target: `*/${moduleSourcePaths(module).zone}`,
+        action: `Fill in the service query stub and add the dictionary .slice() entry. After sync, load fetch.init${moduleClassName}${capitalize(slice)}() in the page and pass the result to a ${moduleClassName}.Zone as an init prop.`,
+        confidence: "medium",
+        message: `Workflow apply does not write page or Zone code for ${module}.${slice}; review where the list should render.`,
+      },
+    ],
+    nextActions: [
+      {
+        command: `akan workflow explain ${plan.workflow}`,
+        reason: "Review view surface guidance before manually editing Zone or page files.",
+      },
+    ],
+  };
+};
+
 export const createWorkflowStepRegistry = ({
   workspace,
   createModule,
@@ -494,6 +543,8 @@ export const createWorkflowStepRegistry = ({
         }),
       ),
     [workflowStepKey("add-mutation", "update-signal")]: inspect,
+    [workflowStepKey("add-mutation", "update-action-surfaces")]: async (_step, plan) =>
+      addMutationActionSurfaceInspection(plan),
     [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addSlice({
@@ -503,6 +554,7 @@ export const createWorkflowStepRegistry = ({
         }),
       ),
     [workflowStepKey("add-slice", "update-signal-slice")]: inspect,
+    [workflowStepKey("add-slice", "connect-view-surfaces")]: async (_step, plan) => addSliceViewSurfaceInspection(plan),
   };
 };
 

package/workflow/source.ts

@@ -160,21 +160,27 @@ export const normalizeFieldType = (typeName: string) => {
   return normalizedTypes[typeName.toLowerCase()] ?? typeName;
 };
 
-export const ensureBaseTypeImport = (content: string, typeName: string) => {
-  if (typeName !== "Int" && typeName !== "Float") return content;
-  const source = sourceFileFor("constant.ts", content);
-  const baseImport = findNamedImport(source, "akanjs/base");
-  if (baseImport) {
-    if (baseImport.names.includes(typeName)) return content;
-    const nextNames = [...baseImport.names, typeName].sort();
+export const ensureNamedImport = (content: string, moduleSpecifier: string, name: string) => {
+  const source = sourceFileFor("source.ts", content);
+  const namedImport = findNamedImport(source, moduleSpecifier);
+  if (namedImport) {
+    if (namedImport.names.includes(name)) return content;
+    const nextNames = [...namedImport.names, name].sort();
     return spliceText(
       content,
-      baseImport.namedBindingsStart,
-      baseImport.namedBindingsEnd,
+      namedImport.namedBindingsStart,
+      namedImport.namedBindingsEnd,
       `{ ${nextNames.join(", ")} }`,
     );
   }
-  return `import { ${typeName} } from "akanjs/base";\n${content}`;
+  return `import { ${name} } from "${moduleSpecifier}";\n${content}`;
+};
+
+export const ensureBaseImport = (content: string, name: string) => ensureNamedImport(content, "akanjs/base", name);
+
+export const ensureBaseTypeImport = (content: string, typeName: string) => {
+  if (typeName !== "Int" && typeName !== "Float") return content;
+  return ensureBaseImport(content, typeName);
 };
 
 export type FieldDefaultValue = string | number | boolean | null;
@@ -200,12 +206,12 @@ const booleanDefault = (rawDefault: FieldDefaultValue): string | null => {
 };
 
 const dateDefault = (rawDefault: FieldDefaultValue): string | null => {
-  if (typeof rawDefault === "number" && Number.isFinite(rawDefault)) return `new Date(${rawDefault})`;
+  if (typeof rawDefault === "number" && Number.isFinite(rawDefault)) return `() => dayjs(${rawDefault})`;
   if (typeof rawDefault !== "string") return null;
   const trimmed = rawDefault.trim();
   if (!trimmed) return null;
-  if (trimmed === "now") return "new Date()";
-  if (!Number.isNaN(Date.parse(trimmed))) return `new Date(${JSON.stringify(trimmed)})`;
+  if (trimmed === "now") return "() => dayjs()";
+  if (!Number.isNaN(Date.parse(trimmed))) return `() => dayjs(${JSON.stringify(trimmed)})`;
   return null;
 };
 

package/codeAgent/agent/AkanAuthStorageBackend.ts

@@ -1,105 +0,0 @@
-import {
-  closeSync,
-  existsSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import path from "node:path";
-import type { AuthStorageBackend } from "@earendil-works/pi-coding-agent";
-
-/**
- * Credential store for `akan code`, in akan's own file rather than the engine's.
- *
- * The engine only asks for a locked read-modify-write over one opaque string, so satisfying its interface with
- * our own file keeps every key under `~/.akan/` — nothing lands in `~/.pi/` and a user who removes akan takes
- * their credentials with them.
- *
- * The lock is an exclusive-create sentinel rather than an advisory flock: two `akan code` processes refreshing
- * an OAuth token at the same moment would otherwise each write a token the other invalidates.
- */
-export class AkanAuthStorageBackend implements AuthStorageBackend {
-  readonly #authPath: string;
-  readonly #lockPath: string;
-
-  constructor(authPath: string) {
-    this.#authPath = authPath;
-    this.#lockPath = `${authPath}.lock`;
-  }
-
-  withLock<T>(fn: (current: string | undefined) => { result: T; next?: string }) {
-    this.#acquire();
-    try {
-      const { result, next } = fn(this.#read());
-      if (next !== undefined) this.#write(next);
-      return result;
-    } finally {
-      this.#release();
-    }
-  }
-
-  async withLockAsync<T>(fn: (current: string | undefined) => Promise<{ result: T; next?: string }>) {
-    this.#acquire();
-    try {
-      const { result, next } = await fn(this.#read());
-      if (next !== undefined) this.#write(next);
-      return result;
-    } finally {
-      this.#release();
-    }
-  }
-
-  #read() {
-    if (!existsSync(this.#authPath)) return undefined;
-    const text = readFileSync(this.#authPath, "utf8");
-    return text.trim() ? text : undefined;
-  }
-
-  #write(next: string) {
-    mkdirSync(path.dirname(this.#authPath), { recursive: true, mode: 0o700 });
-    const temp = `${this.#authPath}.${process.pid}.tmp`;
-    writeFileSync(temp, next, { mode: 0o600 });
-    renameSync(temp, this.#authPath);
-  }
-
-  #acquire() {
-    mkdirSync(path.dirname(this.#lockPath), { recursive: true, mode: 0o700 });
-    const deadline = Date.now() + 5_000;
-    for (;;) {
-      try {
-        closeSync(openSync(this.#lockPath, "wx"));
-        return;
-      } catch {
-        // A lock left behind by a killed process would block every later run, so it expires.
-        if (this.#lockIsStale() || Date.now() > deadline) {
-          try {
-            unlinkSync(this.#lockPath);
-          } catch {
-            // Another process won the race to clear it; retry the create.
-          }
-          continue;
-        }
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
-      }
-    }
-  }
-
-  #lockIsStale() {
-    try {
-      return Date.now() - Bun.file(this.#lockPath).lastModified > 30_000;
-    } catch {
-      return true;
-    }
-  }
-
-  #release() {
-    try {
-      unlinkSync(this.#lockPath);
-    } catch {
-      // Already gone — a stale-lock sweep by another process.
-    }
-  }
-}

package/guideline.ts

@@ -1,19 +0,0 @@
-export interface GuideScan {
-  type: "example" | "source" | "usage" | (string & {});
-  description: string;
-  path: string;
-  filterText?: string;
-  sample?: number;
-}
-export interface GuideUpdate {
-  filePath: string;
-  contents: string[];
-  rules: string[];
-}
-export interface GuideGenerateJson {
-  title: string;
-  description: string;
-  scans: GuideScan[];
-  update: GuideUpdate;
-  page?: string;
-}