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

package/subspaceConfig.ts

@@ -0,0 +1,76 @@
+import path from "node:path";
+import type { SubspaceConfigInput, SubspaceDeclaration } from "akanjs";
+import type { WorkspaceExecutor } from "./executors";
+import { FileSys } from "./fileSys";
+
+export type { SubspaceConfigInput, SubspaceDeclaration };
+
+/**
+ * `akan.subspace.ts` at the workspace root: which customer repo each app is mirrored to.
+ *
+ * There is no branch field. The branch is whichever one the workspace is on, so the same declaration
+ * serves `develop` and `main`, and every subspace on one branch holds the same akanjs version and the
+ * same library source.
+ */
+export class SubspaceConfig {
+  static readonly fileName = "akan.subspace.ts";
+  static readonly defaultPushableBranches = ["main", "develop", "debug"];
+
+  static async from(workspace: WorkspaceExecutor): Promise<SubspaceConfig | null> {
+    const configPath = path.join(workspace.workspaceRoot, SubspaceConfig.fileName);
+    if (!(await FileSys.fileExists(configPath))) return null;
+    const input = await import(configPath).then((mod: { default: SubspaceConfigInput }) => mod.default);
+    return new SubspaceConfig(input);
+  }
+
+  readonly pushableBranches: string[];
+  readonly exclude: string[];
+  readonly subspaces: SubspaceDeclaration[];
+
+  constructor(input: SubspaceConfigInput) {
+    this.pushableBranches = input.pushableBranches ?? SubspaceConfig.defaultPushableBranches;
+    this.exclude = input.exclude ?? [];
+    this.subspaces = input.subspaces ?? [];
+    this.#assertValid();
+  }
+
+  #assertValid() {
+    const seenNames = new Set<string>();
+    const appOwners = new Map<string, string>();
+    for (const subspace of this.subspaces) {
+      if (!subspace.name || !subspace.repo)
+        throw new Error(`${SubspaceConfig.fileName}: every subspace needs a name and a repo`);
+      if (seenNames.has(subspace.name))
+        throw new Error(`${SubspaceConfig.fileName}: duplicate subspace "${subspace.name}"`);
+      seenNames.add(subspace.name);
+      if (!subspace.apps?.length)
+        throw new Error(`${SubspaceConfig.fileName}: subspace "${subspace.name}" declares no apps`);
+      for (const app of subspace.apps) {
+        const owner = appOwners.get(app);
+        //* One app never goes to two subspaces: the two would need per-subspace domains and ids, which
+        //* this declaration cannot express. Share code through a lib instead.
+        if (owner)
+          throw new Error(
+            `${SubspaceConfig.fileName}: app "${app}" is claimed by both "${owner}" and "${subspace.name}"`,
+          );
+        appOwners.set(app, subspace.name);
+      }
+    }
+  }
+
+  select(names: string[]) {
+    if (!names.length) return this.subspaces;
+    return names.map((name) => {
+      const subspace = this.subspaces.find((candidate) => candidate.name === name);
+      if (!subspace) throw new Error(`${SubspaceConfig.fileName}: unknown subspace "${name}"`);
+      return subspace;
+    });
+  }
+
+  assertPushable(branch: string) {
+    if (this.pushableBranches.includes(branch)) return;
+    throw new Error(
+      `Branch "${branch}" is not pushable. ${SubspaceConfig.fileName} allows: ${this.pushableBranches.join(", ")}`,
+    );
+  }
+}

package/fleetConfig.ts

@@ -1,73 +0,0 @@
-import path from "node:path";
-import type { FleetConfigInput, FleetGuardConfig, FleetSpokeDeclaration } from "akanjs";
-import type { WorkspaceExecutor } from "./executors";
-import { FileSys } from "./fileSys";
-
-export type { FleetConfigInput, FleetGuardConfig, 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

@@ -1,121 +0,0 @@
-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

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