@akanjs/devkit 3.1.2-rc.1 → 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

@@ -188,6 +188,8 @@ export const defaultWorkflowPlanPath = (workflow: string, inputs: WorkflowPlanIn
     slugPart(inputs.surface),
     slugPart(inputs.mutation),
     slugPart(inputs.slice),
+    slugPart(inputs.query),
+    slugPart(inputs.to),
   ]
     .filter(Boolean)
     .join("-");
@@ -319,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/codeAgent/skills/akan-scaffold/SKILL.md

@@ -32,6 +32,7 @@ Then pick the workflow that matches the intent:
 | a new field with a closed set of values | `add-enum-field` |
 | a new state-changing action | `add-mutation` |
 | a filtered list, tab, or reusable query | `add-slice` |
+| a slice or query key renamed, with every name derived from it | `rename-key` |
 | a View / Unit / Template / Zone / Util for an existing module | `create-ui` |
 
 ## The chain

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.1",
+  "version": "3.1.2-rc.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.1.2-rc.1",
+    "@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.1",
+    "akanjs": "3.1.2-rc.3",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/workflow/executor.ts

@@ -404,6 +404,7 @@ export const createWorkflowStepRegistry = ({
   addEnumField,
   addMutation,
   addSlice,
+  renameKey,
   createInteraction,
 }: WorkflowPrimitiveOperations): WorkflowStepRegistry => {
   const inspect = async () => undefined;
@@ -520,6 +521,16 @@ export const createWorkflowStepRegistry = ({
       ),
     [workflowStepKey("add-slice", "update-signal-slice")]: inspect,
     [workflowStepKey("add-slice", "connect-view-surfaces")]: async (_step, plan) => addSliceViewSurfaceInspection(plan),
+    [workflowStepKey("rename-key", "rename-key")]: async (_step, plan) =>
+      primitiveReportToWorkflowStepResult(
+        await renameKey({
+          app: workflowStringInput(plan.inputs.app),
+          module: workflowStringInput(plan.inputs.module),
+          slice: workflowStringInput(plan.inputs.slice),
+          query: workflowStringInput(plan.inputs.query),
+          to: workflowStringInput(plan.inputs.to),
+        }),
+      ),
   };
 };
 

package/workflow/index.ts

@@ -2,6 +2,7 @@ export * from "./artifacts";
 export * from "./executor";
 export * from "./guardCatalog";
 export * from "./interactionScaffold";
+export * from "./keyRename";
 export * from "./moduleIndex";
 export * from "./mutationScaffold";
 export * from "./mutationSource";

package/workflow/keyRename.ts

@@ -0,0 +1,78 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { AkanIndex, type AkanRenameEdit } from "@akanjs/language";
+import ts from "typescript";
+import type { Workspace } from "../commandDecorators";
+import { resolveWorkflowSys } from "./executor";
+import { getSysRoot, moduleSourcePaths } from "./source";
+import type { RenameKeyInput, ScaffoldFile, WorkflowDiagnostic } from "./types";
+
+const indexedPath = /^(apps|libs)\/(?!(?:.*\/)?(?:node_modules|dist|\.akan)\/).*\.tsx?$/;
+const keyPattern = /^[a-z][A-Za-z0-9]*$/;
+const slashed = (fileName: string) => fileName.replace(/\\/g, "/");
+
+const refuse = (code: string, input: string, message: string) => ({
+  diagnostics: [{ severity: "error", code, input, message }] satisfies WorkflowDiagnostic[],
+  files: [] as ScaffoldFile[],
+});
+
+export class KeyRename {
+  static async build(workspace: Workspace, input: RenameKeyInput) {
+    const sys = await resolveWorkflowSys(workspace, input.app);
+    if (!sys) return refuse("workflow-target-missing", "app", `No app or library named ${input.app ?? ""}.`);
+    if (!input.module) return refuse("workflow-input-missing", "module", "Module name is required.");
+    if (!input.slice === !input.query)
+      return refuse("rename-key-source-invalid", "slice", "Name exactly one key to rename, as slice or as query.");
+    const family = input.slice ? "slice" : "query";
+    const from = input.slice ?? input.query ?? "";
+    if (!input.to || !keyPattern.test(input.to))
+      return refuse(
+        "rename-key-name-invalid",
+        "to",
+        `New key "${input.to ?? ""}" must be camelCase (inFeed, byTitle).`,
+      );
+    if (input.to === from) return refuse("rename-key-name-same", "to", `New key is the same as ${from}.`);
+
+    const root = workspace.workspaceRoot;
+    const paths = moduleSourcePaths(input.module);
+    const sourceRelative = `${getSysRoot(sys)}/${family === "slice" ? paths.signal : paths.document}`;
+    const sourcePath = slashed(path.join(root, sourceRelative));
+    const texts = new Map<string, string>();
+    const index = new AkanIndex({ ts, root });
+    for (const relative of await workspace.getAllFiles("{apps,libs}/**/*.{ts,tsx}")) {
+      if (!indexedPath.test(slashed(relative))) continue;
+      const fileName = slashed(path.join(root, relative));
+      const text = await readFile(fileName, "utf8");
+      texts.set(fileName, text);
+      index.setFile(fileName, text);
+    }
+
+    const keys = index.sourceKeysOf(sourcePath).filter((key) => key.family === family);
+    const source = keys.find((key) => key.sourceKey === from);
+    if (!source)
+      return refuse("rename-key-source-missing", family, `${sourceRelative} declares no ${family} key ${from}.`);
+    if (keys.some((key) => key.sourceKey === input.to))
+      return refuse("rename-key-exists", "to", `${sourceRelative} already declares the ${family} key ${input.to}.`);
+    const edits = index.renameAt(sourcePath, source.span.start, input.to, (fileName) => texts.get(fileName)) ?? [];
+
+    const byFile = new Map<string, AkanRenameEdit[]>();
+    for (const edit of edits) byFile.set(edit.span.fileName, [...(byFile.get(edit.span.fileName) ?? []), edit]);
+    const files: ScaffoldFile[] = [...byFile].map(([fileName, fileEdits]) => {
+      let content = texts.get(fileName) ?? "";
+      for (const { span, newText } of fileEdits.toSorted((a, b) => b.span.start - a.span.start))
+        content = content.slice(0, span.start) + newText + content.slice(span.end);
+      const names = fileEdits.length === 1 ? "1 name changes" : `${fileEdits.length} names change`;
+      return {
+        path: slashed(path.relative(root, fileName)),
+        content,
+        action: "modify",
+        reason: `${names} with the ${family} key ${from} → ${input.to}.`,
+      };
+    });
+    return { diagnostics: [] as WorkflowDiagnostic[], files: files.toSorted((a, b) => a.path.localeCompare(b.path)) };
+  }
+
+  static targetsOf(files: readonly { path: string }[]) {
+    return [...new Set(files.map((file) => file.path.split("/").slice(0, 2).join("/")))];
+  }
+}

