@rexezuge/tooling 0.0.0-stage → 1.0.1

package/dist/scripts/backup/encrypt-backup.js

@@ -0,0 +1,98 @@
+#!/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, args) {
+    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'];
+const file = backupFileName(new Date());
+let plaintext;
+try {
+    plaintext = readFileSync(SOURCE_FILE, 'utf8');
+}
+catch (error) {
+    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;
+try {
+    compressed = execFileSync('xz', [...XZ_ARGS, '--keep', '--stdout', SOURCE_FILE], { maxBuffer: 512 * 1024 * 1024 });
+}
+catch (error) {
+    fail(`xz failed on ${SOURCE_FILE}: ${error instanceof Error ? error.message : String(error)}`);
+}
+let envelope;
+try {
+    envelope = await encryptSecret(compressed.toString('base64'), key);
+}
+catch (error) {
+    // 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);
+//# sourceMappingURL=encrypt-backup.js.map

package/dist/scripts/backup/encrypt-backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypt-backup.js","sourceRoot":"","sources":["../../../src/scripts/backup/encrypt-backup.ts"],"names":[],"mappings":"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"}

package/dist/scripts/backup/naming.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 declare 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 declare function backupStamp(date: Date): string;
+/** The full artifact name: `<prefix><stamp>.sql.xz.enc`. */
+export declare function backupFileName(date: Date): string;
+/**
+ * `YYYY-MM-DD`, `days` before `now`.
+ */
+export declare function retentionCutoff(now: Date, days: number): string;
+/**
+ * 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 declare function requireRetentionDays(): number;
+//# sourceMappingURL=naming.d.ts.map

package/dist/scripts/backup/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../../src/scripts/backup/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAG9C;AAED,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEjD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAO7C"}

package/dist/scripts/backup/naming.js

@@ -0,0 +1,58 @@
+/**
+ * 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) {
+    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) {
+    return `${BACKUP_FILE_PREFIX}${backupStamp(date)}.sql.xz.enc`;
+}
+/**
+ * `YYYY-MM-DD`, `days` before `now`.
+ */
+export function retentionCutoff(now, days) {
+    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() {
+    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;
+}
+//# sourceMappingURL=naming.js.map

package/dist/scripts/backup/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../../src/scripts/backup/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,cAAc,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAC/B,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,OAAO,GAAG,kBAAkB,GAAG,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC;AAChE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAS,EAAE,IAAY;IACrD,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,wDAAwD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/scripts/check-god-files.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const SOFT_LIMIT = 300;
+/** Default hard limit, as every source repo uses. */
+export declare const HARD_LIMIT = 400;
+/**
+ * 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 declare function shouldSkip(rel: string): boolean;
+/**
+ * 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 declare function isAllowlisted(rel: string, allowlist: readonly string[]): boolean;
+/**
+ * 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 declare function walk(root: string): string[];
+/**
+ * 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 declare function checkGodFiles(options: GodFileOptions): GodFileReport;
+/**
+ * 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 declare function readAllowlist(path: string): 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 declare function checkGodFilesCli(argv?: readonly string[]): number;
+//# sourceMappingURL=check-god-files.d.ts.map

package/dist/scripts/check-god-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-god-files.d.ts","sourceRoot":"","sources":["../../src/scripts/check-god-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAQH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,qDAAqD;AACrD,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,qDAAqD;AACrD,eAAO,MAAM,UAAU,MAAM,CAAC;AA+B9B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAW/C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAqB3C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CA+BpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,GAAG,MAAM,CA0BxF"}

package/dist/scripts/check-god-files.js

@@ -0,0 +1,271 @@
+/**
+ * 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';
+/** 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 = ['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) {
+    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, allowlist) {
+    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) {
+    const out = [];
+    const visit = (dir) => {
+        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) {
+    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 = [];
+    const allowlisted = [];
+    for (const rel of scanned) {
+        const lines = readFileSync(join(options.root, rel), 'utf8').split('\n').length;
+        if (lines <= soft)
+            continue;
+        const finding = { 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) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        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;
+}
+/**
+ * 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 = process.argv.slice(2)) {
+    // 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)));
+}
+//# sourceMappingURL=check-god-files.js.map