Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/08-mobile-cli-storybook-sdk/cli-scaffolding.md
T

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ü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 <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 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 — modular, gute TS-DX, Sub-Command-Routing, auto-generierte Help-Pages. Alternative commander ist verbreiteter aber weniger TS-nativ.
  • Interactive Prompts: @clack/prompts — schöner Output, gute Cancel-Semantik (Ctrl+C wirft sauberes isCancel).
  • 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/promises direkt + pathe für cross-platform-paths.
  • Validation: zod fü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 foo patcht apps/web/app/sidebar/AppSidebar.tsx + apps/web/app/utils/permissions/.server/seedPermissions.ts per AST-Modification über ts-morph. 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 <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 mit prisma.<name>.findMany({ where: { tenantId } }))
      • apps/web/app/modules/<name>/services/<PascalName>Service.ts (Service-Layer mit assertTenantHasAccess Guards)
      • 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.tsx
      • apps/web/app/modules/<name>/components/<PascalName>Form.tsx
      • apps/web/app/modules/<name>/lib/<name>.utils.ts
      • apps/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ügen
      • apps/web/app/utils/permissions/.server/seedPermissions.ts → <prefix>.view, <prefix>.create, <prefix>.update, <prefix>.delete
      • apps/web/app/routes.ts → route("app/:tenant/<name>", ...) 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 <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>.tsx mit ./+types/<filename> import, requireAuth Loader, validateCSRFToken Action, ErrorBoundary Stub
      • apps/web/app/routes/<filename>.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/<filename>"
    • 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 <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 in Entity-Table, Properties in EntityProperty, Permissions, Default-Views, Route-Targets)
      • Wenn nicht --no-code: zusätzlich apps/web/app/modules/<name>/ 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 <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 typecheck grün nach Generation
    • Commit: 08-mobile/cli-scaffolding: add webhook event-type generator with registry patching
  9. (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.ts mit @toolctrl/plugin-sdk-Imports
      • <name>/src/example-hook.ts (Beispiel-Hook-Implementation)
      • <name>/scripts/build.ts, scripts/sign.ts, scripts/submit.ts
      • <name>/README.md mit 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-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: <source>.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/<name>-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 <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 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:
    # 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
    
  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/<filename> 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.