package/workflow/plan.ts

@@ -3,6 +3,7 @@ import type { Workspace } from "../commandDecorators";
 import { workflowPlanApproval } from "./artifacts";
 import { resolveWorkflowSys } from "./executor";
 import { InteractionScaffold } from "./interactionScaffold";
+import { KeyRename } from "./keyRename";
 import { MutationScaffold } from "./mutationScaffold";
 import { coerceFieldDefault, moduleSourcePaths } from "./source";
 import type {
@@ -28,6 +29,8 @@ const nameInputPatterns: Record<string, RegExp> = {
   scalar: identifierPattern,
   field: identifierPattern,
   slice: identifierPattern,
+  query: identifierPattern,
+  to: identifierPattern,
   mutation: identifierPattern,
   interaction: identifierPattern,
 };
@@ -458,7 +461,26 @@ const planString = (inputs: Record<string, WorkflowInputValue>, name: string) =>
 const planStrings = (inputs: Record<string, WorkflowInputValue>, name: string) =>
   Array.isArray(inputs[name]) ? inputs[name] : null;
 
+const inspectRenameKeyPlan = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowPlan> => {
+  if (plan.diagnostics.some((diagnostic) => diagnostic.severity === "error")) return plan;
+  const { diagnostics, files } = await KeyRename.build(workspace, {
+    app: planString(plan.inputs, "app"),
+    module: planString(plan.inputs, "module"),
+    slice: planString(plan.inputs, "slice"),
+    query: planString(plan.inputs, "query"),
+    to: planString(plan.inputs, "to"),
+  });
+  return {
+    ...plan,
+    diagnostics: [...plan.diagnostics, ...diagnostics],
+    predictedChanges: files.length
+      ? files.map((file) => ({ target: file.path, action: "modify", applyScope: "auto", reason: file.reason }))
+      : plan.predictedChanges,
+  };
+};
+
 export const inspectWorkflowPlan = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowPlan> => {
+  if (plan.workflow === "rename-key") return await inspectRenameKeyPlan(workspace, plan);
   if (plan.workflow !== "add-mutation" && plan.workflow !== "create-interaction") return plan;
   const app = planString(plan.inputs, "app");
   if (!app) return plan;

package/workflow/types.ts

@@ -63,6 +63,12 @@ export interface AddSliceInput extends PrimitiveTargetInput {
   slice: string | null;
 }
 
+export interface RenameKeyInput extends PrimitiveTargetInput {
+  slice: string | null;
+  query: string | null;
+  to: string | null;
+}
+
 export interface WorkflowInputSpec {
   type: WorkflowInputType;
   required?: boolean;
@@ -498,5 +504,6 @@ export interface WorkflowPrimitiveOperations {
   addEnumField: (input: AddEnumFieldInput) => Promise<PrimitiveWriteReport>;
   addMutation: (input: AddMutationInput) => Promise<PrimitiveWriteReport>;
   addSlice: (input: AddSliceInput) => Promise<PrimitiveWriteReport>;
+  renameKey: (input: RenameKeyInput) => Promise<PrimitiveWriteReport>;
   createInteraction: (input: CreateInteractionInput) => Promise<PrimitiveWriteReport>;
 }

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))),
+    };
+  }
+}