@catalystiq/test-kit 0.0.0-stage → 0.1.0

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,49 @@
+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. */
+export declare function defineTestKitConfig(options?: TestKitOptions, repo?: ViteUserConfig): ViteUserConfig;

package/dist/setup/config.js

@@ -0,0 +1,82 @@
+/**
+ * The shared Vitest defaults, for a repo's `vitest.config.ts`:
+ *
+ *     import { defineTestKitConfig } from '@catalystiq/test-kit/setup/config';
+ *     export default defineTestKitConfig(
+ *       { productionDatabaseHostsFile: 'db/production-hosts.json', keepEnv: ['TEST_DATABASE_URL'] },
+ *       { test: { setupFiles: ['./vitest.setup.ts'] } },
+ *     );
+ *
+ * Node environment (a DOM test asks for jsdom on its first line), 30 s test and hook timeouts, no retries, `server-only`
+ * aliased to an empty module, `*.pw.ts` (Playwright) excluded, and the kit's setup file FIRST, before the repo's own.
+ * This module runs in the main process: it reads the `.env*` files and the allow-lists once and hands the workers what
+ * they need through Vitest's `provide`.
+ */
+import { readFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mergeConfig } from 'vitest/config';
+import { readAllowList } from "./allow-list.js";
+import { protectedPlaces } from "./database.js";
+const EXT = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+/** The kit's worker setup file. */
+export const SETUP_FILE = fileURLToPath(new URL(`./setup-file${EXT}`, import.meta.url));
+/** The empty module `server-only` resolves to. */
+export const SERVER_ONLY_STUB = fileURLToPath(new URL(`./server-only-stub${EXT}`, import.meta.url));
+function readHostsFile(path) {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    const list = Array.isArray(value) ? value : value?.hosts;
+    if (!Array.isArray(list) || !list.every((h) => typeof h === 'string')) {
+        throw new Error(`test-kit: ${path} must be a JSON array of hosts, or { "hosts": [...] }`);
+    }
+    return list;
+}
+/** What the workers get, from the options. */
+export function provideFor(options = {}) {
+    const root = options.root ?? process.cwd();
+    const at = (path) => (isAbsolute(path) ? path : resolve(root, path));
+    const productionHosts = [
+        ...(options.productionDatabaseHosts ?? []),
+        ...(options.productionDatabaseHostsFile ? readHostsFile(at(options.productionDatabaseHostsFile)) : []),
+    ];
+    const allowList = options.reactWarningAllowList ? readAllowList(at(options.reactWarningAllowList)) : null;
+    return {
+        allowHosts: options.allowHosts ?? [],
+        allowDatabaseHosts: options.allowDatabaseHosts ?? true,
+        keepEnv: options.keepEnv ?? [],
+        stripEnv: options.stripEnv ?? [],
+        productionHosts,
+        protectedPlaces: protectedPlaces(root, options.testDatabaseEnv ?? []),
+        allowedWarnings: (allowList?.entries ?? []).map((e) => ({ pattern: e.pattern, ...(e.file ? { file: e.file } : {}) })),
+    };
+}
+/** The kit's part of a Vitest config. */
+export function testKitConfig(options = {}) {
+    return {
+        resolve: { alias: { 'server-only': SERVER_ONLY_STUB } },
+        test: {
+            environment: 'node',
+            testTimeout: 30_000,
+            hookTimeout: 30_000,
+            retry: 0,
+            include: ['**/*.test.{ts,tsx,mts,cts,js,jsx,mjs}'],
+            exclude: ['**/node_modules/**', '**/dist/**', '**/.git/**', '**/*.pw.ts'],
+            setupFiles: [SETUP_FILE],
+            provide: { testKit: provideFor(options) },
+        },
+    };
+}
+/** The kit's config merged with the repo's; refuses a retry, which hides a broken test. */
+export function defineTestKitConfig(options = {}, repo = {}) {
+    const merged = mergeConfig(testKitConfig(options), repo);
+    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.');
+    }
+    const setupFiles = merged.test?.setupFiles;
+    const list = Array.isArray(setupFiles) ? setupFiles : setupFiles ? [setupFiles] : [];
+    if (list[0] !== SETUP_FILE) {
+        throw new Error("test-kit: the kit's setup file must run first, before the repo's own setupFiles.");
+    }
+    return merged;
+}

