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

package/fleet.command-jv24wcae.js

@@ -0,0 +1,793 @@
+// @bun
+import {
+  SlicePlanner
+} from "./index-jn9b717k.js";
+import {
+  LibSource
+} from "./index-19nz5chq.js";
+import {
+  Workspace,
+  command,
+  runner,
+  script
+} from "./index-1szrbtj9.js";
+import {
+  AppExecutor,
+  Executor,
+  LibExecutor
+} from "./index-zkrzv21w.js";
+import"./index-dp66vwr6.js";
+import"./index-mxvakhsm.js";
+import"./index-1577bej2.js";
+import {
+  FileSys
+} from "./index-67546d0j.js";
+import"./index-yb2wsc7f.js";
+
+// pkgs/@akanjs/devkit/fleetGuard.ts
+import path from "path";
+class FleetGuard {
+  static anchorFile = "akan.fleet.json";
+  static hubOwnedRootFiles = ["package.json", "tsconfig.json", "biome.json", "bunfig.toml"];
+  static spokeOwnedDirs = ["env"];
+  static contact = "Ask the akansoft team to make this change in the hub, then pull it back down.";
+  #workspace;
+  constructor(workspace) {
+    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);
+  }
+  async#anchorCommit() {
+    const commit = await this.#workspace.spawn("git", ["log", "-1", "--format=%H", "--", FleetGuard.anchorFile]);
+    return commit.trim() || null;
+  }
+  #isSpokeOwned(file) {
+    const segments = file.split("/");
+    if (segments[0] !== "apps" && segments[0] !== "libs")
+      return false;
+    return FleetGuard.spokeOwnedDirs.includes(segments[2] ?? "");
+  }
+  #violationOf(file) {
+    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 }) {
+    if (staged) {
+      const cached = await this.#workspace.spawn("git", ["diff", "--cached", "--name-only"]);
+      return cached.split(`
+`).filter((file) => !!file.trim());
+    }
+    const anchor = await this.#anchorCommit();
+    const sinceAnchor = anchor ? (await this.#workspace.spawn("git", ["diff", "--name-only", `${anchor}..HEAD`])).split(`
+`).filter((file) => !!file.trim()) : [];
+    const working = (await this.#workspace.spawn("git", ["status", "--porcelain"])).split(`
+`).filter((line) => !!line.trim()).map((line) => line.slice(3).split(" -> ").at(-1) ?? "").filter((file) => !!file);
+    return [...new Set([...sinceAnchor, ...working])];
+  }
+  async#libDrift() {
+    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 } = {}) {
+    const spoke = await this.#readAnchorFile();
+    if (!spoke)
+      return { spoke: null, anchor: null, violations: [], driftedLibs: [] };
+    const [anchor, changed, driftedLibs] = await Promise.all([
+      this.#anchorCommit(),
+      this.#changedFiles({ staged }),
+      staged ? Promise.resolve([]) : this.#libDrift()
+    ]);
+    const violations = changed.map((file) => this.#violationOf(file)).filter((violation) => !!violation);
+    return { spoke, anchor, violations, driftedLibs };
+  }
+}
+function formatFleetGuardReport(report, { warn = false } = {}) {
+  if (!report.spoke)
+    return "Akan Fleet Guard: not a fleet spoke (no akan.fleet.json) \u2014 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}  \u2014 ${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 \u2014 this commit is not blocked)"] : []]
+  ];
+  return sections.join(`
+`);
+}
+
+// pkgs/@akanjs/devkit/fleetSpoke.ts
+import { mkdir, readdir, rename, rm } from "fs/promises";
+import path2 from "path";
+class FleetSpoke {
+  static anchorFile = "akan.fleet.json";
+  static hubOnlyEntries = ["akan.fleet.ts"];
+  static memberDirs = ["apps", "libs"];
+  static spokeOwnedDirs = ["env"];
+  static secretsMarkers = ["# akan:secrets (managed by akan.config.ts \u2014 do not edit)", "# akan:secrets:end"];
+  static holdDir = ".akan-fleet-hold";
+  static guardHookLine = "bunx akan fleet check --staged --warn";
+  static 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(`
+`);
+  #workspace;
+  #config;
+  #declaration;
+  constructor(workspace, config, declaration) {
+    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 path2.join(this.#workspace.workspaceRoot, ".akan/fleet", this.#declaration.name);
+  }
+  async#git(args) {
+    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();
+  }
+  async fetch(branch) {
+    const remotes = (await this.#git(["remote"])).split(`
+`).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 {
+      return false;
+    }
+  }
+  async anchor(branch) {
+    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(`
+`).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 };
+  }
+  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) {
+    const segments = file.split("/");
+    if (!FleetSpoke.memberDirs.includes(segments[0] ?? ""))
+      return false;
+    return FleetSpoke.spokeOwnedDirs.includes(segments[2] ?? "");
+  }
+  #isStamped(file) {
+    return /^libs\/[^/]+\/package\.json$/.test(file);
+  }
+  async#differsBeyondStamp(ref, file) {
+    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) => {
+      try {
+        const manifest = JSON.parse(content);
+        delete manifest[LibSource.manifestKey];
+        return JSON.stringify(manifest);
+      } catch {
+        return content;
+      }
+    };
+    return normalize(theirs) !== normalize(ours);
+  }
+  async#meaningfulFiles(ref, files) {
+    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) {
+    const hasBranch = await this.fetch(branch);
+    const [{ paths, libs }, anchor] = await Promise.all([
+      this.slice(),
+      hasBranch ? this.anchor(branch) : Promise.resolve({ 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(`
+`).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) {
+    if (!await FileSys.dirExists(path2.join(this.#clonePath, ".git"))) {
+      await rm(this.#clonePath, { recursive: true, force: true });
+      await mkdir(path2.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;
+  }
+  async#holdSpokeOwned() {
+    const held = [];
+    const holdRoot = path2.join(this.#clonePath, FleetSpoke.holdDir);
+    await rm(holdRoot, { recursive: true, force: true });
+    for (const member of FleetSpoke.memberDirs) {
+      const memberRoot = path2.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 = path2.join(memberRoot, name, owned);
+          if (!await FileSys.dirExists(from))
+            continue;
+          const to = path2.join(holdRoot, member, name, owned);
+          await mkdir(path2.dirname(to), { recursive: true });
+          await rename(from, to);
+          held.push({ from, to });
+        }
+      }
+    }
+    return held;
+  }
+  async#restoreSpokeOwned(held) {
+    for (const { from, to } of held)
+      await FleetSpoke.#copyMissing(to, from);
+    await rm(path2.join(this.#clonePath, FleetSpoke.holdDir), { recursive: true, force: true });
+  }
+  static async#copyMissing(from, to) {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from, { withFileTypes: true })) {
+      const source = path2.join(from, entry.name);
+      const target = path2.join(to, entry.name);
+      if (entry.isDirectory())
+        await FleetSpoke.#copyMissing(source, target);
+      else if (!await FileSys.entryExists(target))
+        await rename(source, target);
+    }
+  }
+  async#extract(paths, excludes = []) {
+    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, branch) {
+    const { libs, paths } = await this.slice();
+    const held = await this.#holdSpokeOwned();
+    for (const member of FleetSpoke.memberDirs)
+      await rm(path2.join(this.#clonePath, member), { recursive: true, force: true });
+    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(path2.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 };
+  }
+  async#rewriteGitignore() {
+    const gitignorePath = path2.join(this.#clonePath, ".gitignore");
+    if (!await FileSys.fileExists(gitignorePath))
+      return;
+    const [begin = "", end = ""] = FleetSpoke.secretsMarkers;
+    const lines = (await FileSys.readText(gitignorePath)).split(`
+`);
+    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(`
+`));
+  }
+  async#rewriteWorkspaceSection(libs) {
+    const replacements = [
+      [/^- Repo: .*$/m, `- Repo: ${this.name}`],
+      [/^- Apps: .*$/m, `- Apps: ${this.#declaration.apps.join(", ")}`],
+      [/^- Libraries: .*$/m, `- Libraries: ${libs.length ? libs.join(", ") : "(none)"}`]
+    ];
+    for (const file of ["AGENTS.md", "CLAUDE.md"]) {
+      const filePath = path2.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);
+    }
+  }
+  async#stampLib(clone, lib, branch) {
+    const manifestPath = path2.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);
+    const akan = manifest[LibSource.manifestKey] ?? {};
+    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, lib) {
+    try {
+      const committed = await clone.spawn("git", ["show", `HEAD:libs/${lib}/package.json`]);
+      const manifest = JSON.parse(committed);
+      const akan = manifest[LibSource.manifestKey] ?? {};
+      return akan.source;
+    } catch {
+      return;
+    }
+  }
+  async#hashLib(clone, lib) {
+    const listed = await clone.spawn("git", [
+      "ls-files",
+      "-z",
+      "--cached",
+      "--others",
+      "--exclude-standard",
+      "--",
+      `libs/${lib}`
+    ]);
+    const files = listed.split("\x00").filter((file) => !!file && !this.#isSpokeOwned(file)).sort();
+    const hasher = new Bun.CryptoHasher("sha256");
+    for (const file of files) {
+      const content = await FileSys.readText(path2.join(this.#clonePath, file));
+      hasher.update(file);
+      hasher.update("\x00");
+      if (file === `libs/${lib}/package.json`) {
+        const manifest = JSON.parse(content);
+        delete manifest[LibSource.manifestKey];
+        hasher.update(JSON.stringify(manifest));
+      } else
+        hasher.update(content);
+      hasher.update("\x00");
+    }
+    return hasher.digest("hex").slice(0, 32);
+  }
+  async diff(branch, filter) {
+    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, paths, filter) {
+    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(`
+`).filter((file) => !!file.trim()).filter((file) => !this.#isSpokeOwned(file)));
+    if (!files.length)
+      return { files: [], patch: "" };
+    return { files, patch: await this.#git(["diff", from, "HEAD", "--", ...files]) };
+  }
+  async#writeGuards() {
+    const { ci, preCommit } = this.#config.guard;
+    if (ci === "github") {
+      const workflowPath = path2.join(this.#clonePath, ".github/workflows/akan-fleet-guard.yml");
+      await mkdir(path2.dirname(workflowPath), { recursive: true });
+      await FileSys.writeText(workflowPath, FleetSpoke.guardWorkflow);
+    }
+    if (!preCommit)
+      return;
+    const hookPath = path2.join(this.#clonePath, ".husky/pre-commit");
+    const existing = await FileSys.fileExists(hookPath) ? await FileSys.readText(hookPath) : "";
+    if (existing.includes(FleetSpoke.guardHookLine))
+      return;
+    await mkdir(path2.dirname(hookPath), { recursive: true });
+    const content = existing.trim() ? `${existing.replace(/\n*$/, `
+`)}${FleetSpoke.guardHookLine}
+` : `${FleetSpoke.guardHookLine}
+`;
+    await FileSys.writeText(hookPath, content);
+  }
+  async push(branch, { verify = true } = {}) {
+    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]);
+    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(`
+`).length
+    };
+  }
+  async#writeAnchorFile(branch) {
+    await FileSys.writeJson(path2.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, { adoptLibs = false } = {}) {
+    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} \u2014 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(`
+`).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 };
+  }
+  async#applyPatch(range, files, label) {
+    const { absolute } = await this.#savePatch(range, files, label);
+    await this.#git(["apply", "--3way", absolute]);
+  }
+  async#savePatch(range, files, label) {
+    const patchPath = path2.join(this.#workspace.workspaceRoot, ".akan/fleet", `${this.name}-${label}.patch`);
+    await mkdir(path2.dirname(patchPath), { recursive: true });
+    await FileSys.writeText(patchPath, await this.#git(["diff", range, "--", ...files]));
+    return { path: path2.relative(this.#workspace.workspaceRoot, patchPath), absolute: patchPath, files };
+  }
+}
+function formatFleetStatuses(statuses) {
+  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 \u2014 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(`
+`);
+}
+function formatFleetPushResults(results) {
+  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(`
+`);
+}
+function formatFleetPullResult(result) {
+  const sections = [
+    `Akan Fleet Pull \u2014 ${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 \u2014 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}) \u2014 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(`
+`);
+}
+function formatFleetDiff(result) {
+  const total = result.app.files.length + result.libs.files.length;
+  const sections = [
+    `Akan Fleet Diff \u2014 ${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}) \u2014 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(`
+`);
+}
+
+// pkgs/@akanjs/cli/fleet/fleet.script.ts
+import { Logger } from "akanjs/common";
+
+// pkgs/@akanjs/devkit/fleetConfig.ts
+import path3 from "path";
+class FleetConfig {
+  static fileName = "akan.fleet.ts";
+  static defaultPushableBranches = ["main", "develop", "debug"];
+  static defaultGuard = { ci: "github", preCommit: true };
+  static async from(workspace) {
+    const configPath = path3.join(workspace.workspaceRoot, FleetConfig.fileName);
+    if (!await FileSys.fileExists(configPath))
+      return null;
+    const input = await import(configPath).then((mod) => mod.default);
+    return new FleetConfig(input);
+  }
+  pushableBranches;
+  exclude;
+  guard;
+  spokes;
+  constructor(input) {
+    this.pushableBranches = input.pushableBranches ?? FleetConfig.defaultPushableBranches;
+    this.exclude = input.exclude ?? [];
+    this.guard = { ...FleetConfig.defaultGuard, ...input.guard };
+    this.spokes = input.spokes ?? [];
+    this.#assertValid();
+  }
+  #assertValid() {
+    const seenNames = new Set;
+    const appOwners = new Map;
+    for (const spoke of this.spokes) {
+      if (!spoke.name || !spoke.repo)
+        throw new Error(`${FleetConfig.fileName}: every spoke needs a name and a repo`);
+      if (seenNames.has(spoke.name))
+        throw new Error(`${FleetConfig.fileName}: duplicate spoke "${spoke.name}"`);
+      seenNames.add(spoke.name);
+      if (!spoke.apps?.length)
+        throw new Error(`${FleetConfig.fileName}: spoke "${spoke.name}" declares no apps`);
+      for (const app of spoke.apps) {
+        const owner = appOwners.get(app);
+        if (owner)
+          throw new Error(`${FleetConfig.fileName}: app "${app}" is claimed by both "${owner}" and "${spoke.name}"`);
+        appOwners.set(app, spoke.name);
+      }
+    }
+  }
+  select(names) {
+    if (!names.length)
+      return this.spokes;
+    return names.map((name) => {
+      const spoke = this.spokes.find((candidate) => candidate.name === name);
+      if (!spoke)
+        throw new Error(`${FleetConfig.fileName}: unknown spoke "${name}"`);
+      return spoke;
+    });
+  }
+  assertPushable(branch) {
+    if (this.pushableBranches.includes(branch))
+      return;
+    throw new Error(`Branch "${branch}" is not pushable. ${FleetConfig.fileName} allows: ${this.pushableBranches.join(", ")}`);
+  }
+}
+
+// pkgs/@akanjs/cli/fleet/fleet.runner.ts
+class FleetRunner extends runner("fleet") {
+  async spokes(workspace, names) {
+    const config = await FleetConfig.from(workspace);
+    if (!config)
+      throw new Error(`No ${FleetConfig.fileName} at the workspace root. Declare the customer repos there first.`);
+    const spokes = config.select(names).map((declaration) => new FleetSpoke(workspace, config, declaration));
+    const branch = (await workspace.spawn("git", ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+    return { config, spokes, branch };
+  }
+  async status(workspace, names) {
+    const { spokes, branch } = await this.spokes(workspace, names);
+    const statuses = [];
+    for (const spoke of spokes)
+      statuses.push(await spoke.status(branch));
+    return statuses;
+  }
+  async push(workspace, names, { verify } = {}) {
+    const { config, spokes, branch } = await this.spokes(workspace, names);
+    config.assertPushable(branch);
+    const results = [];
+    for (const spoke of spokes)
+      results.push(await spoke.push(branch, { verify }));
+    return results;
+  }
+  async diff(workspace, name, filter) {
+    const { spokes, branch } = await this.spokes(workspace, [name]);
+    const [spoke] = spokes;
+    if (!spoke)
+      throw new Error(`Unknown spoke "${name}"`);
+    return await spoke.diff(branch, filter);
+  }
+  async check(workspace, { staged } = {}) {
+    return await new FleetGuard(workspace).check({ staged });
+  }
+  async pull(workspace, name, { adoptLibs } = {}) {
+    const { spokes, branch } = await this.spokes(workspace, [name]);
+    const [spoke] = spokes;
+    if (!spoke)
+      throw new Error(`Unknown spoke "${name}"`);
+    return await spoke.pull(branch, { adoptLibs });
+  }
+}
+
+// pkgs/@akanjs/cli/fleet/fleet.script.ts
+class FleetScript extends script("fleet", [FleetRunner]) {
+  async status(workspace, names, format = "text") {
+    const spinner = workspace.spinning("Checking spokes...");
+    const statuses = await this.fleetRunner.status(workspace, names);
+    const drifted = statuses.filter((status) => status.driftedLibs.length).length;
+    spinner.succeed(`Checked ${statuses.length} spoke(s) (${drifted} with library drift)`);
+    Logger.rawLog(format === "json" ? JSON.stringify(statuses, null, 2) : formatFleetStatuses(statuses));
+  }
+  async push(workspace, names, { verify, format }) {
+    const spinner = workspace.spinning("Pushing to spokes...");
+    const results = await this.fleetRunner.push(workspace, names, { verify });
+    const pushed = results.filter((result) => result.outcome === "pushed").length;
+    spinner.succeed(`Pushed ${pushed} of ${results.length} spoke(s)`);
+    Logger.rawLog(format === "json" ? JSON.stringify(results, null, 2) : formatFleetPushResults(results));
+    if (results.some((result) => result.outcome === "refused"))
+      process.exitCode = 1;
+  }
+  async diff(workspace, name, filter, format = "text") {
+    const spinner = workspace.spinning(`Diffing ${name}...`);
+    const result = await this.fleetRunner.diff(workspace, name, filter);
+    const total = result.app.files.length + result.libs.files.length;
+    spinner.succeed(`${total} file(s) differ (${result.libs.files.length} in shared libraries)`);
+    Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatFleetDiff(result));
+  }
+  async check(workspace, { staged, warn, format }) {
+    const report = await this.fleetRunner.check(workspace, { staged });
+    Logger.rawLog(format === "json" ? JSON.stringify(report, null, 2) : formatFleetGuardReport(report, { warn }));
+    const failed = !!report.violations.length || !!report.driftedLibs.length;
+    if (failed && !warn)
+      process.exitCode = 1;
+  }
+  async pull(workspace, name, { adoptLibs, format }) {
+    const spinner = workspace.spinning(`Pulling customer commits from ${name}...`);
+    const result = await this.fleetRunner.pull(workspace, name, { adoptLibs });
+    spinner.succeed(`${result.incoming.length} customer commit(s), ${result.applied.length} file(s) applied`);
+    Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatFleetPullResult(result));
+  }
+}
+
+// pkgs/@akanjs/cli/fleet/fleet.command.ts
+class FleetCommand extends command("fleet", [FleetScript], ({ public: target }) => ({
+  fleet: target({ desc: "Mirror apps and libraries between this hub workspace and the customer repos it serves" }).arg("action", String, {
+    desc: "fleet action",
+    default: "status",
+    enum: ["status", "diff", "push", "pull", "check"]
+  }).arg("spoke", String, { desc: "spoke name; every spoke when omitted (required for pull)", nullable: true }).with(Workspace).option("format", String, { desc: "output format", default: "text", enum: ["text", "json"] }).option("verify", Boolean, {
+    flag: "y",
+    desc: "run bun install + akan sync in the spoke before committing",
+    default: true
+  }).option("adoptLibs", Boolean, { desc: "pull: also apply the spoke's library edits", default: false }).option("path", String, { desc: "diff: limit to one path", nullable: true }).option("staged", Boolean, { desc: "check: only look at what is staged", default: false }).option("warn", Boolean, { desc: "check: report without failing", default: false }).exec(async function(action, spoke, workspace, format, verify, adoptLibs, filePath, staged, warn) {
+    const names = spoke ? [spoke] : [];
+    const output = format;
+    if (action === "status")
+      await this.fleetScript.status(workspace, names, output);
+    else if (action === "check")
+      await this.fleetScript.check(workspace, { staged, warn, format: output });
+    else if (action === "push")
+      await this.fleetScript.push(workspace, names, { verify, format: output });
+    else if (action === "diff" || action === "pull") {
+      if (!spoke)
+        throw new Error(`\`akan fleet ${action}\` needs a spoke name \u2014 it is reviewed one repo at a time.`);
+      if (action === "diff")
+        await this.fleetScript.diff(workspace, spoke, filePath, output);
+      else
+        await this.fleetScript.pull(workspace, spoke, { adoptLibs, format: output });
+    } else
+      throw new Error(`Unknown fleet action: ${action}. Use status, diff, push, pull or check.`);
+  })
+})) {
+}
+export {
+  FleetCommand
+};