@catalystiq/test-kit 0.2.0 → 0.3.0

package/README.md

@@ -1,16 +1,17 @@
 # @catalystiq/test-kit
 
-Shared test helpers: one package, added to part by part. Pin an exact version (`"@catalystiq/test-kit": "0.2.0"`);
+Shared test helpers: one package, added to part by part. Pin an exact version (`"@catalystiq/test-kit": "0.3.0"`);
 Dependabot raises it.
 
 | Part | Import | What |
 |---|---|---|
 | Setup | `@catalystiq/test-kit/setup/config`, `/setup`, `/setup/dom` | Vitest defaults and the safety setup: credentials stripped, network blocked, production and `.env*` databases refused, React warnings fail the test. (`dist/setup/README.md` in the package) |
+| Environment guard | `tk-dev-guard`, `tk-check-env-example`, `@catalystiq/test-kit/env` | A `predev` guard that refuses a production database and lists unset required variables, and a check that `.env.example` lists what the code reads. (`dist/env/README.md` in the package) |
 | Neon test database | `tk-neon-test-db` (bin), `@catalystiq/test-kit/neon-test-db` | `npm run test:db`: a short-lived schema-only Neon branch for one command, deleted afterwards; moved from github-actions' vendored `scripts/neon-test-db.mjs`. (`dist/neon-test-db/README.md` in the package) |
 | MCP Apps host | `@catalystiq/test-kit/mcp-apps-host`, `/mcp-apps-host/playwright` | A fake ChatGPT or Claude host for an MCP Apps card, in jsdom and in Playwright, and `tk-check-bundle`. (`dist/mcp-apps-host/README.md` in the package) |
 
 Vitest 4.1 and Node 22.18 or later. Every peer dependency is optional; install what the parts you use need (`vitest`,
-`@playwright/test`, `@testing-library/react`, `@testing-library/jest-dom`).
+`@playwright/test`, `@testing-library/react`, `@testing-library/jest-dom`; `typescript` for `tk-check-env-example`).
 
 ## Developing
 

package/dist/bin/check-env-example.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/check-env-example.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// tk-check-env-example [--example .env.example] [--exclude <path>]...: fails when .env.example and the code's
+// environment reads disagree. See src/env/scan.ts.
+import { optionValues, refuseUnknownOptions } from "../env/args.js";
+import { checkEnvExample } from "../env/scan.js";
+const USAGE = 'usage: tk-check-env-example [--example .env.example] [--exclude <path>]...';
+const args = process.argv.slice(2);
+try {
+    refuseUnknownOptions(args, ['--example', '--exclude'], USAGE);
+    const example = optionValues(args, '--example', USAGE).at(-1) ?? '.env.example';
+    const result = checkEnvExample(process.cwd(), example, optionValues(args, '--exclude', USAGE));
+    if (result.problems.length > 0) {
+        console.error(`tk-check-env-example: ${example} and the code disagree:\n  ${result.problems.join('\n  ')}`);
+        process.exitCode = 1;
+    }
+    else {
+        console.log(`ok   ${example} lists the ${result.read} variables ${result.files} code files read (${result.listed} listed)`);
+    }
+}
+catch (error) {
+    console.error(`tk-check-env-example: ${error.message}`);
+    process.exitCode = 1;
+}

package/dist/bin/dev-guard.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/dev-guard.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// tk-dev-guard --hosts <file> [--example .env.example]: run it as `predev`. See src/env/dev-guard.ts.
+import { runDevGuard } from "../env/dev-guard.js";
+const { code, lines } = runDevGuard(process.argv.slice(2), process.cwd());
+for (const line of lines)
+    (code === 0 ? console.log : console.error)(line);
+process.exitCode = code;

package/dist/env/README.md

