@akanjs/devkit 3.1.2-rc.3 → 3.2.0-rc.0

package/frontendBuild/ssrDevBundler.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { SsrDevBundler } from "./ssrDevBundler";
+
+const makeTempRoot = tempDirs("akan-ssr-dev-bundler-");
+
+describe("SsrDevBundler bootstrap", () => {
+  const bootstrapOf = async (root: string) => {
+    const appDir = path.join(root, "apps/demo");
+    const app = { name: "demo", cwdPath: appDir, workspace: { workspaceRoot: root } } as never;
+    const { files } = await new SsrDevBundler(app).writeEntries();
+    return await Bun.file(files[SsrDevBundler.bootstrapKey] ?? "").text();
+  };
+
+  test("runs the client runtime and the store, not the client barrel", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "apps/demo/lib/st.ts"), "export const st = {};\n");
+
+    expect(await bootstrapOf(root)).toBe('import "@apps/demo/lib/useClient";\nimport "@apps/demo/lib/st";\n');
+  });
+
+  test("runs nothing for an app without a store", async () => {
+    expect(await bootstrapOf(await makeTempRoot())).toBe("export {};\n");
+  });
+});

package/frontendBuild/ssrDevBundler.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { SSR_DEV_DIRNAME, SSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex } from "../artifact/routeSeedIndex";
+import { StoreBootstrap } from "../artifact/storeBootstrap";
 import type { App } from "../commandDecorators";
 import { bundleDefine } from "./bundleDefine";
 import type { ClientEntryDiscovery } from "./clientBuildTypes";
