@akanjs/devkit 3.0.0-alpha.76 → 3.0.0-alpha.78

package/fleetSpoke.test.ts

@@ -0,0 +1,365 @@
+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, 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);
+  });
+});
+
+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();
+  });
+});