@akanjs/devkit 3.0.0-alpha.1 → 3.0.0-alpha.11

package/frontendBuild/precompressArtifacts.ts

@@ -1,26 +1,41 @@
 import fs from "node:fs";
 import path from "node:path";
+import zlib from "node:zlib";
 import type { App } from "../commandDecorators";
 
 const COMPRESSIBLE_EXTS = new Set([".css", ".html", ".js", ".json", ".svg"]);
 const MIN_COMPRESS_BYTES = 1024;
+/**
+ * Quality 11 is roughly 100x slower than gzip, so it is spent only where it pays: there is one CSS asset
+ * per basePath and it is the largest single file the app ships, worth ~20% over gzip for ~0.2s. Raising the
+ * several hundred JS chunks from 9 to 11 costs ~12s of build time to save a few hundred KB, so they stay at 9.
+ */
+const BROTLI_QUALITY_BY_EXT = { ".css": 11 } as const;
+const DEFAULT_BROTLI_QUALITY = 9;
+const GZIP_LEVEL = 9;
 
 export interface PrecompressArtifactsResult {
   files: number;
   inputBytes: number;
   outputBytes: number;
+  brotliBytes: number;
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  const roots = [path.join(app.dist.cwdPath, ".akan/artifact/client")];
-  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0 };
+  //* styles too: WebRouter serves both prefixes through the same sidecar-aware #fileResponse, and the
+  //* one CSS asset per basePath is the largest uncompressed payload the app ships.
+  const roots = [
+    path.join(app.dist.cwdPath, ".akan/artifact/client"),
+    path.join(app.dist.cwdPath, ".akan/artifact/styles"),
+  ];
+  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0, brotliBytes: 0 };
 
   await Promise.all(roots.map((root) => precompressRoot(root, result)));
   if (result.files > 0) {
     app.verbose(
-      `[precompress] wrote ${result.files} gzip sidecars (${formatBytes(result.inputBytes)} -> ${formatBytes(
+      `[precompress] wrote ${result.files} sidecars (${formatBytes(result.inputBytes)} -> gzip ${formatBytes(
         result.outputBytes,
-      )})`,
+      )} / br ${formatBytes(result.brotliBytes)})`,
     );
   }
   return result;
@@ -32,16 +47,29 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
   for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
     if (!(await shouldPrecompress(filePath))) continue;
     const bytes = await Bun.file(filePath).bytes();
-    const gz = Bun.gzipSync(toArrayBuffer(bytes));
-    await Bun.write(`${filePath}.gz`, gz);
+    const buffer = toArrayBuffer(bytes);
+    const gz = Bun.gzipSync(buffer, { level: GZIP_LEVEL });
+    const br = brotliCompress(buffer, path.extname(filePath).toLowerCase());
+    await Promise.all([Bun.write(`${filePath}.gz`, gz), Bun.write(`${filePath}.br`, br)]);
     result.files += 1;
     result.inputBytes += bytes.byteLength;
     result.outputBytes += gz.byteLength;
+    result.brotliBytes += br.byteLength;
   }
 }
 