@@ -58,7 +59,7 @@ export class SsrDevBundler extends DevRegistryBundler {
     await mkdir(this.entryDir, { recursive: true });
     const file = path.join(this.entryDir, "bootstrap.ts");
     const hasStore = await Bun.file(path.join(this.app.cwdPath, "lib", "st.ts")).exists();
-    const source = hasStore ? `import ${JSON.stringify(`@apps/${this.app.name}/client`)};\n` : "export {};\n";
+    const source = hasStore ? StoreBootstrap.source(this.app.name) : "export {};\n";
     const unchanged = (await Bun.file(file).exists()) && (await Bun.file(file).text()) === source;
     if (!unchanged) await Bun.write(file, source);
     const entryFile = CsrDevPaths.realpath(file);

package/frontendBuild/vendorImportScanner.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { VendorImportScanner } from "./vendorImportScanner";
+
+const makeTempRoot = tempDirs("akan-vendor-imports-");
+const specifiers = ["akanjs/store", "akanjs/common", "akanjs/fetch", "tailwind-merge"];
+const scan = (...sources: string[]) => {
+  const scanner = new VendorImportScanner(specifiers);
+  for (const source of sources) scanner.scan(source);
+  return scanner.usedExports();
+};
+
+describe("VendorImportScanner", () => {
+  test("reads the imported names, not the local aliases, of minified and plain imports", () => {
+    const used = scan(
+      'import{capitalize as He,Logger as K}from"akanjs/common";import{st}from"akanjs/store";',
+      'import { formSetterNames, Logger } from "akanjs/common";\nimport "akanjs/fetch";\n',
+    );
+
+    expect(used).toEqual({
+      "akanjs/store": ["st"],
+      "akanjs/common": ["Logger", "capitalize", "formSetterNames"],
+      "akanjs/fetch": [],
+      "tailwind-merge": [],
+    });
+  });
+
+  test("leaves out a specifier read whole: a namespace import, an export star or a dynamic import", () => {
+    expect(scan('import*as s from"akanjs/store";import{isEmail}from"akanjs/common";')).not.toHaveProperty(
+      "akanjs/store",
+    );
+    expect(scan('export*from"akanjs/store";')).not.toHaveProperty("akanjs/store");
+    expect(scan('export*as s from"akanjs/store";')).not.toHaveProperty("akanjs/store");
+    expect(scan('const load=()=>import("akanjs/store");')).not.toHaveProperty("akanjs/store");
+    expect(scan('export{twMerge as m}from"tailwind-merge";')["tailwind-merge"]).toEqual(["twMerge"]);
+  });
+
+  test("reads nothing from a require, which a browser chunk carries as Bun's shim and never resolves", () => {
+    const used = scan('function C9(){let{untrackedHeaders:n,untrackedRequest:d}=ii("akanjs/fetch");return d}');
+
+    expect(used["akanjs/fetch"]).toEqual([]);
+  });
+
+  test("ignores a specifier quoted in a string, as a docs page shows code", () => {
+    const used = scan(
+      'const sample="import { st } from \\"akanjs/store\\"";const tpl=`export * from "akanjs/store"`;console.info("akanjs/store");',
+    );
+
+    expect(used["akanjs/store"]).toEqual([]);
+  });
+
+  test("collects across every .js file of a directory", async () => {
+    const dir = await makeTempRoot();
+    await write(path.join(dir, "entry-a.js"), 'import{st}from"akanjs/store";');
+    await write(path.join(dir, "chunks/lazy.js"), 'import{RootStore}from"akanjs/store";');
+    await write(path.join(dir, "chunks/lazy.js.map"), 'import{ignored}from"akanjs/store";');
+
+    const used = await VendorImportScanner.exportsUsedIn(dir, ["akanjs/store"]);
+
+    expect(used).toEqual({ "akanjs/store": ["RootStore", "st"] });
+  });
+
+  test("reads a client output directory a build never wrote as importing nothing", async () => {
+    const dir = await makeTempRoot();
+
+    expect(await VendorImportScanner.exportsUsedIn(path.join(dir, "client"), ["akanjs/store"])).toEqual({
+      "akanjs/store": [],
+    });
+  });
+});

package/frontendBuild/vendorImportScanner.ts

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+export class VendorImportScanner {
+  readonly #specifiers: Set<string>;
+  readonly #names = new Map<string, Set<string>>();
+  readonly #whole = new Set<string>();
+
+  constructor(specifiers: readonly string[]) {
+    this.#specifiers = new Set(specifiers);
+    for (const specifier of specifiers) this.#names.set(specifier, new Set());
+  }
+
+  /** The names each specifier's importers read across a directory's `.js` files; a specifier read whole is left out. */
+  static async exportsUsedIn(dir: string, specifiers: readonly string[]): Promise<Record<string, string[]>> {
+    const scanner = new VendorImportScanner(specifiers);
+    if (!fs.existsSync(dir)) return scanner.usedExports();
+    for await (const relative of new Bun.Glob("**/*.js").scan({ cwd: dir }))
+      scanner.scan(await Bun.file(path.join(dir, relative)).text(), relative);
+    return scanner.usedExports();
+  }
+
+  scan(source: string, fileName = "chunk.js"): this {
+    if (![...this.#specifiers].some((specifier) => source.includes(specifier))) return this;
+    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.JS);
+    const visit = (node: ts.Node): void => {
+      if (ts.isImportDeclaration(node)) this.#readImport(node);
+      else if (ts.isExportDeclaration(node)) this.#readExport(node);
+      else if (ts.isCallExpression(node)) this.#readCall(node);
+      ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return this;
+  }
+
+  usedExports(): Record<string, string[]> {
+    return Object.fromEntries(
+      [...this.#names]
+        .filter(([specifier]) => !this.#whole.has(specifier))
+        .map(([specifier, names]) => [specifier, [...names].sort()]),
+    );
+  }
+
+  #specifierOf(node: ts.Expression | undefined): string | null {
+    if (!node || !ts.isStringLiteralLike(node)) return null;
+    return this.#specifiers.has(node.text) ? node.text : null;
+  }
+
+  #readImport(node: ts.ImportDeclaration): void {
+    const specifier = this.#specifierOf(node.moduleSpecifier);
+    const clause = node.importClause;
+    if (!specifier || !clause) return;
+    if (clause.name) this.#add(specifier, "default");
+    const bindings = clause.namedBindings;
+    if (!bindings) return;
+    if (ts.isNamespaceImport(bindings)) this.#whole.add(specifier);
+    else for (const element of bindings.elements) this.#add(specifier, (element.propertyName ?? element.name).text);
+  }
+
+  #readExport(node: ts.ExportDeclaration): void {
+    const specifier = this.#specifierOf(node.moduleSpecifier);
+    if (!specifier) return;
+    const clause = node.exportClause;
+    if (!clause || ts.isNamespaceExport(clause)) this.#whole.add(specifier);
+    else for (const element of clause.elements) this.#add(specifier, (element.propertyName ?? element.name).text);
+  }
+
+  //? Only `import()` reaches the import map: a `require` left in a browser chunk is Bun's shim, which throws there.
+  #readCall(node: ts.CallExpression): void {
+    if (node.expression.kind !== ts.SyntaxKind.ImportKeyword) return;
+    const specifier = this.#specifierOf(node.arguments[0]);
+    if (specifier) this.#whole.add(specifier);
+  }
+
+  #add(specifier: string, name: string): void {
+    if (!/^[A-Za-z_$][\w$]*$/.test(name)) this.#whole.add(specifier);
+    else this.#names.get(specifier)?.add(name);
+  }
+}

