@akanjs/devkit 3.1.2-rc.2 → 3.1.2-rc.3

package/akanApp/akanApp.host.ts

@@ -50,7 +50,7 @@ import {
   UNAVAILABLE_REDIS_HOST,
 } from "./devHostPolicy";
 
-const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route", "build-csr"]);
+const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route", "build-csr", "build-graph"]);
 
 const asMib = (bytes: number) => Math.round(bytes / 1024 / 1024);
 
@@ -504,7 +504,7 @@ export class AkanAppHost {
       await this.#handleInvalidate(message);
       return;
     }
-    if (message.type === "build-route-res" || message.type === "build-csr-res") {
+    if (message.type === "build-route-res" || message.type === "build-csr-res" || message.type === "build-graph-res") {
       const answer = this.#builderRequests.settle(message);
       if (!answer) {
         this.logger.verbose(`[builder] dropped a ${message.type} no live backend is waiting for (id=${message.id})`);
@@ -925,6 +925,8 @@ export class AkanAppHost {
       this.#sendToBackend({ type: "build-route-res", id: message.id, ok: false, error });
     else if (message.type === "build-csr")
       this.#sendToBackend({ type: "build-csr-res", id: message.id, ok: false, error });
+    else if (message.type === "build-graph")
+      this.#sendToBackend({ type: "build-graph-res", id: message.id, ok: false, error });
     else return false;
     return true;
   }
@@ -1308,7 +1310,7 @@ export class AkanAppHost {
       this.logger.verbose(`[csr] armed dev CSR rebuilds (${message.reason})`);
     }
     // Renumbered per backend generation; the failure replies below use that backend's own `message.id`.
-    if (message.type === "build-route" || message.type === "build-csr") {
+    if (message.type === "build-route" || message.type === "build-csr" || message.type === "build-graph") {
       const outgoing = this.#builderRequests.issue(message);
       if (this.#builder?.send(outgoing)) return;
       this.#builderRequests.withdraw(outgoing.id);

package/akanMcpContract.ts

@@ -321,6 +321,12 @@ export const readonlyMcpTools: McpToolDefinition[] = [
       "Legacy broad module context. Pass app in monorepos; prefer inspect_akan_context.moduleContext or fieldInsertionContext for typed add-field evidence.",
     inputSchema: { type: "object", properties: { app: stringProperty, module: stringProperty }, required: ["module"] },
   },
+  {
+    name: "get_graph",
+    description:
+      "Read-only Akan Graph from source, no dev server needed: models with their fields and relations, slices and endpoints with guards, the service methods and queries each calls, the store actions that fetch them, and the components and pages that use them. Every node and edge carries its source location. Pass app and/or module to scope a large workspace.",
+    inputSchema: { type: "object", properties: { app: stringProperty, module: stringProperty } },
+  },
   {
     name: "get_guideline",
     description: "Return an Akan agent guideline resource by name.",

package/incrementalBuilder/builderRequestRouter.ts

@@ -1,7 +1,4 @@
-import type { BuilderCsrReq, BuilderCsrRes, BuilderReq, BuilderRes } from "akanjs/server";
-
-type BuilderRequest = BuilderReq | BuilderCsrReq;
-type BuilderResponse = BuilderRes | BuilderCsrRes;
+import type { BuilderRequest, BuilderResponse } from "akanjs/server";
 
 // `BuilderRpc` numbers from 1 per backend process while the builder outlives backends, so ids collide across a
 // restart; host-owned ids keep a dead generation's answer from settling the new backend's request.

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -108,6 +108,7 @@ describe("IncrementalBuilderHost", () => {
     const { spawns, messages, host } = startRecordingHost();
     expect(host.send({ type: "build-route", id: 1, routeId: "a", seeds: [], knownEntries: [] })).toBe(true);
     expect(host.send({ type: "build-csr", id: 2, reason: "device webview" })).toBe(true);
+    expect(host.send({ type: "build-graph", id: 4 })).toBe(true);
     // Answered before the exit, so this one must not be failed again afterwards.
     expect(host.send({ type: "build-route", id: 3, routeId: "c", seeds: [], knownEntries: [] })).toBe(true);
     spawns[0]?.options.ipc?.({ type: "build-route-res", id: 3, ok: true, data: { routeId: "c" } });
@@ -129,6 +130,12 @@ describe("IncrementalBuilderHost", () => {
         ok: false,
         error: "builder exited to release bundler memory before answering; reload to retry",
       },
+      {
+        type: "build-graph-res",
+        id: 4,
+        ok: false,
+        error: "builder exited to release bundler memory before answering; reload to retry",
+      },
     ]);
 
     // The replacement owes nothing, so its own exit stays quiet.

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage } from "akanjs/server";
+import type { BuilderMessage, BuilderRequest } from "akanjs/server";
 import { CSR_DEV_DIRNAME, CSR_DEV_PATCHING_MARKER, SSR_DEV_DIRNAME } from "akanjs/server/hmr/csrDevManifest";
 import { MemoryLimit } from "akanjs/server/memoryLimit";
 import type { App } from "../commandDecorators";
@@ -9,6 +9,7 @@ import type { App } from "../commandDecorators";
 const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "build-route-res",
   "build-csr-res",
+  "build-graph-res",
   "builder-ready",
   "invalidate",
   "css-updated",
@@ -73,7 +74,7 @@ export class IncrementalBuilderHost {
   #manualStop = false;
   // Nothing else answers a request whose builder exits holding it: a crash or kill sends nothing, and a drain races
   // its own exit, so an unanswered page request would spin forever.
-  readonly #inFlight = new Map<number, "build-route" | "build-csr">();
+  readonly #inFlight = new Map<number, BuilderRequest["type"]>();
   #startOptions: IncrementalBuilderStartOptions = {};
   constructor({
     app,
@@ -129,7 +130,8 @@ export class IncrementalBuilderHost {
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
         if (!msg || typeof msg !== "object") return;
-        if (msg.type === "build-route-res" || msg.type === "build-csr-res") this.#inFlight.delete(msg.id);
+        if (msg.type === "build-route-res" || msg.type === "build-csr-res" || msg.type === "build-graph-res")
+          this.#inFlight.delete(msg.id);
         if (builderMsgTypeSet.has(msg.type)) this.#onMessage(msg);
         if (msg.type === "builder-ready" && !this.ready) {
           this.ready = true;
@@ -269,7 +271,8 @@ export class IncrementalBuilderHost {
     }
     try {
       this.#proc.send(message);
-      if (message.type === "build-route" || message.type === "build-csr") this.#inFlight.set(message.id, message.type);
+      if (message.type === "build-route" || message.type === "build-csr" || message.type === "build-graph")
+        this.#inFlight.set(message.id, message.type);
       return true;
     } catch (error) {
       this.logger.warn(

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -129,6 +129,69 @@ process.send({ type: "build-batch-result", data: { generation, errors, artifact:
     expect(messages.some((message) => message.type === "build-status")).toBe(false);
   }, 30_000);
 
+  test("draws the app's graph on request, with the libs it reaches and no other app", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation } = JSON.parse(process.argv[2]);
+process.send({ type: "build-batch-result", data: { generation, errors: {}, artifact: {}, optimizedFonts: { css: "", files: [] } } });
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    const moduleFiles = (owner: string, name: string) => {
+      const model = `${name[0].toUpperCase()}${name.slice(1)}`;
+      return [
+        writeText(
+          path.join(root, owner, `lib/${name}/${name}.constant.ts`),
+          `export class ${model} extends via((field) => ({ name: field(String) })) {}\n`,
+        ),
+        writeText(
+          path.join(root, owner, `lib/${name}/${name}.service.ts`),
+          `export class ${model}Service extends serve(db.${name}, () => ({})) {}\n`,
+        ),
+      ];
+    };
+    await Promise.all([
+      ...moduleFiles("apps/demo", "memo"),
+      ...moduleFiles("apps/other", "note"),
+      ...moduleFiles("libs/shared", "file"),
+    ]);
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({ type: "build-graph", id: 5 } satisfies BuilderMessage);
+      await until(proc, "build-graph-res", () => messages.some((message) => message.type === "build-graph-res"));
+    } finally {
+      proc.kill();
+      await proc.exited;
+    }
+    const answer = messages.find((message) => message.type === "build-graph-res");
+    if (answer?.type !== "build-graph-res" || !answer.ok) throw new Error(`no graph: ${JSON.stringify(answer)}`);
+    expect(answer.data.workspaceRoot).toBe(root);
+    expect(answer.data.graph.nodes.map((node) => node.id).sort()).toEqual([
+      "model:apps/demo:memo",
+      "model:libs/shared:file",
+    ]);
+  }, 30_000);
+
   test("answers a second shell request in the same generation without building again", async () => {
     const { root } = track(await createTempApp("demo"));
     const appDir = path.join(root, "apps/demo");

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -18,13 +18,16 @@ import { RouteClientBuilder } from "@akanjs/devkit/frontendBuild/routeClientBuil
 import { ServerGraphFile } from "@akanjs/devkit/frontendBuild/serverGraphFile";
 import { SsrDevBundler } from "@akanjs/devkit/frontendBuild/ssrDevBundler";
 import { WatchRootResolver } from "@akanjs/devkit/frontendBuild/watchRootResolver";
+import { WorkspaceGraph } from "@akanjs/devkit/workspaceGraph";
 import { Logger } from "akanjs/common";
 import type {
   BaseBuildArtifact,
   BuilderCsrReq,
+  BuilderGraphReq,
   BuilderMessage,
   BuilderReq,
   BuilderRes,
+  BuildGraphPayload,
   BuildPhase,
   BuildRouteResultPayload,
   ChangeBatch,
@@ -64,6 +67,7 @@ class IncrementalBuilder {
   #watcher: HmrWatcher | null = null;
   #generation = 0;
   #shellKey: string | null = null;
+  #graph: { generation: number; payload: BuildGraphPayload } | null = null;
   #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #csrBundler: CsrDevBundler;
@@ -873,6 +877,22 @@ class IncrementalBuilder {
     this.#logger.verbose(`announced boot state after recycle generation=${generation}`);
   }
 
+  async handleBuildGraph(msg: BuilderGraphReq): Promise<void> {
+    const generation = this.#generation;
+    try {
+      if (this.#graph?.generation !== generation) {
+        const { workspace } = this.#app;
+        const graph = WorkspaceGraph.visibleTo(await WorkspaceGraph.build(workspace), this.#app.name);
+        this.#graph = { generation, payload: { workspaceRoot: workspace.workspaceRoot, graph } };
+      }
+      await BuilderChannel.send({ type: "build-graph-res", id: msg.id, ok: true, data: this.#graph.payload });
+    } catch (err) {
+      const error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
+      this.#logger.error(`build-graph failed: ${error}`);
+      await BuilderChannel.send({ type: "build-graph-res", id: msg.id, ok: false, error });
+    }
+  }
+
   // On demand: dev serves CSR only via the opt-in `/__csr` and `?csr=true` routes; once built, it rebuilds every save.
   async handleBuildCsr(msg: BuilderCsrReq): Promise<void> {
     if (msg.shell) {
@@ -1080,13 +1100,18 @@ class IncrementalBuilder {
         void builder.shutdown(msg.reason);
         return;
       }
-      if (msg.type !== "build-route" && msg.type !== "build-csr") return;
+      if (msg.type !== "build-route" && msg.type !== "build-csr" && msg.type !== "build-graph") return;
       if (!builder || builder.shuttingDown) {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
         BuilderChannel.emit({ type: `${msg.type}-res`, id: msg.id, ok: false, error });
         return;
       }
-      const handled = msg.type === "build-route" ? builder.handleBuildRoute(msg) : builder.handleBuildCsr(msg);
+      const handled =
+        msg.type === "build-route"
+          ? builder.handleBuildRoute(msg)
+          : msg.type === "build-csr"
+            ? builder.handleBuildCsr(msg)
+            : builder.handleBuildGraph(msg);
       // Unhandled, a rejection (an ipc write that failed) would exit the builder and drop the watcher with it.
       void handled.catch((err: unknown) =>
         logger.error(`${msg.type} failed: ${err instanceof Error ? err.message : String(err)}`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.2-rc.2",
+  "version": "3.1.2-rc.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.1.2-rc.2",
+    "@akanjs/language": "3.1.2-rc.3",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.2-rc.2",
+    "akanjs": "3.1.2-rc.3",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/workspaceGraph.ts

@@ -0,0 +1,73 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { type AkanGraph, type AkanGraphNode, AkanIndex } from "@akanjs/language";
+import ts from "typescript";
+import type { Workspace } from "./commandDecorators";
+
+export interface GraphScope {
+  app?: string | null;
+  module?: string | null;
+}
+
+//? `env/` holds each environment's secrets in plain TypeScript; the graph never needs to read it.
+const indexedPath = /^(apps|libs)\/(?!(?:.*\/)?(?:node_modules|dist|\.akan|env)\/).*\.tsx?$/;
+const unscopedNodeLimit = 600;
+const slashed = (fileName: string) => fileName.replace(/\\/g, "/");
+
+export class WorkspaceGraph {
+  static async build(workspace: Workspace): Promise<AkanGraph> {
+    const root = workspace.workspaceRoot;
+    const index = new AkanIndex({ ts, root });
+    const texts = new Map<string, string>();
+    const files = (await workspace.getAllFiles("{apps,libs}/**/*.{ts,tsx}"))
+      .map(slashed)
+      .filter((file) => indexedPath.test(file));
+    await Promise.all(
+      files.map(async (file) => {
+        const fileName = slashed(path.join(root, file));
+        const text = await readFile(fileName, "utf8");
+        texts.set(fileName, text);
+        index.setFile(fileName, text);
+      }),
+    );
+    return index.graph((fileName) => texts.get(fileName));
+  }
+
+  static scope(graph: AkanGraph, { app, module }: GraphScope): AkanGraph {
+    if (!app && !module) return graph;
+    const owners = app ? new Set([`apps/${app}`, `libs/${app}`]) : null;
+    const seeds = new Set(
+      graph.nodes
+        .filter((node) => (!owners || owners.has(node.owner ?? "")) && (!module || node.module === module))
+        .map((node) => node.id),
+    );
+    const edges = graph.edges.filter((edge) => seeds.has(edge.from) || seeds.has(edge.to));
+    const ids = new Set([...seeds, ...edges.flatMap((edge) => [edge.from, edge.to])]);
+    return { version: 1, nodes: graph.nodes.filter((node) => ids.has(node.id)), edges };
+  }
+
+  static visibleTo(graph: AkanGraph, app: string): AkanGraph {
+    const appOwner = `apps/${app}`;
+    const isVisible = ({ owner }: AkanGraphNode) => !owner || owner === appOwner || owner.startsWith("libs/");
+    const nodes = graph.nodes.filter(isVisible);
+    const ids = new Set(nodes.map((node) => node.id));
+    return { version: 1, nodes, edges: graph.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to)) };
+  }
+
+  static answer(graph: AkanGraph, scope: GraphScope) {
+    if (scope.app || scope.module || graph.nodes.length <= unscopedNodeLimit) return WorkspaceGraph.scope(graph, scope);
+    const owners = new Map<string, number>();
+    for (const node of graph.nodes) if (node.owner) owners.set(node.owner, (owners.get(node.owner) ?? 0) + 1);
+    return {
+      diagnostics: [
+        {
+          severity: "error",
+          code: "graph-scope-required",
+          message: `The graph has ${graph.nodes.length} nodes. Pass app, module or both to scope it.`,
+          input: "app",
+        },
+      ],
+      owners: Object.fromEntries([...owners].sort(([a], [b]) => (a < b ? -1 : 1))),
+    };
+  }
+}