@rexezuge/tooling 0.0.0-stage → 1.0.0

package/src/scripts/backup/encrypt-backup.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env tsx
+/**
+ * Compress and encrypt the exported D1 dump.
+ *
+ * Provenance: Edge-Sonic's `scripts/backup/encrypt-backup.ts`, converged with the
+ * AES-GCM envelope every repo in the family already uses for its secrets. This is
+ * the one backup script that ported cleanly and changed *for the better* on the way
+ * in: the source shelled out to `openssl enc -aes-256-cbc -pbkdf2`, which is a
+ * password-derived key with a KDF whose cost is a constant somebody chose once,
+ * and which is not authenticated — a flipped byte in the ciphertext is undetectable.
+ *
+ * The kit's version uses `@rexezuge/d1`'s `encryptSecret`, the same WebCrypto
+ * AES-256-GCM primitive the workers use, over a base64 32-byte key — the same key
+ * format `resolveReplicationKey` reads. One definition of "what an encryption key
+ * looks like" across the deploy path and the backup path is the point: a second
+ * implementation is how a deploy ends up generating something the worker cannot
+ * read, and here it would be how a backup ends up unreadable by the restore path.
+ *
+ * Fail-closed: without `BACKUP_ENCRYPTION_KEY` the script refuses to run and
+ * deletes nothing, so an unencrypted dump can never reach the artifact store the
+ * upload jobs read from.
+ *
+ * The passphrase is read from the environment rather than passed as an argument,
+ * because command-line arguments are visible to any process on the runner via `ps`.
+ *
+ * Emits the resulting file name as the `file` step output.
+ *
+ * Usage, from the repo root (after `wrangler d1 export … --output=backup.sql`):
+ *
+ * ```bash
+ * BACKUP_ENCRYPTION_KEY=… pnpm exec tsx scripts/backup/encrypt-backup.ts
+ * ```
+ */
+
+import { encryptSecret } from '@rexezuge/d1';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { fail, setOutput } from '../lib/github-actions';
+import { backupFileName } from './naming';
+
+/** The dump the export step leaves in the working directory. */
+const SOURCE_FILE = 'backup.sql';
+
+/**
+ * xz preset 6, chosen for ratio over speed: this runs once a day against a dump
+ * that is mostly SQL text and JSON blobs, and LZMA typically beats gzip by 20-30%
+ * there. `-T0` uses every available thread, which matters because xz is markedly
+ * slower than gzip and the job is wall-clock bound.
+ */
+const XZ_ARGS = ['-T0', '-6'];
+
+function run(command: string, args: readonly string[]): void {
+  execFileSync(command, [...args], { stdio: ['ignore', 'inherit', 'inherit'] });
+}
+
+if (!process.env['BACKUP_ENCRYPTION_KEY']) {
+  fail('BACKUP_ENCRYPTION_KEY is not set. Refusing to export an unencrypted database.');
+}
+
+if (!existsSync(SOURCE_FILE)) {
+  fail(`Expected ${SOURCE_FILE} from the export step, but it does not exist.`);
+}
+
+const key = process.env['BACKUP_ENCRYPTION_KEY'] as string;
+const file = backupFileName(new Date());
+
+let plaintext: string;
+try {
+  plaintext = readFileSync(SOURCE_FILE, 'utf8');
+} catch (error: unknown) {
+  fail(`Could not read ${SOURCE_FILE}: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+if (plaintext === '') {
+  fail(`${SOURCE_FILE} is empty. An empty dump is not a backup, and uploading one is a false sense of safety.`);
+}
+
+/**
+ * Compress first, then encrypt.
+ *
+ * The order matters: compression over ciphertext buys nothing, and encrypting the
+ * compressed bytes means the plaintext is never re-materialised on disk at full
+ * size. Unlike gzip, xz leaves its input in place, so the plaintext SQL has to be
+ * removed explicitly here or it survives into the artifact store.
+ */
+let compressed: Buffer;
+try {
+  compressed = execFileSync('xz', [...XZ_ARGS, '--keep', '--stdout', SOURCE_FILE], { maxBuffer: 512 * 1024 * 1024 });
+} catch (error: unknown) {
+  fail(`xz failed on ${SOURCE_FILE}: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+let envelope: { ciphertext: string; iv: string };
+try {
+  envelope = await encryptSecret(compressed.toString('base64'), key);
+} catch (error: unknown) {
+  // A key that is not 32 base64 bytes, or not valid base64 at all, fails here
+  // rather than producing a file nothing can open.
+  fail(`Could not encrypt the dump: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+writeFileSync(file, `${JSON.stringify({ ...envelope, source: basename(SOURCE_FILE) }, null, 2)}\n`, 'utf8');
+rmSync(SOURCE_FILE, { force: true });
+
+console.log(`Backup encrypted: ${file} (${compressed.byteLength} compressed bytes)`);
+setOutput('file', file);

package/src/scripts/backup/naming.ts

@@ -0,0 +1,62 @@
+/**
+ * Backup artifact naming and retention-window handling.
+ *
+ * Provenance: Edge-Sonic's `scripts/backup/naming.ts` and `retention.ts`,
+ * converged into one module because the two answer the same question from either
+ * side — what a file is called, and which of them are still worth keeping — and a
+ * consumer only ever imports one.
+ */
+
+/**
+ * The filename prefix.
+ *
+ * Exported rather than inlined, because the workflow uploads with
+ * `<prefix>_*.sql.xz.enc` and `if-no-files-found: error`. That glob and this prefix
+ * are one fact written in two places — the failure mode being a rename here that
+ * silently stops every upload while each upload job still reports success, since
+ * the upload jobs skip on `needs` rather than failing.
+ */
+export const BACKUP_FILE_PREFIX = 'backup_prod_';
+
+/**
+ * `2026-10-01_04-15-00` — sortable, filename-safe, and UTC.
+ *
+ * UTC rather than local: a retention window computed across a DST boundary is one
+ * day wide in one direction, and a backup pruned a day early is a backup that was
+ * never needed.
+ */
+export function backupStamp(date: Date): string {
+  const iso = date.toISOString();
+  return `${iso.slice(0, 10)}_${iso.slice(11, 19).replaceAll(':', '-')}`;
+}
+
+/** The full artifact name: `<prefix><stamp>.sql.xz.enc`. */
+export function backupFileName(date: Date): string {
+  return `${BACKUP_FILE_PREFIX}${backupStamp(date)}.sql.xz.enc`;
+}
+
+/**
+ * `YYYY-MM-DD`, `days` before `now`.
+ */
+export function retentionCutoff(now: Date, days: number): string {
+  return new Date(now.getTime() - days * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+}
+
+/**
+ * Read `BACKUP_RETENTION_DAYS` from the environment, rejecting bad values.
+ *
+ * Rejected rather than defaulted: silently falling back would either prune
+ * everything or keep backups forever, and both are worse than a failed run that
+ * names the problem.
+ *
+ * `Number()` rather than `parseInt()`: `parseInt('30d')` yields 30, which would
+ * silently accept a mistyped value and prune against the wrong window.
+ */
+export function requireRetentionDays(): number {
+  const raw = process.env['BACKUP_RETENTION_DAYS'];
+  const days = Number(raw);
+  if (!Number.isFinite(days) || days <= 0) {
+    throw new Error(`BACKUP_RETENTION_DAYS must be a positive number, got ${JSON.stringify(raw)}.`);
+  }
+  return days;
+}

package/src/scripts/check-god-files.test.ts

@@ -0,0 +1,131 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { checkGodFiles, checkGodFilesCli, readAllowlist, HARD_LIMIT, SOFT_LIMIT } from './check-god-files';
+
+function tempTree(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), 'god-files-'));
+  for (const [name, content] of Object.entries(files)) {
+    const path = join(root, name);
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, content, 'utf8');
+  }
+  return root;
+}
+
+const pad = (lines: number): string => Array.from({ length: lines }, (_, index) => `// line ${index}`).join('\n');
+
+describe('checkGodFiles', () => {
+  it('passes a small product source tree', () => {
+    const root = tempTree({ 'src/app.ts': pad(10) });
+    const report = checkGodFiles({ root });
+    expect(report.passed).toBe(true);
+    expect(report.findings).toStrictEqual([]);
+    expect(report.scanned).toBe(1);
+  });
+
+  it('reports over-soft as warn and over-hard as critical', () => {
+    const soft = checkGodFiles({ root: tempTree({ 'src/medium.ts': pad(320) }) });
+    expect(soft.findings).toStrictEqual([{ file: 'src/medium.ts', lines: 320, level: 'warn' }]);
+    expect(soft.passed).toBe(true); // warn-only is the family's gate
+
+    const hard = checkGodFiles({ root: tempTree({ 'src/huge.ts': pad(450) }) });
+    expect(hard.findings[0]).toMatchObject({ file: 'src/huge.ts', level: 'critical' });
+    expect(hard.passed).toBe(true); // still passes without --fail-on-hard
+  });
+
+  it('fails only when the caller opts into the hard gate', () => {
+    const root = tempTree({ 'src/huge.ts': pad(450) });
+    expect(checkGodFiles({ root, failOnHard: true }).passed).toBe(false);
+    expect(checkGodFiles({ root, failOnHard: false }).passed).toBe(true);
+    expect(checkGodFiles({ root }).passed).toBe(true);
+  });
+
+  it('keeps allowlisted files out of the findings but still reports them', () => {
+    const root = tempTree({ 'src/huge.ts': pad(450), 'src/other.ts': pad(350) });
+    const report = checkGodFiles({ root, allowlist: ['src/huge.ts'] });
+    expect(report.findings).toStrictEqual([{ file: 'src/other.ts', lines: 350, level: 'warn' }]);
+    expect(report.allowlisted).toStrictEqual([{ file: 'src/huge.ts', lines: 450, level: 'critical' }]);
+    expect(report.passed).toBe(true);
+  });
+
+  it('ignores tests, generated, locales, scripts, configs, and lockfiles', () => {
+    const root = tempTree({
+      'src/app.test.ts': pad(500),
+      'src/generated/x.ts': pad(500),
+      'src/locales/de/translation.json': JSON.stringify({ a: 'b' }),
+      'scripts/build.ts': pad(500),
+      'vite.config.ts': pad(500),
+      'package.json': '{}',
+      'migrations/0001_init.sql': 'SELECT 1;',
+    });
+    expect(checkGodFiles({ root }).scanned).toBe(0);
+  });
+
+  it('skips node_modules, dist, and caches', () => {
+    const root = tempTree({
+      'node_modules/pkg/index.ts': pad(500),
+      'dist/bundle.js': pad(500),
+      'coverage/report.js': pad(500),
+    });
+    expect(checkGodFiles({ root }).scanned).toBe(0);
+  });
+
+  it('sorts findings worst-first', () => {
+    const root = tempTree({ 'src/a.ts': pad(320), 'src/b.ts': pad(450), 'src/c.ts': pad(360) });
+    expect(checkGodFiles({ root }).findings.map((finding) => finding.file)).toStrictEqual(['src/b.ts', 'src/c.ts', 'src/a.ts']);
+  });
+});
+
+describe('readAllowlist', () => {
+  it('returns [] for an absent file', () => {
+    expect(readAllowlist('/nonexistent-xyz/allowlist.json')).toStrictEqual([]);
+  });
+
+  it('rejects a malformed allowlist rather than reading it as empty', () => {
+    const root = mkdtempSync(join(tmpdir(), 'god-allow-'));
+    const path = join(root, 'allowlist.json');
+    writeFileSync(path, '{ not: an array }', 'utf8');
+    expect(() => readAllowlist(path)).toThrow(/not valid JSON/);
+  });
+
+  it('rejects a non-array allowlist', () => {
+    const root = mkdtempSync(join(tmpdir(), 'god-allow-'));
+    const path = join(root, 'allowlist.json');
+    writeFileSync(path, '{"src/a.ts": 400}', 'utf8');
+    expect(() => readAllowlist(path)).toThrow(/JSON array of repo-relative path strings/);
+  });
+
+  it('reads a valid allowlist', () => {
+    const root = mkdtempSync(join(tmpdir(), 'god-allow-'));
+    const path = join(root, 'allowlist.json');
+    writeFileSync(path, '["a.ts", "b.ts"]', 'utf8');
+    expect(readAllowlist(path)).toStrictEqual(['a.ts', 'b.ts']);
+  });
+});
+
+describe('checkGodFilesCli', () => {
+  it('returns 0 in the default warn-only mode, even over the hard limit', () => {
+    const root = tempTree({ 'src/huge.ts': pad(450) });
+    expect(checkGodFilesCli(['--root', root])).toBe(0);
+  });
+
+  it('exits non-zero with --fail-on-hard over the hard limit', () => {
+    const exit = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never);
+    const root = tempTree({ 'src/huge.ts': pad(450) });
+    checkGodFilesCli(['--root', root, '--fail-on-hard']);
+    expect(exit).toHaveBeenCalledWith(1);
+    exit.mockRestore();
+  });
+
+  it('returns 0 on a clean tree with the gate on', () => {
+    const root = tempTree({ 'src/app.ts': pad(10) });
+    expect(checkGodFilesCli(['--root', root, '--fail-on-hard'])).toBe(0);
+  });
+
+  it('exposes the family constants', () => {
+    expect(SOFT_LIMIT).toBe(300);
+    expect(HARD_LIMIT).toBe(400);
+  });
+});

package/src/scripts/check-god-files.ts

@@ -0,0 +1,327 @@
+/**
+ * The rules behind `scripts/check-god-files.ts`.
+ *
+ * Provenance: converged from the seven `.mjs` copies (AWS-AccessBridge,
+ * CalDAV-Bridge, ChordDHT-Tracker, Durable-DAV, Durable-DAV-Router, Edge-Git,
+ * Mail-Meow, Mail-Otter) and the typed ratchet in Edge-Sonic.
+ *
+ * All seven `.mjs` copies are one script with two constants: soft 300 (warn),
+ * hard 400 (error). The typed variant is not a different rule so much as a
+ * different answer to "what does the gate enforce", and that is the decision this
+ * module has to take once for the whole family.
+ *
+ * ### The convergence: warn-only, with an allowlist
+ *
+ * The two source designs:
+ *
+ * - **Ceiling** (six repos) — 300 warn, 400 error, `exit 1` on 400. Durable-DAV's
+ *   own `AGENTS.md` records what that measures: **ten** files sit just over 300
+ *   and none is a god file, so `WARN` reports every run and `HARD` has never
+ *   fired. A ceiling set above the largest file in the tree cannot tell a
+ *   repository getting worse from one that never got better, and raising it is
+ *   always available.
+ * - **Ratchet** (Edge-Sonic) — a committed baseline records every file's size; a
+ *   file may shrink freely and grow only to its recorded size. It cannot be
+ *   satisfied by raising a number, which is its whole strength.
+ *
+ * The ratchet is the better *rule*, and the ceiling is the better *gate*: the
+ * ratchet needs a baseline maintained per file and fails the first time somebody
+ * writes a legitimate 320-line module, which is the failure mode that trains
+ * everyone to ignore a report. So the converged script keeps the 300/400
+ * thresholds — every repo's CI already prints them — and makes the verdict
+ * **warn-only by default**, with two escape valves that are both visible in a
+ * diff:
+ *
+ * 1. `--fail-on-hard` turns the 400 line back into a failing gate, for a repo
+ *   that has paid its debt and wants the ceiling enforced.
+ * 2. An **allowlist** records the files that are over the line and known, so the
+ *   report names only the ones that are *new*. That is the ratchet's
+ *   "recorded size" idea without its per-file bookkeeping: the allowlist is
+ *   reviewed by the same commit that grows the file, because the diff shows what
+ *   was added to it.
+ *
+ * Tests are excluded, as every source does. A double modelling the platform grows
+ * with the platform's surface, not with the complexity of the code it stands in
+ * for — Edge-Sonic's ratchet holds them too, and its own notes record a 4,343-line
+ * fixture, so this is a documented disagreement rather than an oversight.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { join, relative } from 'node:path';
+import { fail } from './lib/github-actions';
+import { isSet, parseFlags, splitPositional, valueOf } from './lib/cli-args';
+
+/**
+ * A file past a size the guard reports on.
+ */
+export interface GodFileFinding {
+  /** Path relative to the root the check ran against. */
+  readonly file: string;
+  /** Lines it has. */
+  readonly lines: number;
+  /** `warn` past the soft limit, `critical` past the hard one. */
+  readonly level: 'warn' | 'critical';
+}
+
+/**
+ * The outcome of one run.
+ */
+export interface GodFileReport {
+  /** Files over a limit, worst first, minus the allowlisted. */
+  readonly findings: readonly GodFileFinding[];
+  /** How many files the walk measured. */
+  readonly scanned: number;
+  /** Allowlisted files that are over a limit — reported, never counted. */
+  readonly allowlisted: readonly GodFileFinding[];
+  /**
+   * Whether the tree may be committed as it stands.
+   *
+   * `true` in warn-only mode, which is the default; a `critical` finding fails
+   * only when the caller asked for the gate.
+   */
+  readonly passed: boolean;
+  /** The message to print, either way. */
+  readonly reported: string;
+}
+
+/**
+ * What `checkGodFiles` accepts.
+ */
+export interface GodFileOptions {
+  /** Directory to walk. */
+  readonly root: string;
+  /**
+   * Repo-relative paths (or directory prefixes ending in `/`) exempt from the
+   * report. Defaults to `god-files.allowlist.json` beside the caller's script
+   * when that file exists — see `readAllowlist`.
+   */
+  readonly allowlist?: readonly string[];
+  /** Soft limit, past which a file is reported as `warn`. */
+  readonly soft?: number;
+  /** Hard limit, past which a file is reported as `critical`. */
+  readonly hard?: number;
+  /** Make a `critical` finding fail the run. */
+  readonly failOnHard?: boolean;
+}
+
+/** Default soft limit, as every source repo uses. */
+export const SOFT_LIMIT = 300;
+/** Default hard limit, as every source repo uses. */
+export const HARD_LIMIT = 400;
+
+/**
+ * Directories the walker never enters.
+ *
+ * Build output and VCS state; `coverage` is here because a generated HTML report
+ * is thousands of "lines" of nothing.
+ */
+const EXCLUDE_DIRS = new Set(['node_modules', 'dist', '.wrangler', 'coverage', 'coverage-integration', 'coverage-web', '.git']);
+
+/**
+ * Source extensions the guard counts.
+ *
+ * `css` is in the set because every source repo counts it, and a 400-line
+ * stylesheet is the same reading problem as a 400-line module.
+ */
+const SOURCE_EXTENSIONS = /\.(?:ts|tsx|js|mjs|cjs|css)$/;
+
+/**
+ * The test-file suffixes the guard skips.
+ *
+ * `.test.tsx` matter as much as `.test.ts`: the walker collects both, so a list
+ * that only named the `.ts` forms let every React test file through the guard and
+ * reported them as god files — which is how Durable-DAV-Router discovered it.
+ * Built from the kinds and extensions rather than enumerated, so a new test
+ * extension cannot silently escape.
+ */
+const TEST_SUFFIXES: readonly string[] = ['test', 'spec'].flatMap((kind) =>
+  ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].map((ext) => `.${kind}${ext}`),
+);
+
+/**
+ * Whether a repo-relative path is exempt from the guard.
+ *
+ * Provenance: AWS-AccessBridge's version is the canonical one, because it
+ * documents and fixes two live bugs in the others.
+ *
+ * Every directory pattern is anchored with `(?:^|/)` rather than a bare leading
+ * `/`. `relative()` yields `test/helpers/x.ts` for a top-level test directory and
+ * `scripts/lib/x.ts` for the scripts directory — **no leading separator** — so a
+ * pattern written as `/\/(?:test|tests|__tests__)\//` never matches either one.
+ * It looks right, it does match when handed an absolute path, and against these
+ * layouts it is silently a no-op. Durable-DAV and ChordDHT-Tracker ship exactly
+ * that dead pattern.
+ */
+export function shouldSkip(rel: string): boolean {
+  if (/(?:^|\/)(?:locales|generated)\//.test(rel)) return true;
+  if (/(?:^|\/)__(?:tests|mocks)__(?:\/|$)/.test(rel)) return true;
+  if (/(?:^|\/)scripts\//.test(rel)) return true;
+  if (/(?:^|\/)(?:test|tests|__tests__)\//.test(rel)) return true;
+  if (/\.config\.(?:m?[jt]s|cjs)$/.test(rel)) return true;
+  if (rel.endsWith('.d.ts')) return true;
+  if (rel.endsWith('.json')) return true;
+  if (rel.endsWith('.sql')) return true;
+  if (rel.endsWith('.md')) return true;
+  return TEST_SUFFIXES.some((suffix) => rel.endsWith(suffix));
+}
+
+/**
+ * Whether a repo-relative path is on the allowlist.
+ *
+ * An entry ending in `/` exempts a whole directory; any other entry is matched
+ * exactly, so `apps/api/src/index.ts` does not exempt `apps/api/src/index.util.ts`.
+ */
+export function isAllowlisted(rel: string, allowlist: readonly string[]): boolean {
+  return allowlist.some((entry) => (entry.endsWith('/') ? rel.startsWith(entry) : rel === entry));
+}
+
+/**
+ * Every source file under `root`, as repo-relative paths.
+ *
+ * Symlink-safe: a dangling symlink or a file removed mid-walk is skipped rather
+ * than thrown, because neither is a god-file problem.
+ */
+export function walk(root: string): string[] {
+  const out: string[] = [];
+  const visit = (dir: string): void => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      let stat;
+      try {
+        stat = statSync(full);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        if (EXCLUDE_DIRS.has(entry)) continue;
+        visit(full);
+      } else if (SOURCE_EXTENSIONS.test(entry)) {
+        out.push(relative(root, full));
+      }
+    }
+  };
+  visit(root);
+  return out;
+}
+
+/**
+ * Run the guard over a tree.
+ *
+ * Pure with respect to the verdict — the only I/O is the walk and a line count —
+ * so a test drives it against a temporary directory.
+ */
+export function checkGodFiles(options: GodFileOptions): GodFileReport {
+  const soft = options.soft ?? SOFT_LIMIT;
+  const hard = options.hard ?? HARD_LIMIT;
+  const allowlist = options.allowlist ?? [];
+
+  const scanned = walk(options.root).filter((rel) => !shouldSkip(rel));
+  const findings: GodFileFinding[] = [];
+  const allowlisted: GodFileFinding[] = [];
+
+  for (const rel of scanned) {
+    const lines = readFileSync(join(options.root, rel), 'utf8').split('\n').length;
+    if (lines <= soft) continue;
+    const finding: GodFileFinding = { file: rel, lines, level: lines > hard ? 'critical' : 'warn' };
+    if (isAllowlisted(rel, allowlist)) {
+      allowlisted.push(finding);
+    } else {
+      findings.push(finding);
+    }
+  }
+
+  findings.sort((left, right) => right.lines - left.lines);
+  allowlisted.sort((left, right) => right.lines - left.lines);
+
+  const critical = findings.filter((finding) => finding.level === 'critical');
+  const passed = options.failOnHard !== true || critical.length === 0;
+
+  const reported = passed
+    ? `God-file check passed (${scanned.length} files, ${findings.length} over soft limit ${soft}, ${allowlisted.length} allowlisted).`
+    : `God-file check failed: ${critical.length} file(s) exceed ${hard} LOC. Split them, or add them to the allowlist in the same commit that grows them.`;
+
+  return { findings, allowlisted, scanned: scanned.length, passed, reported };
+}
+
+/**
+ * Read an allowlist file, or `[]` when it is absent.
+ *
+ * The file is `scripts/god-files.allowlist.json`: a JSON array of repo-relative
+ * paths. Absence is the normal case for a repo with no known offenders, so it is
+ * not an error — a guard that fails on a first run nobody has filled in yet is a
+ * guard that gets disabled.
+ *
+ * A malformed file is an error rather than an empty list, because "the allowlist
+ * is empty" silently un-reports every known offender.
+ */
+export function readAllowlist(path: string): string[] {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    return [];
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error: unknown) {
+    throw new Error(`${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== 'string')) {
+    throw new Error(`${path} must be a JSON array of repo-relative path strings.`);
+  }
+  return parsed as string[];
+}
+
+/**
+ * CLI entry: `checkGodFilesCli(['.', '--fail-on-hard'])`.
+ *
+ * The directory is a positional argument **or** `--root <dir>`, because every other
+ * script in this tree takes its target positionally and a gate that has to be
+ * invoked one way in one script and another way in the next is a gate somebody
+ * invokes wrong. A second positional is an error.
+ *
+ * Flags (see FlagSpec): `--root <dir>` (default `.`), `--allowlist <file>`
+ * (default `scripts/god-files.allowlist.json` beside the root, absent = none),
+ * `--fail-on-hard` (default off, matching every source repo's warn-only gate).
+ * Returns 0 unless `--fail-on-hard` is set and a critical file is found.
+ */
+export function checkGodFilesCli(argv: readonly string[] = process.argv.slice(2)): number {
+  // Split before parsing, because parseFlags rejects anything that is not a declared
+  // flag and a positional directory is neither a mistake nor a flag.
+  const { positional, rest } = splitPositional(argv, ['root', 'allowlist']);
+  const flags = parseFlags(rest, {
+    value: ['root', 'allowlist'],
+    boolean: ['fail-on-hard'],
+  });
+  const root = valueOf(flags, 'root') ?? positional[0] ?? '.';
+  const allowlistPath = valueOf(flags, 'allowlist') ?? join(root, 'scripts/god-files.allowlist.json');
+  const report = checkGodFiles({
+    root,
+    allowlist: readAllowlist(allowlistPath),
+    failOnHard: isSet(flags, 'fail-on-hard'),
+  });
+  console.log(report.reported);
+  for (const finding of report.findings) {
+    console.log(`${finding.level === 'critical' ? 'CRITICAL' : 'WARN'} ${finding.lines} ${finding.file}`);
+  }
+  for (const finding of report.allowlisted) {
+    console.log(`ALLOWLISTED ${finding.lines} ${finding.file}`);
+  }
+  if (!report.passed) {
+    fail(`God-file check failed: run with --root ${root} to see the report.`);
+  }
+  return 0;
+}
+
+// Run only when this file is the entrypoint.
+//
+// The rules above are pure and the tests import them directly, so a module-level
+// call would shell out (and exit) during a test run. The URL comparison rather than
+// an unconditional call is the same guard Durable-DAV's init-secrets.ts uses, and
+// it is what keeps the rule modules importable — which is the whole reason they are
+// separate modules in the first place.
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exit(checkGodFilesCli(process.argv.slice(2)));
+}

package/src/scripts/ensure-spa-shell-stub.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env tsx
+/**
+ * Write a placeholder `apps/api/src/generated/spa-shell.ts` when it is absent.
+ *
+ * Provenance: Durable-DAV's `scripts/ensure-spa-shell-stub.mjs` and Edge-Sonic's
+ * `scripts/build/ensure-spa-shell-stub.ts`. The rule lives in `spa-shell.ts`; this
+ * is the entrypoint that runs it from `postinstall`.
+ *
+ * `pnpm install` runs this before `typegen` so the API worker typechecks in a
+ * fresh clone, where the real file has not been produced by the Vite build yet.
+ * It exits having done nothing when the file already exists, so a real build
+ * output is never overwritten — overwriting would erase the last build with a
+ * stub on the next install. The file is gitignored.
+ *
+ * Usage, from the repo root (typically wired as `postinstall`):
+ *
+ * ```bash
+ * pnpm exec tsx scripts/ensure-spa-shell-stub.ts [repo-root]
+ * ```
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureSpaShellStub } from './spa-shell';
+
+const REPOSITORY_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const root = process.argv[2] === undefined ? REPOSITORY_ROOT : path.resolve(process.argv[2]);
+
+const result = ensureSpaShellStub({ root });
+
+console.log(
+  result.created
+    ? `ensure-spa-shell-stub: created stub at ${result.path}`
+    : `ensure-spa-shell-stub: ${result.path} already present, left untouched`,
+);