@tokenfactory/acc-runner 0.41.7 → 0.43.0

package/dist/migration-seq-guard.js

@@ -0,0 +1,304 @@
+/**
+ * MIG-SEQ-GUARD — re-validate a branch's migration sequence against a FRESHLY
+ * FETCHED integration head, immediately before push.
+ *
+ * The recurring failure it closes (0310 → 0314 → 0315, two collisions in 24h):
+ * an agent computes its next-free migration seq at worktree-FORK time — the max
+ * of `supabase/migrations/` in the fork snapshot plus the applied ledger. That
+ * number is correct when it is chosen and stale by the time the branch pushes,
+ * because a sibling migration merged into `acc/integration` in between and took
+ * it. `scripts/ci/migration-lint.mjs` catches the collision at PR time, but only
+ * after the whole run is spent: the task rework-loops for a rename it could have
+ * done itself. Two migration tasks dispatched concurrently hit it every time.
+ *
+ * MIGFIX-01 (prepr-gate.ts) already auto-renumbers, but it reads the SAME stale
+ * worktree snapshot, so it recomputes exactly the seq the sibling took. The fix
+ * is not a better computation — it is a fresher input. So right before push:
+ *
+ *   1. `git fetch <remote> <integration>` — a real network read, not the fork's
+ *      remote-tracking ref.
+ *   2. Read the migration seqs present on that fresh head (`git ls-tree`), and
+ *      union them with the live `acc.applied_migrations` roster when the caller
+ *      has one.
+ *   3. If this branch's NEW migration no longer holds a free seq (its number is
+ *      at or below that fresh baseline), hand the roster to
+ *      `migration-lint.mjs --renumber --baseline-seqs …`, which already rewrites
+ *      the filename, the `record_migration_applied` self-record, the verify
+ *      RAISE messages and every sibling test that reads the file by path.
+ *   4. Commit the rename so the push carries it, and report the move so the
+ *      caller can emit an event.
+ *
+ * FAIL-OPEN by construction. Every step that touches the network or git is
+ * best-effort: an unreachable remote, a missing ref, a renumber that changed
+ * nothing — each returns a `ran: false` result with a reason, and the push
+ * proceeds exactly as it does today. The guard may only ever turn a PR that CI
+ * would reject into one it accepts; it must never be the reason a push fails.
+ *
+ * Two deliberate non-behaviours:
+ *   • It does NOT act on a forward GAP (a seq ABOVE the fresh baseline + 1).
+ *     A gap is MIGFIX-01's job at fork time, and after a sibling merges, the
+ *     local `supabase/migrations/` is legitimately behind the remote — closing
+ *     "gaps" against a tree that is missing files would renumber healthy
+ *     branches. Only a seq that is provably TAKEN is moved.
+ *   • It commits, it never amends. A rework branch's history is already pushed;
+ *     amending it would force a non-fast-forward push. Same posture as
+ *     MIGFIX-01's `defaultCommitRenumbered`.
+ */
+import path from "node:path";
+import { execa } from "execa";
+import { buildEnv } from "./bin-resolve.js";
+/** Kill switch. Set to `0`/`false` to skip the pre-push re-validation entirely. */
+export const SEQ_GUARD_ENV = "ACC_MIGRATION_SEQ_GUARD";
+const MIGRATIONS_DIR = "supabase/migrations";
+/**
+ * The numeric sequence prefix of a migration path (`…/0315_acc_x.sql` → 315),
+ * or null when the filename does not carry one. Mirrors `parseSeq` in
+ * scripts/ci/migration-lint.mjs — the two must agree on what counts as a
+ * migration, so both accept `_` and `-` after the digits.
+ */
+export function migrationSeq(file) {
+    const base = String(file).split(/[\\/]/).pop() ?? "";
+    const m = /^(\d+)[_-].+\.sql$/i.exec(base);
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/** Whether the guard is enabled. ON by default; `0`/`false`/`no` turns it off. */
+export function seqGuardEnabled(env = process.env) {
+    const raw = env[SEQ_GUARD_ENV]?.trim().toLowerCase();
+    if (raw === undefined || raw === "")
+        return true;
+    return !(raw === "0" || raw === "false" || raw === "no" || raw === "off");
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Default I/O (every one is injectable; the unit suite never shells out)
+// ─────────────────────────────────────────────────────────────────────────────
+async function defaultFetchRef(workdir, remote, branch) {
+    // A single-branch fetch, not `--all`: this runs on the push hot path and the
+    // only ref whose freshness matters is the integration head.
+    const res = await execa("git", ["fetch", "--quiet", remote, branch], {
+        cwd: workdir,
+        env: buildEnv(),
+        reject: false,
+    });
+    if (res.exitCode !== 0) {
+        throw new Error(`git fetch ${remote} ${branch} exited ${res.exitCode ?? "signal"}`);
+    }
+}
+async function defaultListRemoteMigrations(workdir, ref) {
+    const res = await execa("git", ["ls-tree", "-r", "--name-only", ref, "--", MIGRATIONS_DIR], { cwd: workdir, env: buildEnv(), reject: false });
+    if (res.exitCode !== 0)
+        return null;
+    return (res.stdout ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((s) => s.toLowerCase().endsWith(".sql"));
+}
+async function defaultListAddedMigrations(workdir, baseRef) {
+    if (!baseRef)
+        return [];
+    // `--diff-filter=A` (added only): a MODIFIED published migration must never be
+    // renumbered — that is the forward-only violation the linter already rejects.
+    const res = await execa("git", ["diff", "--name-only", "--diff-filter=A", `${baseRef}...HEAD`, "--", MIGRATIONS_DIR], { cwd: workdir, env: buildEnv(), reject: false });
+    if (res.exitCode !== 0)
+        return [];
+    return (res.stdout ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((s) => s.toLowerCase().endsWith(".sql"));
+}
+async function defaultRunRenumber(workdir, files, baselineSeqs) {
+    const script = path.join(workdir, "scripts", "ci", "migration-lint.mjs");
+    const args = ["--renumber"];
+    if (baselineSeqs.length > 0)
+        args.push("--baseline-seqs", baselineSeqs.join(","));
+    // `process.execPath`, not a bare "node": the runner may be launched by
+    // launchd with a PATH that has no node at all, and a silently-unspawnable
+    // renumber reads exactly like a clean no-op (empty output, clean tree).
+    const res = await execa(process.execPath, [script, ...args, ...files], {
+        cwd: workdir,
+        env: buildEnv(),
+        reject: false,
+    });
+    // `reject: false` resolves with the failure rather than throwing, so a spawn
+    // error (no node on PATH) arrives as a result whose exit code is not 0 and
+    // whose explanation lives on `shortMessage` — present at runtime on the
+    // failure shape, absent from execa's success type.
+    const shortMessage = res.shortMessage;
+    const spawnFailure = res.exitCode === 0 ? "" : `\n[exit ${res.exitCode ?? "signal"}] ${shortMessage ?? ""}`;
+    return { output: `${res.stdout ?? ""}\n${res.stderr ?? ""}${spawnFailure}`.trim() };
+}
+async function defaultIsDirty(workdir) {
+    const res = await execa("git", ["status", "--porcelain"], {
+        cwd: workdir,
+        env: buildEnv(),
+        reject: false,
+    });
+    return (res.stdout ?? "").trim().length > 0;
+}
+async function defaultCommit(workdir, message) {
+    await execa("git", ["add", "-A"], { cwd: workdir, env: buildEnv(), reject: false });
+    await execa("git", ["commit", "-m", message], {
+        cwd: workdir,
+        env: buildEnv(),
+        reject: false,
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// The guard
+// ─────────────────────────────────────────────────────────────────────────────
+const OUTPUT_TAIL = 2_000;
+/**
+ * Re-validate this branch's NEW migration seq against a freshly-fetched
+ * integration head and auto-renumber it when a sibling has since taken the
+ * number. Returns what happened; NEVER throws (a crash inside the guard is
+ * reported as `renumber-failed` and the push proceeds).
+ */
+export async function revalidateMigrationSeq(workdir, opts, deps = {}) {
+    const env = deps.env ?? process.env;
+    if (!seqGuardEnabled(env)) {
+        return {
+            renumbered: false,
+            skipped: "disabled",
+            detail: `${SEQ_GUARD_ENV} disables the pre-push migration seq re-validation`,
+        };
+    }
+    if (!opts.baseRef) {
+        return {
+            renumbered: false,
+            skipped: "no-base-ref",
+            detail: "no base ref — cannot tell which migrations this branch added",
+        };
+    }
+    const remote = opts.remote ?? "origin";
+    const listAdded = deps.listAddedMigrations ?? defaultListAddedMigrations;
+    try {
+        // Cheapest check first: a task that adds no migration never fetches. This is
+        // the overwhelming majority of pushes, and the whole happy path stays a
+        // single `git diff`.
+        const added = (await listAdded(workdir, opts.baseRef)).filter((f) => migrationSeq(f) !== null);
+        if (added.length === 0) {
+            return {
+                renumbered: false,
+                skipped: "no-new-migrations",
+                detail: "branch adds no migration — seq re-validation not needed",
+            };
+        }
+        const fetchRef = deps.fetchRef ?? defaultFetchRef;
+        const listRemote = deps.listRemoteMigrations ?? defaultListRemoteMigrations;
+        // The fetch is the entire point: the fork-time remote-tracking ref is what
+        // produced the stale seq in the first place.
+        let fetched = true;
+        try {
+            await fetchRef(workdir, remote, opts.integrationBranch);
+        }
+        catch {
+            fetched = false;
+        }
+        // Prefer FETCH_HEAD (what this fetch just wrote) over the remote-tracking
+        // ref, which a fetch refspec may not have updated. Fall back to the
+        // tracking ref so a failed fetch can still be checked against whatever the
+        // worktree already knows.
+        const refs = fetched
+            ? ["FETCH_HEAD", `${remote}/${opts.integrationBranch}`]
+            : [`${remote}/${opts.integrationBranch}`];
+        let remoteFiles = null;
+        for (const ref of refs) {
+            remoteFiles = await listRemote(workdir, ref);
+            if (remoteFiles && remoteFiles.length > 0)
+                break;
+        }
+        if (!remoteFiles || remoteFiles.length === 0) {
+            return {
+                renumbered: false,
+                skipped: "no-remote-seqs",
+                detail: `could not read ${MIGRATIONS_DIR} on a fresh ${remote}/${opts.integrationBranch} ` +
+                    `(fetch ${fetched ? "ok" : "failed"}) — seq left as-is`,
+                remoteMaxSeq: null,
+            };
+        }
+        // The baseline: everything claimed OUTSIDE this worktree. The remote head's
+        // seqs, plus the live ledger when the caller could read it (a migration can
+        // be applied before its file merges).
+        const claimed = new Set();
+        for (const f of remoteFiles) {
+            const n = migrationSeq(f);
+            if (n !== null)
+                claimed.add(n);
+        }
+        for (const n of opts.appliedSeqs ?? []) {
+            if (Number.isFinite(n) && n > 0)
+                claimed.add(Math.trunc(n));
+        }
+        const baselineSeqs = [...claimed].sort((a, b) => a - b);
+        const remoteMaxSeq = baselineSeqs.length > 0 ? baselineSeqs[baselineSeqs.length - 1] : null;
+        // Stale = at or below the fresh baseline: either the exact number a sibling
+        // took, or one behind it. A seq ABOVE the baseline is left alone (see the
+        // module header — a forward gap is MIGFIX-01's call, not the guard's).
+        const stale = added.filter((f) => {
+            const n = migrationSeq(f);
+            return n !== null && remoteMaxSeq !== null && n <= remoteMaxSeq;
+        });
+        if (stale.length === 0) {
+            return {
+                renumbered: false,
+                skipped: "seq-free",
+                detail: `migration seq still free on a fresh ${remote}/${opts.integrationBranch} ` +
+                    `(head max ${remoteMaxSeq ?? "n/a"}) — pushing unchanged`,
+                remoteMaxSeq,
+            };
+        }
+        const runRenumber = deps.runRenumber ?? defaultRunRenumber;
+        const isDirty = deps.isDirty ?? defaultIsDirty;
+        const commit = deps.commit ?? defaultCommit;
+        const { output } = await runRenumber(workdir, stale, baselineSeqs);
+        if (!(await isDirty(workdir))) {
+            return {
+                renumbered: false,
+                skipped: "renumber-noop",
+                // Carry the tool's own log: "left unchanged" is either a genuine no-op
+                // or a renumber that could not run, and only the log tells them apart.
+                detail: `renumber left the worktree unchanged — seq kept: ${stale.join(", ")}; ` +
+                    `tool said: ${output.slice(-500) || "(no output)"}`,
+                remoteMaxSeq,
+            };
+        }
+        // `move` describes the FIRST stale file. A branch adding several colliding
+        // migrations at once is vanishingly rare, and the renumber tool chains them
+        // correctly anyway (each pass re-reads the directory, so the second lands
+        // above the first). The full tool log rides along in `move.output`, so the
+        // event is never lossy even then.
+        const first = stale[0];
+        const fromSeq = migrationSeq(first);
+        // The tool's own log names the move (`0315 → 0316`); prefer it, and fall
+        // back to the arithmetic the tool would have used so the event is never
+        // empty just because the log format shifts.
+        const moved = /(\d{2,})\s*→\s*(\d{2,})/.exec(output);
+        const toSeq = moved ? Number(moved[2]) : (remoteMaxSeq ?? fromSeq) + 1;
+        const newFile = path.join(path.dirname(first), path.basename(first).replace(/^\d+/, String(toSeq).padStart(4, "0")));
+        await commit(workdir, `chore(acc): re-validate migration seq against fresh ${opts.integrationBranch} (MIG-SEQ-GUARD)`);
+        return {
+            renumbered: true,
+            detail: `migration seq ${fromSeq} was taken on a fresh ${remote}/${opts.integrationBranch} ` +
+                `(head max ${remoteMaxSeq}) — auto-renumbered to ${toSeq} before push`,
+            remoteMaxSeq,
+            move: {
+                file: first,
+                newFile,
+                fromSeq,
+                toSeq,
+                output: output.slice(-OUTPUT_TAIL),
+            },
+        };
+    }
+    catch (err) {
+        // Fail-open: the guard may only ever IMPROVE a push's odds.
+        return {
+            renumbered: false,
+            skipped: "renumber-failed",
+            detail: `seq re-validation crashed (push proceeds): ${err.message?.slice(0, 300)}`,
+        };
+    }
+}
+//# sourceMappingURL=migration-seq-guard.js.map

package/dist/migration-seq-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-seq-guard.js","sourceRoot":"","sources":["../src/migration-seq-guard.ts"],"names":[],"mappings":"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"}

package/dist/node-version.d.ts

@@ -0,0 +1,132 @@
+/** Worktree-relative path of the file `nvm use` reads. */
+export declare const NVMRC_REL = ".nvmrc";
+/**
+ * Explicit escape hatch: a bin dir containing the node the gates must run under.
+ * Set it on a host whose node lives outside every layout below. Trusted as
+ * declared — the version behind it is not re-verified (that would cost a spawn).
+ */
+export declare const NODE_BIN_DIR_ENV = "ACC_RUNNER_NODE_BIN_DIR";
+/** Where a pin was declared. */
+export type NodePinSource = ".nvmrc" | "package.json engines.node";
+export interface NodePin {
+    /** The pin normalised without a leading `v` (`22`, `22.20.0`). */
+    spec: string;
+    /** Major version — the part that actually has to match. */
+    major: number;
+    /** Full `x.y.z` when the pin names one; null for a major-only pin. */
+    exact: string | null;
+    source: NodePinSource;
+}
+/** Version-manager on-disk layouts this module knows how to walk. */
+export type NodeInstallLayout = "nvm" | "fnm" | "volta" | "asdf" | "n";
+/** How `binDir` was arrived at. */
+export type NodeResolutionSource = "current" | "explicit" | NodeInstallLayout | "unresolved" | "unpinned";
+export interface PinnedNodeResolution {
+    /** The repo's pin, or null when it declares none. */
+    pin: NodePin | null;
+    /**
+     * The node version the gates will run under, when knowable: the picked
+     * install's version, or the current process's. Null only for `explicit`
+     * (declared by the operator, deliberately not re-verified).
+     */
+    effective: string | null;
+    /**
+     * True when the node the gates will run under satisfies the pin — and also
+     * true when there is no pin to violate. False means "we ran under the wrong
+     * node and could not fix it", which is exactly the signal that turns a jsdom
+     * failure into an ENVIRONMENT fault rather than a code defect.
+     */
+    satisfied: boolean;
+    /**
+     * Dir to prepend to PATH so `node` (and therefore `pnpm`, whose shim shebangs
+     * `#!/usr/bin/env node`) resolves to the pinned install. Null when the current
+     * node is already right, or when nothing matching was found.
+     */
+    binDir: string | null;
+    source: NodeResolutionSource;
+    /** One-line, log-safe explanation for the runner log. Never contains secrets. */
+    note: string;
+}
+export interface NodeVersionDeps {
+    /** Env source. Default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Home dir the version-manager layouts hang off. Default `os.homedir()`. */
+    homedir?: string;
+    /** The running node's version (`v22.20.0` or `22.20.0`). Default `process.version`. */
+    currentVersion?: string;
+    /** Read a text file. Default `fs.readFile(abs, "utf8")`; rejects when absent. */
+    readTextFile?: (abs: string) => Promise<string>;
+    /** List a directory's entry names. Default `fs.readdir`; rejects when absent. */
+    listDir?: (abs: string) => Promise<string[]>;
+    /** True when `abs` exists and is executable. Default `fs.access(X_OK)`. */
+    isExecutable?: (abs: string) => Promise<boolean>;
+}
+/**
+ * The version a `.nvmrc` names, normalised without the leading `v`. Comments and
+ * blank lines are skipped (nvm allows both). Returns null for an ALIAS
+ * (`lts/*`, `node`, `stable`, `iron`) — resolving one needs nvm's alias table,
+ * and guessing is worse than reporting "unpinned" and falling back to `engines`.
+ */
+export declare function parseNvmrc(text: string): string | null;
+/**
+ * The major version an `engines.node` RANGE requires, as a major-only pin
+ * (`">=22 <23"` → `22`, `"22.x"` → `22`, `"^22.20.0"` → `22`). A range is a
+ * range: even when it names a patch we only ever pin the major, so `>=22.20.0
+ * <23` is satisfied by 22.21.0. Returns null when no number can be read.
+ */
+export declare function parseEnginesRange(range: string): string | null;
+/** Build a `NodePin` from a normalised spec, or null when it is unusable. */
+export declare function nodePinFrom(spec: string, source: NodePinSource): NodePin | null;
+/** `[major, minor, patch]` of a version string, or null when unparseable. */
+export declare function parseNodeVersion(v: string): [number, number, number] | null;
+/** Ascending comparison; unparseable versions sort first. */
+export declare function compareNodeVersions(a: string, b: string): number;
+/**
+ * True when `version` satisfies `pin`: the major must match, and when the pin
+ * names an exact `x.y.z` that must match too. An unparseable version satisfies
+ * nothing (fail closed — an unknown node is not assumed correct).
+ */
+export declare function satisfiesPin(version: string, pin: NodePin): boolean;
+/**
+ * The HIGHEST version in `versions` that satisfies `pin`, or null when none
+ * does. Highest, not first: on a host with 22.11.0 and 22.20.0 installed the
+ * newer patch is the one CI's `node-version: 22` would resolve to.
+ */
+export declare function pickPinnedInstall(versions: string[], pin: NodePin): string | null;
+export interface NodeInstallRoot {
+    layout: NodeInstallLayout;
+    /** Directory whose entries are version names (`v22.20.0` or `22.20.0`). */
+    dir: string;
+    /** The `bin` dir for one entry of `dir`. */
+    binDirFor: (entry: string) => string;
+}
+/**
+ * Version-manager roots to search, in preference order. Honours each manager's
+ * own env override so a non-default install location still resolves. Directories
+ * that do not exist are simply skipped by the caller — listing them is the probe.
+ */
+export declare function nodeInstallRoots(env: NodeJS.ProcessEnv, homedir: string): NodeInstallRoot[];
+/**
+ * Prepend `binDir` to a launchd-safe PATH (see bin-resolve.ts) so the pinned
+ * node wins every lookup — including `pnpm`'s own shebang, which is what makes
+ * the whole `pnpm run test` subtree inherit it. Idempotent: an already-leading
+ * `binDir` is not duplicated.
+ */
+export declare function withPinnedNodePath(env: NodeJS.ProcessEnv, binDir: string | null): NodeJS.ProcessEnv;
+/**
+ * The repo's declared node pin: `.nvmrc` first (it is what a human's `nvm use`
+ * obeys, so runner and human never disagree), then `package.json`
+ * `engines.node`. Null when neither declares a readable version.
+ */
+export declare function readRepoNodePin(workdir: string, deps?: NodeVersionDeps): Promise<NodePin | null>;
+/**
+ * Resolve which node the repo's gates must run under, and where it is.
+ *
+ * Order: no pin → nothing to enforce; current node satisfies → run as-is (the
+ * common case, and it costs one file read); `ACC_RUNNER_NODE_BIN_DIR` →
+ * trusted as declared; then each version-manager layout, highest matching patch
+ * wins; finally `unresolved`, which the caller surfaces rather than papering
+ * over.
+ */
+export declare function resolvePinnedNode(workdir: string, deps?: NodeVersionDeps): Promise<PinnedNodeResolution>;
+//# sourceMappingURL=node-version.d.ts.map

package/dist/node-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version.d.ts","sourceRoot":"","sources":["../src/node-version.ts"],"names":[],"mappings":"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"}