@akanjs/devkit 3.0.0-alpha.77 → 3.0.0-alpha.79

package/fleetSpoke.ts

@@ -0,0 +1,663 @@
+import { mkdir, readdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { AppExecutor, Executor, type WorkspaceExecutor } from "./executors";
+import { FileSys } from "./fileSys";
+import type { FleetConfig, FleetSpokeDeclaration } from "./fleetConfig";
+import { LibSource } from "./libSource";
+import { SlicePlanner } from "./slicePlanner";
+
+export interface FleetIncomingCommit {
+  sha: string;
+  author: string;
+  subject: string;
+}
+
+export interface FleetAnchor {
+  /** Spoke commit that last carried a push, located by the one file only a push writes. */
+  commit: string | null;
+  /** Commits the spoke gained since then — customer work that has never been in the hub. */
+  incoming: FleetIncomingCommit[];
+}
+
+export interface FleetSpokeStatus {
+  name: string;
+  branch: string;
+  /** False when the spoke has no such branch: a push refuses it rather than creating it. */
+  hasBranch: boolean;
+  anchor: FleetAnchor;
+  /** Slice paths where hub and spoke disagree — what a push would change. */
+  behindPaths: string[];
+  /** Libraries the spoke edited on its own: the drift this mechanism exists to stop. */
+  driftedLibs: string[];
+}
+
+export interface FleetDiffSection {
+  files: string[];
+  patch: string;
+}
+
+export interface FleetDiffResult {
+  name: string;
+  branch: string;
+  /** What `akan fleet push` would change in the spoke, split so library changes are impossible to miss. */
+  app: FleetDiffSection;
+  libs: FleetDiffSection;
+}
+
+export interface FleetPushResult {
+  name: string;
+  outcome: "pushed" | "skipped" | "refused";
+  reason?: string;
+  commit?: string;
+  changedFiles: number;
+}
+
+export interface FleetPullResult {
+  name: string;
+  applied: string[];
+  /** Library hunks, left on disk as a patch instead of applied unless `adoptLibs` was passed. */
+  libPatch: { path: string; files: string[] } | null;
+  ignored: string[];
+  incoming: FleetIncomingCommit[];
+}
+
+/**
+ * One customer repo, mirrored from this hub.
+ *
+ * Push is a squashed snapshot of the hub's own tracked files, so a spoke's history never carries the
+ * hub's — which is also what keeps one customer's commit messages out of another's repo. Pull is the
+ * reverse and rare: it compares the spoke against the last push it received rather than against the hub,
+ * so the diff is exactly the customer's own work however far the hub has moved on.
+ */
+export class FleetSpoke {
+  static readonly anchorFile = "akan.fleet.json";
+  /** Never reaches a spoke: it names every other customer's repo. */
+  static readonly hubOnlyEntries = ["akan.fleet.ts"];
+  /** Workspace members, which are replaced wholesale rather than overlaid. */
+  static readonly memberDirs = ["apps", "libs"];
+  /** Spoke-owned in both directions: env values belong to the repo that deploys, not to the hub. */
+  static readonly spokeOwnedDirs = ["env"];
+  static readonly secretsMarkers = ["# akan:secrets (managed by akan.config.ts — do not edit)", "# akan:secrets:end"];
+  static readonly holdDir = ".akan-fleet-hold";
+  static readonly guardHookLine = "bunx akan fleet check --staged --warn";
+  //? `fetch-depth: 0`: the guard locates the last push through history, which a shallow checkout lacks.
+  static readonly guardWorkflow = [
+    "name: akan fleet guard",
+    "on: [push, pull_request]",
+    "jobs:",
+    "  guard:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: oven-sh/setup-bun@v2",
+    "      - run: bun install",
+    "      - run: bunx akan fleet check",
+    "",
+  ].join("\n");
+
+  #workspace: WorkspaceExecutor;
+  #config: FleetConfig;
+  #declaration: FleetSpokeDeclaration;
+
+  constructor(workspace: WorkspaceExecutor, config: FleetConfig, declaration: FleetSpokeDeclaration) {
+    this.#workspace = workspace;
+    this.#config = config;
+    this.#declaration = declaration;
+  }
+
+  get name() {
+    return this.#declaration.name;
+  }
+  get apps() {
+    return this.#declaration.apps;
+  }
+  get #remote() {
+    return `spoke-${this.#declaration.name}`;
+  }
+  get #clonePath() {
+    return path.join(this.#workspace.workspaceRoot, ".akan/fleet", this.#declaration.name);
+  }
+
+  async #git(args: string[]) {
+    return await this.#workspace.spawn("git", args);
+  }
+
+  async branch() {
+    return (await this.#git(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+  }
+
+  async headSha() {
+    return (await this.#git(["rev-parse", "--short", "HEAD"])).trim();
+  }
+
+  /** Adds the spoke as a remote if absent, then fetches the branch into this hub's object store. */
+  async fetch(branch: string) {
+    const remotes = (await this.#git(["remote"])).split("\n").map((line) => line.trim());
+    if (remotes.includes(this.#remote)) await this.#git(["remote", "set-url", this.#remote, this.#declaration.repo]);
+    else await this.#git(["remote", "add", this.#remote, this.#declaration.repo]);
+    try {
+      await this.#git(["fetch", "--quiet", this.#remote, branch]);
+      return true;
+    } catch {
+      //? A spoke that has never had this branch is not an error here — `push` refuses it by name.
+      return false;
+    }
+  }
+
+  /**
+   * The last push, located by the one file only a push writes. A tag or a recorded sha would have to be
+   * kept in step by hand; this file is already in the spoke's history and cannot drift out of it.
+   */
+  async anchor(branch: string): Promise<FleetAnchor> {
+    const ref = `${this.#remote}/${branch}`;
+    const commit = (await this.#git(["log", "-1", "--format=%H", ref, "--", FleetSpoke.anchorFile])).trim();
+    if (!commit) return { commit: null, incoming: [] };
+    const log = await this.#git(["log", "--format=%H%x09%an%x09%s", `${commit}..${ref}`]);
+    const incoming = log
+      .split("\n")
+      .filter((line) => !!line.trim())
+      .map((line) => {
+        const [sha = "", author = "", ...subject] = line.split("\t");
+        return { sha: sha.slice(0, 12), author, subject: subject.join("\t") };
+      });
+    return { commit, incoming };
+  }
+
+  /** App and lib directories this spoke carries. Libraries come from each app's closure, never declared. */
+  async slice() {
+    const plans = await Promise.all(
+      this.#declaration.apps.map(
+        async (appName) => await new SlicePlanner(AppExecutor.from(this.#workspace, appName)).plan(),
+      ),
+    );
+    const libs = [...new Set(plans.flatMap((plan) => plan.libs))].sort();
+    const paths = [...this.#declaration.apps.map((app) => `apps/${app}`), ...libs.map((lib) => `libs/${lib}`)];
+    return { plans, libs, paths };
+  }
+
+  #isSpokeOwned(file: string) {
+    const segments = file.split("/");
+    if (!FleetSpoke.memberDirs.includes(segments[0] ?? "")) return false;
+    return FleetSpoke.spokeOwnedDirs.includes(segments[2] ?? "");
+  }
+
+  /**
+   * A library manifest always differs: the spoke's copy carries the `akan.source` stamp a push writes and
+   * the hub's does not. Comparing it with that key removed is what keeps `status` and `diff` from
+   * reporting every library as changed forever.
+   */
+  #isStamped(file: string) {
+    return /^libs\/[^/]+\/package\.json$/.test(file);
+  }
+
+  async #differsBeyondStamp(ref: string, file: string) {
+    const [theirs, ours] = await Promise.all([
+      this.#git(["show", `${ref}:${file}`]).catch(() => ""),
+      this.#git(["show", `HEAD:${file}`]).catch(() => ""),
+    ]);
+    if (!theirs || !ours) return true;
+    const normalize = (content: string) => {
+      try {
+        const manifest = JSON.parse(content) as Record<string, unknown>;
+        delete manifest[LibSource.manifestKey];
+        return JSON.stringify(manifest);
+      } catch {
+        return content;
+      }
+    };
+    return normalize(theirs) !== normalize(ours);
+  }
+
+  async #meaningfulFiles(ref: string, files: string[]) {
+    const kept = await Promise.all(
+      files.map(async (file) => (this.#isStamped(file) ? await this.#differsBeyondStamp(ref, file) : true)),
+    );
+    return files.filter((_, index) => kept[index]);
+  }
+
+  async status(branch: string): Promise<FleetSpokeStatus> {
+    const hasBranch = await this.fetch(branch);
+    const [{ paths, libs }, anchor] = await Promise.all([
+      this.slice(),
+      hasBranch ? this.anchor(branch) : Promise.resolve<FleetAnchor>({ commit: null, incoming: [] }),
+    ]);
+    if (!hasBranch) return { name: this.name, branch, hasBranch, anchor, behindPaths: [], driftedLibs: [] };
+    const ref = `${this.#remote}/${branch}`;
+    const diff = await this.#git(["diff", "--name-only", "HEAD", ref, "--", ...paths]);
+    const behindPaths = await this.#meaningfulFiles(
+      ref,
+      diff
+        .split("\n")
+        .filter((file) => !!file.trim())
+        .filter((file) => !this.#isSpokeOwned(file)),
+    );
+    const driftedLibs = libs.filter((lib) => behindPaths.some((file) => file.startsWith(`libs/${lib}/`)));
+    return { name: this.name, branch, hasBranch, anchor, behindPaths, driftedLibs };
+  }
+
+  async #ensureClone(branch: string) {
+    if (!(await FileSys.dirExists(path.join(this.#clonePath, ".git")))) {
+      await rm(this.#clonePath, { recursive: true, force: true });
+      await mkdir(path.dirname(this.#clonePath), { recursive: true });
+      await this.#workspace.spawn("git", ["clone", "--quiet", this.#declaration.repo, this.#clonePath]);
+    }
+    const clone = new Executor(`spoke-${this.name}`, this.#clonePath);
+    await clone.spawn("git", ["fetch", "--quiet", "origin", branch]);
+    await clone.spawn("git", ["checkout", "--quiet", "-B", branch, `origin/${branch}`]);
+    await clone.spawn("git", ["clean", "-qfd"]);
+    return clone;
+  }
+
+  /** Moves the spoke's env trees aside, so replacing the members cannot take them with it. */
+  async #holdSpokeOwned() {
+    const held: { from: string; to: string }[] = [];
+    const holdRoot = path.join(this.#clonePath, FleetSpoke.holdDir);
+    await rm(holdRoot, { recursive: true, force: true });
+    for (const member of FleetSpoke.memberDirs) {
+      const memberRoot = path.join(this.#clonePath, member);
+      if (!(await FileSys.dirExists(memberRoot))) continue;
+      for (const name of await readdir(memberRoot)) {
+        for (const owned of FleetSpoke.spokeOwnedDirs) {
+          const from = path.join(memberRoot, name, owned);
+          if (!(await FileSys.dirExists(from))) continue;
+          const to = path.join(holdRoot, member, name, owned);
+          await mkdir(path.dirname(to), { recursive: true });
+          await rename(from, to);
+          held.push({ from, to });
+        }
+      }
+    }
+    return held;
+  }
+
+  /**
+   * Puts back only the files the hub does not ship. The hub still owns the tracked env switch files
+   * (`env.server.ts` / `env.client.ts`), which is what keeps them in step; everything else under `env/` —
+   * the per-environment values, which the hub gitignores and never had — belongs to the spoke and wins.
+   */
+  async #restoreSpokeOwned(held: { from: string; to: string }[]) {
+    for (const { from, to } of held) await FleetSpoke.#copyMissing(to, from);
+    await rm(path.join(this.#clonePath, FleetSpoke.holdDir), { recursive: true, force: true });
+  }
+
+  static async #copyMissing(from: string, to: string) {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from, { withFileTypes: true })) {
+      const source = path.join(from, entry.name);
+      const target = path.join(to, entry.name);
+      if (entry.isDirectory()) await FleetSpoke.#copyMissing(source, target);
+      else if (!(await FileSys.entryExists(target))) await rename(source, target);
+    }
+  }
+
+  /**
+   * `git archive` emits exactly the tracked files at HEAD, which is why the copy needs no exclude list of
+   * its own: generated barrels, the `(libs)`/`public/libs` symlinks, env values, secrets and the lockfile
+   * are all outside git and cannot enter the archive. Directory arguments only — a file list would put
+   * route paths like `page/(docs)/…` through a shell.
+   */
+  async #extract(paths: string[], excludes: string[] = []) {
+    const pathspec = paths.map((entry) => `'${entry}'`).join(" ");
+    const excludeArgs = excludes.map((entry) => `--exclude='${entry}'`).join(" ");
+    await this.#workspace.exec(
+      `git archive HEAD -- ${pathspec} | tar -x -C '${this.#clonePath}' ${excludeArgs}`.trim(),
+    );
+  }
+
+  async #applySlice(clone: Executor, branch: string) {
+    const { libs, paths } = await this.slice();
+    const held = await this.#holdSpokeOwned();
+    for (const member of FleetSpoke.memberDirs)
+      await rm(path.join(this.#clonePath, member), { recursive: true, force: true });
+
+    //* The shell is overlaid, never reconciled: a spoke owns its deployment (its own CI files and
+    //* workflows live there), so a root entry the hub does not have is left alone rather than deleted.
+    await this.#extract(["."], ["apps/*", "libs/*", "pkgs/*"]);
+    await this.#extract(paths);
+    await this.#restoreSpokeOwned(held);
+
+    for (const entry of [...FleetSpoke.hubOnlyEntries, ...this.#config.exclude])
+      await rm(path.join(this.#clonePath, entry), { recursive: true, force: true });
+
+    await this.#rewriteGitignore();
+    await this.#rewriteWorkspaceSection(libs);
+    await this.#writeGuards();
+    for (const lib of libs) await this.#stampLib(clone, lib, branch);
+    return { libs };
+  }
+
+  /**
+   * The `akan:secrets` block akan generates lists every app in the hub by name, so it is filtered down to
+   * this spoke's own apps. `bun.lock` is un-ignored because a spoke commits its lockfile — that is what
+   * makes two spokes on one branch resolve the same dependency tree rather than merely the same ranges.
+   */
+  async #rewriteGitignore() {
+    const gitignorePath = path.join(this.#clonePath, ".gitignore");
+    if (!(await FileSys.fileExists(gitignorePath))) return;
+    const [begin = "", end = ""] = FleetSpoke.secretsMarkers;
+    const lines = (await FileSys.readText(gitignorePath)).split("\n");
+    const beginIdx = lines.indexOf(begin);
+    const endIdx = lines.indexOf(end);
+    const filtered =
+      beginIdx >= 0 && endIdx > beginIdx
+        ? [
+            ...lines.slice(0, beginIdx + 1),
+            ...lines
+              .slice(beginIdx + 1, endIdx)
+              .filter((line) => this.#declaration.apps.some((app) => line.startsWith(`apps/${app}/`))),
+            ...lines.slice(endIdx),
+          ]
+        : lines;
+    await FileSys.writeText(gitignorePath, filtered.filter((line) => line.trim() !== "**/bun.lock").join("\n"));
+  }
+
+  /** The generated `## Workspace` block names every app and library in the hub. */
+  async #rewriteWorkspaceSection(libs: string[]) {
+    const replacements = [
+      [/^- Repo: .*$/m, `- Repo: ${this.name}`],
+      [/^- Apps: .*$/m, `- Apps: ${this.#declaration.apps.join(", ")}`],
+      [/^- Libraries: .*$/m, `- Libraries: ${libs.length ? libs.join(", ") : "(none)"}`],
+    ] as const;
+    for (const file of ["AGENTS.md", "CLAUDE.md"]) {
+      const filePath = path.join(this.#clonePath, file);
+      if (!(await FileSys.fileExists(filePath))) continue;
+      const content = await FileSys.readText(filePath);
+      const rewritten = replacements.reduce((text, [pattern, value]) => text.replace(pattern, value), content);
+      if (rewritten !== content) await FileSys.writeText(filePath, rewritten);
+    }
+  }
+
+  /**
+   * Written onto the clone's manifest directly rather than through `LibSource`, which addresses a library
+   * by its position in the *hub's* workspace. The hash follows the same rule — the library's own git files
+   * with `env/` and the stamp itself left out — and is only written when it would change, so an
+   * up-to-date spoke stays clean and the push is skipped.
+   */
+  async #stampLib(clone: Executor, lib: string, branch: string) {
+    const manifestPath = path.join(this.#clonePath, "libs", lib, "package.json");
+    if (!(await FileSys.fileExists(manifestPath))) return;
+    const origin = `${this.#workspace.repoName}#${branch}`;
+    const sha = await this.headSha();
+    const [hash, previous] = await Promise.all([this.#hashLib(clone, lib), this.#committedStamp(clone, lib)]);
+    const manifest = (await FileSys.readJson(manifestPath)) as Record<string, unknown>;
+    const akan = (manifest[LibSource.manifestKey] ?? {}) as Record<string, unknown>;
+    //* The extraction overwrote the manifest with the hub's, stamp and all, so the previous stamp has to
+    //* come from the clone's HEAD. Reusing its `syncedAt` when nothing else moved is what leaves the file
+    //* byte-identical to what is committed — otherwise every push is dirty and none is ever skipped.
+    const unchanged = previous?.origin === origin && previous.sha === sha && previous.hash === hash;
+    const syncedAt = unchanged ? previous.syncedAt : new Date().toISOString();
+    manifest[LibSource.manifestKey] = { ...akan, source: { origin, sha, hash, syncedAt } };
+    await FileSys.writeJson(manifestPath, manifest);
+  }
+
+  async #committedStamp(clone: Executor, lib: string) {
+    try {
+      const committed = await clone.spawn("git", ["show", `HEAD:libs/${lib}/package.json`]);
+      const manifest = JSON.parse(committed) as Record<string, unknown>;
+      const akan = (manifest[LibSource.manifestKey] ?? {}) as Record<string, unknown>;
+      return akan.source as { origin: string; sha: string; hash: string; syncedAt: string } | undefined;
+    } catch {
+      //? First push: the library is not in the spoke's history yet.
+      return undefined;
+    }
+  }
+
+  async #hashLib(clone: Executor, lib: string) {
+    const listed = await clone.spawn("git", [
+      "ls-files",
+      "-z",
+      "--cached",
+      "--others",
+      "--exclude-standard",
+      "--",
+      `libs/${lib}`,
+    ]);
+    const files = listed
+      .split("\0")
+      .filter((file) => !!file && !this.#isSpokeOwned(file))
+      .sort();
+    const hasher = new Bun.CryptoHasher("sha256");
+    for (const file of files) {
+      const content = await FileSys.readText(path.join(this.#clonePath, file));
+      hasher.update(file);
+      hasher.update("\0");
+      if (file === `libs/${lib}/package.json`) {
+        const manifest = JSON.parse(content) as Record<string, unknown>;
+        delete manifest[LibSource.manifestKey];
+        hasher.update(JSON.stringify(manifest));
+      } else hasher.update(content);
+      hasher.update("\0");
+    }
+    return hasher.digest("hex").slice(0, 32);
+  }
+
+  /** Direction is spoke → hub, so the patch reads as what a push would apply rather than its inverse. */
+  async diff(branch: string, filter?: string | null): Promise<FleetDiffResult> {
+    if (!(await this.fetch(branch))) throw new Error(`Spoke "${this.name}" has no branch "${branch}"`);
+    const { libs, paths } = await this.slice();
+    const libPaths = libs.map((lib) => `libs/${lib}`);
+    const appPaths = paths.filter((entry) => !libPaths.includes(entry));
+    const [app, libSection] = await Promise.all([
+      this.#diffSection(branch, appPaths, filter),
+      this.#diffSection(branch, libPaths, filter),
+    ]);
+    return { name: this.name, branch, app, libs: libSection };
+  }
+
+  async #diffSection(branch: string, paths: string[], filter?: string | null): Promise<FleetDiffSection> {
+    const scoped = filter ? paths.filter((entry) => entry.startsWith(filter) || filter.startsWith(entry)) : paths;
+    if (!scoped.length) return { files: [], patch: "" };
+    const from = `${this.#remote}/${branch}`;
+    const pathspec = filter ? [filter] : scoped;
+    const names = await this.#git(["diff", "--name-only", from, "HEAD", "--", ...pathspec]);
+    const files = await this.#meaningfulFiles(
+      from,
+      names
+        .split("\n")
+        .filter((file) => !!file.trim())
+        .filter((file) => !this.#isSpokeOwned(file)),
+    );
+    if (!files.length) return { files: [], patch: "" };
+    //? argv, not a shell: a route path such as `page/(docs)/…` would need quoting through one.
+    return { files, patch: await this.#git(["diff", from, "HEAD", "--", ...files]) };
+  }
+
+  /**
+   * The spoke-side guard, which is one line calling `akan fleet check` rather than a script of its own —
+   * the logic lives in the CLI, so a spoke never carries a copy that can rot. Written after the shell
+   * overlay, since the hub's own `.husky/pre-commit` travels with it and would otherwise win.
+   */
+  async #writeGuards() {
+    const { ci, preCommit } = this.#config.guard;
+    if (ci === "github") {
+      const workflowPath = path.join(this.#clonePath, ".github/workflows/akan-fleet-guard.yml");
+      await mkdir(path.dirname(workflowPath), { recursive: true });
+      await FileSys.writeText(workflowPath, FleetSpoke.guardWorkflow);
+    }
+    if (!preCommit) return;
+    const hookPath = path.join(this.#clonePath, ".husky/pre-commit");
+    const existing = (await FileSys.fileExists(hookPath)) ? await FileSys.readText(hookPath) : "";
+    if (existing.includes(FleetSpoke.guardHookLine)) return;
+    await mkdir(path.dirname(hookPath), { recursive: true });
+    const content = existing.trim()
+      ? `${existing.replace(/\n*$/, "\n")}${FleetSpoke.guardHookLine}\n`
+      : `${FleetSpoke.guardHookLine}\n`;
+    await FileSys.writeText(hookPath, content);
+  }
+
+  async push(branch: string, { verify = true }: { verify?: boolean } = {}): Promise<FleetPushResult> {
+    this.#config.assertPushable(branch);
+    if (await this.#workspace.hasChanges())
+      return { name: this.name, outcome: "refused", reason: "hub working tree is dirty", changedFiles: 0 };
+    if (!(await this.fetch(branch)))
+      return { name: this.name, outcome: "refused", reason: `spoke has no branch "${branch}"`, changedFiles: 0 };
+
+    const clone = await this.#ensureClone(branch);
+    await this.#applySlice(clone, branch);
+
+    const dirty = (await clone.spawn("git", ["status", "--porcelain"])).trim();
+    if (!dirty) return { name: this.name, outcome: "skipped", reason: "already up to date", changedFiles: 0 };
+
+    await this.#writeAnchorFile(branch);
+    if (verify) {
+      await clone.spawn("bun", ["install"]);
+      for (const app of this.#declaration.apps) await clone.spawn("bunx", ["akan", "sync", app]);
+    }
+    await clone.spawn("git", ["add", "-A"]);
+    const message = `chore(fleet): sync from ${this.#workspace.repoName}@${await this.headSha()}`;
+    await clone.spawn("git", ["commit", "--quiet", "-m", message]);
+    //* Never force: a diverged spoke holds customer commits, and `pull` is how those come back.
+    await clone.spawn("git", ["push", "--quiet", "origin", branch]);
+    return {
+      name: this.name,
+      outcome: "pushed",
+      commit: (await clone.spawn("git", ["rev-parse", "--short", "HEAD"])).trim(),
+      changedFiles: dirty.split("\n").length,
+    };
+  }
+
+  async #writeAnchorFile(branch: string) {
+    await FileSys.writeJson(path.join(this.#clonePath, FleetSpoke.anchorFile), {
+      hub: this.#workspace.repoName,
+      hubSha: await this.headSha(),
+      branch,
+      apps: this.#declaration.apps,
+      syncedAt: new Date().toISOString(),
+    });
+  }
+
+  async pull(branch: string, { adoptLibs = false }: { adoptLibs?: boolean } = {}): Promise<FleetPullResult> {
+    if (!(await this.fetch(branch))) throw new Error(`Spoke "${this.name}" has no branch "${branch}"`);
+    const anchor = await this.anchor(branch);
+    if (!anchor.commit)
+      throw new Error(`Spoke "${this.name}" carries no ${FleetSpoke.anchorFile} — it has never received a push`);
+    if (!anchor.incoming.length) return { name: this.name, applied: [], libPatch: null, ignored: [], incoming: [] };
+
+    const range = `${anchor.commit}..${this.#remote}/${branch}`;
+    const changed = (await this.#git(["diff", "--name-only", range])).split("\n").filter((file) => !!file.trim());
+    const appPrefixes = this.#declaration.apps.map((app) => `apps/${app}/`);
+    const appFiles = changed.filter(
+      (file) => appPrefixes.some((prefix) => file.startsWith(prefix)) && !this.#isSpokeOwned(file),
+    );
+    const libFiles = changed.filter((file) => file.startsWith("libs/") && !this.#isSpokeOwned(file));
+    const ignored = changed.filter((file) => !appFiles.includes(file) && !libFiles.includes(file));
+
+    const applied = adoptLibs ? [...appFiles, ...libFiles] : appFiles;
+    if (applied.length) await this.#applyPatch(range, applied, "incoming");
+    const saved = !adoptLibs && libFiles.length ? await this.#savePatch(range, libFiles, "libs") : null;
+    const libPatch = saved ? { path: saved.path, files: saved.files } : null;
+    return { name: this.name, applied, libPatch, ignored, incoming: anchor.incoming };
+  }
+
+  /** Left uncommitted in the hub's working tree: a conflict is a normal 3-way conflict for a person. */
+  async #applyPatch(range: string, files: string[], label: string) {
+    const { absolute } = await this.#savePatch(range, files, label);
+    await this.#git(["apply", "--3way", absolute]);
+  }
+
+  /**
+   * A library hunk is never applied by default: the hub is the one copy every other spoke is pushed from,
+   * so adopting one customer's edit silently would ship it to all of them.
+   */
+  async #savePatch(range: string, files: string[], label: string) {
+    const patchPath = path.join(this.#workspace.workspaceRoot, ".akan/fleet", `${this.name}-${label}.patch`);
+    await mkdir(path.dirname(patchPath), { recursive: true });
+    await FileSys.writeText(patchPath, await this.#git(["diff", range, "--", ...files]));
+    return { path: path.relative(this.#workspace.workspaceRoot, patchPath), absolute: patchPath, files };
+  }
+}
+
+export function formatFleetStatuses(statuses: FleetSpokeStatus[]) {
+  const sections = [
+    "Akan Fleet Status",
+    `branch: ${statuses[0]?.branch ?? "(none)"}`,
+    "",
+    ...statuses.flatMap((status) => {
+      if (!status.hasBranch) return [`  ${status.name}: no such branch in the spoke — push is refused`];
+      const behind = status.behindPaths.length ? `${status.behindPaths.length} file(s) behind` : "up to date";
+      const incoming = status.anchor.incoming.length
+        ? `${status.anchor.incoming.length} customer commit(s) to pull`
+        : "no customer commits";
+      const drift = status.driftedLibs.length ? `  DRIFTED LIBS: ${status.driftedLibs.join(", ")}` : null;
+      return [
+        `  ${status.name}: ${behind}, ${incoming}`,
+        ...status.anchor.incoming.map((commit) => `    ${commit.sha}  ${commit.author}  ${commit.subject}`),
+        ...(drift ? [drift] : []),
+      ];
+    }),
+  ];
+  return sections.join("\n");
+}
+
+export function formatFleetPushResults(results: FleetPushResult[]) {
+  const sections = [
+    "Akan Fleet Push",
+    "",
+    ...results.map((result) => {
+      const detail =
+        result.outcome === "pushed" ? `${result.commit} (${result.changedFiles} files)` : (result.reason ?? "");
+      return `  ${result.outcome.padEnd(8)} ${result.name}  ${detail}`;
+    }),
+  ];
+  return sections.join("\n");
+}
+
+export function formatFleetPullResult(result: FleetPullResult) {
+  const sections = [
+    `Akan Fleet Pull — ${result.name}`,
+    "",
+    `Customer commits since the last push (${result.incoming.length}):`,
+    "",
+    ...(result.incoming.length
+      ? result.incoming.map((commit) => `  ${commit.sha}  ${commit.author}  ${commit.subject}`)
+      : ["  (none — nothing to pull)"]),
+    "",
+    `Applied to the working tree, uncommitted (${result.applied.length}):`,
+    "",
+    ...(result.applied.length ? result.applied.map((file) => `  ${file}`) : ["  (none)"]),
+    ...(result.libPatch
+      ? [
+          "",
+          `Library edits NOT applied (${result.libPatch.files.length}) — review before adopting:`,
+          "",
+          ...result.libPatch.files.map((file) => `  ${file}`),
+          "",
+          `  patch: ${result.libPatch.path}`,
+          "  adopt with: akan fleet pull <name> --adopt-libs",
+        ]
+      : []),
+    ...(result.ignored.length ? ["", `Ignored (hub-owned or spoke-owned): ${result.ignored.length} file(s)`] : []),
+  ];
+  return sections.join("\n");
+}
+
+export function formatFleetDiff(result: FleetDiffResult) {
+  const total = result.app.files.length + result.libs.files.length;
+  const sections = [
+    `Akan Fleet Diff — ${result.name} (${result.branch})`,
+    "what `akan fleet push` would change in the spoke",
+    "",
+    ...(total ? [] : ["  spoke is identical to the hub for this slice."]),
+    ...(result.libs.files.length
+      ? [
+          `LIBRARY changes (${result.libs.files.length}) — the spoke edited shared code:`,
+          "",
+          ...result.libs.files.map((file) => `  ${file}`),
+          "",
+          result.libs.patch,
+        ]
+      : []),
+    ...(result.app.files.length
+      ? [
+          `App changes (${result.app.files.length}):`,
+          "",
+          ...result.app.files.map((file) => `  ${file}`),
+          "",
+          result.app.patch,
+        ]
+      : []),
+  ];
+  return sections.join("\n");
+}

package/libSource.ts

@@ -91,6 +91,18 @@ export class LibSource {
     return stamp;
   }
 
+  /**
+   * Writes the stamp only when it would change. `syncedAt` moves on every write, so an unconditional
+   * write leaves the manifest dirty and defeats an idempotent caller — the hash is computed with the
+   * stamp removed, so comparing it first is sound.
+   */
+  async syncStamp({ origin, sha }: Pick<LibSourceStamp, "origin" | "sha">) {
+    const [current, hash] = await Promise.all([this.read(), this.computeHash()]);
+    if (current?.origin === origin && current.sha === sha && current.hash === hash)
+      return { stamp: current, changed: false };
+    return { stamp: await this.write({ origin, sha }), changed: true };
+  }
+
   async status(): Promise<LibStatus> {
     const [stamp, hash] = await Promise.all([this.read(), this.computeHash()]);
     const drift = !stamp ? "unstamped" : stamp.hash === hash ? "clean" : "drifted";