package/dist/setup/credentials.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The credential strip. Every exported variable whose NAME says it holds a credential, and every variable whose VALUE
+ * is a URL carrying a password, is deleted before a test file runs. A hand-kept list of names drifts (the next vendor's
+ * variable is missing from it), so the rule is a pattern; a repo keeps what it needs by name (`keepEnv`) and sets its
+ * own placeholders after the kit's setup file.
+ */
+/** A variable whose name says it holds a credential. */
+export declare const CREDENTIAL_ENV_NAME: RegExp;
+/** Whether `value` is a URL with a password in it (`postgres://u:pw@host/db`, `redis://:pw@host`). */
+export declare function urlHasPassword(value: string | undefined): boolean;
+export interface StripOptions {
+    /** Names never deleted, whatever they hold (a test database URL, a fixture secret the repo sets itself). */
+    keep?: readonly string[];
+    /** Names deleted although the rule would keep them (`PGHOST`, `VERCEL_ENV`). */
+    extra?: readonly string[];
+}
+/** Whether the strip deletes this variable. */
+export declare function isStrippedVariable(name: string, value: string | undefined, options?: StripOptions): boolean;
+/** Deletes every stripped variable from `env` in place, and answers the names it deleted (never the values). */
+export declare function stripCredentials(env: NodeJS.ProcessEnv, options?: StripOptions): string[];

package/dist/setup/credentials.js

