@catalystiq/test-kit 0.3.2 → 0.4.0

package/README.md

@@ -1,12 +1,14 @@
 # @catalystiq/test-kit
 
-Shared test helpers: one package, added to part by part. Pin an exact version (`"@catalystiq/test-kit": "0.3.2"`);
+Shared test helpers: one package, added to part by part. Pin an exact version (`"@catalystiq/test-kit": "0.4.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) |
+| Database endpoint reader | `@catalystiq/test-kit/neon-endpoint` | Which database a connection string addresses, read as the clients resolve its host (percent-decoded, IDNA-mapped): a dependency-free module an app also imports at build and boot, fed with its own production and allowed endpoint ids. The two guards above keep their own reading (`src/setup/database.ts`). (`dist/neon-endpoint/README.md` in the package) |
+| Install hardening check | `tk-check-install-scripts`, `@catalystiq/test-kit/install` | package.json `allowScripts` against the lockfile, `.npmrc`'s `min-release-age` and `strict-allow-scripts`, the lockfile's pins and the npm floor, saying precisely what is wrong. (`dist/install/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) |
 

package/dist/bin/check-install-scripts.d.ts

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

package/dist/bin/check-install-scripts.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// tk-check-install-scripts [--root <dir>] [--run <package>]... : fails, saying what is wrong, when the app's install
+// hardening (allowScripts, .npmrc, the lockfile's pins, the npm floor) does not hold. See src/install/index.ts.
+import { runInstallCheck } from "../install/index.js";
+const { code, lines } = runInstallCheck(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

@@ -36,8 +36,14 @@ It reads the environment `next dev` would see (the shell over `.env.development.
 - 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
+  endpoint id on the list (`ep-…`, with or without `-pooler`, so `PGHOST`, `PGOPTIONS`, a keyword/value string and a
+  URL's `?host=` and `options=endpoint…` (encoded once or twice) count too), or a host on the list. A host or an id counts in any spelling a client still resolves to it:
+  percent-encoded (`e%70-…`, UTF-8 escapes too), in fullwidth letters, digits, hyphens or full stops (`ｅｐ－…`), or with
+  a character a URL parser drops inside it (a soft hyphen, a zero-width space, a tab); a listed address in another
+  numeric form (`0x0a.0.0.5` for `10.0.0.5`) where a host stands (after `//`, a URL's `@`, `host=` or `hostaddr=`, or another host of a list; a number
+  elsewhere is a version or a count, so `web@10.0.5` names nothing and `PGHOST=167772165` is not read); a name in its own script or its `xn--` form, whichever the list holds; a
+  keyword/value string's backslash escape (`host=e\p-…`). It names the variable and the list entry, never the value; a
+  `.env` line with no variable name (a pasted connection string) is reported as such and never echoed. `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.
 

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

@@ -1,3 +1,4 @@
+import { productionEntryIn } from '../setup/database.ts';
 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"];
@@ -22,12 +23,7 @@ export interface DevEnv {
  * 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;
+export { productionEntryIn };
 /**
  * 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
@@ -38,6 +34,11 @@ export interface ProductionHit {
     variable: string;
     entry: string;
 }
+/**
+ * What a refusal prints for a variable: its name when it is one. A `.env` line with no `NAME=` parses with everything
+ * before its `=` as the "name" (a pasted connection string's credentials included), and that is never echoed.
+ */
+export declare function printableVariableName(name: string): 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.

package/dist/env/dev-guard.js

@@ -7,14 +7,16 @@
  * 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.
+ * `PGHOST`, `PGOPTIONS endpoint=…` and a URL's `options=endpoint%3D…` all count, and so does a host spelled as a client
+ * still resolves it (percent-encoded, in fullwidth letters, with a soft hyphen inside). A refusal names the variable and the
+ * matched list entry, never the value; a line with no variable name is never echoed.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
+import { domainToASCII } from 'node:url';
 import { parseEnv } from 'node:util';
-import { isProductionHost } from "../setup/database.js";
+import { NON_ASCII, productionEntryIn } 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`). */
@@ -98,27 +100,7 @@ export function loadDevEnv(root, base = process.env) {
             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;
-}
+export { productionEntryIn };
 /**
  * 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
@@ -135,6 +117,9 @@ export function productionHostEntry(entry, source = 'the production list') {
         }
     }
     host = host.replace(/[/?#].*$/, '').replace(/:\d*$/, '').replace(/^\.+/, '');
+    // A name listed in another script is the `xn--` form a client resolves.
+    if (NON_ASCII.test(host))
+        host = domainToASCII(host);
     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)`);
     }
@@ -145,6 +130,17 @@ export function productionHostEntry(entry, source = 'the production list') {
  * 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;
+/** The name the `dev` script's own text is checked under. */
+const DEV_SCRIPT = 'package.json scripts.dev';
+/**
+ * What a refusal prints for a variable: its name when it is one. A `.env` line with no `NAME=` parses with everything
+ * before its `=` as the "name" (a pasted connection string's credentials included), and that is never echoed.
+ */
+export function printableVariableName(name) {
+    if (/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(name) || name === DEV_SCRIPT)
+        return name;
+    return '(a line with no variable name)';
+}
 /**
  * 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.
@@ -158,7 +154,13 @@ export function productionHits(env, productionHosts, allowVariables = [], alsoCh
         if (entry)
             hits.set(variable, entry);
     }
-    return [...hits].sort(([a], [b]) => a.localeCompare(b)).map(([variable, entry]) => ({ variable, entry }));
+    const named = new Map();
+    for (const [variable, entry] of [...hits].sort(([a], [b]) => a.localeCompare(b))) {
+        const name = printableVariableName(variable);
+        if (!named.has(name))
+            named.set(name, entry);
+    }
+    return [...named].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) {
@@ -214,7 +216,7 @@ export function runDevGuard(args, root, base = process.env) {
         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]]);
+        const hits = productionHits(env, hosts, allow, devScript === null ? alsoChecked : [...alsoChecked, [DEV_SCRIPT, 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).');

package/dist/install/README.md

@@ -0,0 +1,55 @@
+# The install hardening check: `tk-check-install-scripts`
+
+One check, for an app's own repository, of the install hardening every getcatalystiq app keeps. It says precisely what
+is wrong, one line each, and what it could not check; a check that did not run is never reported as passed.
+
+```sh
+tk-check-install-scripts --run canvas --min-scripts 6
+```
+
+or from a test (it imports no test runner, so any runner can call it):
+
+```ts
+import { checkInstallHardening } from '@catalystiq/test-kit/install';
+
+it('the install hardening holds', () => {
+  expect(checkInstallHardening(process.cwd(), { run: ['canvas'], minScripts: 6 }).problems).toEqual([]);
+});
+```
+
+A CommonJS test (Jest) runs the bin: `execFileSync('node_modules/.bin/tk-check-install-scripts', ['--run-none'])`.
+
+## What it holds
+
+| Rule | Checked from |
+|---|---|
+| package.json `allowScripts` names exactly the locked packages with an install script (`hasInstallScript`, workspace links left out), each `true` or `false`; no entry is stale. | `package.json`, `package-lock.json` |
+| The entries that run (`true`) are exactly the reviewed list. | `run` / `--run`, `--run-none` |
+| `.npmrc` sets `min-release-age=1` and `strict-allow-scripts=true`, and no `legacy-peer-deps`; a commented line sets nothing. | `.npmrc` |
+| The npm on PATH knows both keys and takes them from the project's file (asked with an empty user and global config, and without npm's own exported `npm_config_*`), reads `legacy-peer-deps` as off, and refuses with `ESTRICTALLOWSCRIPTS`, before running it, an install whose tree has a script `allowScripts` does not name. | `npm config ls -l`, `npm config get`, an offline `npm install` in a temporary directory |
+| The lockfile pins every package it fetches by registry URL and sha512 (the root, links and bundled packages are never fetched). | `package-lock.json` |
+| The app's floor script admits the floor, the next minor and the next major, and refuses the patch and minor below, the major below, a string that is no version and a prerelease of an admitted version; a crash is not a refusal. | `node scripts/check-npm-version.mjs` under a stub `npm` |
+| `vercel.json`'s `installCommand` runs the floor script, then `npm ci`. | `vercel.json` |
+| npm is the package manager: `lockfileVersion` 3, `package-lock.json` tracked, no other manager's lockfile tracked, no `pnpm` key. | `git ls-files`, `package.json` |
+| `packageManager` is `npm@X.Y.Z` at or above the floor and, under `.nvmrc`'s own Node, the npm in use. | `package.json`, `.nvmrc`, `npm --version` |
+
+The floor script stays in the app: Vercel runs it before `npm ci`, when no package is installed.
+
+## Options
+
+| Option | Flag | Default | For |
+|---|---|---|---|
+| `run` | `--run <package>`…, `--run-none` | not checked | Which scripts run. |
+| `minScripts` | `--min-scripts <n>` | 1 | A lockfile with fewer install scripts proves nothing. |
+| `requireDevDependencies` | `--require-dev <package>`… | none | `tsx`, so `npx tsx` installs nothing. |
+| `requireScripts` | `--require-script <name>=<text>`… | none | A pinned `npx --allow-scripts=…` line. |
+| `minReleaseAge` | `--min-release-age <days>` | 1 | |
+| `allowLegacyPeerDeps` | `--allow-legacy-peer-deps` | false | |
+| `lockfilePins`, `registry` | `--no-lockfile-pins`, `--registry <url>` | on, `https://registry.npmjs.org/` | |
+| `npmFloor` | `--npm-floor <X.Y.Z>` | `11.19.1` | |
+| `floorScript` | `--floor-script <path>`, `--no-floor-script` | `scripts/check-npm-version.mjs` | |
+| `prereleaseBelowRelease` | `--no-prerelease-cases` | true | A floor script that reads versions with `parseInt` admits `11.19.1-rc.0`. |
+| `installCommand` | `--install-command <text>`, `--no-install-command` | `node <floorScript> && npm ci` | |
+| `packageManager` | `--package-manager path\|bundled\|declared` | `path` | `bundled`: the npm Node ships beside its binary, not one installed over it. On another Node than `.nvmrc`'s it is reported not checked. |
+| `npmProbes` | `--npm-probes required\|when-supported\|off` | `required` | Under an npm below the floor: fail, or report the npm checks not checked. |
+| root | `--root <dir>` | the working directory | |

package/dist/install/index.d.ts

@@ -0,0 +1,97 @@
+export interface LockEntry {
+    name?: string;
+    hasInstallScript?: boolean;
+    link?: boolean;
+    inBundle?: boolean;
+    resolved?: string;
+    integrity?: string;
+}
+export interface Lock {
+    lockfileVersion?: number;
+    packages?: Record<string, LockEntry>;
+}
+export interface InstallCheckOptions {
+    /**
+     * The `allowScripts` entries that are `true`, exactly: `[]` when every script is skipped. Omitted, which ones run is
+     * not checked (each must still be `true` or `false`).
+     */
+    run?: readonly string[];
+    /** The fewest locked packages with an install script: a lockfile with none proves nothing. Default 1. */
+    minScripts?: number;
+    /** The `min-release-age` `.npmrc` sets, in days. Default 1. */
+    minReleaseAge?: number;
+    /** Let `.npmrc` set `legacy-peer-deps`. Default false: a peer conflict is fixed by the versions. */
+    allowLegacyPeerDeps?: boolean;
+    /** Hold every fetched package of the lockfile to a registry URL and a sha512. Default true. */
+    lockfilePins?: boolean;
+    /** The registry every `resolved` URL starts with. Default `https://registry.npmjs.org/`. */
+    registry?: string;
+    /** The oldest npm that reads `allowScripts`, `strict-allow-scripts` and `min-release-age`. Default `11.19.1`. */
+    npmFloor?: string;
+    /** The app's floor script, run before `npm ci`; `null` when the app has none. Default `scripts/check-npm-version.mjs`. */
+    floorScript?: string | null;
+    /** Hold the floor script to refusing a prerelease of an admitted version. Default true. */
+    prereleaseBelowRelease?: boolean;
+    /**
+     * `vercel.json`'s `installCommand`; `null` when the app does not deploy through one. Default
+     * `node <floorScript> && npm ci`.
+     */
+    installCommand?: string | null;
+    /**
+     * How `packageManager` is held to the npm in use, under `.nvmrc`'s own Node (on another Node it is reported skipped):
+     * `'path'` the npm on PATH, `'bundled'` the npm that Node ships beside its binary, `'declared'` neither (the field
+     * still names an npm the floor admits). Default `'path'`.
+     */
+    packageManager?: 'path' | 'bundled' | 'declared';
+    /** devDependencies that must exist (`tsx`, so `npx tsx` installs nothing). */
+    requireDevDependencies?: readonly string[];
+    /** package.json scripts held to an exact text (a pinned `npx --allow-scripts=…` line). */
+    requireScripts?: Readonly<Record<string, string>>;
+    /**
+     * The checks that ask npm itself: `'required'` fails when the npm on PATH is below the floor, `'when-supported'`
+     * reports them skipped there, `'off'` never runs them (reported skipped). Default `'required'`.
+     */
+    npmProbes?: 'required' | 'when-supported' | 'off';
+    /** The environment `npm`, `node` and `git` run with. Default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+export interface InstallCheck {
+    /** What is wrong, one line each; empty when the hardening holds. */
+    problems: string[];
+    /** The checks that did not run, and why. Never a pass. */
+    skipped: string[];
+    /** The locked packages with an install script. */
+    scripts: string[];
+}
+/** The names of the locked packages that run an install script. */
+export declare function withInstallScripts(lock: Lock): string[];
+/** What is wrong between a lockfile and an `allowScripts`, one line each. */
+export declare function scriptProblems(lock: Lock, allow: Record<string, unknown>): string[];
+/** The lockfile paths npm would fetch that are not pinned to `registry` and a sha512. */
+export declare function unpinnedPackages(lock: Lock, registry?: string): string[];
+/** `X.Y.Z` as numbers, or null: a prerelease (`11.19.1-rc.0`) is below its release, and anything else is no version. */
+export declare function releaseVersion(version: string): [number, number, number] | null;
+/** Whether `version` is a release at or above `floor`. */
+export declare function atLeast(version: string, floor: string): boolean;
+/** The versions a floor script must admit and refuse, from the floor itself. */
+export declare function floorCases(floor: string, prereleases?: boolean): {
+    admitted: string[];
+    refused: string[];
+};
+/** The settings of an `.npmrc` text, by key, as written (comments and blank lines left out; the last one wins). */
+export declare function npmrcSettings(text: string): Record<string, string>;
+/** Every check, over the app at `root`. See the module header and {@link InstallCheckOptions}. */
+export declare function checkInstallHardening(root: string, options?: InstallCheckOptions): InstallCheck;
+export declare const INSTALL_CHECK_USAGE: string;
+/** The bin's arguments as a root and options. Throws, with the usage, on an unknown flag or a value that is not one. */
+export declare function parseInstallCheckArgs(args: readonly string[], cwd: string): {
+    root: string;
+    options: InstallCheckOptions;
+};
+export interface InstallCheckRun {
+    code: 0 | 1;
+    /** What to print: to stderr when `code` is 1, to stdout otherwise. */
+    lines: string[];
+}
+/** The whole bin, as a function. */
+export declare function runInstallCheck(args: readonly string[], cwd: string, env?: NodeJS.ProcessEnv): InstallCheckRun;