@catalystiq/test-kit 0.0.0-stage → 0.2.0

package/dist/neon-test-db/neon-test-db.d.mts

@@ -0,0 +1,35 @@
+// Types for neon-test-db.mjs, the `tk-neon-test-db` CLI (see README.md beside it). The script stays plain JavaScript so
+// it runs with no build step and is the same file github-actions' apps ran as a vendored copy.
+
+export declare const SCHEMA_ONLY_SOURCES: string[];
+export declare const INIT_SOURCES: string[];
+export declare const NEON_API: string;
+export declare const MAX_EXPIRES: number;
+
+export interface NeonTestDbConfig {
+  problems: string[];
+  key: string;
+  project: string;
+  parent: string;
+  expires: number;
+  database: string;
+  init: string;
+  dataParents: string[];
+  keep: boolean;
+  command: string[];
+}
+
+export interface NeonTestDbDeps {
+  /** What the script reads of an answer: `ok`, `status` and `json()`. */
+  fetch: (url: string, init: RequestInit) => Promise<Pick<Response, 'ok' | 'status' | 'json'>>;
+  run: (command: string[], env: Record<string, string | undefined>) => Promise<number>;
+  log: (line: string) => void;
+  now: () => Date;
+  sleep: (ms: number) => Promise<void>;
+  onSignal: (handler: (signal?: string) => void) => () => void;
+}
+
+export declare function readConfig(env: Record<string, string | undefined>, argv: string[]): NeonTestDbConfig;
+export declare function branchName(user: string | undefined, now: Date, rand: string): string;
+/** Runs the whole flow; returns the exit code. */
+export declare function main(env: Record<string, string | undefined>, argv: string[], deps: NeonTestDbDeps): Promise<number>;