@@ -0,0 +1,38 @@
+/**
+ * The credential strip. Every exported variable whose NAME says it holds a credential, and every variable whose VALUE
+ * is a URL carrying a password, is deleted before a test file runs. A hand-kept list of names drifts (the next vendor's
+ * variable is missing from it), so the rule is a pattern; a repo keeps what it needs by name (`keepEnv`) and sets its
+ * own placeholders after the kit's setup file.
+ */
+/** A variable whose name says it holds a credential. */
+export const CREDENTIAL_ENV_NAME = /(KEY|TOKEN|SECRET|DSN|PASSWORD|PASSWD|CREDENTIAL|PRIVATE|WEBHOOK|COOKIE|SESSION|AUTH)/i;
+/** Whether `value` is a URL with a password in it (`postgres://u:pw@host/db`, `redis://:pw@host`). */
+export function urlHasPassword(value) {
+    if (!value || !value.includes('://'))
+        return false;
+    try {
+        return new URL(value).password !== '';
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether the strip deletes this variable. */
+export function isStrippedVariable(name, value, options = {}) {
+    if (options.keep?.includes(name))
+        return false;
+    if (options.extra?.includes(name))
+        return true;
+    return CREDENTIAL_ENV_NAME.test(name) || urlHasPassword(value);
+}
+/** Deletes every stripped variable from `env` in place, and answers the names it deleted (never the values). */
+export function stripCredentials(env, options = {}) {
+    const removed = [];
+    for (const name of Object.keys(env)) {
+        if (isStrippedVariable(name, env[name], options)) {
+            delete env[name];
+            removed.push(name);
+        }
+    }
+    return removed.sort();
+}

package/dist/setup/database.d.ts

@@ -0,0 +1,28 @@
+/** The endpoint id of a host whose first label is one (`ep-quiet-sun-123-pooler.region.example` → `ep-quiet-sun-123`). */
+export declare function endpointOf(host: string): string | null;
+/**
+ * The one database a URL names, as a comparable key: `endpoint:<id>` for an endpoint host, else
+ * `<host>:<port>/<database>` with every loopback name read as `localhost`. Null when the text is not a Postgres URL.
+ */
+export declare function databasePlace(url: string): string | null;
+/** Every Postgres URL in a text. */
+export declare function postgresUrlsIn(text: string): string[];
+/** The names of the `.env*` files at `root` (`.env`, `.env.local`, `.env.production`, …), sorted. */
+export declare function envFilesAt(root: string): string[];
+/**
+ * The places every `.env*` file at `root` names, but the lines whose key is in `testDatabaseEnv` (`KEY=…` or
+ * `export KEY=…`, with or without spaces).
+ */
+export declare function protectedPlaces(root: string, testDatabaseEnv?: readonly string[]): string[];
+/** Whether `host` is on the production list. */
+export declare function isProductionHost(host: string, productionHosts: readonly string[]): boolean;
+export interface DatabaseRules {
+    productionHosts: readonly string[];
+    protectedPlaces: readonly string[];
+}
+/** Throws when `url` names a production host or a database a `.env*` file names. The message never carries the URL. */
+export declare function assertSafeDatabaseUrl(url: string, rules: DatabaseRules, label?: string): void;
+/** Runs {@link assertSafeDatabaseUrl} over every Postgres URL any variable of `env` holds. */
+export declare function assertSafeDatabaseEnv(env: NodeJS.ProcessEnv, rules: DatabaseRules): void;
+/** The hosts of every Postgres URL `env` holds: what the network guard lets through once the URLs passed the check. */
+export declare function databaseHostsIn(env: NodeJS.ProcessEnv): string[];

package/dist/setup/database.js

@@ -0,0 +1,135 @@
+/**
+ * The production-database refusal. Two rules, both thrown before a test runs:
+ *
+ * 1. A database URL in the test environment whose host is on the repo's production list is refused. An entry matches the
+ *    host itself, any subdomain of it, and, for a host whose first label is a compute endpoint id (`ep-…`), that
+ *    endpoint with or without its `-pooler` suffix.
+ * 2. A database URL in the test environment that names the same database as any `.env*` file at the repo root is
+ *    refused: those files hold a developer's own (perhaps production) connection, and a test must never reach it. Every
+ *    `postgres://` text in the files counts, in any variable, quoted any way, or in a comment, except the lines whose key
+ *    the repo names as its test database (`testDatabaseEnv`).
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+/** A Postgres URL anywhere in a text. */
+const POSTGRES_URL = /postgres(?:ql)?:\/\/[^\s'"`]+/gi;
+/** The text's own punctuation after a URL is not part of it: `(postgres://h/db)` names `db`. */
+function trimmedUrl(match) {
+    return match.replace(/[)>,;.]+$/, '');
+}
+/** The endpoint id of a host whose first label is one (`ep-quiet-sun-123-pooler.region.example` → `ep-quiet-sun-123`). */
+export function endpointOf(host) {
+    const first = host.toLowerCase().split('.')[0] ?? '';
+    if (!first.startsWith('ep-'))
+        return null;
+    return first.endsWith('-pooler') ? first.slice(0, -'-pooler'.length) : first;
+}
+/**
+ * The one database a URL names, as a comparable key: `endpoint:<id>` for an endpoint host, else
+ * `<host>:<port>/<database>` with every loopback name read as `localhost`. Null when the text is not a Postgres URL.
+ */
+export function databasePlace(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:')
+        return null;
+    const host = parsed.hostname.toLowerCase();
+    const endpoint = endpointOf(host);
+    if (endpoint)
+        return `endpoint:${endpoint}`;
+    const database = decodeURIComponent(parsed.pathname.replace(/^\//, '')) || decodeURIComponent(parsed.username) || 'postgres';
+    return `${LOOPBACK.has(host) || host === '' ? 'localhost' : host}:${parsed.port || '5432'}/${database}`;
+}
+/** Every Postgres URL in a text. */
+export function postgresUrlsIn(text) {
+    return [...text.matchAll(POSTGRES_URL)].map((m) => trimmedUrl(m[0]));
+}
+/** The names of the `.env*` files at `root` (`.env`, `.env.local`, `.env.production`, …), sorted. */
+export function envFilesAt(root) {
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((name) => name === '.env' || name.startsWith('.env.'))
+        .sort();
+}
+/**
+ * The places every `.env*` file at `root` names, but the lines whose key is in `testDatabaseEnv` (`KEY=…` or
+ * `export KEY=…`, with or without spaces).
+ */
+export function protectedPlaces(root, testDatabaseEnv = []) {
+    const places = new Set();
+    for (const file of envFilesAt(root)) {
+        for (const line of readFileSync(join(root, file), 'utf8').split(/\r?\n/)) {
+            const key = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
+            if (key && testDatabaseEnv.includes(key))
+                continue;
+            for (const url of postgresUrlsIn(line)) {
+                const place = databasePlace(url);
+                if (place)
+                    places.add(place);
+            }
+        }
+    }
+    return [...places].sort();
+}
+/** Whether `host` is on the production list. */
+export function isProductionHost(host, productionHosts) {
+    const h = host.toLowerCase();
+    const endpoint = endpointOf(h);
+    return productionHosts.some((raw) => {
+        const entry = raw.trim().toLowerCase();
+        if (entry === '')
+            return false;
+        if (h === entry || h.endsWith(`.${entry}`))
+            return true;
+        return endpoint !== null && endpointOf(entry) === endpoint;
+    });
+}
+/** Throws when `url` names a production host or a database a `.env*` file names. The message never carries the URL. */
+export function assertSafeDatabaseUrl(url, rules, label = 'a database URL') {
+    const place = databasePlace(url);
+    if (place === null)
+        return;
+    const host = new URL(url).hostname;
+    if (isProductionHost(host, rules.productionHosts)) {
+        throw new Error(`test-kit: ${label} names a PRODUCTION database host (${host}). Tests never connect to production.`);
+    }
+    if (rules.protectedPlaces.includes(place)) {
+        throw new Error(`test-kit: ${label} names the same database as a .env* file at the repository root. ` +
+            'A test database must be its own (a container, or a branch made for the run).');
+    }
+}
+/** Runs {@link assertSafeDatabaseUrl} over every Postgres URL any variable of `env` holds. */
+export function assertSafeDatabaseEnv(env, rules) {
+    for (const [name, value] of Object.entries(env)) {
+        if (!value)
+            continue;
+        for (const url of postgresUrlsIn(value))
+            assertSafeDatabaseUrl(url, rules, `$${name}`);
+    }
+}
+/** The hosts of every Postgres URL `env` holds: what the network guard lets through once the URLs passed the check. */
+export function databaseHostsIn(env) {
+    const hosts = new Set();
+    for (const value of Object.values(env)) {
+        if (!value)
+            continue;
+        for (const url of postgresUrlsIn(value)) {
+            try {
+                const host = new URL(url).hostname;
+                if (host)
+                    hosts.add(host.toLowerCase());
+            }
+            catch {
+                // not a URL after all
+            }
+        }
+    }
+    return [...hosts];
+}

package/dist/setup/dom.d.ts

@@ -0,0 +1,16 @@
+/** jsdom has no `matchMedia`: a stub that matches nothing, as a desktop browser with no preference would answer. */
+export declare function installMatchMedia(): void;
+/**
+ * Node 26 defines `localStorage` / `sessionStorage` on `globalThis` as `undefined` (without `--localstorage-file`), and
+ * Vitest's jsdom environment then skips copying jsdom's real `Storage` over it. Re-binds jsdom's own objects. Inert on
+ * Node versions without the global and under the node environment.
+ */
+export declare function rebindStorage(): void;
+export interface DomOptions {
+    /** Unmount what Testing Library rendered after each test (it does so itself only under Vitest's globals). Default: true. */
+    cleanup?: boolean;
+    /** Load `@testing-library/jest-dom`'s matchers when it is installed. Default: true. */
+    jestDom?: boolean;
+}
+/** Everything a jsdom test file needs, for the file it is called in. */
+export declare function installDom(options?: DomOptions): Promise<void>;

package/dist/setup/dom.js

@@ -0,0 +1,71 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Helpers for a test file that runs under jsdom (`// @vitest-environment jsdom` on its first line). The kit's setup file
+ * calls {@link installDom} on its own whenever a `window` exists; a repo may call the pieces directly.
+ */
+import { afterEach } from 'vitest';
+/** jsdom has no `matchMedia`: a stub that matches nothing, as a desktop browser with no preference would answer. */
+export function installMatchMedia() {
+    if (typeof window === 'undefined' || typeof window.matchMedia === 'function')
+        return;
+    window.matchMedia = ((query) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addEventListener: () => { },
+        removeEventListener: () => { },
+        addListener: () => { },
+        removeListener: () => { },
+        dispatchEvent: () => false,
+    }));
+}
+/**
+ * Node 26 defines `localStorage` / `sessionStorage` on `globalThis` as `undefined` (without `--localstorage-file`), and
+ * Vitest's jsdom environment then skips copying jsdom's real `Storage` over it. Re-binds jsdom's own objects. Inert on
+ * Node versions without the global and under the node environment.
+ */
+export function rebindStorage() {
+    const g = globalThis;
+    const dom = g.jsdom?.window;
+    if (!dom)
+        return;
+    for (const key of ['localStorage', 'sessionStorage']) {
+        if (g[key] == null && dom[key] != null) {
+            Object.defineProperty(globalThis, key, { value: dom[key], configurable: true, writable: true });
+        }
+    }
+}
+async function optionalImport(specifier) {
+    try {
+        return (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ specifier)));
+    }
+    catch (error) {
+        const code = error.code;
+        const message = String(error.message ?? '');
+        if (code === 'ERR_MODULE_NOT_FOUND' || /Cannot find (?:module|package)|Failed to load url/.test(message))
+            return null;
+        throw error;
+    }
+}
+/** Everything a jsdom test file needs, for the file it is called in. */
+export async function installDom(options = {}) {
+    if (typeof window === 'undefined')
+        return;
+    installMatchMedia();
+    rebindStorage();
+    if (options.jestDom ?? true)
+        await optionalImport('@testing-library/jest-dom/vitest');
+    if (options.cleanup ?? true) {
+        const rtl = await optionalImport('@testing-library/react');
+        const cleanup = rtl?.cleanup;
+        if (typeof cleanup === 'function')
+            afterEach(() => cleanup());
+    }
+}

