@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.80

package/fleetGuard.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Executor, LibExecutor, WorkspaceExecutor } from "./executors";
+import { FleetGuard, formatFleetGuardReport } from "./fleetGuard";
+import { LibSource } from "./libSource";
+
+const tempRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const write = async (filePath: string, content: string) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+};
+
+const git = async (cwd: string, args: string[]) =>
+  await new Executor("fixture", cwd).spawn("git", ["-c", "user.email=t@t", "-c", "user.name=t", ...args]);
+
+/**
+ * A spoke as a push leaves it. Built by hand rather than by running a push: `LibExecutor.from` memoises by
+ * library name across the whole process, so a fixture that also builds a hub would hand the guard the
+ * hub's copy of the library. In a real spoke the hub is a different process entirely.
+ */
+const makeSpoke = async (libName: string, appName: string) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-guard-"));
+  tempRoots.push(root);
+  await write(path.join(root, "package.json"), '{ "name": "spoke", "version": "0.0.1", "description": "spoke" }\n');
+  await write(path.join(root, "tsconfig.json"), "{}\n");
+  await write(path.join(root, ".gitignore"), "node_modules\n**/.akan\n");
+  await write(path.join(root, `apps/${appName}/akan.config.ts`), "export default {};\n");
+  await write(path.join(root, `apps/${appName}/env/env.server.local.ts`), "export const env = {};\n");
+  await write(path.join(root, `libs/${libName}/akan.config.ts`), "export default {};\n");
+  await write(path.join(root, `libs/${libName}/package.json`), `{ "name": "@${libName}", "version": "0.0.1" }\n`);
+  await write(path.join(root, `libs/${libName}/common/helper.ts`), "export const helper = 1;\n");
+  await mkdir(path.join(root, `libs/${libName}/lib`), { recursive: true });
+
+  await git(root, ["init", "--quiet", "--initial-branch=develop"]);
+  await git(root, ["add", "-A"]);
+  await git(root, ["commit", "--quiet", "-m", "initial"]);
+
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: `spoke-${libName}` });
+  await new LibSource(LibExecutor.from(workspace, libName)).write({ origin: "hub#develop", sha: "abc1234" });
+  await write(
+    path.join(root, FleetGuard.anchorFile),
+    `${JSON.stringify({ hub: "hub", hubSha: "abc1234", branch: "develop", apps: [appName], syncedAt: "now" }, null, 2)}\n`,
+  );
+  await git(root, ["add", "-A"]);
+  await git(root, ["commit", "--quiet", "-m", "chore(fleet): sync from hub@abc1234"]);
+
+  return { root, workspace, guard: new FleetGuard(workspace) };
+};
+
+describe("FleetGuard", () => {
+  test("passes in a workspace that is not a spoke, so one hook line is safe in the hub too", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "akan-guard-"));
+    tempRoots.push(root);
+    await write(path.join(root, "package.json"), '{ "name": "hub", "version": "0.0.1", "description": "hub" }\n');
+    await git(root, ["init", "--quiet"]);
+
+    const report = await new FleetGuard(
+      WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "bare-hub" }),
+    ).check();
+
+    expect(report.spoke).toBeNull();
+    expect(report.violations).toEqual([]);
+    expect(formatFleetGuardReport(report)).toContain("not a fleet spoke");
+  });
+
+  test("passes a spoke that has changed nothing hub-owned", async () => {
+    const { root, guard } = await makeSpoke("clean-kit", "clean-app");
+    await write(path.join(root, "apps/clean-app/lib/task.ts"), "export const task = 1;\n");
+    await git(root, ["add", "-A"]);
+    await git(root, ["commit", "--quiet", "-m", "customer app work"]);
+
+    const report = await guard.check();
+
+    expect(report.spoke?.branch).toBe("develop");
+    expect(report.anchor).toMatch(/^[0-9a-f]{40}$/);
+    expect(report.violations).toEqual([]);
+    expect(report.driftedLibs).toEqual([]);
+  });
+
+  test("catches a library edit both by path and by stamp", async () => {
+    const { root, guard } = await makeSpoke("drift-kit", "drift-app");
+    await write(path.join(root, "libs/drift-kit/common/helper.ts"), "export const helper = 99;\n");
+    await git(root, ["add", "-A"]);
+    await git(root, ["commit", "--quiet", "-m", "quick fix in the lib"]);
+
+    const report = await guard.check();
+
+    expect(report.violations.map((violation) => violation.path)).toEqual(["libs/drift-kit/common/helper.ts"]);
+    expect(report.violations[0]?.reason).toContain("owned by the hub");
+    expect(report.driftedLibs.map((drift) => drift.lib)).toEqual(["drift-kit"]);
+    expect(formatFleetGuardReport(report)).toContain("akansoft");
+  });
+
+  test("catches a workspace manifest edit and leaves env alone", async () => {
+    const { root, guard } = await makeSpoke("shell-kit", "shell-app");
+    await write(path.join(root, "package.json"), '{ "name": "spoke", "version": "0.0.2", "description": "x" }\n');
+    await write(path.join(root, "apps/shell-app/env/env.server.local.ts"), "export const env = { key: 1 };\n");
+
+    const report = await guard.check();
+
+    expect(report.violations.map((violation) => violation.path)).toEqual(["package.json"]);
+  });
+
+  test("reads only the index in staged mode", async () => {
+    const { root, guard } = await makeSpoke("staged-kit", "staged-app");
+    await write(path.join(root, "libs/staged-kit/common/helper.ts"), "export const helper = 5;\n");
+
+    expect((await guard.check({ staged: true })).violations).toEqual([]);
+    await git(root, ["add", "libs/staged-kit/common/helper.ts"]);
+    expect((await guard.check({ staged: true })).violations.map((violation) => violation.path)).toEqual([
+      "libs/staged-kit/common/helper.ts",
+    ]);
+  });
+});

