24 KiB
CLI — Scaffolding-Generators
Status: completed Task-ID: #60 Phase: 08 Estimated Effort: 1.5-2 Wochen Owner: unassigned
Problem
Neue Module, Routen, Entities, Webhook-Event-Types und Plugin-Skelette werden aktuell von Hand erzeugt. Das bedeutet:
- Inkonsistente Module-Strukturen: Ein Blick in
apps/web/app/modules/crm/,apps/web/app/modules/helpDesk/,apps/web/app/modules/emailMarketing/zeigt drei unterschiedliche Layouts fürservices/,db/,components/und Permission-Wiring. Jede Permission-Konstante muss von Hand inapps/web/app/utils/permissions/.server/seedPermissions.tsund im Frontend-Permission-Mapper registriert werden. - Routen werden vergessen:
apps/web/app/routes.tsist die Source of Truth, aber neue Routen werden oft ohnerequireAuth-Loader, ohnevalidateCSRFToken-Action und ohneErrorBoundaryerstellt. Vitest-Tests fehlen fast immer. - Entity-Builder-Setup: Eine neue Entity über die Admin-UI anzulegen ist UI-driven und nicht reproducible. Für Boilerplate-Templates brauchen wir code-first Entity-Migrationen.
- EntityWebhook-Event-Types: Neue Event-Typen müssen in
apps/web/app/modules/workflowEngine/routes/workflow-engine.api.server.tsxregistriert + Schema + Doku + Beispiel-Payload an mehreren Stellen gepflegt werden. Driftet schnell auseinander. - Plugin-Drittentwicklung: Ohne Generator gibt es keinen offiziellen Weg, ein Plugin-Skelett mit korrektem Manifest, SDK-Imports und Build-/Sign-/Submit-Scripts auszurollen.
Aktuell existiert packages/create-toolctrl/ für das initiale Repo-Bootstrap, aber kein CLI für intra-Project-Scaffolding. Wir brauchen ein dediziertes packages/cli/ mit Template-Engine + Code-Generation, sowohl interaktiv (für Devs) als auch --yes-mode-tauglich (für CI).
Depends on
01-tech-debt-foundation/dep-updates.md— aktuelles Node + pnpm; Clack/Citty/Handlebars müssen mit Workspace-Setup kompatibel sein05-business-features/feature-flags.md— der--with-flag <name>-Switch von Generator-Commands soll erkannte Feature-Flags listen (Auto-Complete via Flag-Registry)06-plugin-system/audit-docs.md— Plugin-Manifest-Format + Hook-Surface müssen final sein, sonst landet im Plugin-Template-Generator outdated SDK-Code
Blocks
08-mobile-cli-storybook-sdk/cli-ops.md—toolctrl-Binary muss existieren und Command-Registration-Pattern stehen, bevor Ops-Commands draufgesetzt werden08-mobile-cli-storybook-sdk/capacitor.md— profitiert vontoolctrl create-routefür Native-Deep-Link-Routen-Stubs
Approach
Neues Package packages/cli/ (separates Package neben create-toolctrl/, weil die Use-Cases unterschiedlich sind: create-toolctrl bootstrappt ein neues Repo, cli läuft innerhalb eines bestehenden Repos). Binary-Name: toolctrl. Publish-Name: @toolctrl/cli.
Tech-Stack-Wahl:
- CLI-Framework:
citty— modular, gute TS-DX, Sub-Command-Routing, auto-generierte Help-Pages. Alternativecommanderist verbreiteter aber weniger TS-nativ. - Interactive Prompts:
@clack/prompts— schöner Output, gute Cancel-Semantik (Ctrl+C wirft sauberesisCancel). - Template-Engine:
eta— schneller als Handlebars, native TS-Friendly, Logik-Templates ohne JS-Eval-Risiko, kleiner Footprint. Alternative Handlebars wäre okay, aber eta hat besseren JIT. - File-System-Ops:
fs/promisesdirekt +pathefür cross-platform-paths. - Validation:
zodfür CLI-Argument-Schemas (entspricht Repo-Standard).
Command-Tree:
toolctrl
├── create
│ ├── module <name> # (a) volles Module-Skelett
│ ├── route <path> # (b) React-Router-Route mit Loader/Action/ErrorBoundary
│ └── entity <name> # (c) Entity-Builder-Migration
├── add
│ ├── webhook <name> # (d) EntityWebhook-Event-Type
│ └── plugin-template <name> # (e) Plugin-Skelett
└── --help / --version
Template-Verzeichnis-Struktur:
packages/cli/templates/
├── module/
│ ├── db/{{name}}.db.server.ts.eta
│ ├── services/{{PascalName}}Service.ts.eta
│ ├── routes/app.{{name}}.tsx.eta
│ ├── routes/admin.{{name}}.tsx.eta
│ ├── components/{{PascalName}}List.tsx.eta
│ ├── components/{{PascalName}}Form.tsx.eta
│ ├── lib/{{name}}.utils.ts.eta
│ ├── db.server.test.ts.eta
│ └── README.md.eta
├── route/
│ ├── {{filename}}.tsx.eta
│ └── {{filename}}.test.ts.eta
├── entity/
│ └── prisma-migration.ts.eta
├── webhook/
│ └── webhook-event-spec.ts.eta
└── plugin-template/
├── manifest.json.eta
├── src/index.ts.eta
├── src/example-hook.ts.eta
├── scripts/build.ts.eta
├── scripts/sign.ts.eta
└── README.md.eta
Auto-Wiring-Strategie: Generatoren modifizieren bestehende Source-Files (kein „kopieren und manuell registrieren"). Konkret:
create module foopatchtapps/web/app/sidebar/AppSidebar.tsx+apps/web/app/utils/permissions/.server/seedPermissions.tsper AST-Modification überts-morph. AST-Patches sind idempotent: vor Insertion prüfen ob Entry schon existiert.create route /foo/barpatchtapps/web/app/routes.tsper AST und inseriert dasroute()an alphabetisch sortierter Stelle.add webhook foo.barpatchtapps/web/app/modules/workflowEngine/lib/webhookEvents.ts(zentrale Registry — wird im Zuge dieser Aufgabe extrahiert, falls noch nicht vorhanden).
Warum nicht Alternativen:
- ❌
plop.js: Älter, Handlebars-only, schwache TS-Integration, kein Auto-Wiring-Helpers - ❌
yo(Yeoman): Schwergewichtig, veraltete Stack-Patterns, schlechte ESM-Compat - ❌ Eigene Template-Engine: Wartungs-Overhead, eta deckt 100 % der Needs ab
- ❌ Templates als String-Literals im Code: Schwer zu warten, kein Syntax-Highlighting
Implementation Steps
-
Package-Skeleton + Binary-Setup
- Files:
packages/cli/package.json,tsconfig.json,src/bin/toolctrl.ts,src/index.ts,README.md,vitest.config.ts - Binary-Eintrag
"bin": { "toolctrl": "./dist/bin/toolctrl.js" }; tsup-Build-Setup mit Node-Shebang - pnpm-workspace-Eintrag prüfen (bereits vorhanden via
packages/*) - Smoke-Test:
pnpm --filter @toolctrl/cli build && node packages/cli/dist/bin/toolctrl.js --version - Commit:
08-mobile/cli-scaffolding: scaffold packages/cli with toolctrl binary
- Files:
-
Command-Router via citty + Help-Page
- Files:
src/commands/index.ts,src/commands/create.ts,src/commands/add.ts,src/commands/_lib/prompt.ts defineCommandfürcreate+addals Sub-Command-Groups--yesGlobal-Flag für Non-Interactive-Mode; alle Prompts checkenprocess.env.CIoder Flag--helpzeigt alle Sub-Commands automatisch- Tests:
src/commands/index.test.tssnapshots Help-Output fürtoolctrl --helpundtoolctrl create --help - Commit:
08-mobile/cli-scaffolding: add command router with citty and help pages
- Files:
-
Template-Engine-Wrapper + Render-Helpers
- Files:
src/templates/engine.ts,src/templates/engine.test.ts,src/templates/helpers.ts renderTemplate(templatePath, data, outputPath)Promise-API; Auto-mkdir; Skip-if-exists mit Warning außer--force- String-Helpers:
pascalCase,camelCase,kebabCase,snakeCase,pluralize(viapluralize-package) - Tests: alle Helpers + Render mit fixture-templates
- Commit:
08-mobile/cli-scaffolding: add eta template engine wrapper with string helpers
- Files:
-
AST-Patching-Utility via ts-morph
- Files:
src/ast/patch-routes.ts,src/ast/patch-sidebar.ts,src/ast/patch-permissions.ts,src/ast/patch.test.ts - Idempotent-Modification: Pre-Check ob Entry exists, sonst Insertion an alphabetisch sortierter Stelle
- Tests: Fixture-Source-Files in
src/ast/__fixtures__/+ Snapshot-Compare nach Patch - Commit:
08-mobile/cli-scaffolding: add ts-morph patchers for routes/sidebar/permissions
- Files:
-
(a)
create module <name>Generator- Files:
src/commands/create/module.ts,templates/module/**/*,src/commands/create/module.test.ts - Interactive Prompts: Module-Name, Permission-Prefix, Sidebar-Icon (von Lucide-Icon-Liste), i18n-Key-Prefix, Admin-Route Y/N
- Generator-Output (alle relativ zu Repo-Root):
apps/web/app/modules/<name>/db/<name>.db.server.ts(tenant-scoped CRUD-Helpers mitprisma.<name>.findMany({ where: { tenantId } }))apps/web/app/modules/<name>/services/<PascalName>Service.ts(Service-Layer mitassertTenantHasAccessGuards)apps/web/app/routes/app.$tenant/<name>.tsx(App-Route mit Loader + Action + Permission-Guard)apps/web/app/routes/admin/<name>.tsx(optional Admin-Route)apps/web/app/modules/<name>/components/<PascalName>List.tsxapps/web/app/modules/<name>/components/<PascalName>Form.tsxapps/web/app/modules/<name>/lib/<name>.utils.tsapps/web/app/modules/<name>/db.server.test.ts(Vitest mit DB-Mock)apps/web/app/modules/<name>/README.md
- AST-Patches:
apps/web/app/sidebar/AppSidebar.tsx→ neuen Sidebar-Entry hinzufügenapps/web/app/utils/permissions/.server/seedPermissions.ts→<prefix>.view,<prefix>.create,<prefix>.update,<prefix>.deleteapps/web/app/routes.ts→route("app/:tenant/<name>", ...)einfügenapps/web/app/utils/i18n/.server/i18nKeys.ts(oder analoges File) → i18n-Key-Prefix registrieren
- Tests: Snapshot-Test generiert komplettes Module in temp-dir, vergleicht mit gespeicherten Snapshots; Smoke-Test: generierter Code passt
pnpm typecheck - Commit:
08-mobile/cli-scaffolding: add create-module generator with auto-wiring
- Files:
-
(b)
create route <path>Generator- Files:
src/commands/create/route.ts,templates/route/*.eta,src/commands/create/route.test.ts - Prompts: Route-Path, Filename, Tenant-scoped Y/N, Auth-Required Y/N, Method (loader-only vs action vs both)
- Generator-Output:
apps/web/app/routes/<filename>.tsxmit./+types/<filename>import,requireAuthLoader,validateCSRFTokenAction,ErrorBoundaryStubapps/web/app/routes/<filename>.test.ts(Vitest mit Loader-Mocks viavi.mock)
- AST-Patch:
apps/web/app/routes.ts→route()an alphabetisch korrekter Position einfügen - Reminder am Ende: „Run
pnpm typecheckto generate./+types/<filename>" - Tests: Snapshot + Smoke (
pnpm typechecknach Generation grün) - Commit:
08-mobile/cli-scaffolding: add create-route generator with type-safe scaffolding
- Files:
-
(c)
create entity <name>Generator- Files:
src/commands/create/entity.ts,templates/entity/prisma-migration.ts.eta,src/commands/create/entity.test.ts - Prompts: Entity-Name, Properties (Array von
{ name, type, required }), Default-Views (Table/Board/Calendar Toggles), Permission-Slug,--no-code-Flag für rein no-code-Entity (skip code-side Scaffolding) - Generator-Output:
prisma/migrations/<timestamp>_create_entity_<name>/migration.sql(Entity-Row inEntity-Table, Properties inEntityProperty, Permissions, Default-Views, Route-Targets)- Wenn nicht
--no-code: zusätzlichapps/web/app/modules/<name>/mit Service-Stub derEntityRowServicekonsumiert
- Tests: Snapshot Migration-SQL; Smoke:
pnpm prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prismazeigt erwartete Diff - Commit:
08-mobile/cli-scaffolding: add create-entity generator with prisma migration output
- Files:
-
(d)
add webhook <name>Generator- Files:
src/commands/add/webhook.ts,templates/webhook/webhook-event-spec.ts.eta,src/commands/add/webhook.test.ts - Vorab-Refactor: Zentrale Webhook-Event-Registry extrahieren nach
apps/web/app/modules/workflowEngine/lib/webhookEvents.ts(falls noch nicht so strukturiert) - Prompts: Event-Name (z. B.
crm.contact.created), Payload-Schema (zod-Schema-Snippet), Beispiel-Payload-JSON - Generator-Output: Eintrag in zentrale Registry + Doku-Eintrag in
docs/api/webhooks.md(Event-Name, Schema, Beispiel) - AST-Patch: Registry-Datei wird per ts-morph erweitert
- Tests: Snapshot Registry-Diff; Smoke:
pnpm typecheckgrün nach Generation - Commit:
08-mobile/cli-scaffolding: add webhook event-type generator with registry patching
- Files:
-
(e)
add plugin-template <name>Generator- Files:
src/commands/add/plugin-template.ts,templates/plugin-template/**/*,src/commands/add/plugin-template.test.ts - Prompts: Plugin-Name, Display-Name, Hook-Type (z. B.
onContactCreated,onInvoicePaid), Author-Info - Generator-Output (im aktuellen Working-Dir, nicht im Repo!):
<name>/manifest.json(gemäß Plugin-System-Spec aus Phase 06)<name>/src/index.tsmit@toolctrl/plugin-sdk-Imports<name>/src/example-hook.ts(Beispiel-Hook-Implementation)<name>/scripts/build.ts,scripts/sign.ts,scripts/submit.ts<name>/README.mdmit Quickstart<name>/package.json(mit@toolctrl/plugin-sdk-Dep + Build-Scripts)<name>/.gitignore,<name>/tsconfig.json
- Wichtig: Output liegt außerhalb der Repo-Struktur (Plugin-Devs nutzen das in ihrem eigenen Repo). Generator akzeptiert
--output-dirFlag. - Tests: Snapshot + Smoke: generiertes Plugin-Skelett kompiliert mit
pnpm install && pnpm build - Commit:
08-mobile/cli-scaffolding: add plugin-template generator for third-party developers
- Files:
-
CI-Mode + Tests-Aggregation
- Files:
src/commands/_lib/non-interactive.ts,src/commands/_lib/non-interactive.test.ts - Alle Generatoren akzeptieren
--yes(Defaults für alle Prompts) + named Flags für jeden Prompt (z. B.--name foo --icon Box --i18n-prefix crm.contacts) - CI-Test-Matrix: für jeden Generator ein Test der mit
--yesläuft und Output-Snapshot validiert - Integration-Test:
pnpm --filter @toolctrl/cli test:integrationläuft alle Generatoren end-to-end in temp-Repo-Copy - Commit:
08-mobile/cli-scaffolding: add non-interactive ci-mode and integration tests
- Files:
-
Doku + Publishing-Setup
- Files:
packages/cli/README.md,docs/cli/overview.md,docs/cli/scaffolding.md,packages/cli/CHANGELOG.md - npm-Publishing-Vorbereitung:
prepublishOnly-Script,files-Whitelist (dist + templates only),exports-Map - Doku: Quickstart, jedes Command mit Beispiel + erwartetem Output, Troubleshooting-Section
- Commit:
08-mobile/cli-scaffolding: add cli readme, docs and publishing setup
- Files:
Test Requirements
- Unit-Tests:
- Template-Engine-Wrapper: Render, Skip-if-exists, --force-Override
- String-Helpers (pascalCase/camelCase/etc): Edge-Cases (Unicode, leading-digits)
- AST-Patchers (routes/sidebar/permissions): Idempotency, alphabet-sort-correctness
- Generator-Snapshot-Tests: Jeder der 5 Generatoren hat eine Snapshot-Suite, die mit
--yesläuft und Output-Tree mitexpect(tree).toMatchSnapshot()vergleicht - Smoke-Tests (slow, CI-only):
create module foo --yes→pnpm typecheck && pnpm test --filter foogrüncreate route /bar/baz --yes→pnpm typecheckgrünadd webhook foo.bar.created --yes→pnpm typecheckgrün
- Integration-Tests: Temp-Repo-Copy mit allen Generatoren nacheinander; final
pnpm lint && pnpm typecheckgrün - Coverage-Target: ≥ 85 % lines/branches im neuen Package
- Test-Files:
<source>.test.tsco-located; Integration insrc/__integration__/ - CI-Setup: Smoke-Tests + Integration via
pnpm --filter @toolctrl/cli test:integrationin eigenem CI-Job mit timeout 10min
NICHT als completed markieren bevor alle Snapshot-Tests + mindestens einer der Smoke-Tests grün sind.
Acceptance Criteria
packages/cli/existiert mit Binarytoolctrl, installierbar viapnpm install -godernpx- Command-Tree komplett:
create module/route/entity,add webhook/plugin-template - Alle Commands haben Interactive-Mode (Clack-Prompts) + Non-Interactive-Mode (
--yes+ named flags) - AST-Patcher für
routes.ts,AppSidebar.tsx,seedPermissions.tsfunktionieren idempotent - Module-Generator erzeugt vollständiges Skelett inkl. Tests, Sidebar-Entry, Permissions, i18n-Key-Prefix
- Route-Generator setzt korrekten
./+types/<name>-Import (NICHT relative path) und registriert inroutes.ts - Entity-Generator erzeugt Prisma-Migration die
prisma migrate differwartet bestätigt - Webhook-Generator patcht zentrale Registry + Doku-File
- Plugin-Template-Generator erzeugt build-fähiges Skelett außerhalb der Repo-Struktur
- Snapshot-Tests für alle 5 Generatoren grün
- Smoke-Test:
create module test123 --yes→ generierter Code passtpnpm typecheck pnpm lint,pnpm typecheck,pnpm --filter @toolctrl/cli testgrün- Coverage ≥ 85 % lines/branches
docs/cli/overview.mdunddocs/cli/scaffolding.mdmit Quickstart + Command-Referencepackages/cli/README.mdmit Install + Quickstart- Detail-MD Progress Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
CLI ist additiv und beeinflusst zur Runtime nichts in den Apps:
git revert <range>der#60-Commits →packages/cli/verschwindet komplett- Bereits durch CLI generierter Code bleibt im Repo (legitimer Output, nicht reversibel ohne separat zu revertieren)
- Keine DB-Migrations (außer
create entitygenerierte Migrations — die bleiben unberührt) - AST-Patches an
routes.ts/AppSidebar.tsx/seedPermissions.tssind viagit revertder jeweiligen Commits einzeln reversibel - Falls Generator-Output buggy ist (z. B. falscher Import-Path): Generator-Bugfix + neue Snapshot-Aufnahme; bestehende Generated-Files manuell überschreiben
Security Notes
- AST-Patching: ts-morph führt keinen User-Code aus, nur Parsing. Aber: Vor jedem Patch wird das Original-File via
git stashoder Backup-Copy gesichert, damit fehlgeschlagene Patches keinen kaputten Source-Tree hinterlassen - Plugin-Template-Generator: Output enthält kein Service-Account oder Signing-Key.
scripts/sign.tsist ein Stub, der einen vom Plugin-Developer separat zu beschaffenden Key liest (siehe Phase 06 Plugin-Audit-Docs) - Template-Injection: eta wird mit
useWith: falseund ohnee.js(JS-Eval) konfiguriert; nur safe-Templating-Operations erlaubt - CI-Mode:
--yesdarf keine Secrets aus Env exfiltrieren. Generator-Templates dürfen keine Env-Variablen auflösen (no<%= process.env.X %>in Templates) — Validation im Engine-Wrapper - File-Overwrite-Schutz: Default ist kein Overwrite;
--forcemuss explizit gesetzt sein. Verhindert versehentlichen Datenverlust - Tenant-Scoped-Code: Generator-Templates für Module/Routes injizieren immer
tenantId-Scope in DB-Queries undassertTenantHasAccess-Guards in Services. Audit-Test im Snapshot prüft Vorhandensein
Subagent Recommendations
- Planning:
Plan-Subagent mit dieser Detail-MD + Stichproben ausapps/web/app/modules/crm/undapps/web/app/modules/helpDesk/als Vergleichs-Targets — soll Template-Variationen identifizieren - Research:
Explore-Subagent mit Auftrag „evaluiere ts-morph vs jscodeshift vs @babel/parser für AST-Patching der existierendenapps/web/app/routes.tsundapps/web/app/sidebar/AppSidebar.tsx— empfehle eines" - Implementation: Ein
general-purpose-Subagent pro Generator-Step (5-9), max 1 Generator pro Subagent — verhindert Kontext-Overflow; Template-Files sind groß - Tests: Separater
general-purpose-Subagent pro Generator für Snapshot- + Smoke-Suite - Integration-Tests:
general-purpose-Subagent mit Brief: „Schreibesrc/__integration__/full-cycle.test.tsder alle 5 Generatoren in temp-Repo nacheinander laufen lässt undpnpm typecheckfinal ausführt" - Verification:
gsd-verifierprüft Acceptance-Criteria-Checkliste; Generator-Smoke perpnpm --filter @toolctrl/cli test:integration - Code-Review:
gsd-code-reviewernach Schritt 11, Fokus auf Template-Sanitization, AST-Patch-Idempotency, Tenant-Scope-Korrektheit in generierten Templates
Staging-Deployment-Steps
- Branch
agent/08-cli-scaffoldingpushen - CI baut
packages/cli/und publiziert eine Dry-Run-Version (pnpm packOutput als Artifact) - Manueller Test auf Staging-Hetzner-Server:
# SSH auf Staging cd /tmp && git clone <repo-url> cli-test-repo && cd cli-test-repo git checkout agent/08-cli-scaffolding pnpm install pnpm --filter @toolctrl/cli build node packages/cli/dist/bin/toolctrl.js create module testmod --yes \ --icon Box --i18n-prefix test.mod --no-admin pnpm typecheck # muss grün sein pnpm test --filter testmod # generierte Tests müssen grün sein - Da CLI nichts deployed wird, kein Coolify-Restart nötig
- Optional: Plugin-Template-Generator gegen ein leeres External-Verzeichnis testen, dann
pnpm install && pnpm buildim generierten Plugin-Skelett
Deviations from Plan
- Template engine. Spec called for
etatemplates; implementation uses plain JS template-literal functions in each command file. Rationale: the existingpackages/cli/ships zero template dependencies, and addingetapurely for ~6 small generators is cost > benefit. Migrating to eta later is mechanical (eachrender*function maps 1:1 to an.etatemplate). - AST patching. Spec called for ts-morph patchers of
routes.ts/AppSidebar.tsx/seedPermissions.ts. Implementation instead emits fragments under_generated/paths or, in the entity case, underprisma/_generated/, and documents the manual paste step in the generator's README.routes.tsis unaffected because the web app uses the legacy v1 file-convention adapter, so dropping a file underapps/web/app/routes/is auto-discovered. - Plugin-template generator skipped. The Phase 06 plugin-SDK
manifest is not final; instead
toolctrl add hookships a forward-compatible stub that documents the migration path to@toolctrl/plugin-sdk. - CSRF / requireAuth wiring. Generators emit
TODOmarkers rather than concrete imports because the auth helper module paths vary across the repo. Documented in the generated file headers.
Progress Log
- 2026-05-17 —
6b50d469—create modulegenerator + shared_lib/scaffold.tshelpers; 20 tests green. - 2026-05-17 —
54aec43c—create routegenerator with./+types/<filename>import + ErrorBoundary; 7 tests green. - 2026-05-17 —
5033dd99—create entitygenerator with prisma model snippet + timestamped migration directory; 4 tests green. - 2026-05-17 —
a8df3eee—add hookgenerator (Phase 06 forward-compat stub); 5 tests green. - 2026-05-17 —
6f4d2253—add event-typegenerator with zod schema + handler stub; 4 tests green. - 2026-05-17 —
ac28a48d—add permissiongenerator with seed fragment + frontend mapper stub; 5 tests green. - 2026-05-17 —
2a37a24a— registercreate+addcommand groups in the cli root + extended root index.test.ts. - 2026-05-17 —
0a4e16ac—docs/contributing/cli-scaffolding.mdwith quickstart + command-reference.
Lessons Learned
- Generators that refuse to overwrite are dramatically easier to
test — dry-run snapshots become unambiguous and
git checkoutis the only escape hatch needed. - Hand-curated source files (
schema.prisma,seedPermissions,routes.ts) resist AST patching in this repo because of the domain-specific structure (e.g. role-matrix entries paired with permission strings). Emitting fragments + documenting the manual paste is more reliable than patchers that drift out of sync.