package/dist/setup/index.d.ts

@@ -0,0 +1,6 @@
+/** What a test file imports from the kit's setup part. */
+export { allowReactWarnings, isReactWarning, REACT_WARNING_PATTERNS } from './react-warnings.ts';
+export { allowNetworkHosts, hostAllowed, LOOPBACK_HOSTS } from './network.ts';
+export { assertSafeDatabaseUrl, databasePlace, endpointOf, isProductionHost, protectedPlaces, type DatabaseRules, } from './database.ts';
+export { CREDENTIAL_ENV_NAME, isStrippedVariable, stripCredentials, urlHasPassword } from './credentials.ts';
+export { allowListGrowth, parseAllowList, readAllowList, type AllowList, type AllowListEntry } from './allow-list.ts';

package/dist/setup/index.js

@@ -0,0 +1,6 @@
+/** What a test file imports from the kit's setup part. */
+export { allowReactWarnings, isReactWarning, REACT_WARNING_PATTERNS } from "./react-warnings.js";
+export { allowNetworkHosts, hostAllowed, LOOPBACK_HOSTS } from "./network.js";
+export { assertSafeDatabaseUrl, databasePlace, endpointOf, isProductionHost, protectedPlaces, } from "./database.js";
+export { CREDENTIAL_ENV_NAME, isStrippedVariable, stripCredentials, urlHasPassword } from "./credentials.js";
+export { allowListGrowth, parseAllowList, readAllowList } from "./allow-list.js";