+function brotliCompress(buffer: ArrayBuffer, ext: string): Buffer {
+  const quality = BROTLI_QUALITY_BY_EXT[ext as keyof typeof BROTLI_QUALITY_BY_EXT] ?? DEFAULT_BROTLI_QUALITY;
+  return zlib.brotliCompressSync(buffer, {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: buffer.byteLength,
+    },
+  });
+}
+
 async function shouldPrecompress(filePath: string): Promise<boolean> {
-  if (filePath.endsWith(".gz")) return false;
+  if (filePath.endsWith(".gz") || filePath.endsWith(".br")) return false;
   if (!COMPRESSIBLE_EXTS.has(path.extname(filePath).toLowerCase())) return false;
   const file = Bun.file(filePath);
   if (!(await file.exists())) return false;

package/frontendBuild/routeClientBuilder.ts

@@ -33,6 +33,15 @@ export interface BuildRouteClientOptions {
   routeId?: string;
   command?: "build" | "start";
   discovery?: ClientEntryDiscovery;
+  /**
+   * Client entries resolved by the caller, which skips discovery and bundles exactly this list.
+   *
+   * `AllRoutesBuilder` passes every route's entries at once so they share one `Bun.build`. Chunk
+   * splitting is scoped to a single invocation, so a dependency reachable from entries spread across
+   * several invocations is emitted once per invocation — mermaid landed in `apps/akan` four times that
+   * way. Dev keeps one build per route and leaves this unset.
+   */
+  entries?: string[];
 }
 
 export interface BuildRouteClientResult {
@@ -61,6 +70,7 @@ export class RouteClientBuilder {
   #knownEntries: Set<string>;
   #command: "build" | "start";
   #discovery?: ClientEntryDiscovery;
+  #entries?: string[];
 
   constructor(options: BuildRouteClientOptions) {
     this.#app = options.app;
@@ -68,11 +78,13 @@ export class RouteClientBuilder {
     this.#knownEntries = options.knownEntries ?? new Set<string>();
     this.#command = options.command ?? "start";
     this.#discovery = options.discovery;
+    this.#entries = options.entries;
   }
 
   async build(): Promise<BuildRouteClientResult> {
-    const discovery = this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app));
-    const discovered = await discovery.discover(this.#seeds);
+    const discovered =
+      this.#entries ??
+      (await (this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app))).discover(this.#seeds));
     const entries = discovered.filter((e) => !this.#knownEntries.has(e));
     if (entries.length === 0) return this.#emptyResult(discovered);
 

package/lint/no-bang-comment-in-client.grit

@@ -0,0 +1,20 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Bun's bundler classifies `//!` and `/*!` as legal comments (the `@license` / `@preserve` class) and keeps
+// them through `minify: true`, so a `//!` marker in browser-reachable code ships verbatim to every visitor.
+// `legalComments` is not a Bun.build option, so the source is the only place to stop it.
+// The two alternatives anchor the marker to line start or to whitespace after code, which keeps a literal
+// like `'https://host//!path'` from tripping the rule. A marker on the file's very first line is trivia that
+// Biome does not expose to the pattern, so it is the one case this rule cannot see.
+JsModule() as $mod where {
+  or {
+    $mod <: r"(?m)(?s).*^[ \t]*//!.*",
+    $mod <: r"(?s).*[^\s/][ \t]+//!.*"
+  },
+  register_diagnostic(
+    span = $mod,
+    message = "The `//!` marker survives minification (Bun keeps it as a legal comment) and ships to the browser. Use `// FIXME:` or `// TODO:` in client-reachable code; keep `//!` for server, srvkit, and CLI files.",
+    severity = "error"
+  )
+}

package/lint/no-import-client-in-server.grit

@@ -0,0 +1,48 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Server files (*.document.ts, *.dictionary.ts, *.service.ts, *.signal.ts, srvkit/) and shared files
+// (common/, *.constant.ts) run in Bun with no DOM and no bundler, and every CLI command, worker, and
+// migration that loads a service loads whatever the service imports. Reaching into the client graph
+// pulls React, the store, and the browser globals they touch into that process, and it runs the
+// dependency backwards: the client entrypoint is built on top of cnst and sig, not the other way round.
+//
+// `import type` is erased before bundling and stays legal. A mixed value-and-type import is not exempt.
+or {
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\".*\.store\"",
+      r"\".*\.(?:Template|Unit|Util|View|Zone)\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Client module. A server or shared file must not import a *.store or a module component (*.Template, *.Unit, *.Util, *.View, *.Zone) — server code reaches the model through cnst and db, never through client state or JSX.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\"(?:.*/)?(?:ui|webkit)(?:/.*)?\"",
+      r"\".*/client(?:/.*)?\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Client entrypoint. A server or shared file must not import ui/, webkit/, or a package client entrypoint such as '@libs/<lib>/client' or 'akanjs/client' — import the server entrypoint or a common/ helper instead.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\"(?:.*/)?(?:st|store|useClient)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Client barrel. A server or shared file must not import st, store, or useClient — server code holds no client state, and Err comes from dict on the server.",
+      severity = "error"
+    )
+  }
+}

package/lint/no-import-server-in-client.grit

@@ -0,0 +1,45 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Client files (ui/, webkit/, page/, *.store.ts, every .tsx) and shared files (common/, *.constant.ts)
+// are compiled into the browser bundle, so a single value import of a server module drags its whole
+// graph along — the database driver, node:crypto, a secret resolved from process.env. The boundary has
+// to hold at the import statement, because by the call site the module is already bundled.
+//
+// `import type` is erased before bundling and stays legal, so a shared file may still name a server-side
+// type. A mixed value-and-type import is not exempt: it emits a real edge.
+or {
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\".*\.(?:document|dictionary|service|signal)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Server module. A client or shared file must not import a *.document, *.dictionary, *.service, or *.signal file — take the model from the package client entrypoint ('@libs/<lib>/client') or from its *.constant instead. Write 'import type' if only the type is needed.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\"(?:.*/)?srvkit(?:/.*)?\"",
+      r"\".*/server(?:/.*)?\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Server entrypoint. A client or shared file must not import srvkit/ or a package server entrypoint such as '@apps/<app>/server' or 'akanjs/server' — import the matching client entrypoint instead.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\"(?:.*/)?(?:db|srv|sig|dict|option|useServer)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Server barrel. A client or shared file must not import db, srv, sig, dict, option, or useServer — read models from cnst, state from st, and Err from the package client entrypoint.",
+      severity = "error"
+    )
+  }
+}

package/lint/no-return-in-store-action.grit

@@ -0,0 +1,35 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Every prototype method of a `store(...)` class is registered as an action
+// (StoreRegistry.register) and reaches callers only as `st.do.<action>`, which re-wraps it
+// (StoreInstance.#extendAccessors) and is typed void by `VoidActions` in
+// pkgs/akanjs/store/types.ts. A returned value is therefore unreachable from every call
+// site — it reads like a contract while being dead code. Write the result into state with
+// `this.set({ ... })` instead.
+//
+// Deliberately not flagged, because none of these are actions: a bare `return;` guard, a
+// `return` belonging to a nested callback, a getter, a `static` helper, and a class-property
+// arrow (an instance field, so `register` never sees it).
+`return $value;` as $return where {
+  not $value <: r"",
+  $return <: within JsClassDeclaration() as $storeClass where {
+    $storeClass <: contains JsExtendsClause() as $extends where {
+      $extends <: r"extends\s+store\([\s\S]*"
+    }
+  },
+  $return <: within JsMethodClassMember() as $action where {
+    not $action <: r"static[\s\S]*"
+  },
+  not $return <: within JsArrowFunctionExpression(),
+  not $return <: within JsFunctionExpression(),
+  not $return <: within JsFunctionDeclaration(),
+  not $return <: within JsMethodObjectMember(),
+  not $return <: within JsGetterObjectMember(),
+  not $return <: within JsSetterObjectMember(),
+  register_diagnostic(
+    span = $return,
+    message = "Store actions dispatch as void — st.do.<action>() never exposes this value. Write the result into state with this.set({ ... }) and drop the returned value; a bare 'return;' guard clause is fine.",
+    severity = "error"
+  )
+}

package/linter.ts

@@ -58,19 +58,31 @@ interface LintResponse {
   warnings: LintMessage[];
 }
 
+/** Biome reads `biome.json` first and `biome.jsonc` second; only the latter may carry comments. */
+const BIOME_CONFIG_FILES = ["biome.json", "biome.jsonc"] as const;
+
 export class Linter {
   lintRoot: string;
+  configPath: string;
   #biomeBin: string;
 
   constructor(cwdPath: string) {
     this.lintRoot = this.#findBiomeRootPath(cwdPath);
+    this.configPath = Linter.#configPathIn(this.lintRoot) ?? path.join(this.lintRoot, "biome.json");
     const localBiomeBin = path.join(this.lintRoot, "node_modules/.bin/biome");
     this.#biomeBin = existsSync(localBiomeBin) ? localBiomeBin : "biome";
   }
 
+  static #configPathIn(dir: string): string | null {
+    for (const fileName of BIOME_CONFIG_FILES) {
+      const configPath = path.join(dir, fileName);
+      if (existsSync(configPath)) return configPath;
+    }
+    return null;
+  }
+
   #findBiomeRootPath(dir: string): string {
-    const configPath = path.join(dir, "biome.json");
-    if (existsSync(configPath)) return dir;
+    if (Linter.#configPathIn(dir)) return dir;
     const parentDir = path.dirname(dir);
     if (parentDir === dir) throw new Error(`biome.json not found from ${dir}`);
     return this.#findBiomeRootPath(parentDir);
@@ -193,7 +205,7 @@ export class Linter {
       "--max-diagnostics=none",
       "--no-errors-on-unmatched",
       "--config-path",
-      path.join(this.lintRoot, "biome.json"),
+      this.configPath,
       this.#toBiomePath(filePath),
     ]);
     const report = this.#parseBiomeReport(stdout || stderr);
@@ -390,14 +402,7 @@ export class Linter {
 
     const source = readFileSync(resolvedFilePath, "utf8");
     const { stdout } = await this.#runBiome(
-      [
-        "check",
-        "--write",
-        "--config-path",
-        path.join(this.lintRoot, "biome.json"),
-        "--stdin-file-path",
-        this.#toBiomePath(resolvedFilePath),
-      ],
+      ["check", "--write", "--config-path", this.configPath, "--stdin-file-path", this.#toBiomePath(resolvedFilePath)],
       source,
     );
     const lintResult = await this.lintFile(resolvedFilePath);
@@ -412,7 +417,7 @@ export class Linter {
   async getConfigForFile(filePath: string): Promise<unknown> {
     const resolvedFilePath = this.#resolveFilePath(filePath);
     if (!existsSync(resolvedFilePath)) throw new Error(`File not found: ${filePath}`);
-    return JSON.parse(readFileSync(path.join(this.lintRoot, "biome.json"), "utf8")) as unknown;
+    return JSON.parse(readFileSync(this.configPath, "utf8")) as unknown;
   }
 
   /**

package/mcpScanner.ts

@@ -0,0 +1,217 @@
+import path from "node:path";
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+interface ExposedDeclaration {
+  name: string;
+  kind: "endpoint" | "slice";
+  line: number;
+  /** `unknown` when the option object holds a spread, where a `guards` key may arrive from somewhere unreadable. */
+  guards: "declared" | "missing" | "unknown";
+}
+
+/**
+ * Checks the two things about an MCP exposure that source alone can answer: that it carries a description an agent
+ * can act on, and that somebody decided who may call it.
+ *
+ * A tool's name and argument names are the only other thing a model sees, and neither says what the tool is for
+ * or when to reach for it. An undescribed tool is not merely undocumented — it is a tool the model will either
+ * skip or call wrongly, so this rides with the exposure decision rather than with general dictionary hygiene.
+ *
+ * Guards are here because the omission is *syntactic*: the `guards` key sits in the same option literal as
+ * `mcp: { expose: true }`, and a named slice inherits nothing from the `slice()` call's own guards map. So the
+ * shape that publishes an unguarded read without anyone writing it down is visible in the file, with no resolved
+ * types needed — which is what makes it worth checking here rather than only in a boot log.
+ *
+ * The generated CRUD a slice opts in through `mcp: { get: true }` is checked by neither rule: none of those
+ * entries has text of its own to leave out, so each borrows the model's — the `.of()` label as a title, the model
+ * `.desc()` appended to the framework's "Get X" as a description — and each takes the `slice()` guards map, which
+ * is the one place those guards do reach.
+ *
+ * It reads source, so it finds `mcp: { expose: true }` only where an author writes it as a literal inside the
+ * `slice(` / `endpoint(` call — an option hoisted to a `const`, or an `expose: flag`, is invisible to it. Right
+ * for a warning that must not fire on something it merely failed to resolve, but it makes a clean scan "nothing
+ * obviously wrong" rather than "everything exposed is described and guarded". The complete answer is the boot log:
+ * `McpRouter.report()` holds the resolved catalogue and names every published entry with no description and every
+ * one with no guards, generated entries included — and the refusals, which turn on a resolved return type and so
+ * are the one class this file could never see.
+ */
+export class McpScanner {
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const dictionaries = new Map(
+      sourceFiles
+        .filter((sourceFile) => sourceFile.file.endsWith(".dictionary.ts"))
+        .map((sourceFile) => [path.dirname(sourceFile.file), sourceFile]),
+    );
+    return sourceFiles
+      .filter((sourceFile) => sourceFile.file.endsWith(".signal.ts"))
+      .flatMap((sourceFile) => this.#scanSignal(sourceFile, dictionaries.get(path.dirname(sourceFile.file))));
+  }
+
+  #scanSignal(signal: SourceFileInfo, dictionary: SourceFileInfo | undefined): QualityWarning[] {
+    const exposed = McpScanner.#exposedDeclarations(signal);
+    if (!exposed.length) return [];
+    const refName = path.basename(signal.file, ".signal.ts").replace(/^_+/, "");
+    const described = dictionary ? McpScanner.#describedEntries(dictionary) : new Map<string, Set<string>>();
+    return [
+      ...exposed
+        .filter(({ name, kind }) => !McpScanner.#isDescribed(described, refName, name, kind))
+        .map(({ name, kind, line }) => ({
+          rule: "akan.mcp.missing-description",
+          scope: "mcp" as const,
+          severity: "warning" as const,
+          file: signal.file,
+          line,
+          message: `MCP-exposed ${kind} "${name}" has no dictionary .desc(); an agent sees its name and nothing else.`,
+        })),
+      ...exposed
+        .filter(({ guards }) => guards === "missing")
+        .map(({ name, kind, line }) => ({
+          rule: "akan.mcp.unguarded-exposure",
+          scope: "mcp" as const,
+          severity: "warning" as const,
+          file: signal.file,
+          line,
+          message: `MCP-exposed ${kind} "${name}" declares no guards; a slice's guards map never reaches a named slice.`,
+        })),
+    ];
+  }
+
+  static #isDescribed(described: Map<string, Set<string>>, refName: string, name: string, kind: string) {
+    if (described.get(kind)?.has(name)) return true;
+    // A slice may instead be described through the endpoint it generates, which is how a dictionary that wants
+    // separate wording for the list reads (`bannerListInPublic`).
+    return kind === "slice" && !!described.get("endpoint")?.has(`${refName}List${McpScanner.#capitalize(name)}`);
+  }
+
+  /** Names declared with `mcp: { expose: true }`, keyed by whether they sit in the slice or endpoint builder. */
+  static #exposedDeclarations(signal: SourceFileInfo): ExposedDeclaration[] {
+    const found: ExposedDeclaration[] = [];
+    const visit = (node: ts.Node) => {
+      if (McpScanner.#isExposeOption(node)) {
+        const declaration = McpScanner.#enclosingDeclaration(node, signal.sourceFile);
+        if (declaration) found.push(declaration);
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(signal.sourceFile);
+    return found;
+  }
+
+  static #isExposeOption(node: ts.Node) {
+    if (!ts.isPropertyAssignment(node) || McpScanner.#propertyName(node) !== "mcp") return false;
+    if (!ts.isObjectLiteralExpression(node.initializer)) return false;
+    return node.initializer.properties.some(
+      (property) =>
+        ts.isPropertyAssignment(property) &&
+        McpScanner.#propertyName(property) === "expose" &&
+        property.initializer.kind === ts.SyntaxKind.TrueKeyword,
+    );
+  }
+
+  /**
+   * The name is the property holding the builder chain the option sits in — `inCategory: init({ mcp })…` or
+   * `echoTitle: builder.query(String, { mcp })…` — and the kind is the factory that property is declared inside.
+   * Reading the kind from the factory rather than from the chain's first identifier keeps it right when a slice
+   * callback names its parameter something other than `init`.
+   */
+  static #enclosingDeclaration(option: ts.Node, sourceFile: ts.SourceFile): ExposedDeclaration | null {
+    let declaration: ts.PropertyAssignment | null = null;
+    for (let node = option.parent; node; node = node.parent) {
+      if (!declaration && ts.isPropertyAssignment(node)) {
+        declaration = node;
+        continue;
+      }
+      const kind = McpScanner.#factoryKind(node);
+      if (!kind || !declaration) continue;
+      const name = McpScanner.#propertyName(declaration);
+      if (!name) return null;
+      const line = sourceFile.getLineAndCharacterOfPosition(declaration.getStart(sourceFile)).line + 1;
+      return { name, kind, line, guards: McpScanner.#guardState(option) };
+    }
+    return null;
+  }
+
+  /**
+   * Read off the literal the `mcp` option sits in, which is the same literal `guards` belongs to — `init({ guards,
+   * mcp })`, `query(cnst.X, { guards, mcp })`. A spread in there makes the answer unreadable rather than missing,
+   * and a warning that fires on what it merely failed to resolve is worse than one that stays quiet.
+   */
+  static #guardState(option: ts.Node): ExposedDeclaration["guards"] {
+    const options = option.parent;
+    if (!ts.isObjectLiteralExpression(options)) return "unknown";
+    if (options.properties.some((property) => ts.isSpreadAssignment(property))) return "unknown";
+    return options.properties.some(
+      (property) => ts.isPropertyAssignment(property) && McpScanner.#propertyName(property) === "guards",
+    )
+      ? "declared"
+      : "missing";
+  }
+
+  static #factoryKind(node: ts.Node): ExposedDeclaration["kind"] | null {
+    if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return null;
+    const factory = node.expression.text;
+    return factory === "slice" || factory === "endpoint" ? factory : null;
+  }
+
+  /** Entry names that carry a `.desc()`, per dictionary stage. */
+  static #describedEntries(dictionary: SourceFileInfo): Map<string, Set<string>> {
+    const described = new Map<string, Set<string>>();
+    const visit = (node: ts.Node) => {
+      const stage = McpScanner.#dictionaryStage(node);
+      if (stage) {
+        for (const [name, chain] of McpScanner.#stageEntries(node as ts.CallExpression)) {
+          if (!chain.has("desc")) continue;
+          const names = described.get(stage) ?? new Set<string>();
+          names.add(name);
+          described.set(stage, names);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(dictionary.sourceFile);
+    return described;
+  }
+
+  static #dictionaryStage(node: ts.Node) {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return null;
+    const stage = node.expression.name.text;
+    return stage === "endpoint" || stage === "slice" ? stage : null;
+  }
+
+  static #stageEntries(stage: ts.CallExpression): Array<[string, Set<string>]> {
+    const callback = stage.arguments[0];
+    if (!callback || !ts.isArrowFunction(callback)) return [];
+    const body = ts.isParenthesizedExpression(callback.body) ? callback.body.expression : callback.body;
+    if (!ts.isObjectLiteralExpression(body)) return [];
+    return body.properties.flatMap((property) => {
+      if (!ts.isPropertyAssignment(property)) return [];
+      const name = McpScanner.#propertyName(property);
+      return name ? [[name, McpScanner.#chainCalls(property.initializer)] as [string, Set<string>]] : [];
+    });
+  }
+
+  /**
+   * Only the calls on the entry's own chain. A nested `.arg((t) => ({ x: t([…]).desc([…]) }))` describes an
+   * argument, not the entry, so a subtree walk would read every entry as described.
+   */
+  static #chainCalls(expression: ts.Expression): Set<string> {
+    const calls = new Set<string>();
+    let current: ts.Node = expression;
+    while (ts.isCallExpression(current) || ts.isPropertyAccessExpression(current)) {
+      if (ts.isPropertyAccessExpression(current)) calls.add(current.name.text);
+      current = current.expression;
+    }
+    return calls;
+  }
+
+  static #propertyName(property: ts.PropertyAssignment) {
+    const { name } = property;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+    return null;
+  }
+
+  static #capitalize(value: string) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.11",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -23,6 +23,7 @@
       "default": "./index.ts"
     },
     "./package.json": "./package.json",
+    "./biome.base.json": "./biome.base.json",
     "./akanApp": "./akanApp/index.ts",
     "./akanConfig": "./akanConfig/index.ts",
     "./artifact": "./artifact/index.ts",
@@ -44,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.1",
+    "akanjs": "3.0.0-alpha.11",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",