package/frontendBuild/vendorNarrowing.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { ClientEntriesBundler } from "./clientEntriesBundler";
+import { VendorNarrowing } from "./vendorNarrowing";
+
+const makeTempRoot = tempDirs("akan-vendor-narrowing-");
+const akanjsRoot = path.resolve(import.meta.dir, "../../../akanjs");
+const vendorFile = (name: string) => path.join(akanjsRoot, "server/vendor", `${name}.ts`);
+const agentOnlyText = "path must be an internal path starting with /.";
+
+const staticClosure = (absPath: string, seen = new Set<string>()): Set<string> => {
+  if (seen.has(absPath)) return seen;
+  seen.add(absPath);
+  const transpiler = new Bun.Transpiler({ loader: "js" });
+  for (const { path: imported, kind } of transpiler.scanImports(readFileSync(absPath, "utf8")))
+    if (kind !== "dynamic-import" && imported.startsWith("."))
+      staticClosure(path.resolve(path.dirname(absPath), imported), seen);
+  return seen;
+};
+const closureText = (absPath: string) =>
+  [...staticClosure(absPath)].map((file) => readFileSync(file, "utf8")).join("\n");
+
+const buildVendors = async (storeNames: string[], plugins: Awaited<ReturnType<VendorNarrowing["plugins"]>>) => {
+  const root = await makeTempRoot();
+  const storeAlias = path.join(root, "store.ts");
+  const agentAlias = path.join(root, "agent.ts");
+  await write(storeAlias, ClientEntriesBundler.narrowedAliasSource(vendorFile("akanjs-store"), storeNames));
+  await write(agentAlias, `export * from ${JSON.stringify(vendorFile("akanjs-store-agent"))};\n`);
+  const result = await Bun.build({
+    entrypoints: [storeAlias, agentAlias],
+    outdir: path.join(root, "out"),
+    splitting: true,
+    target: "browser",
+    format: "esm",
+    plugins,
+  });
+  expect(result.logs.map((log) => log.message)).toEqual([]);
+  const outputOf = (name: string) => {
+    const output = result.outputs.find((o) => o.kind === "entry-point" && path.basename(o.path) === `${name}.js`);
+    if (!output) throw new Error(`no ${name}.js output`);
+    return output.path;
+  };
+  return { store: closureText(outputOf("store")), agent: closureText(outputOf("agent")) };
+};
+
+describe("VendorNarrowing", () => {
+  test("maps each narrowed specifier's vendor entry to its names and leaves the rest whole", () => {
+    const narrowing = new VendorNarrowing(akanjsRoot, { "akanjs/store": ["st"], "akanjs/base": [] });
+
+    expect(
+      narrowing.entryExports([
+        { specifier: "akanjs/store", absPath: "/v/akanjs-store.ts" },
+        { specifier: "akanjs/base", absPath: "/v/akanjs-base.ts" },
+        { specifier: "akanjs/common", absPath: "/v/akanjs-common.ts" },
+      ]),
+    ).toEqual({ "/v/akanjs-store.ts": ["st"], "/v/akanjs-base.ts": [] });
+  });
+
+  test("keeps the deprecated agent re-export when a route imports one of its names, or reads the store whole", async () => {
+    expect(await new VendorNarrowing(akanjsRoot, { "akanjs/store": ["AgentContext", "st"] }).plugins()).toEqual([]);
+    expect(await new VendorNarrowing(akanjsRoot, {}).plugins()).toEqual([]);
+  });
+
+  test("a store vendor no route reads an agent name from loads no agent runtime; the agent vendor does", async () => {
+    const narrowing = new VendorNarrowing(akanjsRoot, { "akanjs/store": ["StoreRegistry", "store"] });
+    const plugins = await narrowing.plugins();
+    expect(plugins).toHaveLength(1);
+
+    const { store, agent } = await buildVendors(["StoreRegistry", "store"], plugins);
+
+    expect(store).not.toContain(agentOnlyText);
+    expect(agent).toContain(agentOnlyText);
+  }, 60_000);
+
+  test("without the blanking, the deprecated re-export drags the agent runtime into the store vendor", async () => {
+    const { store } = await buildVendors(["StoreRegistry", "store"], []);
+
+    expect(store).toContain(agentOnlyText);
+  }, 60_000);
+
+  test("an akanjs older than the agent split keeps whole vendors and gets no agent entry", async () => {
+    const root = await makeTempRoot();
+    for (const name of ["akanjs-store", "akanjs-base"])
+      await write(path.join(root, "server/vendor", `${name}.ts`), `export * from "${name}";\n`);
+    const entries = VendorNarrowing.entriesIn(path.join(root, "server"));
+    const narrowing = new VendorNarrowing(root, { "akanjs/store": ["st"], "akanjs/base": [] });
+
+    expect(entries.map(({ specifier }) => specifier)).toEqual(["akanjs/store", "akanjs/base"]);
+    expect(narrowing.entryExports(entries)).toEqual({});
+    expect(await narrowing.plugins()).toEqual([]);
+    expect(VendorNarrowing.entriesIn(path.join(akanjsRoot, "server")).map(({ specifier }) => specifier)).toContain(
+      "akanjs/store/agent",
+    );
+  });
+
+  test("an alias narrowed to no names still loads its entry, so the entry's side effects run", () => {
+    expect(ClientEntriesBundler.narrowedAliasSource("/v/akanjs-fetch.ts", [])).toBe(
+      `export {} from ${JSON.stringify(path.resolve("/v/akanjs-fetch.ts"))};\n`,
+    );
+  });
+});