package/fleetGuard.ts

@@ -0,0 +1,157 @@
+import path from "node:path";
+import { LibExecutor, type WorkspaceExecutor } from "./executors";
+import { FileSys } from "./fileSys";
+import { LibSource } from "./libSource";
+
+export interface FleetAnchorFile {
+  hub: string;
+  hubSha: string;
+  branch: string;
+  apps: string[];
+  syncedAt: string;
+}
+
+export interface FleetViolation {
+  path: string;
+  reason: string;
+}
+
+export interface FleetLibDrift {
+  lib: string;
+  expected: string;
+  actual: string;
+}
+
+export interface FleetGuardReport {
+  /** Null when this workspace is not a spoke, which is a pass — the same hook line is safe in the hub. */
+  spoke: FleetAnchorFile | null;
+  anchor: string | null;
+  violations: FleetViolation[];
+  driftedLibs: FleetLibDrift[];
+}
+
+/**
+ * The spoke-side half of the fleet contract, run *inside* a customer repo by its own CI and pre-commit
+ * hook. It needs no hub access and no credentials: the library stamps carry the hash to compare against,
+ * and the last push is found by the one file only a push writes.
+ *
+ * Guards `libs/**` and the workspace-shell manifests, which the hub owns. `env/` is deliberately not
+ * guarded — those values belong to the repo that deploys.
+ */
+export class FleetGuard {
+  static readonly anchorFile = "akan.fleet.json";
+  static readonly hubOwnedRootFiles = ["package.json", "tsconfig.json", "biome.json", "bunfig.toml"];
+  static readonly spokeOwnedDirs = ["env"];
+  static readonly contact = "Ask the akansoft team to make this change in the hub, then pull it back down.";
+
+  #workspace: WorkspaceExecutor;
+  constructor(workspace: WorkspaceExecutor) {
+    this.#workspace = workspace;
+  }
+
+  async #readAnchorFile() {
+    const anchorPath = path.join(this.#workspace.workspaceRoot, FleetGuard.anchorFile);
+    if (!(await FileSys.fileExists(anchorPath))) return null;
+    return (await FileSys.readJson(anchorPath)) as FleetAnchorFile;
+  }
+
+  /** The push commit: the newest one that touched the file only a push writes. */
+  async #anchorCommit() {
+    const commit = await this.#workspace.spawn("git", ["log", "-1", "--format=%H", "--", FleetGuard.anchorFile]);
+    return commit.trim() || null;
+  }
+
+  #isSpokeOwned(file: string) {
+    const segments = file.split("/");
+    if (segments[0] !== "apps" && segments[0] !== "libs") return false;
+    return FleetGuard.spokeOwnedDirs.includes(segments[2] ?? "");
+  }
+
+  #violationOf(file: string): FleetViolation | null {
+    if (this.#isSpokeOwned(file)) return null;
+    if (file === FleetGuard.anchorFile) return { path: file, reason: "the fleet anchor is written by a push" };
+    if (FleetGuard.hubOwnedRootFiles.includes(file))
+      return { path: file, reason: "workspace manifests are owned by the hub" };
+    if (file.startsWith("libs/")) return { path: file, reason: "shared libraries are owned by the hub" };
+    return null;
+  }
+
+  async #changedFiles({ staged }: { staged: boolean }) {
+    if (staged) {
+      const cached = await this.#workspace.spawn("git", ["diff", "--cached", "--name-only"]);
+      return cached.split("\n").filter((file) => !!file.trim());
+    }
+    const anchor = await this.#anchorCommit();
+    const sinceAnchor = anchor
+      ? (await this.#workspace.spawn("git", ["diff", "--name-only", `${anchor}..HEAD`]))
+          .split("\n")
+          .filter((file) => !!file.trim())
+      : [];
+    const working = (await this.#workspace.spawn("git", ["status", "--porcelain"]))
+      .split("\n")
+      .filter((line) => !!line.trim())
+      //? Porcelain v1: two status columns, a space, then the path — and a rename carries `old -> new`.
+      .map((line) => line.slice(3).split(" -> ").at(-1) ?? "")
+      .filter((file) => !!file);
+    return [...new Set([...sinceAnchor, ...working])];
+  }
+
+  async #libDrift(): Promise<FleetLibDrift[]> {
+    const libNames = await this.#workspace.getLibs();
+    const statuses = await Promise.all(
+      libNames.map(async (libName) => await new LibSource(LibExecutor.from(this.#workspace, libName)).status()),
+    );
+    return statuses
+      .filter((status) => status.drift === "drifted")
+      .map((status) => ({ lib: status.lib, expected: status.stamp?.hash ?? "", actual: status.hash }));
+  }
+
+  async check({ staged = false }: { staged?: boolean } = {}): Promise<FleetGuardReport> {
+    const spoke = await this.#readAnchorFile();
+    //* Not a spoke: a pass, so one `akan fleet check` line in a shared pre-commit hook is safe in the hub
+    //* too — the hub is where hub-owned files are supposed to be edited.
+    if (!spoke) return { spoke: null, anchor: null, violations: [], driftedLibs: [] };
+    const [anchor, changed, driftedLibs] = await Promise.all([
+      this.#anchorCommit(),
+      this.#changedFiles({ staged }),
+      staged ? Promise.resolve<FleetLibDrift[]>([]) : this.#libDrift(),
+    ]);
+    const violations = changed
+      .map((file) => this.#violationOf(file))
+      .filter((violation): violation is FleetViolation => !!violation);
+    return { spoke, anchor, violations, driftedLibs };
+  }
+}
+
+export function formatFleetGuardReport(report: FleetGuardReport, { warn = false }: { warn?: boolean } = {}) {
+  if (!report.spoke) return "Akan Fleet Guard: not a fleet spoke (no akan.fleet.json) — nothing to check.";
+  const clean = !report.violations.length && !report.driftedLibs.length;
+  const sections = [
+    "Akan Fleet Guard",
+    `hub: ${report.spoke.hub}#${report.spoke.branch}  apps: ${report.spoke.apps.join(", ")}`,
+    `last push: ${report.anchor?.slice(0, 12) ?? "(none)"}`,
+    "",
+    ...(clean ? ["  no hub-owned file was changed here."] : []),
+    ...(report.violations.length
+      ? [
+          `Hub-owned files changed in this repo (${report.violations.length}):`,
+          "",
+          ...report.violations.map((violation) => `  ${violation.path}  — ${violation.reason}`),
+        ]
+      : []),
+    ...(report.driftedLibs.length
+      ? [
+          "",
+          `Libraries edited since the last push (${report.driftedLibs.length}):`,
+          "",
+          ...report.driftedLibs.map(
+            (drift) => `  libs/${drift.lib}  stamped ${drift.expected.slice(0, 12)}, now ${drift.actual.slice(0, 12)}`,
+          ),
+        ]
+      : []),
+    ...(clean
+      ? []
+      : ["", `  ${FleetGuard.contact}`, ...(warn ? ["  (warning only — this commit is not blocked)"] : [])]),
+  ];
+  return sections.join("\n");
+}

package/fleetSpoke.test.ts

@@ -0,0 +1,390 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Executor, WorkspaceExecutor } from "./executors";
+import { FileSys } from "./fileSys";
+import { FleetConfig } from "./fleetConfig";
+import { FleetSpoke, formatFleetDiff, formatFleetPushResults, formatFleetStatuses } from "./fleetSpoke";
+
+const tempRoots: string[] = [];
+const originalEnv = { ...process.env };
+
+beforeEach(() => {
+  process.env = { ...originalEnv };
+  process.env.AKAN_PUBLIC_REPO_NAME = "hub";
+  process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+  process.env.AKAN_PUBLIC_ENV = "local";
+});
+
+afterEach(async () => {
+  process.env = { ...originalEnv };
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const write = async (filePath: string, content: string) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+};
+
+const git = async (cwd: string, args: string[]) =>
+  await new Executor("fixture", cwd).spawn("git", ["-c", "user.email=t@t", "-c", "user.name=t", ...args]);
+
+const hubGitignore = [
+  "node_modules",
+  "**/.akan",
+  "**/bun.lock",
+  "apps/*/lib/cnst.ts",
+  "**/env.server.local.ts",
+  "**/akan.app.json",
+  "",
+  "# akan:secrets (managed by akan.config.ts — do not edit)",
+  "apps/served/secrets/**/*",
+  "apps/private/secrets/**",
+  "# akan:secrets:end",
+].join("\n");
+
+const hubAgents = [
+  "# Hub",
+  "",
+  "## Workspace",
+  "",
+  "- Repo: hub",
+  "- Apps: private, served",
+  "- Libraries: kit",
+  "",
+].join("\n");
+
+const makeSys = async (root: string, member: "apps" | "libs", name: string, extra: Record<string, string> = {}) => {
+  await write(path.join(root, member, name, "akan.config.ts"), "export default {};\n");
+  await write(path.join(root, member, name, "tsconfig.json"), "{}\n");
+  await write(path.join(root, member, name, "package.json"), `{ "name": "@${name}", "version": "0.0.1" }\n`);
+  await mkdir(path.join(root, member, name, "lib"), { recursive: true });
+  for (const [relative, content] of Object.entries(extra))
+    await write(path.join(root, member, name, relative), content);
+};
+
+/** A hub with two apps, one shared library, and a spoke that serves only the first app. */
+const makeFleet = async (servedApp: string, privateApp: string, libName: string) => {
+  const workRoot = await mkdtemp(path.join(os.tmpdir(), "akan-fleet-"));
+  tempRoots.push(workRoot);
+  const hubRoot = path.join(workRoot, "hub");
+  const bareRoot = path.join(workRoot, "spoke.git");
+  await mkdir(hubRoot, { recursive: true });
+
+  await write(path.join(hubRoot, "package.json"), '{ "name": "hub", "version": "0.0.1", "description": "hub" }\n');
+  await write(path.join(hubRoot, ".gitignore"), `${hubGitignore}\n`);
+  await write(path.join(hubRoot, "AGENTS.md"), hubAgents);
+  await write(path.join(hubRoot, "biome.json"), "{}\n");
+  await write(path.join(hubRoot, "benchmarks/bench.ts"), "export {};\n");
+  await write(
+    path.join(hubRoot, "akan.fleet.ts"),
+    `export default { pushableBranches: ["develop"], exclude: ["benchmarks"], spokes: [{ name: "acme", repo: "${bareRoot}", apps: ["${servedApp}"] }] };\n`,
+  );
+
+  await makeSys(hubRoot, "apps", servedApp, {
+    "lib/task/task.constant.ts": `import { helper } from "@libs/${libName}/common";\n\nexport { helper };\n`,
+    "lib/cnst.ts": "export {};\n",
+    "env/env.server.local.ts": "export const env = { from: 'hub' };\n",
+    "env/env.server.ts": "export const env = {};\n",
+  });
+  await makeSys(hubRoot, "apps", privateApp, { "lib/task/task.constant.ts": "export const task = 1;\n" });
+  await makeSys(hubRoot, "libs", libName, { "common/helper.ts": "export const helper = 1;\n" });
+
+  await git(hubRoot, ["init", "--quiet", "--initial-branch=develop"]);
+  await git(hubRoot, ["add", "-A"]);
+  await git(hubRoot, ["commit", "--quiet", "-m", "hub"]);
+
+  await git(workRoot, ["init", "--bare", "--quiet", "--initial-branch=develop", bareRoot]);
+  const seedRoot = path.join(workRoot, "seed");
+  await git(workRoot, ["clone", "--quiet", bareRoot, seedRoot]);
+  await write(path.join(seedRoot, "README.md"), "spoke\n");
+  await git(seedRoot, ["checkout", "--quiet", "-B", "develop"]);
+  await git(seedRoot, ["add", "-A"]);
+  await git(seedRoot, ["commit", "--quiet", "-m", "seed"]);
+  await git(seedRoot, ["push", "--quiet", "origin", "develop"]);
+
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: hubRoot, repoName: `hub-${servedApp}` });
+  const config = await FleetConfig.from(workspace);
+  if (!config) throw new Error("fixture config missing");
+  const declaration = config.spokes[0];
+  if (!declaration) throw new Error("fixture spoke missing");
+  const spoke = new FleetSpoke(workspace, config, declaration);
+  const clonePath = path.join(hubRoot, ".akan/fleet/acme");
+  return { workRoot, hubRoot, bareRoot, workspace, spoke, clonePath };
+};
+
+/** A working copy of the spoke, as a customer developer would have. */
+const cloneSpoke = async (workRoot: string, bareRoot: string, name: string) => {
+  const root = path.join(workRoot, name);
+  await git(workRoot, ["clone", "--quiet", bareRoot, root]);
+  await git(root, ["checkout", "--quiet", "develop"]);
+  return root;
+};
+
+describe("FleetSpoke push", () => {
+  test("ships the slice, holds back everything hub-only, and preserves the spoke's env", async () => {
+    const { hubRoot, bareRoot, workRoot, spoke, clonePath } = await makeFleet("served", "private", "kit");
+
+    const result = await spoke.push("develop", { verify: false });
+    expect(result.outcome).toBe("pushed");
+
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "check");
+    const entries = await readdir(spokeRoot);
+
+    expect(await FileSys.fileExists(path.join(spokeRoot, "apps/served/lib/task/task.constant.ts"))).toBe(true);
+    expect(await FileSys.fileExists(path.join(spokeRoot, "libs/kit/common/helper.ts"))).toBe(true);
+    expect(await FileSys.dirExists(path.join(spokeRoot, "apps/private"))).toBe(false);
+    expect(entries).not.toContain("benchmarks");
+    expect(entries).not.toContain("akan.fleet.ts");
+    expect(await FileSys.fileExists(path.join(spokeRoot, "apps/served/lib/cnst.ts"))).toBe(false);
+    expect(await FileSys.fileExists(path.join(spokeRoot, "apps/served/env/env.server.local.ts"))).toBe(false);
+    expect(await FileSys.fileExists(path.join(spokeRoot, "apps/served/env/env.server.ts"))).toBe(true);
+    expect(await FileSys.fileExists(path.join(spokeRoot, "README.md"))).toBe(true);
+    void hubRoot;
+    void clonePath;
+  });
+
+  test("filters the leaky generated blocks down to this spoke", async () => {
+    const { bareRoot, workRoot, spoke } = await makeFleet("leak-served", "leak-private", "leak-kit");
+    await spoke.push("develop", { verify: false });
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "check");
+
+    const gitignore = await FileSys.readText(path.join(spokeRoot, ".gitignore"));
+    expect(gitignore).not.toContain("apps/private/secrets");
+    expect(gitignore).not.toContain("**/bun.lock");
+
+    const agents = await FileSys.readText(path.join(spokeRoot, "AGENTS.md"));
+    expect(agents).toContain("- Apps: leak-served");
+    expect(agents).toContain("- Libraries: leak-kit");
+    expect(agents).not.toContain("leak-private");
+  });
+
+  test("writes the anchor file and stamps the library it shipped", async () => {
+    const { bareRoot, workRoot, spoke } = await makeFleet("stamp-served", "stamp-private", "stamp-kit");
+    await spoke.push("develop", { verify: false });
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "check");
+
+    const anchor = (await FileSys.readJson(path.join(spokeRoot, FleetSpoke.anchorFile))) as {
+      branch: string;
+      apps: string[];
+    };
+    expect(anchor.branch).toBe("develop");
+    expect(anchor.apps).toEqual(["stamp-served"]);
+
+    const manifest = (await FileSys.readJson(path.join(spokeRoot, "libs/stamp-kit/package.json"))) as {
+      akan: { source: { origin: string; hash: string } };
+    };
+    expect(manifest.akan.source.origin).toContain("#develop");
+    expect(manifest.akan.source.hash).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  test("is idempotent — a second push with no hub change is skipped", async () => {
+    const { spoke } = await makeFleet("idem-served", "idem-private", "idem-kit");
+    expect((await spoke.push("develop", { verify: false })).outcome).toBe("pushed");
+    expect((await spoke.push("develop", { verify: false })).outcome).toBe("skipped");
+  });
+
+  test("refuses a branch the spoke does not have, and one the config does not allow", async () => {
+    const { spoke } = await makeFleet("refuse-served", "refuse-private", "refuse-kit");
+    const missing = await spoke.push("release", { verify: false }).catch((error: Error) => error);
+    expect((missing as Error).message).toContain("not pushable");
+  });
+
+  test("installs the spoke-side guard, calling the CLI rather than shipping a script", async () => {
+    const { bareRoot, workRoot, spoke } = await makeFleet("guard-served", "guard-private", "guard-kit");
+    await spoke.push("develop", { verify: false });
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "check");
+
+    const workflow = await FileSys.readText(path.join(spokeRoot, ".github/workflows/akan-fleet-guard.yml"));
+    expect(workflow).toContain("bunx akan fleet check");
+    expect(workflow).toContain("fetch-depth: 0");
+
+    const hook = await FileSys.readText(path.join(spokeRoot, ".husky/pre-commit"));
+    expect(hook.trim()).toBe(FleetSpoke.guardHookLine);
+  });
+
+  //? The fixture hub deliberately does not gitignore `.env`, so this also proves the clone-local exclude.
+  test("leaves the clone a runnable workspace root without shipping the file that makes it one", async () => {
+    const { bareRoot, workRoot, spoke, clonePath } = await makeFleet("env-served", "env-private", "env-kit");
+    await spoke.push("develop", { verify: false });
+
+    const localEnv = await FileSys.readText(path.join(clonePath, ".env"));
+    expect(localEnv).toContain("AKAN_PUBLIC_REPO_NAME=acme");
+    expect(localEnv).toContain("AKAN_PUBLIC_SERVE_DOMAIN=example.com");
+    expect(localEnv).not.toContain("hub");
+    expect(await FileSys.readText(path.join(clonePath, ".git/info/exclude"))).toContain("/.env");
+
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "env-check");
+    expect(await FileSys.fileExists(path.join(spokeRoot, ".env"))).toBe(false);
+  });
+
+  test("reports a refusal's whole reason, indented, instead of one truncated line", () => {
+    const report = formatFleetPushResults([
+      { name: "acme", outcome: "refused", reason: "verification failed\nexit code: 1", changedFiles: 12 },
+      { name: "beta", outcome: "pushed", commit: "abc1234", changedFiles: 3 },
+    ]);
+    expect(report).toContain("refused  acme  verification failed");
+    expect(report).toContain("    exit code: 1");
+    expect(report).toContain("pushed   beta  abc1234 (3 files)");
+  });
+});
+
+describe("FleetSpoke status", () => {
+  test("reads clean right after a push, despite the stamp only the spoke carries", async () => {
+    const { spoke } = await makeFleet("status-served", "status-private", "status-kit");
+    await spoke.push("develop", { verify: false });
+
+    const status = await spoke.status("develop");
+
+    expect(status.hasBranch).toBe(true);
+    expect(status.behindPaths).toEqual([]);
+    expect(status.driftedLibs).toEqual([]);
+    expect(status.anchor.commit).toMatch(/^[0-9a-f]{40}$/);
+    expect(status.anchor.incoming).toEqual([]);
+    expect(formatFleetStatuses([status])).toContain("up to date, no customer commits");
+  });
+
+  test("names the drifted library and counts the customer commits", async () => {
+    const { bareRoot, workRoot, spoke } = await makeFleet("sdrift-served", "sdrift-private", "sdrift-kit");
+    await spoke.push("develop", { verify: false });
+
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "customer");
+    await write(path.join(spokeRoot, "libs/sdrift-kit/common/helper.ts"), "export const helper = 99;\n");
+    await git(spokeRoot, ["add", "-A"]);
+    await git(spokeRoot, ["commit", "--quiet", "-m", "lib hack"]);
+    await git(spokeRoot, ["push", "--quiet", "origin", "develop"]);
+
+    const status = await spoke.status("develop");
+
+    expect(status.driftedLibs).toEqual(["sdrift-kit"]);
+    expect(status.anchor.incoming.map((commit) => commit.subject)).toEqual(["lib hack"]);
+    expect(formatFleetStatuses([status])).toContain("DRIFTED LIBS: sdrift-kit");
+  });
+
+  test("reports a spoke with no such branch instead of creating one", async () => {
+    const { spoke } = await makeFleet("nobranch-served", "nobranch-private", "nobranch-kit");
+    const status = await spoke.status("main");
+
+    expect(status.hasBranch).toBe(false);
+    expect(formatFleetStatuses([status])).toContain("no such branch");
+  });
+});
+
+describe("FleetSpoke diff", () => {
+  test("reads as what a push would apply, with library changes split out", async () => {
+    const { bareRoot, workRoot, spoke } = await makeFleet("diff-served", "diff-private", "diff-kit");
+    await spoke.push("develop", { verify: false });
+
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "customer");
+    await write(path.join(spokeRoot, "libs/diff-kit/common/helper.ts"), "export const helper = 99;\n");
+    await write(path.join(spokeRoot, "apps/diff-served/lib/task/task.service.ts"), "export const fixed = true;\n");
+    await git(spokeRoot, ["add", "-A"]);
+    await git(spokeRoot, ["commit", "--quiet", "-m", "customer work"]);
+    await git(spokeRoot, ["push", "--quiet", "origin", "develop"]);
+
+    const result = await spoke.diff("develop");
+
+    expect(result.libs.files).toEqual(["libs/diff-kit/common/helper.ts"]);
+    expect(result.app.files).toEqual(["apps/diff-served/lib/task/task.service.ts"]);
+    //? Direction: the hub would restore `helper = 1` and delete the file the spoke added.
+    expect(result.libs.patch).toContain("-export const helper = 99;");
+    expect(result.libs.patch).toContain("+export const helper = 1;");
+    expect(formatFleetDiff(result)).toContain("LIBRARY changes (1)");
+  });
+
+  test("is empty right after a push", async () => {
+    const { spoke } = await makeFleet("quietdiff-served", "quietdiff-private", "quietdiff-kit");
+    await spoke.push("develop", { verify: false });
+
+    const result = await spoke.diff("develop");
+    expect(result.app.files).toEqual([]);
+    expect(result.libs.files).toEqual([]);
+    expect(formatFleetDiff(result)).toContain("identical to the hub");
+  });
+});
+
+describe("FleetSpoke pull", () => {
+  test("applies the customer's app commits and holds their library edits back", async () => {
+    const { hubRoot, bareRoot, workRoot, spoke } = await makeFleet("pull-served", "pull-private", "pull-kit");
+    await spoke.push("develop", { verify: false });
+
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "customer");
+    await write(path.join(spokeRoot, "apps/pull-served/lib/task/task.service.ts"), "export const fixed = true;\n");
+    await write(path.join(spokeRoot, "libs/pull-kit/common/helper.ts"), "export const helper = 99;\n");
+    await write(path.join(spokeRoot, "apps/pull-served/env/env.server.local.ts"), "export const env = {};\n");
+    await git(spokeRoot, ["add", "-A"]);
+    await git(spokeRoot, ["commit", "--quiet", "-m", "customer hotfix"]);
+    await git(spokeRoot, ["push", "--quiet", "origin", "develop"]);
+
+    const result = await spoke.pull("develop");
+
+    expect(result.incoming.map((commit) => commit.subject)).toEqual(["customer hotfix"]);
+    expect(result.applied).toEqual(["apps/pull-served/lib/task/task.service.ts"]);
+    expect(await FileSys.fileExists(path.join(hubRoot, "apps/pull-served/lib/task/task.service.ts"))).toBe(true);
+
+    expect(result.libPatch?.files).toEqual(["libs/pull-kit/common/helper.ts"]);
+    expect(await FileSys.readText(path.join(hubRoot, "libs/pull-kit/common/helper.ts"))).toContain("helper = 1;");
+    expect(await FileSys.fileExists(path.join(hubRoot, result.libPatch?.path ?? "missing"))).toBe(true);
+  });
+
+  test("adopts library edits only when asked", async () => {
+    const { hubRoot, bareRoot, workRoot, spoke } = await makeFleet("adopt-served", "adopt-private", "adopt-kit");
+    await spoke.push("develop", { verify: false });
+
+    const spokeRoot = await cloneSpoke(workRoot, bareRoot, "customer");
+    await write(path.join(spokeRoot, "libs/adopt-kit/common/helper.ts"), "export const helper = 99;\n");
+    await git(spokeRoot, ["add", "-A"]);
+    await git(spokeRoot, ["commit", "--quiet", "-m", "lib tweak"]);
+    await git(spokeRoot, ["push", "--quiet", "origin", "develop"]);
+
+    const result = await spoke.pull("develop", { adoptLibs: true });
+
+    expect(result.applied).toEqual(["libs/adopt-kit/common/helper.ts"]);
+    expect(result.libPatch).toBeNull();
+    expect(await FileSys.readText(path.join(hubRoot, "libs/adopt-kit/common/helper.ts"))).toContain("helper = 99;");
+  });
+
+  test("is a no-op when the spoke has no commits of its own", async () => {
+    const { spoke } = await makeFleet("quiet-served", "quiet-private", "quiet-kit");
+    await spoke.push("develop", { verify: false });
+
+    const result = await spoke.pull("develop");
+    expect(result.incoming).toEqual([]);
+    expect(result.applied).toEqual([]);
+  });
+});
+
+describe("FleetConfig", () => {
+  test("refuses one app claimed by two spokes", () => {
+    expect(
+      () =>
+        new FleetConfig({
+          spokes: [
+            { name: "a", repo: "a.git", apps: ["shared"] },
+            { name: "b", repo: "b.git", apps: ["shared"] },
+          ],
+        }),
+    ).toThrow(/claimed by both/);
+  });
+
+  test("refuses a spoke with no apps and a duplicate name", () => {
+    expect(() => new FleetConfig({ spokes: [{ name: "a", repo: "a.git", apps: [] }] })).toThrow(/declares no apps/);
+    expect(
+      () =>
+        new FleetConfig({
+          spokes: [
+            { name: "a", repo: "a.git", apps: ["one"] },
+            { name: "a", repo: "b.git", apps: ["two"] },
+          ],
+        }),
+    ).toThrow(/duplicate spoke/);
+  });
+
+  test("defaults the pushable branches and rejects anything else", () => {
+    const config = new FleetConfig({ spokes: [{ name: "a", repo: "a.git", apps: ["one"] }] });
+    expect(config.pushableBranches).toEqual(FleetConfig.defaultPushableBranches);
+    expect(() => config.assertPushable("feature/x")).toThrow(/not pushable/);
+    expect(() => config.assertPushable("develop")).not.toThrow();
+  });
+});