ci(catalog): fail build if catalog.generated.ts is stale vs source JSON (issue #19)

[johnnyhuy]

Closes #19.

Problem

The catalog flow is:

1. Edit src/main/{providers,gateways}/catalog.source.json
2. Run npm run gen:catalog
3. Push

Step 2 is easy to forget. Without it the app and CLI ship a stale catalog — types drift silently, new entries never reach the wizard.

The prebuild hook covers local builds but:

• Doesn't run for npm run typecheck / npm run lint
• Doesn't fail loudly if gen-catalog.mjs itself errors
• Doesn't surface the issue in CI without a build step succeeding first

Solution

A direct, byte-for-byte comparison runs in CI before typecheck. If the source JSON has changed but the generated TS hasn't, CI fails with a one-line fix.

Changes

scripts/gen-catalog.mjs (refactor)

• Exports SOURCES array and buildForSource(source) for reuse by the checker
• Computes a stable SHA-256 fingerprint (16-hex prefix) of the entries (sorted by id, then keys sorted within objects) and writes it into the file header:

  /**
   * GENERATED FILE — DO NOT EDIT BY HAND.
   * ...
   * fingerprint: 3d35ef2c7f6a58e0  (entries: 18)
   */
  

• The grep-friendly fingerprint lets future tools do cheap "is this stale?" checks without re-running the generator

scripts/check-catalog-stale.mjs (new)

• For each source in SOURCES:
  • Read on-disk catalog.generated.ts (or detect ENOENT separately)
  • Build the expected body via buildForSource(source)
  • Compare; if different, log path + heading + actionable hint
• Exit 0 if everything matches, 1 otherwise
• Distinct messages for "missing file" vs "out of sync"

npm + CI wiring

• package.json adds catalog:check script
• .github/workflows/ci.yml runs npm run catalog:check immediately after npm ci, before typecheck. The prebuild hook remains as a developer convenience.

Verification

$ node scripts/check-catalog-stale.mjs
✓ src/main/providers/catalog.generated.ts
✓ src/main/gateways/catalog.generated.ts

all catalog.generated.ts files are in sync with their sources
exit=0

# mutate JSON without regen
$ node scripts/check-catalog-stale.mjs
✗ .../src/main/providers/catalog.generated.ts
    catalog.generated.ts is stale vs src/main/providers/catalog.source.json.
    Run:  npm run gen:catalog

1 catalog(s) out of date.
exit=1

# delete a generated file
$ node scripts/check-catalog-stale.mjs
✗ .../src/main/gateways/catalog.generated.ts
    catalog.generated.ts is missing. Run: npm run gen:catalog

1 catalog(s) out of date.
exit=1

Local CI:

• npm run catalog:check ✓
• npm run typecheck ✓
• npm run lint ✓
• npm run test:extractor ✓ (carryover from feat(gateway): suggest URL from clipboard on Gateway step (issue #18) #20)
• npm run build ✓
• bun build src/index.ts --compile ✓ (CLI Mach-O arm64)

Out of scope

• Pinning the fingerprint as a separate CI assertion step (the == comparison catches any drift; the comment is for humans/git-diffs)
• Auto-running gen:catalog from CI (intentional — keep developer step explicit so the diff is reviewable)