Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,341 @@
|
||||
# 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`](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 <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`](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 <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:
|
||||
```bash
|
||||
# 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.
|
||||
Reference in new issue
Block a user