package/frontendBuild/vendorNarrowing.ts

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import { VENDOR_SPECIFIERS, type VendorSpecifier } from "./vendorSpecifiers";
+
+//? Bun puts a module in the chunk of every entry that reaches it, read or not, so a deprecated re-export would keep
+//? its target in a vendor every page loads; a narrowed build blanks it unless a route imports one of its names.
+const deprecatedReexports: Partial<Record<VendorSpecifier, string>> = { "akanjs/store": "store/deprecatedAgent.ts" };
+
+export interface VendorEntry {
+  specifier: VendorSpecifier;
+  absPath: string;
+}
+
+export class VendorNarrowing {
+  readonly #akanjsRoot: string;
+  readonly #vendorExports: Partial<Record<VendorSpecifier, readonly string[]>>;
+
+  //? A devkit newer than the installed akanjs finds no agent vendor or deprecated re-export there, and builds that
+  //? akanjs's vendors whole, as the devkit it shipped with did.
+  static entriesIn(akanServerPath: string): VendorEntry[] {
+    return VENDOR_SPECIFIERS.map((specifier) => ({
+      specifier,
+      absPath: path.resolve(akanServerPath, "vendor", `${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`),
+    })).filter(({ absPath }) => fs.existsSync(absPath));
+  }
+
+  constructor(akanjsRoot: string, vendorExports: Partial<Record<VendorSpecifier, readonly string[]>>) {
+    this.#akanjsRoot = akanjsRoot;
+    const current = Object.values(deprecatedReexports).every((file) => fs.existsSync(path.join(akanjsRoot, file)));
+    this.#vendorExports = current ? vendorExports : {};
+  }
+
+  entryExports(vendorEntries: VendorEntry[]): Record<string, readonly string[]> {
+    return Object.fromEntries(
+      vendorEntries.flatMap(({ specifier, absPath }) => {
+        const names = this.#vendorExports[specifier];
+        return names ? [[absPath, names]] : [];
+      }),
+    );
+  }
+
+  async plugins(): Promise<BunPlugin[]> {
+    const blanked: string[] = [];
+    for (const [specifier, file] of Object.entries(deprecatedReexports) as [VendorSpecifier, string][]) {
+      const used = this.#vendorExports[specifier];
+      if (!used) continue;
+      const source = await Bun.file(path.join(this.#akanjsRoot, file)).text();
+      const names = new Bun.Transpiler({ loader: "ts" }).scan(source).exports;
+      if (!names.some((name) => used.includes(name))) blanked.push(`akanjs/${file}`);
+    }
+    if (blanked.length === 0) return [];
+    const escaped = blanked.map((file) => file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replaceAll("/", "[\\\\/]"));
+    const filter = new RegExp(`[\\\\/](?:${escaped.join("|")})$`);
+    return [
+      {
+        name: "akan-blank-deprecated-reexports",
+        setup(build) {
+          build.onLoad({ filter }, () => ({ contents: "export {};\n", loader: "ts" }));
+        },
+      },
+    ];
+  }
+}

package/frontendBuild/vendorSpecifiers.ts

@@ -8,6 +8,7 @@ export const VENDOR_SPECIFIERS = [
   "scheduler",
   "react-server-dom-webpack/client.browser",
   "akanjs/store",
+  "akanjs/store/agent",
   "akanjs/base",
   "akanjs/common",
   "akanjs/constant",
@@ -16,3 +17,15 @@ export const VENDOR_SPECIFIERS = [
 ] as const;
 
 export type VendorSpecifier = (typeof VENDOR_SPECIFIERS)[number];
+
+//? The vendor entries a build narrows to the names its client code imports: each is an ESM `export *`, while React's
+//? entries list a CommonJS module's names by hand.
+export const NARROWABLE_VENDOR_SPECIFIERS = [
+  "akanjs/store",
+  "akanjs/store/agent",
+  "akanjs/base",
+  "akanjs/common",
+  "akanjs/constant",
+  "akanjs/fetch",
+  "tailwind-merge",
+] as const satisfies readonly VendorSpecifier[];

package/gitRevision.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdir, mkdtemp, rm, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { GitRevision } from "./gitRevision";
+
+const roots: string[] = [];
+const byName = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const repoOf = async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "akan-git-"));
+  roots.push(root);
+  const git = (...args: string[]) => {
+    const result = Bun.spawnSync(
+      ["git", "-c", "user.name=akan", "-c", "user.email=akan@example.com", "-c", "commit.gpgsign=false", ...args],
+      { cwd: root, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } },
+    );
+    expect(result.exitCode).toBe(0);
+    return result.stdout.toString().trim();
+  };
+  const write = async (file: string, text: string) => {
+    await mkdir(path.dirname(path.join(root, file)), { recursive: true });
+    await writeFile(path.join(root, file), text);
+  };
+  git("init", "-q", "-b", "main");
+  return { root, git, write };
+};
+
+describe("GitRevision", () => {
+  it("lists each changed file with its change, a rename as a removal and an addition", async () => {
+    const { root, git, write } = await repoOf();
+    await write(".gitignore", "apps/*/scripts\n");
+    await write("apps/demo/lib/memo/memo.constant.ts", "a\n");
+    await write("apps/demo/lib/memo/memo.service.ts", "b\n");
+    await write("apps/demo/lib/memo/memo.store.ts", "c\n");
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "base");
+    const base = git("rev-parse", "HEAD");
+    await write("apps/demo/lib/memo/memo.constant.ts", "a2\n");
+    await unlink(path.join(root, "apps/demo/lib/memo/memo.service.ts"));
+    git("mv", "apps/demo/lib/memo/memo.store.ts", "apps/demo/lib/memo/memo2.store.ts");
+    await write("apps/demo/lib/memo/memo.signal.ts", "d\n");
+    await write("apps/demo/scripts/seed.ts", "e\n");
+    const git2 = new GitRevision(root);
+    expect(await git2.changedFilesSince(base)).toEqual([
+      { file: "apps/demo/lib/memo/memo.constant.ts", change: "changed" },
+      { file: "apps/demo/lib/memo/memo.service.ts", change: "removed" },
+      { file: "apps/demo/lib/memo/memo.signal.ts", change: "added" },
+      { file: "apps/demo/lib/memo/memo.store.ts", change: "removed" },
+      { file: "apps/demo/lib/memo/memo2.store.ts", change: "added" },
+    ]);
+    expect((await git2.workingFiles()).sort(byName)).toEqual([
+      "apps/demo/lib/memo/memo.constant.ts",
+      "apps/demo/lib/memo/memo.service.ts",
+      "apps/demo/lib/memo/memo.signal.ts",
+      "apps/demo/lib/memo/memo2.store.ts",
+    ]);
+    expect([...(await git2.filesAt(base, () => true)).keys()].sort(byName)).toEqual([
+      "apps/demo/lib/memo/memo.constant.ts",
+      "apps/demo/lib/memo/memo.service.ts",
+      "apps/demo/lib/memo/memo.store.ts",
+    ]);
+  });
+
+  it("says so when HEAD shares no commit with the revision, instead of comparing with its tip", async () => {
+    const { git, write, root } = await repoOf();
+    await write("apps/demo/a.ts", "a\n");
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "main");
+    git("checkout", "-q", "--orphan", "other");
+    await write("apps/demo/b.ts", "b\n");
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "other");
+    const revision = new GitRevision(root);
+    expect((await revision.forkPointOf("main")).error).toContain("shares no commit with main");
+    expect((await revision.forkPointOf(null)).error).toContain("shares no commit with main");
+    expect((await revision.forkPointOf("-x")).error).toBe("-x is not a commit in this repository.");
+  });
+});

