@akanjs/devkit 3.0.0-beta.18 → 3.0.0-beta.19

package/platformTest/LinuxDockerTarget.ts

@@ -0,0 +1,120 @@
+import os from "node:os";
+import path from "node:path";
+import type { LinuxTestTargetConfig, PlatformGatePolicy } from "../cloud/constants";
+import { IdleWatchedProcess } from "./IdleWatchedProcess";
+import { type PlatformRunContext, PlatformTestTarget } from "./PlatformTestTarget";
+
+export class LinuxDockerTarget extends PlatformTestTarget {
+  static readonly cacheVolume = "akan-test-bun-cache";
+
+  readonly platform = "linux";
+  readonly policy: PlatformGatePolicy;
+  readonly #config: LinuxTestTargetConfig;
+  #container: string | null = null;
+
+  constructor(config: LinuxTestTargetConfig = {}) {
+    super();
+    this.#config = config;
+    this.policy = config.policy ?? "gate";
+  }
+
+  //* No compiler in the image, on purpose: with a toolchain present at install time ssh2 builds its native
+  //* addon, and Bun then panics loading it (`uv_version_string`, oven-sh/bun#18546).
+  static readonly dockerfile = [
+    `FROM oven/bun:${Bun.version}-slim`,
+    "RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates procps lsof && rm -rf /var/lib/apt/lists/*",
+  ].join("\n");
+
+  get image() {
+    return `akan-test-linux:bun-${Bun.version}-${Bun.hash(LinuxDockerTarget.dockerfile).toString(16).slice(0, 8)}`;
+  }
+
+  protected async prepare(context: PlatformRunContext) {
+    if ((await LinuxDockerTarget.#docker(["info"])).exitCode !== 0)
+      throw new Error("Docker is not running — start Docker Desktop, or leave linux out of --platforms");
+    await this.#ensureImage();
+    const container = `akan-test-${context.runId}`;
+    const cpus = this.#config.cpus ?? Math.max(2, Math.floor(os.availableParallelism() / 2));
+    const started = await LinuxDockerTarget.#docker([
+      "run",
+      "-d",
+      "--rm",
+      "--name",
+      container,
+      "--cpus",
+      String(cpus),
+      ...(this.#config.memory ? ["--memory", this.#config.memory] : []),
+      "-v",
+      `${LinuxDockerTarget.cacheVolume}:/root/.bun/install/cache`,
+      "-v",
+      `${path.dirname(context.snapshot.tarPath)}:/io:ro`,
+      "-v",
+      `${context.envPath}:/io-env:ro`,
+      "-w",
+      "/w",
+      this.image,
+      "sleep",
+      "infinity",
+    ]);
+    if (started.exitCode !== 0) throw new Error(`docker run failed: ${started.stderr.trim()}`);
+    this.#container = container;
+    const extract = await this.exec(
+      `tar -xf /io/${path.basename(context.snapshot.tarPath)} -C /w && cp /io-env /w/.env && git -C /w init -q`,
+      path.join(context.logDir, this.platform, "extract.log"),
+      PlatformTestTarget.installIdleMs,
+    );
+    if (extract.exitCode !== 0) throw new Error("extracting the snapshot into the container failed");
+  }
+
+  protected async exec(command: string, logPath: string, idleMs: number) {
+    const container = this.#container;
+    if (!container) throw new Error("the linux container is not running");
+    return await new IdleWatchedProcess(
+      ["docker", "exec", ...LinuxDockerTarget.#gitIdentityEnv(), container, "sh", "-c", command],
+      {
+        logPath,
+        idleMs,
+        onIdle: async () => {
+          await LinuxDockerTarget.#docker(["exec", container, "pkill", "-9", "bun"]);
+        },
+      },
+    ).run();
+  }
+
+  protected async cleanup() {
+    if (this.#container) await LinuxDockerTarget.#docker(["rm", "-f", this.#container]);
+    this.#container = null;
+  }
+
+  async #ensureImage() {
+    if ((await LinuxDockerTarget.#docker(["image", "inspect", this.image])).exitCode === 0) return;
+    const built = await LinuxDockerTarget.#docker(["build", "-t", this.image, "-"], LinuxDockerTarget.dockerfile);
+    if (built.exitCode !== 0) throw new Error(`building ${this.image} failed: ${built.stderr.trim().slice(-400)}`);
+  }
+
+  static #gitIdentityEnv() {
+    return Object.entries({
+      GIT_AUTHOR_NAME: "akan-test",
+      GIT_AUTHOR_EMAIL: "akan-test@localhost",
+      GIT_COMMITTER_NAME: "akan-test",
+      GIT_COMMITTER_EMAIL: "akan-test@localhost",
+      GIT_CONFIG_COUNT: "1",
+      GIT_CONFIG_KEY_0: "init.defaultBranch",
+      GIT_CONFIG_VALUE_0: "main",
+    }).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
+  }
+
+  static async #docker(args: string[], stdin?: string) {
+    const proc = Bun.spawn(["docker", ...args], {
+      stdin: stdin === undefined ? "ignore" : new Response(stdin),
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { stdout, stderr, exitCode };
+  }
+}

package/platformTest/PlatformTestRun.test.ts

@@ -0,0 +1,68 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { BunTestReport } from "./BunTestReport";
+import { PlatformTestRun } from "./PlatformTestRun";
+import type { PackageTestResult, PlatformTestResult } from "./PlatformTestTarget";
+
+const roots: string[] = [];
+afterAll(async () => {
+  await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const pkg = (status: PackageTestResult["status"]): PackageTestResult => ({
+  pkg: "akanjs",
+  status,
+  report: new BunTestReport(""),
+  ms: 1,
+  logPath: "x.log",
+});
+const result = (
+  platform: PlatformTestResult["platform"],
+  policy: PlatformTestResult["policy"],
+  packages: PackageTestResult[],
+  infraError: string | null = null,
+): PlatformTestResult => ({ platform, policy, packages, envWarnings: [], infraError, ms: 1 });
+
+describe("PlatformTestRun", () => {
+  test("a failing gate blocks, a failing warn only warns, and a setup failure counts as a failure", () => {
+    const verdict = PlatformTestRun.verdict([
+      result("linux", "gate", [pkg("pass"), pkg("fail")]),
+      result("windows", "warn", [pkg("pass")], "cannot reach user@host over ssh"),
+    ]);
+
+    expect(verdict.blocking.map((one) => one.platform)).toEqual(["linux"]);
+    expect(verdict.warning.map((one) => one.platform)).toEqual(["windows"]);
+  });
+
+  test("a hung package fails its platform", () => {
+    expect(PlatformTestRun.failed(result("windows", "gate", [pkg("pass"), pkg("hung")]))).toBe(true);
+    expect(PlatformTestRun.failed(result("windows", "gate", [pkg("pass")]))).toBe(false);
+  });
+
+  test("hands a test host only the env keys the CLI needs, never the secrets beside them", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "akan-platform-env-"));
+    roots.push(root);
+    await writeFile(
+      path.join(root, ".env"),
+      ["USE_AKANJS_PKGS=true", "OPENAI_API_KEY=sk-secret", 'AKAN_PUBLIC_SERVE_DOMAIN="akanjs.com"', "JEV_KEY=x"].join(
+        "\n",
+      ),
+    );
+
+    expect(await PlatformTestRun.allowlistedEnv(root)).toBe(
+      'USE_AKANJS_PKGS=true\nAKAN_PUBLIC_SERVE_DOMAIN="akanjs.com"\n',
+    );
+  });
+
+  test("reads a comma-separated platform list, where none means no remote platform", () => {
+    expect(PlatformTestRun.parsePlatforms("linux, Windows,linux")).toEqual(["linux", "windows"]);
+    expect(PlatformTestRun.parsePlatforms("none")).toEqual([]);
+    expect(() => PlatformTestRun.parsePlatforms("linux,mac")).toThrow("mac");
+  });
+
+  test("run ids sort by time", () => {
+    expect(PlatformTestRun.newRunId(new Date(2026, 8, 26, 9, 5, 7))).toBe("20260926-090507");
+  });
+});

package/platformTest/PlatformTestRun.ts

@@ -0,0 +1,141 @@
+import path from "node:path";
+import chalk from "chalk";
+import type { TestTargetsConfig } from "../cloud/constants";
+import { GlobalConfig } from "../cloud/globalConfig";
+import { LinuxDockerTarget } from "./LinuxDockerTarget";
+import { type PlatformTestResult, PlatformTestTarget, type RemoteTestPlatform } from "./PlatformTestTarget";
+import { TestSnapshot } from "./TestSnapshot";
+import { WindowsSshTarget } from "./WindowsSshTarget";
+
+interface PlatformTestRunOptions {
+  workspaceRoot: string;
+  platforms: RemoteTestPlatform[];
+  pkgs: string[];
+  targets: TestTargetsConfig;
+  onProgress: (message: string) => void;
+}
+
+export interface PlatformVerdict {
+  blocking: PlatformTestResult[];
+  warning: PlatformTestResult[];
+}
+
+export class PlatformTestRun {
+  //? The CLI refuses a root without these, and the cli suite builds temp workspaces from them; none is a secret.
+  static readonly envKeys = [
+    "USE_AKANJS_PKGS",
+    "AKAN_PUBLIC_REPO_NAME",
+    "AKAN_PUBLIC_SERVE_DOMAIN",
+    "AKAN_PUBLIC_ENV",
+    "AKAN_PUBLIC_OPERATION_MODE",
+    "APP_OPERATION_MODE",
+    "SERVER_MODE",
+  ] as const;
+  static readonly promoteAfterGreenRuns = 3;
+
+  readonly runId: string;
+  readonly logDir: string;
+  readonly snapshot: TestSnapshot;
+  readonly #results: Promise<PlatformTestResult[]>;
+
+  constructor(runId: string, logDir: string, snapshot: TestSnapshot, results: Promise<PlatformTestResult[]>) {
+    this.runId = runId;
+    this.logDir = logDir;
+    this.snapshot = snapshot;
+    this.#results = results;
+  }
+
+  static async start({ workspaceRoot, platforms, pkgs, targets, onProgress }: PlatformTestRunOptions) {
+    const runId = PlatformTestRun.newRunId();
+    const logDir = path.join(workspaceRoot, "local", "deploy-test", runId);
+    const snapshot = await TestSnapshot.create(workspaceRoot, logDir);
+    const envPath = path.join(logDir, "env");
+    await Bun.write(envPath, await PlatformTestRun.allowlistedEnv(workspaceRoot));
+    const instances = platforms.map((platform) => {
+      if (platform === "linux") return new LinuxDockerTarget(targets.linux);
+      if (!targets.windows) throw new Error("the windows test target is not configured");
+      return new WindowsSshTarget(targets.windows);
+    });
+    const results = Promise.all(
+      instances.map((target) => target.run({ snapshot, envPath, runId, logDir, pkgs, onProgress })),
+    );
+    return new PlatformTestRun(runId, logDir, snapshot, results);
+  }
+
+  async results() {
+    return await this.#results;
+  }
+
+  static parsePlatforms(value: string): RemoteTestPlatform[] {
+    const names = value
+      .split(",")
+      .map((name) => name.trim().toLowerCase())
+      .filter((name) => name && name !== "none");
+    const unknown = names.filter((name) => name !== "linux" && name !== "windows");
+    if (unknown.length)
+      throw new Error(`Unknown test platform: ${unknown.join(", ")} (expected linux, windows, or none)`);
+    return [...new Set(names as RemoteTestPlatform[])];
+  }
+
+  static newRunId(now = new Date()) {
+    const pad = (value: number) => String(value).padStart(2, "0");
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  }
+
+  static async allowlistedEnv(workspaceRoot: string) {
+    const envFile = Bun.file(path.join(workspaceRoot, ".env"));
+    const lines = (await envFile.exists()) ? (await envFile.text()).split(/\r?\n/) : [];
+    const allowed = new Set<string>(PlatformTestRun.envKeys);
+    const kept = lines.filter((line) => allowed.has(line.split("=", 1)[0]?.trim() ?? ""));
+    return `${kept.join("\n")}\n`;
+  }
+
+  static failed(result: PlatformTestResult) {
+    return !!result.infraError || result.packages.some((pkg) => pkg.status !== "pass");
+  }
+
+  static verdict(results: PlatformTestResult[]): PlatformVerdict {
+    const failed = results.filter((result) => PlatformTestRun.failed(result));
+    return {
+      blocking: failed.filter((result) => result.policy === "gate"),
+      warning: failed.filter((result) => result.policy === "warn"),
+    };
+  }
+
+  format(results: PlatformTestResult[], { maxFailures = 15 }: { maxFailures?: number } = {}) {
+    const lines = [
+      chalk.bold(
+        `Platform tests · snapshot ${this.snapshot.digest} (${this.snapshot.fileCount} files) · ${path.relative(this.snapshot.root, this.logDir)}`,
+      ),
+    ];
+    for (const result of results) {
+      const mark = PlatformTestRun.failed(result) ? chalk.red("✖") : chalk.green("✔");
+      lines.push(`${mark} ${result.platform} (${result.policy}, ${Math.round(result.ms / 1000)}s)`);
+      if (result.infraError) lines.push(chalk.red(`    setup: ${result.infraError}`));
+      for (const warning of result.envWarnings) lines.push(chalk.yellow(`    env: ${warning}`));
+      for (const pkg of result.packages) {
+        const line = `    ${PlatformTestTarget.describe(pkg)}`;
+        lines.push(pkg.status === "pass" ? line : chalk.red(line));
+        for (const failure of pkg.report.failures.slice(0, maxFailures))
+          lines.push(chalk.dim(`      ${failure.file ? `${failure.file} › ` : ""}${failure.name}`));
+        if (pkg.report.failures.length > maxFailures)
+          lines.push(chalk.dim(`      … ${pkg.report.failures.length - maxFailures} more in ${pkg.logPath}`));
+      }
+    }
+    return lines.join("\n");
+  }
+
+  /** A `warn` platform becomes a gate once it has been green for enough deploys in a row. */
+  static async recordStreaks(results: PlatformTestResult[]) {
+    const targets = await GlobalConfig.getTestTargets();
+    const windows = targets.windows;
+    const result = results.find((one) => one.platform === "windows");
+    if (!windows || !result || (windows.policy ?? "warn") !== "warn") return null;
+    const greenStreak = PlatformTestRun.failed(result) ? 0 : (windows.greenStreak ?? 0) + 1;
+    const promoted = greenStreak >= PlatformTestRun.promoteAfterGreenRuns;
+    await GlobalConfig.setTestTargets({
+      windows: { ...windows, greenStreak, ...(promoted ? { policy: "gate" } : {}) },
+    });
+    return { platform: "windows" as const, greenStreak, promoted };
+  }
+}

package/platformTest/PlatformTestTarget.ts

@@ -0,0 +1,120 @@
+import path from "node:path";
+import type { PlatformGatePolicy } from "../cloud/constants";
+import { BunTestReport } from "./BunTestReport";
+import type { IdleWatchedResult } from "./IdleWatchedProcess";
+import type { TestSnapshot } from "./TestSnapshot";
+
+export type RemoteTestPlatform = "linux" | "windows";
+export type PackageTestStatus = "pass" | "fail" | "hung";
+
+export interface PackageTestResult {
+  pkg: string;
+  status: PackageTestStatus;
+  report: BunTestReport;
+  ms: number;
+  logPath: string;
+}
+
+export interface PlatformTestResult {
+  platform: RemoteTestPlatform;
+  policy: PlatformGatePolicy;
+  packages: PackageTestResult[];
+  envWarnings: string[];
+  infraError: string | null;
+  ms: number;
+}
+
+export interface PlatformRunContext {
+  snapshot: TestSnapshot;
+  envPath: string;
+  runId: string;
+  logDir: string;
+  pkgs: string[];
+  onProgress: (message: string) => void;
+}
+
+export abstract class PlatformTestTarget {
+  static readonly installIdleMs = 5 * 60_000;
+  static readonly testIdleMs = 2 * 60_000;
+
+  abstract readonly platform: RemoteTestPlatform;
+  abstract readonly policy: PlatformGatePolicy;
+  protected readonly tolerateScriptFailures: string[] = [];
+
+  protected abstract prepare(context: PlatformRunContext): Promise<void>;
+  protected abstract exec(command: string, logPath: string, idleMs: number): Promise<IdleWatchedResult>;
+  protected abstract cleanup(context: PlatformRunContext): Promise<void>;
+
+  async run(context: PlatformRunContext): Promise<PlatformTestResult> {
+    const startedAt = performance.now();
+    const envWarnings: string[] = [];
+    const packages: PackageTestResult[] = [];
+    const result = (infraError: string | null): PlatformTestResult => ({
+      platform: this.platform,
+      policy: this.policy,
+      packages,
+      envWarnings,
+      infraError,
+      ms: performance.now() - startedAt,
+    });
+    try {
+      await this.prepare(context);
+      await this.#install(context, envWarnings);
+      const build = await this.exec(
+        "bun run buildAkan",
+        this.#logPath(context, "build"),
+        PlatformTestTarget.installIdleMs,
+      );
+      if (build.exitCode !== 0) throw new Error(`buildAkan failed — see ${this.#logPath(context, "build")}`);
+      for (const pkg of context.pkgs) {
+        const logPath = this.#logPath(context, `test-${pkg.replaceAll("/", "__")}`);
+        const run = await this.exec(
+          `bun dist/pkgs/@akanjs/cli/index.js test ${pkg}`,
+          logPath,
+          PlatformTestTarget.testIdleMs,
+        );
+        const report = new BunTestReport(run.output);
+        const status: PackageTestStatus =
+          run.hung || run.timedOut ? "hung" : report.passed && run.exitCode === 0 ? "pass" : "fail";
+        packages.push({ pkg, status, report, ms: run.ms, logPath });
+        context.onProgress(`[${this.platform}] ${PlatformTestTarget.describe(packages.at(-1) as PackageTestResult)}`);
+      }
+      return result(null);
+    } catch (error) {
+      return result(error instanceof Error ? error.message : String(error));
+    } finally {
+      await this.cleanup(context).catch(() => undefined);
+    }
+  }
+
+  static describe({ pkg, status, report, ms }: PackageTestResult) {
+    const seconds = `${Math.round(ms / 1000)}s`;
+    if (status === "hung") return `${pkg}: hung${report.lastFile ? ` in ${report.lastFile}` : ""} (${seconds})`;
+    return `${pkg}: ${report.pass} pass / ${report.fail} fail${report.errors ? ` / ${report.errors} errors` : ""} (${seconds})`;
+  }
+
+  async #install(context: PlatformRunContext, envWarnings: string[]) {
+    const logPath = this.#logPath(context, "install");
+    const install = await this.exec("bun install --frozen-lockfile", logPath, PlatformTestTarget.installIdleMs);
+    if (install.exitCode === 0) return;
+    const failedScripts = [...install.output.matchAll(/(?:pre|post)?install script from "([^"]+)" exited/g)].map(
+      (match) => match[1] ?? "",
+    );
+    const tolerable =
+      failedScripts.length > 0 && failedScripts.every((pkg) => this.tolerateScriptFailures.includes(pkg));
+    if (!tolerable) throw new Error(`bun install failed — see ${logPath}`);
+    //* A failed lifecycle script makes bun skip linking the workspace root's `.bin`, so every tool the suites
+    //* spawn from there disappears; a second pass without scripts links them.
+    envWarnings.push(`install script failed for ${failedScripts.join(", ")} — tolerated on ${this.platform}`);
+    const relink = await this.exec(
+      "bun install --frozen-lockfile --ignore-scripts",
+      this.#logPath(context, "install-relink"),
+      PlatformTestTarget.installIdleMs,
+    );
+    if (relink.exitCode !== 0) throw new Error(`bun install --ignore-scripts failed — see ${logPath}`);
+  }
+
+  #logPath(context: PlatformRunContext, name: string) {
+    return path.join(context.logDir, this.platform, `${name}.log`);
+  }
+}

