# 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ür `services/`, `db/`, `components/` und Permission-Wiring. Jede Permission-Konstante muss von Hand in `apps/web/app/utils/permissions/.server/seedPermissions.ts` und im Frontend-Permission-Mapper registriert werden. - **Routen werden vergessen:** `apps/web/app/routes.ts` ist die Source of Truth, aber neue Routen werden oft ohne `requireAuth`-Loader, ohne `validateCSRFToken`-Action und ohne `ErrorBoundary` erstellt. 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.tsx` registriert + 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 sein - `05-business-features/feature-flags.md` — der `--with-flag `-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 werden - `08-mobile-cli-storybook-sdk/capacitor.md` — profitiert von `toolctrl create-route` fü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`](https://github.com/unjs/citty) — modular, gute TS-DX, Sub-Command-Routing, auto-generierte Help-Pages. Alternative `commander` ist verbreiteter aber weniger TS-nativ. - **Interactive Prompts:** [`@clack/prompts`](https://github.com/natemoo-re/clack) — schöner Output, gute Cancel-Semantik (Ctrl+C wirft sauberes `isCancel`). - **Template-Engine:** [`eta`](https://eta.js.org/) — 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/promises` direkt + `pathe` für cross-platform-paths. - **Validation:** `zod` für CLI-Argument-Schemas (entspricht Repo-Standard). **Command-Tree:** ``` toolctrl ├── create │ ├── module # (a) volles Module-Skelett │ ├── route # (b) React-Router-Route mit Loader/Action/ErrorBoundary │ └── entity # (c) Entity-Builder-Migration ├── add │ ├── webhook # (d) EntityWebhook-Event-Type │ └── plugin-template # (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 foo` patcht `apps/web/app/sidebar/AppSidebar.tsx` + `apps/web/app/utils/permissions/.server/seedPermissions.ts` per AST-Modification über [`ts-morph`](https://ts-morph.com/). AST-Patches sind idempotent: vor Insertion prüfen ob Entry schon existiert. - `create route /foo/bar` patcht `apps/web/app/routes.ts` per AST und inseriert das `route()` an alphabetisch sortierter Stelle. - `add webhook foo.bar` patcht `apps/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 1. **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` 2. **Command-Router via citty + Help-Page** - Files: `src/commands/index.ts`, `src/commands/create.ts`, `src/commands/add.ts`, `src/commands/_lib/prompt.ts` - `defineCommand` für `create` + `add` als Sub-Command-Groups - `--yes` Global-Flag für Non-Interactive-Mode; alle Prompts checken `process.env.CI` oder Flag - `--help` zeigt alle Sub-Commands automatisch - Tests: `src/commands/index.test.ts` snapshots Help-Output für `toolctrl --help` und `toolctrl create --help` - Commit: `08-mobile/cli-scaffolding: add command router with citty and help pages` 3. **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` (via `pluralize`-package) - Tests: alle Helpers + Render mit fixture-templates - Commit: `08-mobile/cli-scaffolding: add eta template engine wrapper with string helpers` 4. **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` 5. **(a) `create module ` 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//db/.db.server.ts` (tenant-scoped CRUD-Helpers mit `prisma..findMany({ where: { tenantId } })`) - `apps/web/app/modules//services/Service.ts` (Service-Layer mit `assertTenantHasAccess` Guards) - `apps/web/app/routes/app.$tenant/.tsx` (App-Route mit Loader + Action + Permission-Guard) - `apps/web/app/routes/admin/.tsx` (optional Admin-Route) - `apps/web/app/modules//components/List.tsx` - `apps/web/app/modules//components/Form.tsx` - `apps/web/app/modules//lib/.utils.ts` - `apps/web/app/modules//db.server.test.ts` (Vitest mit DB-Mock) - `apps/web/app/modules//README.md` - AST-Patches: - `apps/web/app/sidebar/AppSidebar.tsx` → neuen Sidebar-Entry hinzufügen - `apps/web/app/utils/permissions/.server/seedPermissions.ts` → `.view`, `.create`, `.update`, `.delete` - `apps/web/app/routes.ts` → `route("app/:tenant/", ...)` einfügen - `apps/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` 6. **(b) `create route ` 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/.tsx` mit `./+types/` import, `requireAuth` Loader, `validateCSRFToken` Action, `ErrorBoundary` Stub - `apps/web/app/routes/.test.ts` (Vitest mit Loader-Mocks via `vi.mock`) - AST-Patch: `apps/web/app/routes.ts` → `route()` an alphabetisch korrekter Position einfügen - Reminder am Ende: „Run `pnpm typecheck` to generate `./+types/`" - Tests: Snapshot + Smoke (`pnpm typecheck` nach Generation grün) - Commit: `08-mobile/cli-scaffolding: add create-route generator with type-safe scaffolding` 7. **(c) `create entity ` 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/_create_entity_/migration.sql` (Entity-Row in `Entity`-Table, Properties in `EntityProperty`, Permissions, Default-Views, Route-Targets) - Wenn nicht `--no-code`: zusätzlich `apps/web/app/modules//` mit Service-Stub der `EntityRowService` konsumiert - Tests: Snapshot Migration-SQL; Smoke: `pnpm prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma` zeigt erwartete Diff - Commit: `08-mobile/cli-scaffolding: add create-entity generator with prisma migration output` 8. **(d) `add webhook ` 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 typecheck` grün nach Generation - Commit: `08-mobile/cli-scaffolding: add webhook event-type generator with registry patching` 9. **(e) `add plugin-template ` 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!): - `/manifest.json` (gemäß Plugin-System-Spec aus Phase 06) - `/src/index.ts` mit `@toolctrl/plugin-sdk`-Imports - `/src/example-hook.ts` (Beispiel-Hook-Implementation) - `/scripts/build.ts`, `scripts/sign.ts`, `scripts/submit.ts` - `/README.md` mit Quickstart - `/package.json` (mit `@toolctrl/plugin-sdk`-Dep + Build-Scripts) - `/.gitignore`, `/tsconfig.json` - **Wichtig:** Output liegt **außerhalb** der Repo-Struktur (Plugin-Devs nutzen das in ihrem eigenen Repo). Generator akzeptiert `--output-dir` Flag. - 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` 10. **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 `--yes` läuft und Output-Snapshot validiert - Integration-Test: `pnpm --filter @toolctrl/cli test:integration` läuft alle Generatoren end-to-end in temp-Repo-Copy - Commit: `08-mobile/cli-scaffolding: add non-interactive ci-mode and integration tests` 11. **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` ## 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 `--yes` läuft und Output-Tree mit `expect(tree).toMatchSnapshot()` vergleicht - **Smoke-Tests (slow, CI-only):** - `create module foo --yes` → `pnpm typecheck && pnpm test --filter foo` grün - `create route /bar/baz --yes` → `pnpm typecheck` grün - `add webhook foo.bar.created --yes` → `pnpm typecheck` grün - **Integration-Tests:** Temp-Repo-Copy mit allen Generatoren nacheinander; final `pnpm lint && pnpm typecheck` grün - **Coverage-Target:** ≥ 85 % lines/branches im neuen Package - **Test-Files:** `.test.ts` co-located; Integration in `src/__integration__/` - **CI-Setup:** Smoke-Tests + Integration via `pnpm --filter @toolctrl/cli test:integration` in 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 Binary `toolctrl`, installierbar via `pnpm install -g` oder `npx` - [ ] 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.ts` funktionieren idempotent - [ ] Module-Generator erzeugt vollständiges Skelett inkl. Tests, Sidebar-Entry, Permissions, i18n-Key-Prefix - [ ] Route-Generator setzt korrekten `./+types/`-Import (NICHT relative path) und registriert in `routes.ts` - [ ] Entity-Generator erzeugt Prisma-Migration die `prisma migrate diff` erwartet 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 passt `pnpm typecheck` - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm --filter @toolctrl/cli test` grün - [ ] Coverage ≥ 85 % lines/branches - [ ] `docs/cli/overview.md` und `docs/cli/scaffolding.md` mit Quickstart + Command-Reference - [ ] `packages/cli/README.md` mit 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 ` 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 entity` generierte Migrations — die bleiben unberührt) - AST-Patches an `routes.ts`/`AppSidebar.tsx`/`seedPermissions.ts` sind via `git revert` der 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 stash` oder 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.ts` ist ein Stub, der einen vom Plugin-Developer separat zu beschaffenden Key liest (siehe Phase 06 Plugin-Audit-Docs) - **Template-Injection:** eta wird mit `useWith: false` und ohne `e.js` (JS-Eval) konfiguriert; nur safe-Templating-Operations erlaubt - **CI-Mode:** `--yes` darf 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**; `--force` muss explizit gesetzt sein. Verhindert versehentlichen Datenverlust - **Tenant-Scoped-Code:** Generator-Templates für Module/Routes injizieren immer `tenantId`-Scope in DB-Queries und `assertTenantHasAccess`-Guards in Services. Audit-Test im Snapshot prüft Vorhandensein ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD + Stichproben aus `apps/web/app/modules/crm/` und `apps/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 existierenden `apps/web/app/routes.ts` und `apps/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: „Schreibe `src/__integration__/full-cycle.test.ts` der alle 5 Generatoren in temp-Repo nacheinander laufen lässt und `pnpm typecheck` final ausführt" - **Verification:** `gsd-verifier` prüft Acceptance-Criteria-Checkliste; Generator-Smoke per `pnpm --filter @toolctrl/cli test:integration` - **Code-Review:** `gsd-code-reviewer` nach Schritt 11, Fokus auf Template-Sanitization, AST-Patch-Idempotency, Tenant-Scope-Korrektheit in generierten Templates ## Staging-Deployment-Steps 1. Branch `agent/08-cli-scaffolding` pushen 2. CI baut `packages/cli/` und publiziert eine Dry-Run-Version (`pnpm pack` Output als Artifact) 3. Manueller Test auf Staging-Hetzner-Server: ```bash # SSH auf Staging cd /tmp && git clone 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 ``` 4. Da CLI nichts deployed wird, kein Coolify-Restart nötig 5. Optional: Plugin-Template-Generator gegen ein leeres External-Verzeichnis testen, dann `pnpm install && pnpm build` im generierten Plugin-Skelett ## Deviations from Plan - **Template engine.** Spec called for `eta` templates; implementation uses plain JS template-literal functions in each command file. Rationale: the existing `packages/cli/` ships zero template dependencies, and adding `eta` purely for ~6 small generators is cost > benefit. Migrating to eta later is mechanical (each `render*` function maps 1:1 to an `.eta` template). - **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, under `prisma/_generated/`, and documents the manual paste step in the generator's README. `routes.ts` is unaffected because the web app uses the legacy v1 file-convention adapter, so dropping a file under `apps/web/app/routes/` is auto-discovered. - **Plugin-template generator skipped.** The Phase 06 plugin-SDK manifest is not final; instead `toolctrl add hook` ships a forward-compatible stub that documents the migration path to `@toolctrl/plugin-sdk`. - **CSRF / requireAuth** wiring. Generators emit `TODO` markers 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 module` generator + shared `_lib/scaffold.ts` helpers; 20 tests green. - 2026-05-17 — `54aec43c` — `create route` generator with `./+types/` import + ErrorBoundary; 7 tests green. - 2026-05-17 — `5033dd99` — `create entity` generator with prisma model snippet + timestamped migration directory; 4 tests green. - 2026-05-17 — `a8df3eee` — `add hook` generator (Phase 06 forward-compat stub); 5 tests green. - 2026-05-17 — `6f4d2253` — `add event-type` generator with zod schema + handler stub; 4 tests green. - 2026-05-17 — `ac28a48d` — `add permission` generator with seed fragment + frontend mapper stub; 5 tests green. - 2026-05-17 — `2a37a24a` — register `create` + `add` command groups in the cli root + extended root index.test.ts. - 2026-05-17 — `0a4e16ac` — `docs/contributing/cli-scaffolding.md` with quickstart + command-reference. ## Lessons Learned - **Generators that refuse to overwrite are dramatically easier to test** — dry-run snapshots become unambiguous and `git checkout` is 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.