@catalystiq/test-kit 0.1.0 → 0.3.0

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

@@ -26,9 +26,9 @@ A file that needs a DOM says so on its first line: `// @vitest-environment jsdom
 
 | 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. |
+| 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). A refused request fails the test even when the code swallowed the error. `allowNetworkHosts(host)` adds one for the rest of a 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 = () => {}`). |

package/dist/setup/config.d.ts

@@ -45,5 +45,9 @@ export declare const SERVER_ONLY_STUB: string;
 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. */
+/**
+ * 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;

package/dist/setup/config.js

@@ -66,9 +66,15 @@ export function testKitConfig(options = {}) {
         },
     };
 }
-/** The kit's config merged with the repo's; refuses a retry, which hides a broken test. */
+/**
+ * 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 function defineTestKitConfig(options = {}, repo = {}) {
     const merged = mergeConfig(testKitConfig(options), repo);
+    if (repo.test?.include !== undefined && merged.test)
+        merged.test.include = repo.test.include;
     const retry = merged.test?.retry;
     if (retry !== undefined && retry !== 0) {
         throw new Error('test-kit: `retry` must stay 0. A retry makes a broken test pass; raise a timeout instead.');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalystiq/test-kit",
-  "version": "0.1.0",
-  "description": "Shared test setup for Vitest and a fake MCP Apps host for jsdom and Playwright.",
+  "version": "0.3.0",
+  "description": "Shared test setup for Vitest, a fake MCP Apps host for jsdom and Playwright, the local Neon test-database run, and the local environment guard.",
   "type": "module",
   "license": "MIT",
   "sideEffects": true,
@@ -22,7 +22,8 @@
     },
     "./setup/config": {
       "types": "./dist/setup/config.d.ts",
-      "import": "./dist/setup/config.js"
+      "import": "./dist/setup/config.js",
+      "default": "./dist/setup/config.js"
     },
     "./setup/dom": {
       "types": "./dist/setup/dom.d.ts",
@@ -37,11 +38,22 @@
       "types": "./dist/mcp-apps-host/playwright.d.ts",
       "import": "./dist/mcp-apps-host/playwright.js"
     },
+    "./env": {
+      "types": "./dist/env/index.d.ts",
+      "import": "./dist/env/index.js"
+    },
+    "./neon-test-db": {
+      "types": "./dist/neon-test-db/neon-test-db.d.mts",
+      "import": "./dist/neon-test-db/neon-test-db.mjs"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
     "tk-check-bundle": "dist/bin/check-bundle.js",
-    "tk-check-allowlist": "dist/bin/check-allowlist.js"
+    "tk-check-allowlist": "dist/bin/check-allowlist.js",
+    "tk-dev-guard": "dist/bin/dev-guard.js",
+    "tk-check-env-example": "dist/bin/check-env-example.js",
+    "tk-neon-test-db": "dist/neon-test-db/neon-test-db.mjs"
   },
   "files": [
     "dist",
@@ -61,7 +73,8 @@
     "@playwright/test": ">=1.50",
     "@testing-library/jest-dom": ">=6",
     "@testing-library/react": ">=16",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "typescript": ">=5"
   },
   "peerDependenciesMeta": {
     "@playwright/test": {
@@ -75,6 +88,9 @@
     },
     "vitest": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "devDependencies": {