package/dist/neon-test-db/neon-test-db.mjs

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+// THE LOCAL DATABASE TEST RUN (@catalystiq/test-kit, bin `tk-neon-test-db`): `npm run test:db`.
+//
+// Moved here from getcatalystiq/github-actions' scripts/neon-test-db.mjs, which every app vendored unchanged; the apps now
+// run it from the package. Add the package as an exact-pinned dev dependency and the script:
+//
+//   "test:db": "tk-neon-test-db -- npm run ci:db"
+//
+// It CUTS a short-lived, SCHEMA-ONLY Neon branch (init_source schema-only: the parent's schema, none of its rows, so
+// never production data; NEON_TEST_DB_INIT=parent-data, below, is the one exception, for a synthetic parent), runs the
+// command after `--` with DATABASE_URL set to that branch, and DELETES the branch it made whatever the command did, a
+// Ctrl-C included. The branch also carries an expiry (default 2 hours, at most 6), so one whose process died is collected
+// by Neon. Nothing else is ever deleted: the delete names the id this run created.
+//
+// Configuration, from the environment (a repository's `.env.local` is NOT read; export them or use `dotenv --`):
+//   NEON_API_KEY             a key that reaches the project (a personal key, or `neonctl`'s token for a short run)
+//   NEON_TEST_DB_PROJECT     the Neon project id (each repository's CLAUDE.md or README names it)
+//   NEON_TEST_DB_PARENT      the parent branch id (br-…) or name whose schema is copied (staging's, or the CI project's
+//                            ci-synthetic). Never production's: NEON_TEST_DB_REFUSE names project ids to refuse.
+//   NEON_TEST_DB_REFUSE      project ids this command refuses outright (name production)
+//   NEON_TEST_DB_DATABASE    the database to connect to (default: the branch's one database that is not `postgres`)
+//   NEON_TEST_DB_EXPIRES     minutes until Neon deletes the branch on its own (default 120, at most 360)
+//   NEON_TEST_DB_KEEP=1      keep the branch afterwards (it still expires); prints its id, never its password
+//   NEON_TEST_DB_INIT        `schema-only` (the default) or `parent-data`: a DATA copy of the parent, for a suite that
+//                            needs rows the parent carries (divorce-virtual's migration ledger and reference catalog on
+//                            ci-synthetic). Only for a SYNTHETIC parent, never one that holds customer rows: it is
+//                            refused unless the parent's branch ID (br-…, never a name, which anyone can give another
+//                            branch) is listed in NEON_TEST_DB_DATA_PARENTS, the parents the repository's own script
+//                            names as customer-free. The lock is the parent, not the project, because a project can hold
+//                            production beside a synthetic branch (divorce-virtual's does). The branch must come back as
+//                            a data copy (not schema-only) of that parent, or it is deleted unused.
+//
+// The connection string is never printed. The branch is named `tmp/test-db-<user>-<UTC yyyymmddhhmmss>-<4 hex>`.
+
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { constants as osConstants, userInfo } from 'node:os';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The init_source values that mean schema-only: Neon's answer and the request's spelling (actions/neon-branch's inventory reads the same list). */
+export const SCHEMA_ONLY_SOURCES = ['parent-schema', 'schema-only'];
+/** NEON_TEST_DB_INIT's values: what the create asks for. */
+export const INIT_SOURCES = ['schema-only', 'parent-data'];
+
+export const NEON_API = 'https://console.neon.tech/api/v2';
+export const MAX_EXPIRES = 360;
+const ID = /^[a-z0-9-]{1,64}$/;
+
+/** One Neon API call; returns { ok, status, body }. Never throws; never puts the key or a body in an error. */
+async function call(deps, key, method, path, body) {
+  try {
+    const res = await deps.fetch(`${NEON_API}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${key}`, Accept: 'application/json', ...(body ? { 'Content-Type': 'application/json' } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(30_000),
+    });
+    let parsed = null;
+    try {
+      parsed = await res.json();
+    } catch {}
+    return { ok: res.ok, status: res.status, body: parsed };
+  } catch {
+    return { ok: false, status: 0, body: null };
+  }
+}
+
+export function readConfig(env, argv) {
+  const sep = argv.indexOf('--');
+  const command = sep < 0 ? [] : argv.slice(sep + 1);
+  const problems = [];
+  if (command.length === 0) problems.push('no command: run it as `tk-neon-test-db -- npm run ci:db`');
+  const key = env.NEON_API_KEY ?? '';
+  if (!key) problems.push('NEON_API_KEY is not set');
+  const project = (env.NEON_TEST_DB_PROJECT ?? '').trim();
+  if (!ID.test(project)) problems.push('NEON_TEST_DB_PROJECT is not a Neon project id');
+  const refuse = (env.NEON_TEST_DB_REFUSE ?? '').split(/[\s,]+/).filter(Boolean);
+  if (refuse.includes(project)) problems.push(`NEON_TEST_DB_PROJECT ${project} is in NEON_TEST_DB_REFUSE: this command never cuts from that project`);
+  const parent = (env.NEON_TEST_DB_PARENT ?? '').trim();
+  if (!/^[A-Za-z0-9_./-]{1,128}$/.test(parent)) problems.push('NEON_TEST_DB_PARENT is not a branch id or name');
+  const expiresRaw = (env.NEON_TEST_DB_EXPIRES ?? '120').trim();
+  const expires = Number(expiresRaw);
+  if (!/^[0-9]+$/.test(expiresRaw) || expires < 5 || expires > MAX_EXPIRES) problems.push(`NEON_TEST_DB_EXPIRES must be whole minutes from 5 to ${MAX_EXPIRES}`);
+  const database = (env.NEON_TEST_DB_DATABASE ?? '').trim();
+  const init = (env.NEON_TEST_DB_INIT ?? '').trim() || 'schema-only';
+  if (!INIT_SOURCES.includes(init)) problems.push(`NEON_TEST_DB_INIT must be ${INIT_SOURCES.join(' or ')}`);
+  // The parents allowed to hand out rows, by branch id; checked against the RESOLVED parent's id in main().
+  const dataParents = (env.NEON_TEST_DB_DATA_PARENTS ?? '').split(/[\s,]+/).filter(Boolean);
+  if (init === 'parent-data' && dataParents.length === 0) {
+    problems.push('NEON_TEST_DB_INIT=parent-data copies the parent\'s rows: list the customer-free parent\'s branch id in NEON_TEST_DB_DATA_PARENTS');
+  }
+  return { problems, key, project, parent, expires, database, init, dataParents, keep: env.NEON_TEST_DB_KEEP === '1', command };
+}
+
+export function branchName(user, now, rand) {
+  const who = (user || 'dev').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 20) || 'dev';
+  const stamp = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+  return `tmp/test-db-${who}-${stamp}-${rand}`;
+}
+
+/** Runs the whole flow; returns the exit code. `deps`: fetch, run(command, env) → Promise<code>, log, now, sleep, onSignal. */
+export async function main(env, argv, deps) {
+  const c = readConfig(env, argv);
+  if (c.problems.length) {
+    for (const p of c.problems) deps.log(`neon-test-db: ${p}`);
+    return 2;
+  }
+  // The parent: by id, or the one branch of that name.
+  const list = await call(deps, c.key, 'GET', `/projects/${c.project}/branches`);
+  if (!list.ok) {
+    deps.log(`neon-test-db: could not list the project's branches (HTTP ${list.status || 'no answer'}). Does the key reach ${c.project}?`);
+    return 1;
+  }
+  const branches = Array.isArray(list.body?.branches) ? list.body.branches : [];
+  const matches = branches.filter((b) => b.id === c.parent || b.name === c.parent);
+  if (matches.length !== 1) {
+    deps.log(`neon-test-db: ${matches.length === 0 ? 'no' : matches.length} branch(es) match NEON_TEST_DB_PARENT=${c.parent}.`);
+    return 1;
+  }
+  const parent = matches[0];
+  if (c.init === 'parent-data' && !c.dataParents.includes(parent.id)) {
+    deps.log(`neon-test-db: NEON_TEST_DB_INIT=parent-data copies the parent's rows, and ${parent.id} is not in NEON_TEST_DB_DATA_PARENTS; nothing was created.`);
+    return 2;
+  }
+  // userInfo() throws in a container whose uid has no passwd entry; branchName names an empty user 'dev'.
+  let user = env.USER || '';
+  if (!user) try { user = userInfo().username; } catch { /* no passwd entry */ }
+  const name = branchName(user, deps.now(), randomBytes(2).toString('hex'));
+  const expiresAt = new Date(deps.now().getTime() + c.expires * 60_000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+  // Ctrl-C is caught from before the create: once a branch exists, every exit path below deletes it (or keeps it, with
+  // NEON_TEST_DB_KEEP=1), an interrupt included.
+  // `interrupted` holds the signal's name; the exit is 128 + its number (130 SIGINT, 143 SIGTERM, 129 SIGHUP).
+  let interrupted = '';
+  const stop = deps.onSignal((sig) => {
+    interrupted = interrupted || sig || 'SIGINT';
+  });
+  const signalExit = () => signalCode(interrupted);
+  const startedAt = deps.now().getTime();
+  const madeByThisRun = (b) => {
+    const t = Date.parse(b?.created_at ?? '');
+    // Ten minutes of slack either way: Neon's clock and this machine's need not agree, and no other branch's
+    // created_at falls this close to a create whose answer named it.
+    return Number.isFinite(t) && t >= startedAt - 600_000 && t <= deps.now().getTime() + 600_000;
+  };
+  // ONE ownership rule: a branch is deleted only when it is shown to be this run's, by the name asked for or by a
+  // created_at inside this run. Anything else (another name, or no name whose read-back failed) may be a branch that
+  // existed (the list read may be one page of several), so it is left alone; a branch this run did make carries the
+  // expiry it asked for.
+  const named = (b) => typeof b?.name === 'string' && b.name !== '';
+  let owned = false; // set once ANY answer about this id (the create, or a read with the same id) shows it this run's
+  const note = (b) => {
+    if ((named(b) && b.name === name) || madeByThisRun(b)) owned = true;
+  };
+  const ours = (b) => {
+    note(b);
+    return owned;
+  };
+  // One rule for "schema-only": the refusal and the delete message both read it.
+  const isSchemaOnly = (b) => SCHEMA_ONLY_SOURCES.includes(b?.init_source ?? '');
+  // One rule for "the source asked for": schema-only (either spelling), or a data copy: any reported source that is not
+  // schema-only (Neon spells its answers its own way, as 'parent-schema' shows), and, checked below, this parent's.
+  const dataCopy = c.init === 'parent-data';
+  const isSourceAsked = (b) => (dataCopy ? b?.init_source != null && !isSchemaOnly(b) : isSchemaOnly(b));
+  // One rule for the expiry: no later than asked (60 s of clock slack). The check and the delete message both use it.
+  const latest = Date.parse(expiresAt) + 60_000;
+  const expiresInTime = (b) => {
+    const t = Date.parse(b?.expires_at ?? '');
+    return Number.isFinite(t) && t <= latest;
+  };
+  let branch;
+  let code = 1;
+  let ok = false;
+  try {
+    const created = await call(deps, c.key, 'POST', `/projects/${c.project}/branches`, {
+      branch: { name, parent_id: parent.id, init_source: c.init, expires_at: expiresAt },
+      endpoints: [{ type: 'read_write' }],
+    });
+    branch = created.body?.branch;
+    // An id goes into the read-back and delete paths, so it must look like one (br-…) and must not be a branch that
+    // existed before this create (the list read above): otherwise nothing is touched by it.
+    // The id must be a STRING of the id shape: a non-string (an array, an object) would pass a String() test and
+    // miss the `===` comparison with the list, and then name another branch in every path built from it.
+    if (!created.ok || branch?.id === undefined) {
+      // A failed create deletes nothing, even if its answer names an id: a branch it may have made carries the expiry.
+      deps.log(`neon-test-db: could not create ${name} (HTTP ${created.status || 'no answer'}). Nothing to delete; if it was created anyway it expires at ${expiresAt}.`);
+      branch = undefined;
+      return 1; // an interrupt's code is set in finally
+    }
+    // A malformed id, or one already in the list, is never touched even under the name asked for: deleting it safely
+    // would need another list by that name; a branch this run made carries its expiry.
+    const idOk = typeof branch.id === 'string' && ID.test(branch.id);
+    const existed = idOk && branches.some((b) => b.id === branch.id);
+    if (!idOk || existed) {
+      deps.log(`neon-test-db: the create answered with ${existed ? 'the id of a branch that already existed' : 'a malformed branch id'}; touching nothing. ${name}, if it exists, expires at ${expiresAt}.`);
+      branch = undefined;
+      return 1; // an interrupt's code is set in finally
+    }
+    // Every refusal below deletes this id only when an answer about it (the create, or a read of it) shows it this
+    // run's (ours); otherwise the branch is left to its expiry, and nothing else is ever deleted. An answer missing the
+    // name, the source or the expiry is read back from GET /branches/<id> (a few tries); a read that never answers is
+    // said as such.
+    note(branch);
+    if (!named(branch) || branch.init_source == null || branch.expires_at == null) {
+      let read = null;
+      for (let attempt = 1; attempt <= 5 && !interrupted; attempt++) {
+        const r = await call(deps, c.key, 'GET', `/projects/${c.project}/branches/${branch.id}`);
+        // Neon's read is the authority: every checked field comes from it, never from the incomplete create answer.
+        const got = r.ok && typeof r.body?.branch?.id === 'string' && r.body.branch.id === branch.id ? r.body.branch : null;
+        if (got) note(got); // a partial read still counts as evidence that the branch is this run's
+        if (got && named(got) && got.init_source != null && got.expires_at != null) {
+          read = got;
+          break;
+        }
+        if (attempt < 5) await deps.sleep(2000);
+      }
+      if (interrupted) return signalExit();
+      if (!read) {
+        deps.log(`neon-test-db: could not read back the branch answered (${branch.id}) with its name, source and expiry; ${ours(branch) ? 'deleting it' : 'it is not shown to be this run\'s, so it is left alone'}.`);
+        return 1;
+      }
+      branch = read;
+    }
+    // Neon answers a schema-only create with parent_id null and init_source 'parent-schema' (measured on easy-passport's
+    // project, 2026-11-07); the request's spelling 'schema-only' counts too (SCHEMA_ONLY_SOURCES, pinned equal to the
+    // inventory's list by a test). The branch must carry the name asked for, a schema-only source, an expiry no later
+    // than the one asked for, and the parent asked for or, as Neon reports it, none. With no parent in the answer the
+    // branch cannot be traced to the parent asked for; the log says so rather than naming one.
+    // A data copy must name its parent: rows from an unknown branch are never used.
+    const why =
+      branch.name !== name ? `came back named ${branch.name ?? '(none)'}`
+      : !isSourceAsked(branch) ? `came back not ${dataCopy ? 'a data copy' : 'schema-only'} (init_source=${branch.init_source ?? 'none'})`
+      : dataCopy && branch.parent_id !== parent.id ? `came back ${branch.parent_id == null ? 'naming no parent' : `from another parent (${branch.parent_id})`}`
+      : branch.parent_id != null && branch.parent_id !== parent.id ? `came back from another parent (${branch.parent_id})`
+      : !Number.isFinite(Date.parse(branch.expires_at ?? '')) ? 'came back with no expiry'
+      : !expiresInTime(branch) ? `came back expiring later than asked (${branch.expires_at})`
+      : '';
+    if (why) {
+      deps.log(`neon-test-db: the branch answered (${branch.id}) ${why}; ${ours(branch) ? 'deleting it' : 'Neon does not show it as made by this run, so it is left alone'}.`);
+      return 1; // an interrupt's code is set in finally
+    }
+    const from = branch.parent_id === parent.id ? `from ${parent.name}` : `(Neon names no parent; asked for ${parent.name})`;
+    deps.log(`neon-test-db: ${name} (${branch.id}), ${dataCopy ? 'a data copy' : 'schema-only'} ${from}, expires ${branch.expires_at}.`);
+    ok = true;
+    if (interrupted) return signalExit();
+    const url = await connectionString(deps, c, branch.id, () => interrupted);
+    if (interrupted) return signalExit();
+    if (!url) return 1;
+    code = await deps.run(c.command, { ...env, DATABASE_URL: url, NEON_TEST_DB_BRANCH: name });
+  } finally {
+    // The handlers stay until the delete is done: a second Ctrl-C or a follow-up SIGTERM must not kill the cleanup.
+    if (branch?.id && !ours(branch)) {
+      deps.log(`neon-test-db: touching nothing. ${name}, if it exists, expires at ${expiresAt}.`);
+    } else if (branch?.id) {
+      if (ok && c.keep) deps.log(`neon-test-db: kept ${name} (${branch.id}); it expires ${branch.expires_at}.`);
+      else {
+        // Its own expiry, and that it holds no data, are promised only for a branch confirmed both. The log names the
+        // branch Neon reported, which is the one left behind if the delete fails.
+        const confirmed = expiresInTime(branch) && isSourceAsked(branch);
+        if (!(await remove(deps, c, branch.id, named(branch) ? branch.name : name, confirmed, dataCopy)) && ok) code = code || 1;
+      }
+    }
+    stop();
+    // An interrupt at ANY point, the cleanup included, ends the run with the signal's code. Returning from finally
+    // overrides the try's own return (a refusal's 1, a run's code, a failed delete's 1) on purpose.
+    // eslint-disable-next-line no-unsafe-finally
+    if (interrupted) return signalExit();
+  }
+  // Reached only by the run itself (every refusal returned above): a failed delete after a passing run is a failure.
+  return code;
+}
+
+async function connectionString(deps, c, branchId, stopped = () => false) {
+  let database = c.database;
+  let role = '';
+  for (let attempt = 1; attempt <= 30; attempt++) {
+    if (stopped()) return null;
+    const dbs = await call(deps, c.key, 'GET', `/projects/${c.project}/branches/${branchId}/databases`);
+    const list = Array.isArray(dbs.body?.databases) ? dbs.body.databases : [];
+    const pick = database ? list.filter((d) => d.name === database) : list.filter((d) => d.name && d.name !== 'postgres' && d.owner_name);
+    if (dbs.ok && pick.length === 1) {
+      database = pick[0].name;
+      role = pick[0].owner_name;
+      break;
+    }
+    if (attempt === 30) {
+      deps.log(`neon-test-db: expected one ${database ? `database named ${database}` : 'application database'} on the branch, found ${pick.length}.`);
+      return null;
+    }
+    await deps.sleep(2000);
+  }
+  const q = new URLSearchParams({ branch_id: branchId, database_name: database, role_name: role });
+  for (let attempt = 1; attempt <= 30; attempt++) {
+    if (stopped()) return null;
+    const uri = await call(deps, c.key, 'GET', `/projects/${c.project}/connection_uri?${q}`);
+    const value = typeof uri.body?.uri === 'string' ? uri.body.uri : '';
+    if (uri.ok && /^postgres(ql)?:\/\//.test(value)) return value;
+    if (attempt === 30) {
+      deps.log(`neon-test-db: could not read the branch's connection string (HTTP ${uri.status || 'no answer'}).`);
+      return null;
+    }
+    await deps.sleep(2000);
+  }
+  return null;
+}
+
+/** A shell's exit code for a process ended by a signal: 128 + its number (SIGINT 130, SIGTERM 143, SIGHUP 129). */
+function signalCode(name) {
+  return 128 + (osConstants.signals[name] ?? 2);
+}
+
+/** Deletes ONLY the branch this run created, by id, retrying while Neon holds it (423). */
+async function remove(deps, c, branchId, name, confirmed = true, dataCopy = false) {
+  for (let attempt = 1; attempt <= 10; attempt++) {
+    const r = await call(deps, c.key, 'DELETE', `/projects/${c.project}/branches/${branchId}`);
+    if (r.ok || r.status === 404) {
+      deps.log(`neon-test-db: deleted ${name}.`);
+      return true;
+    }
+    if (r.status !== 423 && r.status !== 0) break;
+    await deps.sleep(3000);
+  }
+  deps.log(`neon-test-db: could not delete ${name} (${branchId}); ${confirmed ? 'it expires on its own. Delete it in the Neon console to free the slot now' : `it was not confirmed to expire on its own or to hold ${dataCopy ? 'only its parent\'s rows' : 'no data'}. Delete it in the Neon console`}.`);
+  return false;
+}
+
+function realMain() {
+  // After a SIGHUP the terminal is gone and a log line to it fails (EIO); that must not kill the cleanup.
+  process.stderr.on('error', () => {});
+  return main(process.env, process.argv.slice(2), {
+    fetch: (url, init) => fetch(url, init),
+    log: (line) => console.error(line),
+    now: () => new Date(),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    run: (command, env) =>
+      new Promise((done) => {
+        const child = spawn(command[0], command.slice(1), { stdio: 'inherit', env });
+        // SIGINT is never passed on: a Ctrl-C or a runner's cancel reaches the child through its process group, and a
+        // second one makes Vitest force-quit. SIGTERM and SIGHUP, which a runner or a closed terminal may send to this
+        // process alone, are; one sent to the whole group therefore reaches the child twice, an accepted cost (this
+        // process cannot tell the two apart). (`kill -INT <this pid>` alone leaves the child running: send it to the group.)
+        const handlers = ['SIGTERM', 'SIGHUP'].map((sig) => [sig, () => child.kill(sig)]);
+        for (const [sig, h] of handlers) process.on(sig, h);
+        const end = (code) => {
+          for (const [sig, h] of handlers) process.off(sig, h);
+          done(code);
+        };
+        child.on('error', () => end(127));
+        // A child killed by a signal exits 128 + its number (130 for SIGINT, 143 for SIGTERM), as a shell reports it.
+        child.on('exit', (code, signal) => end(code ?? (signal ? signalCode(signal) : 1)));
+      }),
+    onSignal: (fn) => {
+      // This process stays up on Ctrl-C, SIGTERM or SIGHUP (a closed terminal) to delete the branch.
+      const h = (sig) => fn(sig);
+      for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, h);
+      return () => {
+        for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.off(sig, h);
+      };
+    },
+  });
+}
+
+/** Whether this file is the process's entry point (npm's `.bin` link included); never throws, as it runs on import. */
+function isEntryPoint() {
+  try {
+    return Boolean(process.argv[1]) && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  realMain().then(
+    (code) => process.exit(code),
+    () => {
+      console.error('neon-test-db: crashed. It tried to delete any branch it made; one it could not delete expires on its own (tmp/test-db-*).');
+      process.exit(1);
+    },
+  );
+}

package/dist/setup/README.md

@@ -0,0 +1,54 @@
+# `@catalystiq/test-kit/setup`
+
+The shared Vitest setup: one config helper and one worker setup file that every test file runs first.
+
+## Use it
+
+```ts
+// vitest.config.ts
+import { defineTestKitConfig } from '@catalystiq/test-kit/setup/config';
+
+export default defineTestKitConfig(
+  {
+    productionDatabaseHostsFile: 'db/production-hosts.json', // your production hosts, kept in your repo
+    keepEnv: ['TEST_DATABASE_URL'],
+    testDatabaseEnv: ['TEST_DATABASE_URL'],
+    allowHosts: [],
+    reactWarningAllowList: 'react-warnings.allow.json',
+  },
+  { test: { setupFiles: ['./vitest.setup.ts'] } }, // your own setup runs after the kit's
+);
+```
+
+A file that needs a DOM says so on its first line: `// @vitest-environment jsdom`.
+
+## What it does, for every test file
+
+| Rule | What happens |
+|---|---|
+| Defaults | `environment: 'node'`, 30 s test and hook timeouts, `retry: 0` (a retry is refused), `server-only` resolves to an empty module, `*.pw.ts` is excluded, the kit's setup file runs first. A repo's own `include` replaces the kit's catch-all glob rather than joining it; every other list is merged. The config helper loads from a CommonJS `vitest.config.ts` too (a package without `"type": "module"`). |
+| Credentials | Every variable whose name holds `KEY`, `TOKEN`, `SECRET`, `DSN`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, `PRIVATE`, `WEBHOOK`, `COOKIE`, `SESSION` or `AUTH`, and every variable whose value is a URL with a password, is deleted. `keepEnv` keeps names; `stripEnv` deletes more. Set the placeholders your code needs in your own setup file. |
+| Network | `fetch` and every TCP socket (`http`, `https`, `tls`, undici, database drivers) are refused unless the host is loopback, on `allowHosts` (`*.example.test` matches subdomains), or the host of a database URL that passed the check below (`allowDatabaseHosts`, default true). Only a URL the credential strip kept counts, so name the test database in `keepEnv` or set it in your own setup file. Neon's serverless HTTP driver sends a query to the region's gateway (`api.<region>.neon.tech`, the database named in a header), not to the database's host: a repo that runs it against a Neon branch lists that gateway in `allowHosts` itself, knowing it serves every database in the region (the credential strip is what keeps another database's password out). A refused request fails the test even when the code swallowed the error. `allowNetworkHosts(host)` adds one for the rest of a file. |
+| Production databases | A Postgres URL in the environment whose host is on your production list (a host, a subdomain of it, or a compute endpoint id `ep-…` with or without `-pooler`) is refused before any test runs, and again before the tests (your own setup file may set the URL). |
+| `.env*` files | A Postgres URL in the environment that names the same database as any `.env*` file at the root is refused: those hold a developer's own connections. Every `postgres://` text counts, comments included, except lines keyed by `testDatabaseEnv`. |
+| React warnings | A React or Radix warning (`console.error` / `console.warn`) fails the test, also when the test muted the console (`vi.spyOn(console, 'error').mockImplementation(() => {})`, `console.error = vi.fn()`, `console.error = () => {}`). |
+| DOM files | Under jsdom: a `matchMedia` stub, `localStorage` / `sessionStorage` re-bound on Node 26, Testing Library's `cleanup` after each test, and jest-dom's matchers when installed. |
+
+## Allowing a React warning
+
+In one test, while you mean to provoke it:
+
+```ts
+import { allowReactWarnings } from '@catalystiq/test-kit/setup';
+allowReactWarnings(/not wrapped in act\(/);
+```
+
+Across the repo, for warnings not fixed yet, `react-warnings.allow.json`:
+
+```json
+{ "max": 1, "entries": [{ "pattern": "not wrapped in act\\(", "file": "src/cart/", "reason": "cart timers, being fixed" }] }
+```
+
+`max` must equal the number of entries, and the list only shrinks: run `tk-check-allowlist react-warnings.allow.json`
+in CI (it needs the base branch fetched); it fails when an entry was added or `max` rose against `origin/main`
+(`--base` to change it).

package/dist/setup/allow-list.d.ts

@@ -0,0 +1,14 @@
+export interface AllowListEntry {
+    pattern: string;
+    reason: string;
+    file?: string;
+}
+export interface AllowList {
+    max: number;
+    entries: AllowListEntry[];
+}
+/** Validates a parsed allow-list; throws naming the first problem. */
+export declare function parseAllowList(value: unknown, source?: string): AllowList;
+export declare function readAllowList(path: string): AllowList;
+/** The problems with `current` against `base` (the file as the base branch has it); empty when it only shrank. */
+export declare function allowListGrowth(current: AllowList, base: AllowList | null): string[];

package/dist/setup/allow-list.js

@@ -0,0 +1,62 @@
+/**
+ * The repo's React-warning allow-list: the warnings it has not fixed yet. A JSON file:
+ *
+ *     { "max": 2, "entries": [{ "pattern": "not wrapped in act\\(", "file": "src/cart/", "reason": "…" }] }
+ *
+ * Its entries only shrink. `max` must equal the number of entries, so removing one means lowering `max` in the same
+ * change and adding one means raising it, which a reviewer sees; `tk-check-allowlist` fails a change whose file has an
+ * entry its base (`origin/main`) did not have, or a larger `max`.
+ */
+import { readFileSync } from 'node:fs';
+/** Validates a parsed allow-list; throws naming the first problem. */
+export function parseAllowList(value, source = 'the React-warning allow-list') {
+    if (!value || typeof value !== 'object')
+        throw new Error(`${source} must be a JSON object { max, entries }`);
+    const { max, entries } = value;
+    if (!Array.isArray(entries))
+        throw new Error(`${source}: "entries" must be an array`);
+    if (typeof max !== 'number' || !Number.isInteger(max) || max < 0)
+        throw new Error(`${source}: "max" must be a whole number`);
+    if (max !== entries.length) {
+        throw new Error(`${source}: "max" is ${max} but there are ${entries.length} entries. It must equal the number of entries: lower it when you remove one.`);
+    }
+    const seen = new Set();
+    const parsed = entries.map((raw, i) => {
+        const e = raw;
+        if (!e || typeof e.pattern !== 'string' || e.pattern === '')
+            throw new Error(`${source}: entry ${i} needs a "pattern"`);
+        if (typeof e.reason !== 'string' || e.reason.trim() === '')
+            throw new Error(`${source}: entry ${i} needs a "reason"`);
+        if (e.file !== undefined && typeof e.file !== 'string')
+            throw new Error(`${source}: entry ${i}'s "file" must be a string`);
+        try {
+            new RegExp(e.pattern);
+        }
+        catch {
+            throw new Error(`${source}: entry ${i}'s pattern is not a valid regular expression`);
+        }
+        const key = `${e.pattern}\u0000${e.file ?? ''}`;
+        if (seen.has(key))
+            throw new Error(`${source}: entry ${i} repeats an earlier one`);
+        seen.add(key);
+        return { pattern: e.pattern, reason: e.reason, ...(e.file === undefined ? {} : { file: e.file }) };
+    });
+    return { max, entries: parsed };
+}
+export function readAllowList(path) {
+    return parseAllowList(JSON.parse(readFileSync(path, 'utf8')), path);
+}
+/** The problems with `current` against `base` (the file as the base branch has it); empty when it only shrank. */
+export function allowListGrowth(current, base) {
+    if (base === null)
+        return [];
+    const problems = [];
+    if (current.max > base.max)
+        problems.push(`"max" rose from ${base.max} to ${current.max}`);
+    const before = new Set(base.entries.map((e) => `${e.pattern}\u0000${e.file ?? ''}`));
+    for (const e of current.entries) {
+        if (!before.has(`${e.pattern}\u0000${e.file ?? ''}`))
+            problems.push(`a new entry: /${e.pattern}/${e.file ? ` in ${e.file}` : ''}`);
+    }
+    return problems;
+}

package/dist/setup/config.d.ts

@@ -0,0 +1,53 @@
+import { type ViteUserConfig } from 'vitest/config';
+export interface TestKitOptions {
+    /** The repository root, where the `.env*` files are. Default: `process.cwd()`. */
+    root?: string;
+    /** Hosts a test may reach besides loopback (`*.example.test` matches subdomains). */
+    allowHosts?: string[];
+    /** Let a test reach the host of each database URL that passed the production check. Default: true. */
+    allowDatabaseHosts?: boolean;
+    /** Variables the credential strip keeps (the test database URL, a key a global setup needs). */
+    keepEnv?: string[];
+    /** Variables the strip deletes although their names look harmless (`PGHOST`, `VERCEL_ENV`). */
+    stripEnv?: string[];
+    /** Production database hosts or endpoint ids. */
+    productionDatabaseHosts?: string[];
+    /** A JSON file holding more of them: an array, or `{ "hosts": [...] }`. Relative to `root`. */
+    productionDatabaseHostsFile?: string;
+    /** `.env*` keys that name the TEST database, whose lines do not protect what they name. */
+    testDatabaseEnv?: string[];
+    /** The React-warning allow-list file, relative to `root` (see the README). */
+    reactWarningAllowList?: string;
+}
+/** What the workers receive. */
+export interface TestKitProvided {
+    allowHosts: string[];
+    allowDatabaseHosts: boolean;
+    keepEnv: string[];
+    stripEnv: string[];
+    productionHosts: string[];
+    protectedPlaces: string[];
+    allowedWarnings: Array<{
+        pattern: string;
+        file?: string;
+    }>;
+}
+declare module 'vitest' {
+    interface ProvidedContext {
+        testKit: TestKitProvided;
+    }
+}
+/** The kit's worker setup file. */
+export declare const SETUP_FILE: string;
+/** The empty module `server-only` resolves to. */
+export declare const SERVER_ONLY_STUB: string;
+/** What the workers get, from the options. */
+export declare function provideFor(options?: TestKitOptions): TestKitProvided;
+/** The kit's part of a Vitest config. */
+export declare function testKitConfig(options?: TestKitOptions): ViteUserConfig;
+/**
+ * The kit's config merged with the repo's; refuses a retry, which hides a broken test. A repo that names its own
+ * `include` gets exactly that list: Vite's merge concatenates arrays, which would add the kit's catch-all glob and run
+ * files the repo never ran (another suite's, a script's `.test.mjs`).
+ */
+export declare function defineTestKitConfig(options?: TestKitOptions, repo?: ViteUserConfig): ViteUserConfig;