package/platformTest/TestSnapshot.test.ts

@@ -0,0 +1,80 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { TestSnapshot } from "./TestSnapshot";
+
+const roots: string[] = [];
+const git = async (cwd: string, ...args: string[]) => {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd,
+    stdout: "ignore",
+    stderr: "ignore",
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: "t",
+      GIT_AUTHOR_EMAIL: "t@t",
+      GIT_COMMITTER_NAME: "t",
+      GIT_COMMITTER_EMAIL: "t@t",
+    },
+  });
+  expect(await proc.exited).toBe(0);
+};
+const write = async (root: string, file: string, content: string) => {
+  await mkdir(path.dirname(path.join(root, file)), { recursive: true });
+  await writeFile(path.join(root, file), content);
+};
+const makeRepo = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-snapshot-"));
+  roots.push(root);
+  await git(root, "init", "-q");
+  await write(root, ".gitignore", "ignored/\nlocal/\n.env\n");
+  await write(root, "tracked.ts", "export {};\n");
+  await write(root, "gone.ts", "export {};\n");
+  await git(root, "add", ".");
+  await git(root, "commit", "-q", "-m", "init");
+  await unlink(path.join(root, "gone.ts"));
+  await write(root, "untracked.ts", "export const a = 1;\n");
+  await write(root, "ignored/secret.ts", "export {};\n");
+  await write(root, ".env", "OPENAI_API_KEY=nope\n");
+  return root;
+};
+const tarEntries = async (tarPath: string) => {
+  const proc = Bun.spawn(["tar", "-tf", tarPath], { stdout: "pipe" });
+  return (await new Response(proc.stdout).text()).split(/\r?\n/).filter(Boolean).sort();
+};
+
+afterAll(async () => {
+  await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("TestSnapshot", () => {
+  test("packs what git would show — tracked and untracked, never ignored or deleted", async () => {
+    const root = await makeRepo();
+    const snapshot = await TestSnapshot.create(root, path.join(root, "local", "run"));
+
+    expect(await tarEntries(snapshot.tarPath)).toEqual([".gitignore", "tracked.ts", "untracked.ts"]);
+    expect(snapshot.fileCount).toBe(3);
+  });
+
+  test("reports what changed underneath it", async () => {
+    const root = await makeRepo();
+    const snapshot = await TestSnapshot.create(root, path.join(root, "local", "run"));
+    await write(root, "tracked.ts", "export const changed = true;\n");
+    await write(root, "added.ts", "export {};\n");
+    await unlink(path.join(root, "untracked.ts"));
+
+    expect(await snapshot.drift()).toEqual({ changed: ["tracked.ts"], added: ["added.ts"], removed: ["untracked.ts"] });
+  });
+
+  test("refuses an env file git does not ignore instead of shipping it to a test host", async () => {
+    const root = await makeRepo();
+    await write(root, "apps/demo/env/env.server.local.ts", "export default {};\n");
+    await write(root, "apps/demo/env/env.server.example.ts", "export default {};\n");
+    await write(root, "templates/.env.template", "KEY=\n");
+
+    await expect(TestSnapshot.create(root, path.join(root, "local", "run"))).rejects.toThrow(
+      "apps/demo/env/env.server.local.ts",
+    );
+  });
+});

package/platformTest/TestSnapshot.ts

@@ -0,0 +1,107 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface SnapshotDrift {
+  changed: string[];
+  added: string[];
+  removed: string[];
+}
+
+/**
+ * The exact bytes a platform run tests: every tracked file plus every untracked one git would show, which is
+ * what `akan deploy-akan` goes on to build and publish. The per-file hashes are kept so the tree can be
+ * compared again before publishing — a test run is only a gate if nothing changed underneath it.
+ */
+export class TestSnapshot {
+  static readonly #secretPatterns = [
+    /(^|\/)\.env(\.(?!(template|example|sample)$)[^/]+)?$/,
+    /(^|\/)env\/env\.(client|server)\.(?!(type|example)\.ts$)[^/]+\.ts$/,
+  ];
+
+  readonly root: string;
+  readonly tarPath: string;
+  readonly digest: string;
+  readonly #hashes: Map<string, string>;
+
+  constructor(root: string, tarPath: string, hashes: Map<string, string>) {
+    this.root = root;
+    this.tarPath = tarPath;
+    this.#hashes = hashes;
+    this.digest = TestSnapshot.#digestOf(hashes);
+  }
+
+  get fileCount() {
+    return this.#hashes.size;
+  }
+
+  static async create(root: string, outDir: string) {
+    const hashes = await TestSnapshot.#hashTree(root);
+    //? A tracked file is already in the repository; only an untracked one nobody ignored can leak by being copied.
+    const untracked = await TestSnapshot.#gitList(root, ["--others", "--exclude-standard"]);
+    const secrets = untracked.filter((file) => TestSnapshot.#secretPatterns.some((re) => re.test(file)));
+    if (secrets.length)
+      throw new Error(
+        `Refusing to snapshot env files git does not ignore — they would be copied to every test target: ${secrets.join(", ")}`,
+      );
+    await mkdir(outDir, { recursive: true });
+    const listPath = path.join(outDir, "files.txt");
+    const tarPath = path.join(outDir, "src.tar");
+    await writeFile(listPath, `${[...hashes.keys()].join("\n")}\n`);
+    const tar = Bun.spawn(
+      ["tar", ...(process.platform === "darwin" ? ["--no-xattrs"] : []), "-cf", tarPath, "-T", listPath],
+      { cwd: root, env: { ...process.env, COPYFILE_DISABLE: "1" }, stdout: "ignore", stderr: "pipe" },
+    );
+    if ((await tar.exited) !== 0) throw new Error(`tar failed: ${await new Response(tar.stderr).text()}`);
+    return new TestSnapshot(root, tarPath, hashes);
+  }
+
+  async drift(): Promise<SnapshotDrift> {
+    const current = await TestSnapshot.#hashTree(this.root);
+    const changed = [...current].filter(([file, hash]) => this.#hashes.has(file) && this.#hashes.get(file) !== hash);
+    return {
+      changed: changed.map(([file]) => file),
+      added: [...current.keys()].filter((file) => !this.#hashes.has(file)),
+      removed: [...this.#hashes.keys()].filter((file) => !current.has(file)),
+    };
+  }
+
+  static async #gitList(root: string, args: string[]) {
+    const proc = Bun.spawn(["git", "ls-files", ...args, "-z"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (exitCode !== 0) throw new Error(`git ls-files failed in ${root}: ${stderr.trim()}`);
+    return [...new Set(stdout.split("\0").filter(Boolean))].sort();
+  }
+
+  static async #listFiles(root: string) {
+    const listed = await TestSnapshot.#gitList(root, ["--cached", "--others", "--exclude-standard"]);
+    //? `--cached` still lists a tracked file deleted from the working tree, which tar would then fail on.
+    const present = await Promise.all(
+      listed.map(async (file) => ((await stat(path.join(root, file)).catch(() => null))?.isFile() ? file : null)),
+    );
+    return present.filter((file): file is string => file !== null);
+  }
+
+  static async #hashTree(root: string) {
+    const files = await TestSnapshot.#listFiles(root);
+    const hashes = new Map<string, string>();
+    for (let start = 0; start < files.length; start += 64) {
+      const batch = files.slice(start, start + 64);
+      const batchHashes = await Promise.all(
+        batch.map(async (file) => Bun.hash(await Bun.file(path.join(root, file)).bytes()).toString(16)),
+      );
+      for (const [idx, file] of batch.entries()) hashes.set(file, batchHashes[idx] ?? "");
+    }
+    return hashes;
+  }
+
+  static #digestOf(hashes: Map<string, string>) {
+    return Bun.hash([...hashes].map(([file, hash]) => `${file}:${hash}`).join("\n"))
+      .toString(16)
+      .padStart(16, "0")
+      .slice(0, 12);
+  }
+}