@@ -0,0 +1,66 @@
+# The local environment guard: `tk-dev-guard` and `tk-check-env-example`
+
+Two CLIs for an app's own repository: a `predev` guard that refuses to start against production, and a check that keeps
+`.env.example` equal to the variables the code reads.
+
+## `.env.example`
+
+Every variable the app reads, one line each, no real values. The comment block above a variable (or a run of variables)
+says what it is for. Two words, in capitals, in that block mark it:
+
+- `REQUIRED`, opening a comment line (`# REQUIRED — …`): the app does not start without it; the guard fails while it
+  is unset.
+- `UNSCANNED`: the code reads it in a way the check cannot see (a name held in a list, a tool reading it itself).
+
+A line `# NAME=` lists a variable that is documented but not set by hand, such as `VERCEL_ENV`.
+
+```sh
+# REQUIRED. The app's Postgres string: a development branch of your own, never production.
+DATABASE_URL=
+
+# Set by Vercel on a deployment.
+# VERCEL_ENV=
+```
+
+Keep it out of `.gitignore`'s `.env*` with `!.env.example`.
+
+## `tk-dev-guard`
+
+```json
+"predev": "tk-dev-guard --hosts db/production-hosts.json"
+```
+
+It reads the environment `next dev` would see (the shell over `.env.development.local`, `.env.local`,
+`.env.development` and `.env`) and:
+
+- refuses to start when any variable (but the two that hold its own command line, `npm_lifecycle_script` and
+  `npm_package_scripts_predev`), or the `dev` script's own text, names a production database, file values expanded as
+  `next dev` expands them (`$NAME`, `${NAME:-default}`): a Postgres URL whose host is on the list, a compute
+  endpoint id on the list (`ep-…`, with or without `-pooler`, so `PGHOST`, `PGOPTIONS` and a URL's `options=endpoint…`
+  count too), or a host on the list. It names the variable and the list entry, never the value. `ALLOW_PROD_DB=1` in
+  the shell (never a `.env` file) turns the refusal into a warning, for a deliberate production operation;
+- fails while a `REQUIRED` variable of `.env.example` is unset, naming each, and counts the optional ones unset.
+
+The list is `--hosts <file>` (a JSON array, or `{ "hosts": [...] }`: test-kit's setup reads the same file), `--host
+<entry>` and `PRODUCTION_DATABASE_HOSTS` (comma-separated). An entry is a host or an endpoint id (a scheme, credentials, a port or a
+path are dropped); with no entry at all it fails: a guard with nothing to refuse is not one. `--example` names another file; `--allow-var NAME` skips a variable that holds a production id on purpose.
+
+## `tk-check-env-example`
+
+```sh
+tk-check-env-example [--example .env.example] [--exclude scripts/one-off]
+```
+
+Parses the tracked code (`git ls-files`, less tests, fixtures, `e2e/`, type declarations and each `--exclude` path) with
+TypeScript's parser (`typescript` is a peer dependency) for `process.env.NAME`, `process.env['NAME']`, `'NAME' in
+process.env`, `const { NAME } = process.env`, the same on `import.meta.env` (less Vite's own `DEV`, `MODE`, …) and on an
+object named `env` (capitals only), and fails
+when the code reads a name `.env.example` does not list, when `.env.example` lists one no code reads (unless `UNSCANNED`),
+on a name listed twice, and on a scan that found no code or no read. Run it from a test, so it cannot drift:
+
+```ts
+import { execFileSync } from 'node:child_process';
+it('.env.example lists what the code reads', () => {
+  execFileSync('node_modules/.bin/tk-check-env-example', [], { stdio: 'pipe' });
+});
+```

package/dist/env/args.d.ts

@@ -0,0 +1,5 @@
+/** The two bins' flag parsing: `--flag value`, repeatable, nothing else. */
+/** Every value given for `flag`. Throws on a flag with no value after it. */
+export declare function optionValues(args: readonly string[], flag: string, usage: string): string[];
+/** Throws on an argument that is neither one of `flags` nor the value after one. */
+export declare function refuseUnknownOptions(args: readonly string[], flags: readonly string[], usage: string): void;

package/dist/env/args.js

@@ -0,0 +1,20 @@
+/** The two bins' flag parsing: `--flag value`, repeatable, nothing else. */
+/** Every value given for `flag`. Throws on a flag with no value after it. */
+export function optionValues(args, flag, usage) {
+    const found = [];
+    args.forEach((arg, i) => {
+        if (arg !== flag)
+            return;
+        const next = args[i + 1];
+        if (next === undefined || next.startsWith('--'))
+            throw new Error(`${flag} needs a value\n${usage}`);
+        found.push(next);
+    });
+    return found;
+}
+/** Throws on an argument that is neither one of `flags` nor the value after one. */
+export function refuseUnknownOptions(args, flags, usage) {
+    const unknown = args.filter((a, i) => !flags.includes(a) && !flags.includes(args[i - 1] ?? ''));
+    if (unknown.length > 0)
+        throw new Error(`unknown argument ${unknown.join(', ')}\n${usage}`);
+}

package/dist/env/dev-guard.d.ts

@@ -0,0 +1,61 @@
+import { type ExampleEntry } from './example.ts';
+/** The files `next dev` loads, most precedent first (`NODE_ENV=test`: the test set, without `.env.local`). */
+export declare const DEV_ENV_FILES: readonly [".env.development.local", ".env.local", ".env.development", ".env"];
+export declare const TEST_ENV_FILES: readonly [".env.test.local", ".env.test", ".env"];
+export interface DevEnv {
+    /** The environment the app would run with. */
+    env: Record<string, string>;
+    /**
+     * Every value the guard checks, beyond `env`: each file's own values as written and expanded two ways, so a
+     * production string the expansion rules would hide (or a file `env` overrode) is still seen.
+     */
+    alsoChecked: Array<[string, string]>;
+    /** The files that existed and were read, most precedent first. */
+    files: string[];
+    /** Whether `env` came from Next's own loader (`@next/env`, resolved from the root). */
+    fromNext: boolean;
+}
+/**
+ * The environment `next dev` would run with at `root`. In the real process (`base` is `process.env`) with `next`
+ * installed, that is Next's own loader, so its file set, `KEY: value` lines and expansion rules are exactly the app's.
+ * Otherwise the shell over the files, file values expanded. Either way every file's values are also checked as written
+ * and expanded against the shell alone and against the shell and the files (`alsoChecked`): a guard errs on refusing.
+ */
+export declare function loadDevEnv(root: string, base?: NodeJS.ProcessEnv): DevEnv;
+/**
+ * The production list entry a value names, or null. One pass over every host-shaped token of the value, as written and
+ * percent-decoded, so every connection-string shape counts: a URL (one host or several), a keyword/value string
+ * (`host=… dbname=…`), `PGHOST` (with a port), `PGOPTIONS endpoint=…`, a URL's `options=endpoint%3D…`.
+ */
+export declare function productionEntryIn(value: string, productionHosts: readonly string[]): string | null;
+/**
+ * A list entry as the host it names: a URL (`postgres://u:p@db.prod.example:5432/app`) is read as one, and a host
+ * loses a port, a path and a leading dot. An entry that names no host throws, naming where it came from but not the
+ * entry itself (it may be a whole connection string).
+ */
+export declare function productionHostEntry(entry: string, source?: string): string;
+export interface ProductionHit {
+    variable: string;
+    entry: string;
+}
+/**
+ * Every variable that names a production database, once each, by name: the variables of `env`, and the extra
+ * `[name, value]` pairs. The two variables that hold the guard's own command line are left out.
+ */
+export declare function productionHits(env: Record<string, string | undefined>, productionHosts: readonly string[], allowVariables?: readonly string[], alsoChecked?: ReadonlyArray<readonly [string, string]>): ProductionHit[];
+/** The variables of `.env.example` that are unset or blank, required and optional (documented ones, `# NAME=`, left out). */
+export declare function unsetEntries(entries: readonly ExampleEntry[], env: Record<string, string | undefined>): {
+    required: string[];
+    optional: string[];
+};
+/** A production list file: a JSON array of hosts, or `{ "hosts": [...] }` (other keys, such as `_comment`, ignored). */
+export declare function readProductionHostsFile(path: string): string[];
+export interface DevGuardResult {
+    code: 0 | 1;
+    lines: string[];
+}
+/**
+ * The whole guard, as a function: `tk-dev-guard` prints its lines and exits with its code. `ALLOW_PROD_DB=1` is read
+ * from the shell alone (`base`): a line in a `.env` file would make the override permanent.
+ */
+export declare function runDevGuard(args: readonly string[], root: string, base?: NodeJS.ProcessEnv): DevGuardResult;

package/dist/env/dev-guard.js

@@ -0,0 +1,254 @@
+/**
+ * The local guard `npm run dev` runs first (`tk-dev-guard`): it refuses an environment that names a production database
+ * and lists the required variables (`.env.example`, `REQUIRED`) that are unset.
+ *
+ * The environment is the one `next dev` would see: the process's own variables, over `.env.development.local`,
+ * `.env.local`, `.env.development` and `.env` at the root (Next's own loader when `next` is installed), and every file
+ * value is also checked as written. Every variable is checked (but npm's command-line ones), not
+ * one named database variable: a value names production when any host-shaped token in it is on the production list (a
+ * host or a subdomain of it, or a compute endpoint id `ep-…`, pooled or not), so a URL, a keyword/value string,
+ * `PGHOST`, `PGOPTIONS endpoint=…` and a URL's `options=endpoint%3D…` all count. A refusal names the variable and the
+ * matched list entry, never the value.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { parseEnv } from 'node:util';
+import { isProductionHost } from "../setup/database.js";
+import { optionValues, refuseUnknownOptions } from "./args.js";
+import { parseEnvExample } from "./example.js";
+/** The files `next dev` loads, most precedent first (`NODE_ENV=test`: the test set, without `.env.local`). */
+export const DEV_ENV_FILES = ['.env.development.local', '.env.local', '.env.development', '.env'];
+export const TEST_ENV_FILES = ['.env.test.local', '.env.test', '.env'];
+const MAX_EXPANDED_LENGTH = 64 * 1024;
+const REFERENCE = /(\\)?\$(?:\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}|([A-Za-z_][A-Za-z0-9_]*))/g;
+/** `$NAME`, `${NAME}` and `${NAME:-default}` against `lookup`; `\$` stays a dollar sign. */
+function expand(value, lookup, expanding = new Set()) {
+    const out = value.replace(REFERENCE, (match, escaped, braced, fallback, bare) => {
+        if (escaped)
+            return match.slice(1);
+        const name = (braced ?? bare);
+        // A name already being expanded (`A=$A`) expands to nothing, as a cycle.
+        if (expanding.has(name))
+            return '';
+        const found = lookup(name);
+        return expand(found ? found : (fallback ?? ''), lookup, new Set([...expanding, name]));
+    });
+    return out.length > MAX_EXPANDED_LENGTH ? out.slice(0, MAX_EXPANDED_LENGTH) : out;
+}
+/** A `.env` file's variables; dotenv's `KEY: value` lines, which `next dev` reads too, as `KEY=value`. */
+function parseEnvFile(text) {
+    return parseEnv(text.replace(/^(\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_.-]*):[ \t]+/gm, '$1='));
+}
+/** Next's own loader, from the root's dependencies, or null. */
+function nextEnvAt(root) {
+    try {
+        const loaded = createRequire(resolve(root, 'package.json'))('@next/env');
+        return typeof loaded.loadEnvConfig === 'function' ? loaded : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The environment `next dev` would run with at `root`. In the real process (`base` is `process.env`) with `next`
+ * installed, that is Next's own loader, so its file set, `KEY: value` lines and expansion rules are exactly the app's.
+ * Otherwise the shell over the files, file values expanded. Either way every file's values are also checked as written
+ * and expanded against the shell alone and against the shell and the files (`alsoChecked`): a guard errs on refusing.
+ */
+export function loadDevEnv(root, base = process.env) {
+    const fileSet = base.NODE_ENV === 'test' ? TEST_ENV_FILES : DEV_ENV_FILES;
+    const fromFiles = {};
+    const files = [];
+    const perFile = [];
+    for (const file of [...fileSet].reverse()) {
+        const path = resolve(root, file);
+        // A file (or a pipe), as Next reads: a `.env/` directory is a Python virtualenv, not variables.
+        const kind = existsSync(path) ? statSync(path) : null;
+        if (!kind || !(kind.isFile() || kind.isFIFO()))
+            continue;
+        const parsed = parseEnvFile(readFileSync(path, 'utf8'));
+        perFile.push(parsed);
+        Object.assign(fromFiles, parsed);
+        files.unshift(file);
+    }
+    const alsoChecked = [];
+    const shellOnly = (name) => base[name] || undefined;
+    const shellThenFiles = (name) => base[name] || fromFiles[name];
+    for (const parsed of perFile) {
+        for (const [name, value] of Object.entries(parsed)) {
+            alsoChecked.push([name, value], [name, expand(value, shellOnly)], [name, expand(value, shellThenFiles)]);
+        }
+    }
+    const next = base === process.env ? nextEnvAt(root) : null;
+    if (next) {
+        const quiet = { info: () => undefined, error: () => undefined };
+        const loaded = next.loadEnvConfig(root, true, quiet, true);
+        const env = {};
+        for (const [name, value] of Object.entries(loaded.combinedEnv))
+            if (value !== undefined)
+                env[name] = value;
+        return { env, alsoChecked, files: loaded.loadedEnvFiles.map((f) => f.path), fromNext: true };
+    }
+    const env = {};
+    for (const [name, value] of Object.entries(fromFiles))
+        env[name] = expand(value, shellThenFiles);
+    for (const [name, value] of Object.entries(base))
+        if (value !== undefined)
+            env[name] = value;
+    return { env, alsoChecked, files, fromNext: false };
+}
+/** A host-shaped run of a value: labels of letters, digits and `-`, joined by dots (`ep-…-pooler.c-1.example`, `ep-…`). */
+const HOST_TOKEN = /[a-z0-9-]+(?:\.[a-z0-9-]+)*/gi;
+/** The value with each `%XX` escape decoded on its own, so one malformed `%` elsewhere cannot hide the rest. */
+function decoded(value) {
+    return value.replace(/%([0-9a-f]{2})/gi, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+}
+/**
+ * The production list entry a value names, or null. One pass over every host-shaped token of the value, as written and
+ * percent-decoded, so every connection-string shape counts: a URL (one host or several), a keyword/value string
+ * (`host=… dbname=…`), `PGHOST` (with a port), `PGOPTIONS endpoint=…`, a URL's `options=endpoint%3D…`.
+ */
+export function productionEntryIn(value, productionHosts) {
+    for (const text of new Set([value, decoded(value)])) {
+        for (const token of text.matchAll(HOST_TOKEN)) {
+            const entry = productionHosts.find((e) => isProductionHost(token[0], [e]));
+            if (entry)
+                return entry.trim();
+        }
+    }
+    return null;
+}
+/**
+ * A list entry as the host it names: a URL (`postgres://u:p@db.prod.example:5432/app`) is read as one, and a host
+ * loses a port, a path and a leading dot. An entry that names no host throws, naming where it came from but not the
+ * entry itself (it may be a whole connection string).
+ */
+export function productionHostEntry(entry, source = 'the production list') {
+    let host = entry.trim().toLowerCase();
+    if (host.includes('://')) {
+        try {
+            host = new URL(host).hostname;
+        }
+        catch {
+            host = '';
+        }
+    }
+    host = host.replace(/[/?#].*$/, '').replace(/:\d*$/, '').replace(/^\.+/, '');
+    if (!/^[a-z0-9-]+(?:\.[a-z0-9-]+)*$/.test(host)) {
+        throw new Error(`an entry of ${source} names no host (an entry is a host or an ep-… endpoint id)`);
+    }
+    return host;
+}
+/**
+ * The two variables that hold the guard's own command line (its `--host ep-…`): npm's `npm_lifecycle_script` and
+ * yarn's `npm_package_scripts_predev`. Every other `npm_*` variable is checked, and so is the `dev` script itself.
+ */
+const GUARD_COMMAND_LINE = /^npm_(?:lifecycle_script|package_scripts_predev)$/i;
+/**
+ * Every variable that names a production database, once each, by name: the variables of `env`, and the extra
+ * `[name, value]` pairs. The two variables that hold the guard's own command line are left out.
+ */
+export function productionHits(env, productionHosts, allowVariables = [], alsoChecked = []) {
+    const hits = new Map();
+    for (const [variable, value] of [...Object.entries(env), ...alsoChecked]) {
+        if (!value || hits.has(variable) || allowVariables.includes(variable) || GUARD_COMMAND_LINE.test(variable))
+            continue;
+        const entry = productionEntryIn(value, productionHosts);
+        if (entry)
+            hits.set(variable, entry);
+    }
+    return [...hits].sort(([a], [b]) => a.localeCompare(b)).map(([variable, entry]) => ({ variable, entry }));
+}
+/** The variables of `.env.example` that are unset or blank, required and optional (documented ones, `# NAME=`, left out). */
+export function unsetEntries(entries, env) {
+    const unset = entries.filter((e) => !e.commented && !env[e.name]?.trim());
+    const names = (list) => [...new Set(list.map((e) => e.name))].sort();
+    return { required: names(unset.filter((e) => e.required)), optional: names(unset.filter((e) => !e.required)) };
+}
+/** A production list file: a JSON array of hosts, or `{ "hosts": [...] }` (other keys, such as `_comment`, ignored). */
+export function readProductionHostsFile(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(`${path} must be a JSON array of hosts, or { "hosts": [...] }`);
+    }
+    return list;
+}
+/** `vercel env pull` of the production environment. */
+const PULLS_PRODUCTION = /\bvercel\s+env\s+pull\b[^&|;]*(?:--environment[= ]+prod(?:uction)?\b|--prod\b)/i;
+/** The `dev` script of the root's package.json, which runs after the guard and may set variables itself, or null. */
+function devScriptOf(root) {
+    try {
+        const scripts = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')).scripts;
+        return typeof scripts?.dev === 'string' ? scripts.dev : null;
+    }
+    catch {
+        return null;
+    }
+}
+const USAGE = 'usage: tk-dev-guard --hosts <production-hosts.json> [--host <host>] [--example .env.example] [--allow-var NAME]';
+const FLAGS = ['--hosts', '--host', '--example', '--allow-var'];
+/**
+ * The whole guard, as a function: `tk-dev-guard` prints its lines and exits with its code. `ALLOW_PROD_DB=1` is read
+ * from the shell alone (`base`): a line in a `.env` file would make the override permanent.
+ */
+export function runDevGuard(args, root, base = process.env) {
+    const lines = [];
+    // Read before the files are loaded: Next's loader writes them into process.env, which may be `base`.
+    const allowProduction = base.ALLOW_PROD_DB === '1';
+    try {
+        refuseUnknownOptions(args, FLAGS, USAGE);
+        const examplePath = optionValues(args, '--example', USAGE).at(-1) ?? '.env.example';
+        const { env, alsoChecked, files } = loadDevEnv(root, base);
+        const fromEnv = (env.PRODUCTION_DATABASE_HOSTS ?? '').split(',');
+        const listed = [
+            ...optionValues(args, '--hosts', USAGE).flatMap((f) => readProductionHostsFile(resolve(root, f)).map((h) => [h, `--hosts ${f}`])),
+            ...optionValues(args, '--host', USAGE).map((h) => [h, '--host']),
+            ...fromEnv.map((h) => [h, 'PRODUCTION_DATABASE_HOSTS']),
+        ];
+        const hosts = listed.filter(([h]) => h.trim() !== '').map(([h, source]) => productionHostEntry(h, source));
+        if (hosts.length === 0)
+            throw new Error(`no production database host to refuse: pass --hosts or --host\n${USAGE}`);
+        const allow = ['PRODUCTION_DATABASE_HOSTS', ...optionValues(args, '--allow-var', USAGE)];
+        const source = files.length > 0 ? files.join(', ') : 'no .env file';
+        let failed = false;
+        const devScript = devScriptOf(root);
+        const hits = productionHits(env, hosts, allow, devScript === null ? alsoChecked : [...alsoChecked, ['package.json scripts.dev', devScript]]);
+        if (devScript !== null && PULLS_PRODUCTION.test(devScript) && !allowProduction) {
+            failed = true;
+            lines.push('tk-dev-guard: refusing to start: the dev script pulls the PRODUCTION environment (vercel env pull --environment=production).');
+        }
+        if (hits.length > 0 && allowProduction) {
+            lines.push(`tk-dev-guard: WARNING ALLOW_PROD_DB=1: running against PRODUCTION (${hits.map((h) => h.variable).join(', ')}).`);
+        }
+        else if (hits.length > 0) {
+            failed = true;
+            lines.push('tk-dev-guard: refusing to start: the environment names a PRODUCTION database.', ...hits.map((h) => `  ${h.variable} names ${h.entry}`), `  Read from: the shell and ${source}.`, '  Point it at a development or test branch of your own. Never pull production variables onto a laptop.', '  Override, only for a deliberate production operation, in the shell: ALLOW_PROD_DB=1 npm run dev.');
+        }
+        let exampleText = null;
+        try {
+            exampleText = readFileSync(resolve(root, examplePath), 'utf8');
+        }
+        catch {
+            failed = true;
+            lines.push(`tk-dev-guard: ${examplePath} could not be read, so the required variables are unknown.`);
+        }
+        if (exampleText !== null) {
+            const entries = parseEnvExample(exampleText);
+            const { required: missing, optional } = unsetEntries(entries, env);
+            if (missing.length > 0) {
+                failed = true;
+                lines.push(`tk-dev-guard: required variables unset (see ${examplePath}):`, ...missing.map((name) => `  ${name}`));
+            }
+            if (optional.length > 0)
+                lines.push(`tk-dev-guard: ${optional.length} optional variables unset; the features that need them are off (${examplePath}).`);
+        }
+        if (!failed)
+            lines.push(`tk-dev-guard: ok: no production database (${hosts.length} refused), required variables set. Read from: the shell and ${source}.`);
+        return { code: failed ? 1 : 0, lines };
+    }
+    catch (error) {
+        return { code: 1, lines: [...lines, `tk-dev-guard: ${error.message}`] };
+    }
+}

package/dist/env/example.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Reading a repository's `.env.example`: which variables it names, which the app needs to start, and which the code
+ * reads in a way a scan cannot see.
+ *
+ * A variable is a line `NAME=…` (or `export NAME=…`). A line `# NAME=…` (one space at most after the `#`) names one
+ * too, documented but not to be set by hand (one the platform sets, such as `VERCEL_ENV`). Consecutive variable lines
+ * share the comment block above the first of them; a blank line ends a block. Two words in a block, in capitals, mark
+ * its variables:
+ *
+ * - `REQUIRED`, opening a comment line (`# REQUIRED — …`): the app does not start without it. `tk-dev-guard` lists a required variable that is unset and fails.
+ * - `UNSCANNED`: the code reads it in a way `tk-check-env-example` cannot see (a name held in a list, a tool reading it
+ *   on its own), so the check does not call it unread.
+ */
+export interface ExampleEntry {
+    name: string;
+    /** 1-based line number in the file. */
+    line: number;
+    /** `# NAME=`: documented, not set by hand. */
+    commented: boolean;
+    required: boolean;
+    unscanned: boolean;
+}
+export declare function parseEnvExample(text: string): ExampleEntry[];
+/** The names the file lists more than once. */
+export declare function duplicateNames(entries: readonly ExampleEntry[]): string[];

package/dist/env/example.js

@@ -0,0 +1,77 @@
+/**
+ * Reading a repository's `.env.example`: which variables it names, which the app needs to start, and which the code
+ * reads in a way a scan cannot see.
+ *
+ * A variable is a line `NAME=…` (or `export NAME=…`). A line `# NAME=…` (one space at most after the `#`) names one
+ * too, documented but not to be set by hand (one the platform sets, such as `VERCEL_ENV`). Consecutive variable lines
+ * share the comment block above the first of them; a blank line ends a block. Two words in a block, in capitals, mark
+ * its variables:
+ *
+ * - `REQUIRED`, opening a comment line (`# REQUIRED — …`): the app does not start without it. `tk-dev-guard` lists a required variable that is unset and fails.
+ * - `UNSCANNED`: the code reads it in a way `tk-check-env-example` cannot see (a name held in a list, a tool reading it
+ *   on its own), so the check does not call it unread.
+ */
+/**
+ * `NAME=` / `export NAME=`, or, commented, `# NAME=` with at most one space after the `#` and none before the `=`: a
+ * prose line (`# REQUIRED  = …`) or an indented command in a comment (`#     NAME=dev/you`) is not a variable. A set
+ * variable may be in any case (`Api_Key=`), as the code may read one; a commented one is in capitals.
+ */
+const VARIABLE = /^\s*(?:(#)[ \t]?(?:export\s+)?([A-Z][A-Z0-9_]*)=|(?:export\s+)?([A-Za-z][A-Za-z0-9_]*)\s*=)/;
+export function parseEnvExample(text) {
+    const entries = [];
+    let block = [];
+    let afterVariable = false;
+    /** The quote a multi-line value opened and has not closed yet: its lines are the value, not variables. */
+    let openQuote = null;
+    text.split(/\r?\n/).forEach((raw, index) => {
+        if (openQuote !== null) {
+            if (raw.includes(openQuote))
+                openQuote = null;
+            return;
+        }
+        const line = raw.trim();
+        if (line === '') {
+            block = [];
+            afterVariable = false;
+            return;
+        }
+        const variable = VARIABLE.exec(raw);
+        if (variable) {
+            const text = block.join('\n');
+            entries.push({
+                name: (variable[2] ?? variable[3]),
+                line: index + 1,
+                commented: variable[1] !== undefined,
+                required: /^#\s*REQUIRED\b/m.test(text),
+                unscanned: /\bUNSCANNED\b/.test(text),
+            });
+            afterVariable = true;
+            if (variable[1] === undefined) {
+                const value = raw.slice(raw.indexOf('=') + 1).trim();
+                const quote = value[0];
+                if ((quote === '"' || quote === "'" || quote === '`') && !value.slice(1).includes(quote))
+                    openQuote = quote;
+            }
+            return;
+        }
+        if (line.startsWith('#')) {
+            if (afterVariable)
+                block = [];
+            afterVariable = false;
+            block.push(line);
+            return;
+        }
+        // Any other line (a stray value) ends the block.
+        block = [];
+        afterVariable = false;
+    });
+    return entries;
+}
+/** The names the file lists more than once. */
+export function duplicateNames(entries) {
+    const seen = new Set();
+    const twice = new Set();
+    for (const e of entries)
+        (seen.has(e.name) ? twice : seen).add(e.name);
+    return [...twice].sort();
+}

package/dist/env/index.d.ts

@@ -0,0 +1,3 @@
+export { parseEnvExample, duplicateNames, type ExampleEntry } from './example.ts';
+export { envNamesInText, stringConstants, isScannedPath, scannedFiles, envReads, checkEnvExample, type EnvExampleCheck } from './scan.ts';
+export { DEV_ENV_FILES, loadDevEnv, productionEntryIn, productionHits, unsetEntries, productionHostEntry, readProductionHostsFile, runDevGuard, type DevEnv, type ProductionHit, type DevGuardResult, } from './dev-guard.ts';

package/dist/env/index.js

@@ -0,0 +1,3 @@
+export { parseEnvExample, duplicateNames } from "./example.js";
+export { envNamesInText, stringConstants, isScannedPath, scannedFiles, envReads, checkEnvExample } from "./scan.js";
+export { DEV_ENV_FILES, loadDevEnv, productionEntryIn, productionHits, unsetEntries, productionHostEntry, readProductionHostsFile, runDevGuard, } from "./dev-guard.js";

package/dist/env/scan.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The variable names a source text reads, from its syntax tree (TypeScript's parser): comments, strings and regular
+ * expressions are never mistaken for code.
+ *
+ * A key may be a literal or a top-level string constant (`env[GOOGLE_CLIENT_ID_ENV]`), this file's or one in
+ * `constants` (the repository's, {@link stringConstants}).
+ *
+ * The environment is `process.env` (also `globalThis.process.env`, `process['env']`), `import.meta.env` (less Vite's
+ * own `DEV`, `MODE`, …), a name the file binds to one of those (`const e = process.env`), and any object named `env`
+ * (capitals only: `env.local` is not a variable; a file whose `env` is something else goes in `--exclude`). A read off
+ * it is a property (`.NAME`, `?.NAME`), an element with a literal key (`['NAME']`), an `in` test (`'NAME' in …`), or a
+ * destructuring (`const { NAME, OTHER: x }: T = …`, a parameter default, an assignment `({ NAME } = …)`). A method call
+ * (`process.env.toString()`) and a write (`process.env.TZ = …`, `delete process.env.X`) are not reads; a presence check
+ * (`Object.hasOwn(process.env, 'X')`, `Reflect.has(…)`, `.hasOwnProperty('X')`) is. `const { env: e } = process` makes
+ * `e` an alias.
+ */
+export declare function envNamesInText(source: string, fileName?: string, constants?: ReadonlyMap<string, string>): string[];
+/**
+ * The repository's top-level string constants, by name, so a read through a constant another file exports
+ * (`process.env[SECRET_ENV]`) is seen. A name two files define with different text resolves to nothing.
+ */
+export declare function stringConstants(texts: ReadonlyArray<readonly [file: string, text: string]>): Map<string, string>;
+/** Whether a repository-relative path is code the scan reads. */
+export declare function isScannedPath(path: string, exclude?: readonly string[]): boolean;
+/** The code files of the repository at `root`: tracked, or new and not ignored. */
+export declare function scannedFiles(root: string, exclude?: readonly string[]): string[];
+/** Each name read, with the first file that reads it. */
+export declare function envReads(root: string, files: readonly string[]): Map<string, string>;
+export interface EnvExampleCheck {
+    problems: string[];
+    files: number;
+    read: number;
+    listed: number;
+}
+/** Compares `.env.example` with what the code reads. Every problem names variables, never a value. */
+export declare function checkEnvExample(root: string, example: string, exclude?: readonly string[]): EnvExampleCheck;

package/dist/env/scan.js

@@ -0,0 +1,327 @@
+/**
+ * Which environment variables a repository's code reads, by name, and whether `.env.example` lists exactly those.
+ *
+ * The reads come from each file's syntax tree (see {@link envNamesInText}). A name built at run time
+ * (`process.env[name]`) is not seen: list it in `.env.example` under a comment saying `UNSCANNED`.
+ *
+ * The files are the repository's tracked code (`git ls-files`), less tests, fixtures, type declarations and the paths
+ * the caller excludes. Needs `typescript` installed (a peer dependency).
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { duplicateNames, parseEnvExample } from "./example.js";
+const CAPITALS = /^[A-Z][A-Z0-9_]*$/;
+const CODE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
+const SKIP_SEGMENTS = new Set(['node_modules', '__tests__', '__mocks__', 'fixtures', '.next', 'dist', 'coverage']);
+/** Test trees at the top of the repository only: `src/app/test/page.tsx` is a route. */
+const SKIP_TOP = new Set(['test', 'tests', 'e2e']);
+const SKIP_FILE = /\.(?:test|spec)\.[^/]+$|\.pw\.ts$|\.d\.ts$/;
+/** npm's own variables and a runtime's internals (`__NEXT_…`) are not the app's to list. */
+const NOT_THE_APPS = /^(?:npm_|_)/;
+/** What Vite itself puts on `import.meta.env`. */
+const VITE_BUILT_INS = new Set(['BASE_URL', 'DEV', 'MODE', 'PROD', 'SSR']);
+/** TypeScript, loaded on first use, so `/env` imports (the guard) work where it is not installed. */
+let tsModule = null;
+function typescript() {
+    if (tsModule === null) {
+        try {
+            tsModule = createRequire(import.meta.url)('typescript');
+        }
+        catch {
+            throw new Error('tk-check-env-example needs typescript installed (a peer dependency of @catalystiq/test-kit)');
+        }
+    }
+    return tsModule;
+}
+/** Whether `name`, read off that object, is an environment variable. A bare `env` object counts in capitals only. */
+function isVariable(kind, name) {
+    if (NOT_THE_APPS.test(name))
+        return false;
+    if (kind === 'bare')
+        return CAPITALS.test(name);
+    if (kind === 'meta')
+        return !VITE_BUILT_INS.has(name);
+    return true;
+}
+function scriptKind(ts, fileName) {
+    if (/\.tsx$/.test(fileName))
+        return ts.ScriptKind.TSX;
+    if (/\.[mc]?ts$/.test(fileName))
+        return ts.ScriptKind.TS;
+    return ts.ScriptKind.JSX;
+}
+/**
+ * The variable names a source text reads, from its syntax tree (TypeScript's parser): comments, strings and regular
+ * expressions are never mistaken for code.
+ *
+ * A key may be a literal or a top-level string constant (`env[GOOGLE_CLIENT_ID_ENV]`), this file's or one in
+ * `constants` (the repository's, {@link stringConstants}).
+ *
+ * The environment is `process.env` (also `globalThis.process.env`, `process['env']`), `import.meta.env` (less Vite's
+ * own `DEV`, `MODE`, …), a name the file binds to one of those (`const e = process.env`), and any object named `env`
+ * (capitals only: `env.local` is not a variable; a file whose `env` is something else goes in `--exclude`). A read off
+ * it is a property (`.NAME`, `?.NAME`), an element with a literal key (`['NAME']`), an `in` test (`'NAME' in …`), or a
+ * destructuring (`const { NAME, OTHER: x }: T = …`, a parameter default, an assignment `({ NAME } = …)`). A method call
+ * (`process.env.toString()`) and a write (`process.env.TZ = …`, `delete process.env.X`) are not reads; a presence check
+ * (`Object.hasOwn(process.env, 'X')`, `Reflect.has(…)`, `.hasOwnProperty('X')`) is. `const { env: e } = process` makes
+ * `e` an alias.
+ */
+export function envNamesInText(source, fileName = 'file.ts', constants = new Map()) {
+    const ts = typescript();
+    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKind(ts, fileName));
+    const own = topLevelStrings(ts, file);
+    const aliases = new Map();
+    const unwrapped = (node) => {
+        let n = node;
+        while (ts.isParenthesizedExpression(n) || ts.isNonNullExpression(n) || ts.isAsExpression(n) || ts.isSatisfiesExpression(n))
+            n = n.expression;
+        return n;
+    };
+    const literal = (node) => node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : undefined;
+    /** `process`, or `globalThis.process`. */
+    const isProcess = (node) => {
+        const n = unwrapped(node);
+        if (ts.isIdentifier(n))
+            return n.text === 'process';
+        return ts.isPropertyAccessExpression(n) && n.name.text === 'process' && ts.isIdentifier(n.expression) && n.expression.text === 'globalThis';
+    };
+    const envObject = (node) => {
+        const n = unwrapped(node);
+        if (ts.isIdentifier(n))
+            return aliases.get(n.text) ?? (n.text === 'env' ? 'bare' : null);
+        const key = ts.isPropertyAccessExpression(n) ? n.name.text : ts.isElementAccessExpression(n) ? literal(n.argumentExpression) : undefined;
+        if (key !== 'env' || !(ts.isPropertyAccessExpression(n) || ts.isElementAccessExpression(n)))
+            return null;
+        const owner = n.expression;
+        if (isProcess(owner))
+            return 'process';
+        if (ts.isMetaProperty(owner) && owner.keywordToken === ts.SyntaxKind.ImportKeyword && owner.name.text === 'meta')
+            return 'meta';
+        return null;
+    };
+    /** A method call on the object, an assignment to it, or a `delete` of it. */
+    const isNotARead = (node) => {
+        const parent = node.parent;
+        if (ts.isCallExpression(parent) && parent.expression === node)
+            return true;
+        if (ts.isDeleteExpression(parent))
+            return true;
+        // Only a plain `=` writes without reading: `??=`, `||=` and `+=` read the variable first.
+        return ts.isBinaryExpression(parent) && parent.left === node && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+    };
+    // Aliases first: `const e = process.env` makes `e.NAME` a read, for a name the file declares only once (there is no
+    // scope analysis, so a name declared twice, once as the environment and once as something else, is no alias).
+    const declared = new Map();
+    const candidates = new Map();
+    const collectAliases = (node) => {
+        if ((ts.isVariableDeclaration(node) || ts.isParameter(node)) && ts.isIdentifier(node.name)) {
+            declared.set(node.name.text, (declared.get(node.name.text) ?? 0) + 1);
+            const kind = ts.isVariableDeclaration(node) && node.initializer ? envObject(node.initializer) : null;
+            if (kind === 'process' || kind === 'meta')
+                candidates.set(node.name.text, kind);
+        }
+        if (ts.isBindingElement(node) && ts.isIdentifier(node.name)) {
+            declared.set(node.name.text, (declared.get(node.name.text) ?? 0) + 1);
+            // `const { env: e } = process` (or `globalThis.process`).
+            const declaration = node.parent.parent;
+            const key = node.propertyName ?? node.name;
+            if (ts.isIdentifier(key) && key.text === 'env' && ts.isVariableDeclaration(declaration) && declaration.initializer && isProcess(declaration.initializer)) {
+                candidates.set(node.name.text, 'process');
+            }
+        }
+        ts.forEachChild(node, collectAliases);
+    };
+    collectAliases(file);
+    for (const [name, kind] of candidates)
+        if (declared.get(name) === 1)
+            aliases.set(name, kind);
+    /** A literal key, or a named constant holding one (`env[GOOGLE_CLIENT_ID_ENV]`): this file's, else the repository's. */
+    const keyOf = (node) => {
+        const text = literal(node);
+        if (text !== undefined || !ts.isIdentifier(node))
+            return text;
+        // A name the file declares again (a parameter `KEY`, a local `const KEY`) is not the constant.
+        const declarations = declared.get(node.text) ?? 0;
+        if (own.has(node.text))
+            return declarations === 1 ? own.get(node.text) : undefined;
+        return declarations === 0 ? constants.get(node.text) : undefined;
+    };
+    const names = new Set();
+    const add = (kind, name) => {
+        if (kind !== null && name !== undefined && isVariable(kind, name))
+            names.add(name);
+    };
+    const keyText = (key) => {
+        if (key === undefined)
+            return undefined;
+        if (ts.isIdentifier(key) || ts.isStringLiteral(key))
+            return key.text;
+        if (ts.isComputedPropertyName(key))
+            return literal(key.expression);
+        return undefined;
+    };
+    const addPattern = (pattern, from) => {
+        if (!from || !ts.isObjectBindingPattern(pattern))
+            return;
+        const kind = envObject(from);
+        for (const element of pattern.elements)
+            if (!element.dotDotDotToken)
+                add(kind, keyText(element.propertyName ?? element.name));
+    };
+    /** `Object.hasOwn(env, 'X')`, `Reflect.has(env, 'X')`, `env.hasOwnProperty('X')`: a presence check is a read. */
+    const presenceCheck = (node) => {
+        const callee = unwrapped(node.expression);
+        if (!ts.isPropertyAccessExpression(callee))
+            return;
+        const method = callee.name.text;
+        const owner = unwrapped(callee.expression);
+        if (method === 'hasOwnProperty' || method === 'propertyIsEnumerable')
+            add(envObject(owner), literal(node.arguments[0]));
+        else if (ts.isIdentifier(owner) && ((owner.text === 'Object' && method === 'hasOwn') || (owner.text === 'Reflect' && method === 'has'))) {
+            const target = node.arguments[0];
+            if (target)
+                add(envObject(target), literal(node.arguments[1]));
+        }
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node))
+            presenceCheck(node);
+        if (ts.isPropertyAccessExpression(node)) {
+            if (!isNotARead(node))
+                add(envObject(node.expression), node.name.text);
+        }
+        else if (ts.isElementAccessExpression(node)) {
+            if (!isNotARead(node))
+                add(envObject(node.expression), keyOf(node.argumentExpression));
+        }
+        else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.InKeyword) {
+            add(envObject(node.right), keyOf(node.left));
+        }
+        else if (ts.isVariableDeclaration(node) || ts.isParameter(node)) {
+            addPattern(node.name, node.initializer);
+        }
+        else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isObjectLiteralExpression(unwrapped(node.left))) {
+            const kind = envObject(node.right);
+            for (const property of unwrapped(node.left).properties) {
+                if (ts.isShorthandPropertyAssignment(property) || ts.isPropertyAssignment(property))
+                    add(kind, keyText(property.name));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return [...names].sort();
+}
+/** A file's top-level `const NAME = 'text'` (exported or not, `as const` or not), by name. */
+function topLevelStrings(ts, file) {
+    const found = new Map();
+    for (const statement of file.statements) {
+        if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            let init = declaration.initializer;
+            while (init && (ts.isAsExpression(init) || ts.isSatisfiesExpression(init) || ts.isParenthesizedExpression(init)))
+                init = init.expression;
+            if (ts.isIdentifier(declaration.name) && init && (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init))) {
+                found.set(declaration.name.text, init.text);
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The repository's top-level string constants, by name, so a read through a constant another file exports
+ * (`process.env[SECRET_ENV]`) is seen. A name two files define with different text resolves to nothing.
+ */
+export function stringConstants(texts) {
+    const ts = typescript();
+    const found = new Map();
+    for (const [fileName, text] of texts) {
+        const file = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, false, scriptKind(ts, fileName));
+        for (const [name, value] of topLevelStrings(ts, file))
+            found.set(name, found.has(name) && found.get(name) !== value ? null : value);
+    }
+    return new Map([...found].filter((entry) => entry[1] !== null));
+}
+/** Whether a repository-relative path is code the scan reads. */
+export function isScannedPath(path, exclude = []) {
+    if (!CODE.test(path) || SKIP_FILE.test(path))
+        return false;
+    const segments = path.split('/');
+    if (SKIP_TOP.has(segments[0]) || segments.some((segment) => SKIP_SEGMENTS.has(segment)))
+        return false;
+    return !exclude.map(normalisedPrefix).some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+/** `./scripts/one-off/` as git spells it: `scripts/one-off`. */
+function normalisedPrefix(prefix) {
+    return prefix.replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+}
+/** The code files of the repository at `root`: tracked, or new and not ignored. */
+export function scannedFiles(root, exclude = []) {
+    // Tracked files and new ones git does not ignore, so a file not yet added is scanned too.
+    const listed = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    const paths = listed
+        .split('\0')
+        .filter(Boolean)
+        .filter((path) => isScannedPath(path, exclude));
+    return [...new Set(paths)].sort();
+}
+/** Each name read, with the first file that reads it. */
+export function envReads(root, files) {
+    const texts = [];
+    for (const file of files) {
+        try {
+            texts.push([file, readFileSync(join(root, file), 'utf8')]);
+        }
+        catch {
+            // listed by git but deleted in the working tree
+        }
+    }
+    const constants = stringConstants(texts);
+    const reads = new Map();
+    for (const [file, text] of texts)
+        for (const name of envNamesInText(text, file, constants))
+            if (!reads.has(name))
+                reads.set(name, file);
+    return reads;
+}
+/** Compares `.env.example` with what the code reads. Every problem names variables, never a value. */
+export function checkEnvExample(root, example, exclude = []) {
+    let text;
+    try {
+        text = readFileSync(join(root, example), 'utf8');
+    }
+    catch {
+        return { problems: [`${example} does not exist`], files: 0, read: 0, listed: 0 };
+    }
+    const entries = parseEnvExample(text);
+    const all = scannedFiles(root);
+    const files = all.filter((path) => isScannedPath(path, exclude));
+    const reads = envReads(root, files);
+    const problems = [];
+    if (files.length === 0)
+        problems.push('the scan found no code files: the check would pass on nothing');
+    else if (reads.size === 0)
+        problems.push(`the scan found no environment read in ${files.length} files: the check would pass on nothing`);
+    if (entries.length === 0)
+        problems.push(`${example} names no variable`);
+    for (const prefix of exclude) {
+        if (all.every((path) => isScannedPath(path, [prefix])))
+            problems.push(`--exclude ${prefix} matches no scanned file`);
+    }
+    for (const name of duplicateNames(entries))
+        problems.push(`${name} is listed more than once in ${example}`);
+    const listed = new Map(entries.map((e) => [e.name, e]));
+    for (const [name, file] of [...reads].sort(([a], [b]) => a.localeCompare(b))) {
+        if (!listed.has(name))
+            problems.push(`${name} is read (${file}) but not listed in ${example}`);
+    }
+    for (const e of entries) {
+        if (!e.unscanned && !reads.has(e.name) && listed.get(e.name) === e) {
+            problems.push(`${e.name} is listed in ${example} (line ${e.line}) but no code reads it: remove it, or say UNSCANNED in its comment`);
+        }
+    }
+    return { problems, files: files.length, read: reads.size, listed: listed.size };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalystiq/test-kit",
-  "version": "0.2.0",
-  "description": "Shared test setup for Vitest, a fake MCP Apps host for jsdom and Playwright, and the local Neon test-database run.",
+  "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,
@@ -38,6 +38,10 @@
       "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"
@@ -47,6 +51,8 @@
   "bin": {
     "tk-check-bundle": "dist/bin/check-bundle.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": [
@@ -67,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": {
@@ -81,6 +88,9 @@
     },
     "vitest": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "devDependencies": {