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

package/executors.ts

@@ -941,6 +941,26 @@ export class WorkspaceExecutor extends Executor {
     // Argument vector, not a shell string: a message carrying a double quote breaks the interpolated form.
     await this.spawn("git", ["commit", "--quiet", "-m", message]);
   }
+  /** `git commit` exits non-zero on an empty index, so a re-runnable caller has to ask first. */
+  async hasChanges() {
+    return !!(await this.spawn("git", ["status", "--porcelain"])).trim();
+  }
+  /**
+   * Workspace-relative paths git knows about, sorted. `untracked` adds files that exist but are not
+   * committed yet, still honoring `.gitignore` — which is what a freshly copied library looks like.
+   *
+   * Reading the file set from git is what keeps generated barrels, the `page/**` and `public/libs`
+   * symlinks, env values and the lockfile out of it without any caller restating that list.
+   */
+  async listGitFiles(paths: string[], { untracked = false }: { untracked?: boolean } = {}) {
+    if (!paths.length) return [];
+    const mode = untracked ? ["--cached", "--others", "--exclude-standard"] : ["--cached"];
+    const stdout = await this.spawn("git", ["ls-files", "-z", ...mode, "--", ...paths]);
+    return stdout
+      .split("\0")
+      .filter((file) => !!file)
+      .sort();
+  }
   async #getDirHasFile(basePath: string, targetFilename: string) {
     const AVOID_DIRS = ["node_modules", "dist", "public", "webkit"];
     const getDirs = async (dirname: string, maxDepth = 3, results: string[] = [], prefix = "") => {

package/fleetConfig.ts

@@ -0,0 +1,101 @@
+import path from "node:path";
+import type { WorkspaceExecutor } from "./executors";
+import { FileSys } from "./fileSys";
+
+export interface FleetSpokeDeclaration {
+  /** Short name used on the command line and as the git remote suffix. */
+  name: string;
+  repo: string;
+  /** Apps this spoke serves. Libraries are never listed — they are derived from each app's closure. */
+  apps: string[];
+}
+
+export interface FleetGuardConfig {
+  /** CI system the guard job is written for. `"none"` leaves it out — wire `akan fleet check` yourself. */
+  ci: "github" | "none";
+  /** Add the `akan fleet check` line to the spoke's pre-commit hook. */
+  preCommit: boolean;
+}
+
+export interface FleetConfigInput {
+  /**
+   * Branches a push may target. A hub feature branch is refused, because pushing it would copy the hub's
+   * branch namespace into every customer repo.
+   */
+  pushableBranches?: string[];
+  /**
+   * Workspace-root entries to keep out of every spoke, on top of the ones that always are. Top-level
+   * names or `dir/` prefixes — a hub's own release and benchmark trees are the usual entries.
+   */
+  exclude?: string[];
+  /** What a push installs in each spoke to keep hub-owned files from being edited there. */
+  guard?: Partial<FleetGuardConfig>;
+  spokes: FleetSpokeDeclaration[];
+}
+
+/**
+ * `akan.fleet.ts` at the workspace root: which customer repo each app is mirrored to.
+ *
+ * There is no branch field. The branch is whichever one the hub is on, so the same declaration serves
+ * `develop` and `main` and every spoke on one branch holds the same akanjs version and library source.
+ */
+export class FleetConfig {
+  static readonly fileName = "akan.fleet.ts";
+  static readonly defaultPushableBranches = ["main", "develop", "debug"];
+  static readonly defaultGuard: FleetGuardConfig = { ci: "github", preCommit: true };
+
+  static async from(workspace: WorkspaceExecutor): Promise<FleetConfig | null> {
+    const configPath = path.join(workspace.workspaceRoot, FleetConfig.fileName);
+    if (!(await FileSys.fileExists(configPath))) return null;
+    const input = await import(configPath).then((mod: { default: FleetConfigInput }) => mod.default);
+    return new FleetConfig(input);
+  }
+
+  readonly pushableBranches: string[];
+  readonly exclude: string[];
+  readonly guard: FleetGuardConfig;
+  readonly spokes: FleetSpokeDeclaration[];
+
+  constructor(input: FleetConfigInput) {
+    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<string>();
+    const appOwners = new Map<string, string>();
+    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);
+        //* One app never goes to two spokes: the two would need per-spoke domains and ids, which this
+        //* declaration cannot express. Share code through a lib instead.
+        if (owner)
+          throw new Error(`${FleetConfig.fileName}: app "${app}" is claimed by both "${owner}" and "${spoke.name}"`);
+        appOwners.set(app, spoke.name);
+      }
+    }
+  }
+
+  select(names: string[]) {
+    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: string) {
+    if (this.pushableBranches.includes(branch)) return;
+    throw new Error(
+      `Branch "${branch}" is not pushable. ${FleetConfig.fileName} allows: ${this.pushableBranches.join(", ")}`,
+    );
+  }
+}

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");
+}