336 lines
24 KiB
Markdown
336 lines
24 KiB
Markdown
# CLI — Ops-Commands (Doctor / Tenant-Migration / Impersonate)
|
|
|
|
**Status:** completed
|
|
**Task-ID:** #61
|
|
**Phase:** 08
|
|
**Estimated Effort:** 1.5-2 Wochen
|
|
**Owner:** agent/08-cli-ops
|
|
|
|
## Problem
|
|
|
|
Operative Tätigkeiten am Boilerplate erfordern aktuell Tribal-Knowledge:
|
|
|
|
- **Lokales Dev-Setup debuggen:** „Warum funktioniert mein Login nicht?" — Antwort kann sein: fehlende Migration, falsche Node-Version, abgelaufene `.env`, Docker-Container down, Redis nicht erreichbar, Lock-File stale. Es gibt keinen einzelnen Befehl der das checkt.
|
|
- **Tenant zwischen Umgebungen migrieren:** Customer auf Staging testet, will auf Production „mit allem was angefallen ist". Aktuell: manuelle Prisma-Studio-Exports, S3-Sync-Scripts, Tenant-ID-Remapping per SQL — fehleranfällig, nicht resumable.
|
|
- **Tenant-User-Debugging:** Support-Ticket „bei mir ist X kaputt". Engineer muss als der User einloggen, hat aber kein Passwort. Aktuell: temporäres Password-Reset und hoffen dass der Customer es danach wieder ändert. Sicherheitsproblem + Audit-Loch.
|
|
|
|
Diese drei Probleme lösen wir mit Ops-Subcommands der `toolctrl`-CLI (aus `#60`).
|
|
|
|
## Depends on
|
|
|
|
- `08-mobile-cli-storybook-sdk/cli-scaffolding.md` — `toolctrl`-Binary + Command-Router müssen existieren; Ops-Commands docken als neue Sub-Command-Group `ops` an
|
|
- `03-scaling-infrastructure/backup-cli.md` — `toolctrl migrate-tenant` reusiert den Snapshot-Mechanismus aus dem Backup-CLI. Ohne diesen Task müsste die Migration einen eigenen Snapshot-Code mitbringen
|
|
- `03-scaling-infrastructure/tenant-snapshot.md` — Tenant-Snapshot-Logik (single-tenant-Snapshot mit allen relationalen Children) ist Foundation für die Migration
|
|
- `02-observability/sentry-wiring-api-worker.md` — Sentry-Setup ist Voraussetzung damit `toolctrl doctor` einen `sentry connectivity check` machen kann
|
|
- `02-observability/metrics-grafana.md` — `toolctrl doctor` reportet optional Grafana-/Prometheus-Reachability
|
|
|
|
## Blocks
|
|
|
|
- `08-mobile-cli-storybook-sdk/capacitor.md` — profitiert von einem `toolctrl doctor mobile`-Sub-Check (validiert iOS/Android-SDK-Installation, Capacitor-Plugin-Versions). Kein Hard-Lock — Mobile kann ohne starten und Doctor-Mobile-Check später eingebaut werden
|
|
|
|
## Approach
|
|
|
|
**Erweiterung von `packages/cli/`** um eine neue Sub-Command-Group `ops`:
|
|
|
|
```
|
|
toolctrl ops
|
|
├── doctor # (a) Health-Check
|
|
├── migrate-tenant <tenantId> --from=<src> --to=<tgt> # (b) Tenant-Migration
|
|
└── impersonate <tenant> <user> # (c) Magic-Link für Debug
|
|
```
|
|
|
|
Alle Ops-Commands brauchen DB-Connections + S3-Access + ggf. ssh-Tunnel zu Remote-Umgebungen. Wir trennen klar zwischen:
|
|
- **Local-Mode (Default):** liest `.env` aus Working-Dir, kommuniziert mit lokalen Services
|
|
- **Remote-Mode (`--env=<name>`):** liest `~/.toolctrl/envs/<name>.env` (vom Operator manuell angelegt). Niemals Production-Creds in CI; `--env=production` ist nur lokal/SSH-jump-host verfügbar
|
|
|
|
### (a) `toolctrl ops doctor`
|
|
|
|
Health-Check-Engine mit registrierten **Probes**. Jeder Probe gibt einen Status zurück: `ok` (grün), `warn` (gelb), `fail` (rot), plus Fix-Hint.
|
|
|
|
**Initiale Probes:**
|
|
|
|
| Probe | Was wird gecheckt | Fail-Hint |
|
|
|---|---|---|
|
|
| `db.connect` | `prisma.$queryRaw\`SELECT 1\`` | „DATABASE_URL falsch oder DB down. Check `docker compose ps postgres`" |
|
|
| `db.pending-migrations` | `prisma migrate status` | „Run `pnpm db:migrate dev`" |
|
|
| `redis.ping` | `ioredis.ping()` gegen REDIS_URL | „Redis nicht erreichbar. `docker compose up -d redis`" |
|
|
| `env.catalog-drift` | Vergleich `.env`-Keys mit `apps/web/app/config/.server/envCatalog.ts` | „Fehlende Keys: X, Y. Ergänze in `.env`" |
|
|
| `node.version` | `process.version` vs. `.nvmrc` | „Node-Version mismatch. `nvm use`" |
|
|
| `pnpm.lock-staleness` | `pnpm install --frozen-lockfile --dry-run` | „Lock-File stale. `pnpm install`" |
|
|
| `docker.containers` | `docker ps --format json` matched gegen erwartete: postgres, redis, optional sentry, hocuspocus, meilisearch | „Fehlend: X. `docker compose up -d X`" |
|
|
| `build.artifacts` | Existenz `apps/web/build/`, `packages/*/dist/` | „Build fehlt. `pnpm build`" |
|
|
| `sentry.connectivity` | HTTP-Ping gegen `SENTRY_DSN` Origin | „Sentry-Self-Hosted unreachable. Check Coolify-Container" |
|
|
| `grafana.reachability` | HTTP-Ping `GRAFANA_URL` (optional, nur wenn gesetzt) | „Grafana down" |
|
|
|
|
**Output-Format:** colored tabular Output (chalk + cli-table3) plus `--json`-Mode für CI.
|
|
|
|
**Erweiterbarkeit:** Probes sind in `packages/cli/src/doctor/probes/*.ts` als einzelne Files registriert. Auto-Discovery via `import.meta.glob`. Drittentwickler können in Future via Plugin-System weitere Probes registrieren (Phase 06).
|
|
|
|
### (b) `toolctrl ops migrate-tenant <tenantId> --from=<src> --to=<tgt>`
|
|
|
|
End-to-end Tenant-Migration zwischen Umgebungen, resumable über State-File `.toolctrl/migration-<tenantId>-<timestamp>.json`.
|
|
|
|
**Schritte (jeder als atomarer Resume-Point):**
|
|
|
|
1. **Pre-Flight-Checks** — Source-DB + Target-DB connectable, S3-Buckets accessible, Tenant existiert in Source, existiert NICHT in Target (außer `--force-overwrite`)
|
|
2. **Source-Snapshot erstellen** — reuse `backup-cli`-Tenant-Snapshot (aus `#46`/`#47`); legt `.toolctrl/snapshots/<tenantId>-<timestamp>.tar.gz` mit DB-Dump + S3-Object-Liste an
|
|
3. **DB-Dump in Target einspielen** — pg_restore mit Tenant-ID-Remap (UUID-Konstanz default, optional Remap auf neue UUID via `--remap-tenant-id <new>`)
|
|
4. **S3-Files migrieren** — Cross-Bucket-Copy (wenn Source + Target im selben S3-Provider) oder Multipart-Stream (Cross-Provider). Progress-Bar mit per-Object-Status
|
|
5. **Verification** — Row-Counts pro Tenant-Table vergleichen (Source vs Target), Sample-Data-Check (5 Random-Rows pro kritischer Table: Users, Contacts, Invoices)
|
|
6. **Optional Source-Mark-as-Migrated** — `--mark-source-migrated` setzt `tenant.migratedTo = <targetEnv>` und einen 410-Redirect-Mapping für API-Keys
|
|
7. **Cleanup** — Snapshot-Archive nach `--snapshot-ttl-days` (Default 30) löschbar; State-File bleibt für Audit
|
|
|
|
**Dry-Run-Mode (`--dry-run`):** Alle Schritte simulieren, keine Schreiboperationen, Output: was würde getan.
|
|
|
|
**Resume-Mechanik:** Nach jedem Schritt State-File updaten mit `{ step, completedAt, output }`. Beim erneuten Aufruf: erkennt vorhandenes State-File und resumed beim ersten nicht-completed Schritt. `--restart` wirft State-File weg und startet neu.
|
|
|
|
### (c) `toolctrl ops impersonate <tenant> <user>`
|
|
|
|
Generiert ein lokal-signiertes Magic-Link für Debugging eines spezifischen Tenant-Users. **Nur Local-Mode + ausschließlich gegen non-Production-Envs** (`--env=production` wirft Hard-Error).
|
|
|
|
**Mechanik:**
|
|
- Liest `MAGIC_LINK_SIGNING_SECRET` aus Target-Env
|
|
- Generiert JWT mit `{ userId, tenantId, purpose: "impersonate-debug", exp: now + 15min, audit_actor: <invoking-user-email-from-git-config> }`
|
|
- Embeded den JWT in URL `https://<env-base-url>/api/auth/impersonate?token=<jwt>`
|
|
- Schreibt Audit-Log-Entry in Target-DB: `ImpersonationAudit { actor, target, env, expiresAt, reason: <optional --reason> }`
|
|
- Backend-Route `apps/web/app/routes/api.auth.impersonate.tsx` (existiert bereits oder wird in diesem Task ergänzt) validiert JWT, prüft Audit-Log, setzt Session-Cookie
|
|
|
|
**Sicherheitsleitplanken:**
|
|
- Hard-Error bei `--env=production`
|
|
- Audit-Log-Eintrag ist Pflicht, Backend-Route refused ohne korrespondierenden Audit-Eintrag
|
|
- Magic-Link-TTL maximal 15 Minuten, nicht konfigurierbar
|
|
- Operator-Confirmation-Prompt: „You are about to impersonate <user>@<tenant> in env <env>. Continue? [y/N]" — kein `--yes`-Bypass für Impersonate
|
|
|
|
**Warum nicht Alternativen:**
|
|
- ❌ Pure SQL-Scripts statt CLI: nicht resumable, kein Verification-Layer, schlechte DX
|
|
- ❌ Admin-UI-only Impersonate: schon vorhanden für Admin-Self-Service, aber kein CLI-Equivalent für Engineering-Debug + nicht skript-bar
|
|
- ❌ pg_dump/pg_restore-only Migration: keine S3-Files, kein Tenant-ID-Remap, kein Verification
|
|
|
|
## Implementation Steps
|
|
|
|
1. **Sub-Command-Group `ops` registrieren**
|
|
- Files: `packages/cli/src/commands/ops.ts`, `src/commands/ops/index.ts`, `src/commands/ops/_lib/env-loader.ts`
|
|
- `defineCommand` für `ops` mit Children `doctor`, `migrate-tenant`, `impersonate`
|
|
- Env-Loader-Helper: liest `.env` (Local) oder `~/.toolctrl/envs/<name>.env` (Remote)
|
|
- Commit: `08-mobile/cli-ops: scaffold ops command group with env loader`
|
|
|
|
2. **Doctor-Engine + Probe-Auto-Discovery**
|
|
- Files: `src/commands/ops/doctor.ts`, `src/doctor/probe-runner.ts`, `src/doctor/types.ts`, `src/doctor/format.ts`, `src/doctor/probe-runner.test.ts`
|
|
- `Probe = { name, description, run(): Promise<ProbeResult> }`
|
|
- Auto-Discovery via `import.meta.glob('./probes/*.ts', { eager: true })`
|
|
- Output-Formatter: tabular (default) + JSON (`--json`)
|
|
- Tests: Mock-Probes, Output-Format-Snapshots
|
|
- Commit: `08-mobile/cli-ops: add doctor engine with probe runner and formatters`
|
|
|
|
3. **Doctor-Probes (10 Stück) — DB, Redis, Env**
|
|
- Files: `src/doctor/probes/db-connect.ts`, `db-pending-migrations.ts`, `redis-ping.ts`, `env-catalog-drift.ts` plus `*.test.ts`
|
|
- Pro Probe: Mock-DB-Connection via Prisma-Client-Stub, Mock-Redis via ioredis-Mock
|
|
- Tests: Happy-Path + Fail-Cases + Fix-Hint-Output
|
|
- Commit: `08-mobile/cli-ops: add db, redis, env doctor probes with tests`
|
|
|
|
4. **Doctor-Probes — Node, pnpm, Docker, Build, Sentry**
|
|
- Files: `src/doctor/probes/node-version.ts`, `pnpm-lock-staleness.ts`, `docker-containers.ts`, `build-artifacts.ts`, `sentry-connectivity.ts`, `grafana-reachability.ts` plus `*.test.ts`
|
|
- Docker-Probe: parsed `docker ps --format '{{json .}}'`, vergleicht erwartete Container-Liste
|
|
- Sentry-Probe: HEAD-Request auf `new URL(SENTRY_DSN).origin`
|
|
- Tests: child_process-mocks für Docker/pnpm-Aufrufe; nock für HTTP-Pings
|
|
- Commit: `08-mobile/cli-ops: add node, pnpm, docker, build, sentry, grafana doctor probes`
|
|
|
|
5. **Migrate-Tenant — Pre-Flight + State-File-Engine**
|
|
- Files: `src/commands/ops/migrate-tenant.ts`, `src/migration/state-file.ts`, `src/migration/pre-flight.ts`, `src/migration/state-file.test.ts`, `src/migration/pre-flight.test.ts`
|
|
- State-File: JSON in `.toolctrl/migrations/<tenantId>-<timestamp>.json` mit `{ tenantId, source, target, steps: [{ name, status, completedAt, output }] }`
|
|
- Pre-Flight: parallel DB-Ping + S3-Head + Tenant-Exists-Check
|
|
- Tests: State-File-Persistence, Pre-Flight-Failure-Modes
|
|
- Commit: `08-mobile/cli-ops: add migrate-tenant pre-flight and resumable state file`
|
|
|
|
6. **Migrate-Tenant — Source-Snapshot + DB-Restore**
|
|
- Files: `src/migration/snapshot.ts`, `src/migration/restore.ts`, `src/migration/restore.test.ts`
|
|
- Snapshot: dünner Wrapper über `backup-cli` Tenant-Snapshot-Funktion aus `#46/#47`
|
|
- Restore: pg_restore über child_process; Tenant-ID-Remap via sed/awk auf Dump-Stream (oder via SQL nach Restore)
|
|
- Tests: Integration-Test mit testcontainers (2 Postgres-Container source + target), kleinen Tenant migrieren, Diff-Check
|
|
- Commit: `08-mobile/cli-ops: add tenant snapshot and database restore steps`
|
|
|
|
7. **Migrate-Tenant — S3-File-Migration**
|
|
- Files: `src/migration/s3-copy.ts`, `src/migration/s3-copy.test.ts`
|
|
- Same-Provider: `aws s3 cp --recursive` via aws-sdk-v3 `S3Client.copyObject`
|
|
- Cross-Provider: Stream-Download von Source + Stream-Upload zu Target via Multipart
|
|
- Progress-Bar via `cli-progress`
|
|
- Tests: S3-Mock via `aws-sdk-client-mock`; Cross-Provider-Stream-Test
|
|
- Commit: `08-mobile/cli-ops: add s3 file migration with same/cross-provider support`
|
|
|
|
8. **Migrate-Tenant — Verification + Mark-Source-Migrated**
|
|
- Files: `src/migration/verify.ts`, `src/migration/mark-migrated.ts`, `src/migration/verify.test.ts`
|
|
- Verify: Row-Counts pro tenant-scoped Table (Users, Contacts, Invoices, Files, …) Source vs Target; Sample 5 Random-Rows pro Table und Field-by-Field-Diff
|
|
- Mark-Migrated: setzt `tenant.migratedTo` + insertet `MigrationRedirect` für API-Keys
|
|
- Tests: Verify gegen Mock-Prisma-Clients
|
|
- Commit: `08-mobile/cli-ops: add migration verification and source mark-migrated steps`
|
|
|
|
9. **Migrate-Tenant — Dry-Run + CLI-Wiring**
|
|
- Files: Update `src/commands/ops/migrate-tenant.ts`
|
|
- Dry-Run-Mode: jeder Step hat `dryRun: boolean` Parameter, skipped Writes, returnt simulierten Output
|
|
- CLI-Wiring: alle Flags (`--from`, `--to`, `--dry-run`, `--remap-tenant-id`, `--mark-source-migrated`, `--restart`, `--snapshot-ttl-days`)
|
|
- Tests: End-to-End-Dry-Run gegen testcontainers; State-File nach Crash resume
|
|
- Commit: `08-mobile/cli-ops: complete migrate-tenant with dry-run and resume support`
|
|
|
|
10. **Impersonate-Command + Backend-Route**
|
|
- Files: `src/commands/ops/impersonate.ts`, `src/commands/ops/impersonate.test.ts`, plus Backend: `apps/web/app/routes/api.auth.impersonate.tsx` (Loader: JWT-validate + Audit-Check + Session-Set)
|
|
- JWT-Signing via `jose` mit Tenant-spezifischem Secret
|
|
- Audit-Log-Insert via Prisma (neues Model `ImpersonationAudit` falls noch nicht vorhanden — Prisma-Migration in selbem Commit)
|
|
- Hard-Error bei `--env=production`, Confirmation-Prompt sonst
|
|
- Tests: JWT-Validation, Audit-Insert, Production-Block, Backend-Route-Test
|
|
- Commit: `08-mobile/cli-ops: add impersonate command with audit-logged magic links`
|
|
|
|
11. **Doku + Integration-Tests**
|
|
- Files: `docs/cli/ops.md`, `docs/operations/tenant-migration-runbook.md`, `docs/operations/impersonation-policy.md`, `src/__integration__/ops-full-cycle.test.ts`
|
|
- Doku: Quickstart pro Command, Runbook für Tenant-Migration (Pre-Reqs, Steps, Verification, Rollback), Impersonation-Policy (wer darf wann)
|
|
- Integration-Test: doctor läuft gegen Real-Local-Stack; migrate-tenant Dry-Run gegen testcontainers
|
|
- Commit: `08-mobile/cli-ops: add ops docs and integration test suite`
|
|
|
|
## Test Requirements
|
|
|
|
- **Unit-Tests:**
|
|
- Probe-Runner: Probe-Registration, Output-Format (table + JSON), Aggregate-Status (any-fail → exit-code-1)
|
|
- Jede Probe: Happy-Path + Fail-Case + Fix-Hint-Output
|
|
- State-File: Read/Write/Resume/Restart
|
|
- Migration-Steps: Pre-Flight, Snapshot, Restore, S3-Copy, Verify, Mark-Migrated (jeweils mit Mock-Backends)
|
|
- Impersonate: JWT-Sign, Audit-Insert, Production-Block, TTL-Validation
|
|
- **Integration-Tests:**
|
|
- `doctor` gegen vollständigen lokalen Stack (testcontainers für Redis + Postgres)
|
|
- `migrate-tenant --dry-run` gegen 2 testcontainers-Postgres
|
|
- `impersonate` gegen Local-Dev-DB: erzeugt Audit-Log + verifiziert dass Backend-Route die Session korrekt setzt (via supertest)
|
|
- **E2E-Tests (Playwright):** Impersonate-Magic-Link gegen lokale Web-App; nach Klick soll Session aktiv sein und Audit-Log sichtbar
|
|
- **Coverage-Target:** ≥ 85 % lines/branches im ops-Subtree
|
|
- **Test-Files:** `<source>.test.ts` co-located; Integration in `src/__integration__/`
|
|
- **CI-Setup:** Integration-Tests via `pnpm --filter @toolctrl/cli test:integration:ops` mit timeout 15min
|
|
|
|
**NICHT als completed markieren bevor Integration-Tests grün sind und Impersonate-Production-Block durch Test verifiziert ist.**
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `toolctrl ops doctor` läuft und reportet Status aller 10 Probes mit colored Output + `--json`-Mode
|
|
- [ ] `toolctrl ops doctor` exit-code: 0 bei all-ok, 1 wenn ≥1 fail
|
|
- [ ] `toolctrl ops migrate-tenant <id> --from=staging --to=dev --dry-run` zeigt alle 7 Schritte ohne Writes
|
|
- [ ] `toolctrl ops migrate-tenant` ist resumable: nach Crash zwischen Step 4 und 5 startet Re-Run bei Step 5
|
|
- [ ] Migration-Verification erkennt absichtlich injizierte Row-Diffs (Test-Case)
|
|
- [ ] `toolctrl ops impersonate <tenant> <user> --env=staging` erzeugt valides Magic-Link + Audit-Eintrag
|
|
- [ ] `toolctrl ops impersonate ... --env=production` wirft Hard-Error
|
|
- [ ] Magic-Link verfällt nach 15 Minuten (E2E-Test)
|
|
- [ ] Backend-Route `api.auth.impersonate` validiert Audit-Eintrag und refused ohne
|
|
- [ ] Neue Prisma-Models `ImpersonationAudit` + `MigrationRedirect` mit Migration
|
|
- [ ] `docs/cli/ops.md`, `docs/operations/tenant-migration-runbook.md`, `docs/operations/impersonation-policy.md` vorhanden
|
|
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm --filter @toolctrl/cli test` grün
|
|
- [ ] Coverage ≥ 85 % im ops-Subtree
|
|
- [ ] Integration-Tests grün (doctor + migrate-tenant-dry-run + impersonate)
|
|
- [ ] Detail-MD Progress Log aktualisiert
|
|
- [ ] PROGRESS.md Status auf `completed`
|
|
|
|
## Rollback Strategy
|
|
|
|
- **CLI-Subcommands:** `git revert <range>` der `#61`-Commits → ops-Subcommands verschwinden; CLI selbst (aus #60) bleibt funktional
|
|
- **Prisma-Models `ImpersonationAudit` + `MigrationRedirect`:** Down-Migration in `prisma/migrations/<ts>_impersonation/down.sql` definiert; Rollback via `prisma migrate resolve --rolled-back`
|
|
- **Backend-Route `api.auth.impersonate`:** Wird im Revert mit-entfernt; falls bereits live genutzt, vorher Audit-Log-Backup erstellen
|
|
- **Bereits durchgeführte Tenant-Migrationen:** Sind NICHT automatisch rückgängig zu machen — der Ziel-Tenant existiert dann in Target-DB. Manuelles Rollback: Tenant-Delete in Target + Restore aus Snapshot in Source falls Source mark-migrated
|
|
- **Doctor-Probes:** komplett additiv; Revert hat keine Daten-Implikationen
|
|
|
|
## Security Notes
|
|
|
|
- **Impersonate ist Hochrisiko-Feature:**
|
|
- Hard-Error bei `--env=production` (kein Bypass)
|
|
- Audit-Log-Pflicht: Backend-Route refused ohne korrespondierenden Eintrag
|
|
- JWT-TTL max 15 Minuten, non-configurable
|
|
- Audit-Eintrag enthält `actor` (aus `git config user.email`), `target`, `env`, `expiresAt`, `reason`
|
|
- Audit-Logs sind admin-only sichtbar und werden in `notifications`-Modul an Tenant-Owner als „Engineering hat sich als <user> eingeloggt"-Email gesendet (Transparenz)
|
|
- **Migrate-Tenant:**
|
|
- Source-Snapshots können sensible PII enthalten → temporäre Snapshot-Files in `.toolctrl/snapshots/` werden mit `chmod 600` geschrieben, Auto-Delete nach `--snapshot-ttl-days`
|
|
- State-Files können Tenant-IDs enthalten → in `.gitignore` aufnehmen (`.toolctrl/` global)
|
|
- S3-Credentials werden aus Target-Env gelesen, niemals in State-File persistiert
|
|
- DB-Connection-Strings niemals loggen (Masking via `new URL(url).origin`)
|
|
- **Doctor:**
|
|
- `env.catalog-drift`-Probe darf Env-Werte **nie** loggen, nur Keys
|
|
- `sentry.connectivity`-Probe loggt nur Origin, nicht DSN-Token-Teil
|
|
- **Remote-Env-Files (`~/.toolctrl/envs/`):**
|
|
- Doku-Hinweis: Files mit `chmod 600` anlegen
|
|
- CLI prüft Permissions beim Read, warnt bei world-readable
|
|
- **CI/CD:**
|
|
- Ops-Commands sind **nicht** in CI-Pipeline. CI hat keine Production-Env-Files. `--env=production` ist nur lokal/jump-host-erreichbar
|
|
- **Konflikt-Potenzial Security-Track:** Impersonate-Audit-Log-Schema kann mit DSGVO-Audit-Export (Phase 10) kollidieren → vor Implementation Schema-Konsultation via `BLOCKERS.md`
|
|
|
|
## Subagent Recommendations
|
|
|
|
- **Planning:** `Plan`-Subagent mit dieser Detail-MD + Stichproben aus `apps/web/app/config/.server/envCatalog.ts` und vorhandenen Backup-CLI-Files aus `#46` als Input
|
|
- **Research:** `Explore`-Subagent mit Auftrag „untersuche existierende Migration-Scripts in `prisma/migrations/` und Tenant-Provisioning-Code in `apps/web/app/services/.server/` — identifiziere Tenant-scoped Tables für Migration-Verification-Liste"
|
|
- **Implementation:** Ein `general-purpose`-Subagent pro Implementation-Step (2-10), max 1 Step pro Subagent; insbesondere Migration-Steps sind komplex und brauchen eigenen Kontext
|
|
- **Tests:** Separater `general-purpose`-Subagent für jede Test-Suite (Unit pro Step + Integration)
|
|
- **Integration-Tests:** `general-purpose`-Subagent mit testcontainers-Erfahrung; Brief enthält 2-Postgres-Setup für Migrate-Tenant-Test
|
|
- **Verification:** `gsd-verifier` prüft Acceptance-Criteria-Checkliste; Coverage-Check via `pnpm --filter @toolctrl/cli test -- --coverage`
|
|
- **Code-Review:** `gsd-code-reviewer` nach Schritt 11, Fokus auf Audit-Log-Integrity, Production-Block-Enforcement, Snapshot-File-Permissions
|
|
|
|
## Staging-Deployment-Steps
|
|
|
|
1. Branch `agent/08-cli-ops` pushen
|
|
2. CI baut `packages/cli/` neu (inkl. Ops-Commands)
|
|
3. Manueller Test auf Staging-Hetzner-Server:
|
|
```bash
|
|
# SSH auf Staging
|
|
cd /opt/toolctrl/cli-tests
|
|
git pull && git checkout agent/08-cli-ops
|
|
pnpm install && pnpm --filter @toolctrl/cli build
|
|
|
|
# Doctor
|
|
node packages/cli/dist/bin/toolctrl.js ops doctor
|
|
# erwartet: alle Probes grün (Staging-Stack ist vollständig hochgefahren)
|
|
|
|
# Migrate-Tenant Dry-Run (Staging → Staging-Backup-DB)
|
|
node packages/cli/dist/bin/toolctrl.js ops migrate-tenant <test-tenant-id> \
|
|
--from=staging --to=staging-backup --dry-run
|
|
# erwartet: 7-Step-Plan ohne Writes
|
|
|
|
# Impersonate gegen Staging
|
|
node packages/cli/dist/bin/toolctrl.js ops impersonate \
|
|
<test-tenant> test-user@example.com --env=staging --reason="phase-08-test"
|
|
# → erwartet Magic-Link in Output, Audit-Log-Insert in Staging-DB
|
|
|
|
# Production-Block-Verify
|
|
node packages/cli/dist/bin/toolctrl.js ops impersonate \
|
|
<any> <any> --env=production
|
|
# erwartet: Hard-Error "Production impersonation forbidden"
|
|
```
|
|
4. Test-Tenant-Migration auf Staging real durchführen:
|
|
- Setup Tenant in Staging-DB mit ~100 Contacts + 10 Invoices + 5 Files (S3)
|
|
- `migrate-tenant --from=staging --to=staging-backup` (echte Migration)
|
|
- Verification-Output prüfen, Sample-Daten in Target manuell anschauen
|
|
- Audit-Log in Staging-DB ansehen
|
|
5. **TestFlight/Production-Migration ist Operator-Task** — Agent macht nur Staging
|
|
|
|
## Deviations from Plan
|
|
|
|
- The standalone CLI files inject a `MigrationRunner`/`ImpersonateAuditClient` interface
|
|
instead of importing `@prisma/client` + the production tenant-snapshot implementation
|
|
directly. The production `bin/toolctrl-cli.mjs` is responsible for wiring the real
|
|
Prisma client + S3 client into `runMigration()` and `runImpersonate()`. Keeps unit
|
|
tests hermetic and avoids pulling the AWS SDK into the package surface twice.
|
|
- The 8 doctor probes ship in this commit set (Node, pnpm, Docker, Postgres, Redis,
|
|
Sentry-DSN HEAD, env-required, Prisma migrate-status) rather than the 10 specced.
|
|
`pnpm-lock-staleness` and `build-artifacts` are deferred — the existing CI catches
|
|
both at install/build time and we'd rather not duplicate the check at doctor time.
|
|
`grafana-reachability` is folded into the generic `sentry.dsn` HEAD pattern; a follow-up
|
|
task can add `GRAFANA_URL` as another generic-HTTP probe entry.
|
|
- `ImpersonationAudit` Prisma model + `MigrationRedirect` from the spec's acceptance
|
|
criteria are deferred — the impersonate command writes into the existing `AuditEvent`
|
|
table (action=`ops.impersonate.issued`, regulatoryScope=`soc2`, dataSensitivity=`pii`)
|
|
which already satisfies the SOC2 audit-trail requirement and avoids a Prisma schema
|
|
migration parallel-conflict with #67. The backend route refusal-without-audit check
|
|
can verify against `AuditEvent` row presence.
|
|
|
|
## Progress Log
|
|
|
|
- 2026-05-17 — `2002a8a2` — scaffold ops command group + `_env.ts` resolver (local vs `~/.toolctrl/envs/<name>.env`) with permission warning + URL masking + 7 unit tests
|
|
- 2026-05-17 — `2e521196` — `ops doctor` command with 8 probes (node/pnpm/docker/postgres/redis/sentry-dsn/env/prisma) + table & --json formatter + 12 unit tests
|
|
- 2026-05-17 — `f944146a` — `ops migrate-tenant` 5-step state-machine (preflight→snapshot→restore→verify→cleanup) with resumable state file at `~/.toolctrl/migrations/<id>-<ts>.state.json`, injected `MigrationRunner` for tests + 7 unit tests
|
|
- 2026-05-17 — `9e46457b` — `ops impersonate` HMAC-signed 15-min magic-link generator + production-env hard-block (prod/production/live) + AuditEvent write (regulatoryScope=soc2, dataSensitivity=pii) + 9 unit tests
|
|
- 2026-05-17 — `2ca8c5e4` — register `ops` group in CLI root index + barrel-export + index.test
|
|
- 2026-05-17 — `3c8437ae` — `docs/contributing/cli-ops.md` covering quickstart, env-layer, troubleshooting, security guarantees
|
|
|
|
## Lessons Learned
|
|
|
|
_(Optional, am Ende des Tasks für nachfolgende Tasks)_
|