package/dist/setup/network.d.ts

@@ -0,0 +1,11 @@
+export declare const LOOPBACK_HOSTS: readonly string[];
+/** Lower-cased, brackets off an IPv6 literal. */
+export declare function normalizeHost(host: string): string;
+/** Whether `host` is allowed: an exact entry, or a `*.example.test` entry matching a subdomain. */
+export declare function hostAllowed(host: string, permitted: Iterable<string>): boolean;
+/** Installs both guards once per process; a second call replaces the allow-list. */
+export declare function installNetworkGuard(allowHosts?: Iterable<string>): void;
+/** Adds hosts to the allow-list for the rest of the file (a database a test starts itself). */
+export declare function allowNetworkHosts(...hosts: string[]): void;
+/** The refusals since the last take, cleared. */
+export declare function takeNetworkViolations(): string[];

package/dist/setup/network.js

@@ -0,0 +1,109 @@
+/**
+ * The network guard. `fetch` and every TCP socket (`net.Socket.prototype.connect`, which `http`, `https`, `tls`,
+ * undici and database drivers all reach) are refused unless the host is on the allow-list. A refusal throws (or destroys
+ * the socket with an ECONNREFUSED-shaped error) AND is recorded, so code that swallows the error still fails the test.
+ * A unix socket always passes.
+ */
+import net from 'node:net';
+export const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0'];
+const STATE = Symbol.for('catalystiq.test-kit.network');
+function state() {
+    const g = globalThis;
+    g[STATE] ??= { permitted: new Set(LOOPBACK_HOSTS), violations: [] };
+    return g[STATE];
+}
+/** Lower-cased, brackets off an IPv6 literal. */
+export function normalizeHost(host) {
+    const lower = host.trim().toLowerCase();
+    return lower.startsWith('[') && lower.endsWith(']') ? lower.slice(1, -1) : lower;
+}
+/** Whether `host` is allowed: an exact entry, or a `*.example.test` entry matching a subdomain. */
+export function hostAllowed(host, permitted) {
+    const h = normalizeHost(host);
+    for (const entry of permitted) {
+        const e = normalizeHost(entry);
+        if (e === h)
+            return true;
+        if (e.startsWith('*.') && h.endsWith(e.slice(1)))
+            return true;
+    }
+    return false;
+}
+function requestUrl(input) {
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    if (input && typeof input === 'object' && 'url' in input)
+        return String(input.url);
+    return String(input);
+}
+function connectTarget(args) {
+    const [first, second] = args;
+    if (Array.isArray(first))
+        return connectTarget(first);
+    if (first && typeof first === 'object')
+        return first;
+    if (typeof first === 'string' && !/^\d+$/.test(first))
+        return { path: first };
+    return { port: first, host: typeof second === 'string' ? second : undefined };
+}
+/** Installs both guards once per process; a second call replaces the allow-list. */
+export function installNetworkGuard(allowHosts = []) {
+    const s = state();
+    s.permitted = new Set([...LOOPBACK_HOSTS, ...allowHosts].map(normalizeHost));
+    if (!s.realFetch && typeof globalThis.fetch === 'function') {
+        const realFetch = globalThis.fetch;
+        s.realFetch = realFetch;
+        const guardedFetch = (async (input, init) => {
+            const url = requestUrl(input);
+            let host = '';
+            try {
+                const parsed = new URL(url);
+                if (parsed.protocol === 'data:' || parsed.protocol === 'blob:')
+                    return (state().realFetch ?? realFetch)(input, init);
+                host = parsed.hostname;
+            }
+            catch {
+                host = '';
+            }
+            if (!hostAllowed(host, state().permitted)) {
+                state().violations.push(`fetch ${url}`);
+                throw new TypeError(`fetch failed: ${url} is outside the hosts this test may reach (test-kit network guard)`);
+            }
+            // Read from the state, so a test of the guard can stand an answer in for the real network.
+            return (state().realFetch ?? realFetch)(input, init);
+        });
+        globalThis.fetch = guardedFetch;
+    }
+    const prototype = net.Socket.prototype;
+    if (!s.realConnect) {
+        const realConnect = prototype.connect;
+        s.realConnect = realConnect;
+        prototype.connect = function guardedConnect(...args) {
+            const target = connectTarget(args);
+            if (typeof target.path === 'string')
+                return realConnect.apply(this, args);
+            const host = typeof target.host === 'string' && target.host !== '' ? target.host : 'localhost';
+            if (hostAllowed(host, state().permitted))
+                return realConnect.apply(this, args);
+            const where = `${host}:${String(target.port ?? '')}`;
+            state().violations.push(`socket ${where}`);
+            const refused = Object.assign(new Error(`connect ECONNREFUSED ${where}: outside the hosts this test may reach (test-kit network guard)`), { code: 'ECONNREFUSED' });
+            process.nextTick(() => this.destroy(refused));
+            return this;
+        };
+    }
+}
+/** Adds hosts to the allow-list for the rest of the file (a database a test starts itself). */
+export function allowNetworkHosts(...hosts) {
+    for (const host of hosts)
+        state().permitted.add(normalizeHost(host));
+}
+/** The refusals since the last take, cleared. */
+export function takeNetworkViolations() {
+    const s = state();
+    const list = [...s.violations];
+    s.violations.length = 0;
+    return list;
+}