package/gitRevision.ts

@@ -0,0 +1,128 @@
+import type { AkanChangedFile } from "@akanjs/language";
+
+export type ForkPoint = { sha: string; error?: undefined } | { sha?: undefined; error: string };
+
+const systemPaths = ["apps", "libs"];
+const changeOfStatus: { [status: string]: AkanChangedFile["change"] | undefined } = { A: "added", D: "removed" };
+
+//? Commands run in the workspace root, which may sit below the repository root; `./<path>` and `--relative` keep every
+//? path git reads or prints relative to the workspace.
+export class GitRevision {
+  static readonly #defaultBranches = ["upstream/HEAD", "upstream/main", "origin/HEAD", "origin/main", "main", "master"];
+  //? Studio and MCP read git beside the user's own commands; without this, `git diff` may take index.lock to refresh it.
+  static readonly #env = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
+  readonly #root: string;
+
+  constructor(root: string) {
+    this.#root = root;
+  }
+
+  async forkPointOf(since: string | null): Promise<ForkPoint> {
+    if ((await this.#git(["rev-parse", "--is-inside-work-tree"]))?.trim() !== "true")
+      return { error: "The Change Map compares with git history, and this workspace is not in a git repository." };
+    if (since !== null) {
+      //? A leading `-` would reach git as an option.
+      const sha = /^[^-\s][^\s]*$/.test(since)
+        ? (await this.#git(["rev-parse", "--verify", "--quiet", `${since}^{commit}`]))?.trim()
+        : undefined;
+      if (!sha) return { error: `${since} is not a commit in this repository.` };
+      return await this.#mergeBase(since, sha);
+    }
+    for (const branch of GitRevision.#defaultBranches)
+      if ((await this.#git(["rev-parse", "--verify", "--quiet", `${branch}^{commit}`])) !== null)
+        return await this.#mergeBase(branch, branch);
+    const head = (await this.#git(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]))?.trim();
+    return head ? { sha: head } : { error: "The repository has no commit to compare with yet." };
+  }
+
+  async #mergeBase(name: string, revision: string): Promise<ForkPoint> {
+    const sha = (await this.#git(["merge-base", "HEAD", revision]))?.trim();
+    if (sha) return { sha };
+    return {
+      error: `HEAD shares no commit with ${name} here. In a shallow clone, \`git fetch --unshallow\` brings the history in.`,
+    };
+  }
+
+  async filesAt(
+    sha: string,
+    isWanted: (file: string) => boolean,
+    paths: string[] = systemPaths,
+  ): Promise<Map<string, string>> {
+    const listed = await this.#git(["ls-tree", "-r", "-z", "--name-only", sha, "--", ...paths]);
+    if (listed === null) throw new Error(`git ls-tree failed for ${sha}`);
+    const files = listed.split("\0").filter((file) => file && isWanted(file));
+    const texts = new Map<string, string>();
+    if (!files.length) return texts;
+    const proc = Bun.spawn(["git", "cat-file", "--batch"], {
+      cwd: this.#root,
+      env: GitRevision.#env,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const output = new Response(proc.stdout).arrayBuffer();
+    proc.stdin.write(files.map((file) => `${sha}:./${file}\n`).join(""));
+    await proc.stdin.end();
+    const bytes = new Uint8Array(await output);
+    if ((await proc.exited) !== 0) throw new Error(`git cat-file failed for ${sha}`);
+    const decoder = new TextDecoder();
+    let offset = 0;
+    for (const file of files) {
+      const lineEnd = bytes.indexOf(10, offset);
+      if (lineEnd < 0) throw new Error(`git cat-file ended before ${file} at ${sha}`);
+      const header = decoder.decode(bytes.subarray(offset, lineEnd));
+      offset = lineEnd + 1;
+      if (header.endsWith(" missing")) continue;
+      const [, type, size] = header.split(" ");
+      const length = Number(size);
+      if (type === "blob") texts.set(file, decoder.decode(bytes.subarray(offset, offset + length)));
+      offset += length + 1;
+    }
+    return texts;
+  }
+
+  async changedFilesSince(sha: string): Promise<AkanChangedFile[]> {
+    const [tracked, untracked] = await Promise.all([
+      this.#git(["diff", "--name-status", "--no-renames", "--relative", "-z", sha, "--", ...systemPaths]),
+      this.#git(["ls-files", "-z", "--others", "--exclude-standard", "--", ...systemPaths]),
+    ]);
+    if (tracked === null || untracked === null) throw new Error(`git could not list the changes since ${sha}`);
+    const changes = new Map<string, AkanChangedFile["change"]>();
+    const fields = tracked.split("\0");
+    for (let idx = 0; idx + 1 < fields.length; idx += 2)
+      changes.set(fields[idx + 1], changeOfStatus[fields[idx]] ?? "changed");
+    for (const file of untracked.split("\0")) if (file) changes.set(file, "added");
+    return [...changes].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([file, change]) => ({ file, change }));
+  }
+
+  //? Tracked and untracked files, `.gitignore` applied, so the working side of a Change Map sees what the base side
+  //? can: a glob would read ignored files the base never has and mark them added.
+  async workingFiles(): Promise<string[]> {
+    const listed = await this.#git([
+      "ls-files",
+      "-z",
+      "--cached",
+      "--others",
+      "--exclude-standard",
+      "--",
+      ...systemPaths,
+    ]);
+    if (listed === null) throw new Error("git ls-files failed");
+    return [...new Set(listed.split("\0").filter(Boolean))];
+  }
+
+  async #git(args: string[]) {
+    try {
+      const proc = Bun.spawn(["git", ...args], {
+        cwd: this.#root,
+        env: GitRevision.#env,
+        stdout: "pipe",
+        stderr: "ignore",
+      });
+      const [text, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+      return exitCode === 0 ? text : null;
+    } catch {
+      return null;
+    }
+  }
+}

package/incrementalBuilder/builderGraphPayloads.ts

@@ -0,0 +1,60 @@
+import type { App } from "@akanjs/devkit/commandDecorators";
+import { FrameworkGraph } from "@akanjs/devkit/frameworkGraph";
+import { GitRevision } from "@akanjs/devkit/gitRevision";
+import { WorkspaceGraph } from "@akanjs/devkit/workspaceGraph";
+import type { BuildChangesPayload, BuilderGraphReq, BuildFrameworkPayload, BuildGraphPayload } from "akanjs/server";
+
+export class BuilderGraphPayloads {
+  readonly #app: App;
+  readonly #generation: () => number;
+  #graph: { generation: number; payload: BuildGraphPayload } | null = null;
+  #changes: { key: string; payload: Promise<BuildChangesPayload> } | null = null;
+
+  constructor(app: App, generation: () => number) {
+    this.#app = app;
+    this.#generation = generation;
+  }
+
+  touched(files: string[]) {
+    FrameworkGraph.touched(this.#app.workspace.workspaceRoot, files);
+  }
+
+  async of(msg: BuilderGraphReq): Promise<BuildGraphPayload | BuildChangesPayload | BuildFrameworkPayload> {
+    if (msg.framework) return await this.#framework();
+    return msg.changes ? await this.#changesSince(msg.changes.since) : await this.#workspaceGraph();
+  }
+
+  async #workspaceGraph(): Promise<BuildGraphPayload> {
+    const generation = this.#generation();
+    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 } };
+    }
+    return this.#graph.payload;
+  }
+
+  async #framework(): Promise<BuildFrameworkPayload> {
+    const { workspaceRoot } = this.#app.workspace;
+    return { workspaceRoot, framework: await FrameworkGraph.cached(workspaceRoot) };
+  }
+
+  async #changesSince(since: string | null): Promise<BuildChangesPayload> {
+    const { workspace, name } = this.#app;
+    const { workspaceRoot } = workspace;
+    const forkPoint = await new GitRevision(workspaceRoot).forkPointOf(since);
+    if (forkPoint.error !== undefined) return { workspaceRoot, changes: { error: forkPoint.error } };
+    const key = `${this.#generation()}:${forkPoint.sha}`;
+    if (this.#changes?.key !== key) {
+      const payload = WorkspaceGraph.changesAt(workspace, forkPoint.sha).then((changes) => ({
+        workspaceRoot,
+        changes: WorkspaceGraph.changesVisibleTo(changes, name),
+      }));
+      payload.catch(() => {
+        if (this.#changes?.payload === payload) this.#changes = null;
+      });
+      this.#changes = { key, payload };
+    }
+    return await this.#changes.payload;
+  }
+}