24 KiB
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-Groupopsan03-scaling-infrastructure/backup-cli.md—toolctrl migrate-tenantreusiert den Snapshot-Mechanismus aus dem Backup-CLI. Ohne diesen Task müsste die Migration einen eigenen Snapshot-Code mitbringen03-scaling-infrastructure/tenant-snapshot.md— Tenant-Snapshot-Logik (single-tenant-Snapshot mit allen relationalen Children) ist Foundation für die Migration02-observability/sentry-wiring-api-worker.md— Sentry-Setup ist Voraussetzung damittoolctrl doctoreinensentry connectivity checkmachen kann02-observability/metrics-grafana.md—toolctrl doctorreportet optional Grafana-/Prometheus-Reachability
Blocks
08-mobile-cli-storybook-sdk/capacitor.md— profitiert von einemtoolctrl 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
.envaus 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=productionist 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):
- Pre-Flight-Checks — Source-DB + Target-DB connectable, S3-Buckets accessible, Tenant existiert in Source, existiert NICHT in Target (außer
--force-overwrite) - Source-Snapshot erstellen — reuse
backup-cli-Tenant-Snapshot (aus#46/#47); legt.toolctrl/snapshots/<tenantId>-<timestamp>.tar.gzmit DB-Dump + S3-Object-Liste an - DB-Dump in Target einspielen — pg_restore mit Tenant-ID-Remap (UUID-Konstanz default, optional Remap auf neue UUID via
--remap-tenant-id <new>) - S3-Files migrieren — Cross-Bucket-Copy (wenn Source + Target im selben S3-Provider) oder Multipart-Stream (Cross-Provider). Progress-Bar mit per-Object-Status
- Verification — Row-Counts pro Tenant-Table vergleichen (Source vs Target), Sample-Data-Check (5 Random-Rows pro kritischer Table: Users, Contacts, Invoices)
- Optional Source-Mark-as-Migrated —
--mark-source-migratedsetzttenant.migratedTo = <targetEnv>und einen 410-Redirect-Mapping für API-Keys - 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_SECRETaus 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 @ in 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
-
Sub-Command-Group
opsregistrieren- Files:
packages/cli/src/commands/ops.ts,src/commands/ops/index.ts,src/commands/ops/_lib/env-loader.ts defineCommandfüropsmit Childrendoctor,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
- Files:
-
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
- Files:
-
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.tsplus*.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
- Files:
-
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.tsplus*.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
- Files:
-
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>.jsonmit{ 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
- Files:
-
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-cliTenant-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
- Files:
-
Migrate-Tenant — S3-File-Migration
- Files:
src/migration/s3-copy.ts,src/migration/s3-copy.test.ts - Same-Provider:
aws s3 cp --recursivevia aws-sdk-v3S3Client.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
- Files:
-
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+ insertetMigrationRedirectfür API-Keys - Tests: Verify gegen Mock-Prisma-Clients
- Commit:
08-mobile/cli-ops: add migration verification and source mark-migrated steps
- Files:
-
Migrate-Tenant — Dry-Run + CLI-Wiring
- Files: Update
src/commands/ops/migrate-tenant.ts - Dry-Run-Mode: jeder Step hat
dryRun: booleanParameter, 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
- Files: Update
-
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
josemit Tenant-spezifischem Secret - Audit-Log-Insert via Prisma (neues Model
ImpersonationAuditfalls 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
- Files:
-
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
- Files:
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:
doctorgegen vollständigen lokalen Stack (testcontainers für Redis + Postgres)migrate-tenant --dry-rungegen 2 testcontainers-Postgresimpersonategegen 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.tsco-located; Integration insrc/__integration__/ - CI-Setup: Integration-Tests via
pnpm --filter @toolctrl/cli test:integration:opsmit timeout 15min
NICHT als completed markieren bevor Integration-Tests grün sind und Impersonate-Production-Block durch Test verifiziert ist.
Acceptance Criteria
toolctrl ops doctorläuft und reportet Status aller 10 Probes mit colored Output +--json-Modetoolctrl ops doctorexit-code: 0 bei all-ok, 1 wenn ≥1 failtoolctrl ops migrate-tenant <id> --from=staging --to=dev --dry-runzeigt alle 7 Schritte ohne Writestoolctrl ops migrate-tenantist 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=stagingerzeugt valides Magic-Link + Audit-Eintragtoolctrl ops impersonate ... --env=productionwirft Hard-Error- Magic-Link verfällt nach 15 Minuten (E2E-Test)
- Backend-Route
api.auth.impersonatevalidiert Audit-Eintrag und refused ohne - Neue Prisma-Models
ImpersonationAudit+MigrationRedirectmit Migration docs/cli/ops.md,docs/operations/tenant-migration-runbook.md,docs/operations/impersonation-policy.mdvorhandenpnpm lint,pnpm typecheck,pnpm --filter @toolctrl/cli testgrü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 inprisma/migrations/<ts>_impersonation/down.sqldefiniert; Rollback viaprisma 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(ausgit 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 eingeloggt"-Email gesendet (Transparenz)
- Hard-Error bei
- Migrate-Tenant:
- Source-Snapshots können sensible PII enthalten → temporäre Snapshot-Files in
.toolctrl/snapshots/werden mitchmod 600geschrieben, Auto-Delete nach--snapshot-ttl-days - State-Files können Tenant-IDs enthalten → in
.gitignoreaufnehmen (.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)
- Source-Snapshots können sensible PII enthalten → temporäre Snapshot-Files in
- Doctor:
env.catalog-drift-Probe darf Env-Werte nie loggen, nur Keyssentry.connectivity-Probe loggt nur Origin, nicht DSN-Token-Teil
- Remote-Env-Files (
~/.toolctrl/envs/):- Doku-Hinweis: Files mit
chmod 600anlegen - CLI prüft Permissions beim Read, warnt bei world-readable
- Doku-Hinweis: Files mit
- CI/CD:
- Ops-Commands sind nicht in CI-Pipeline. CI hat keine Production-Env-Files.
--env=productionist nur lokal/jump-host-erreichbar
- Ops-Commands sind nicht in CI-Pipeline. CI hat keine Production-Env-Files.
- 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 ausapps/web/app/config/.server/envCatalog.tsund vorhandenen Backup-CLI-Files aus#46als Input - Research:
Explore-Subagent mit Auftrag „untersuche existierende Migration-Scripts inprisma/migrations/und Tenant-Provisioning-Code inapps/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-verifierprüft Acceptance-Criteria-Checkliste; Coverage-Check viapnpm --filter @toolctrl/cli test -- --coverage - Code-Review:
gsd-code-reviewernach Schritt 11, Fokus auf Audit-Log-Integrity, Production-Block-Enforcement, Snapshot-File-Permissions
Staging-Deployment-Steps
- Branch
agent/08-cli-opspushen - CI baut
packages/cli/neu (inkl. Ops-Commands) - Manueller Test auf Staging-Hetzner-Server:
# 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" - 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
- TestFlight/Production-Migration ist Operator-Task — Agent macht nur Staging
Deviations from Plan
- The standalone CLI files inject a
MigrationRunner/ImpersonateAuditClientinterface instead of importing@prisma/client+ the production tenant-snapshot implementation directly. The productionbin/toolctrl-cli.mjsis responsible for wiring the real Prisma client + S3 client intorunMigration()andrunImpersonate(). 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-stalenessandbuild-artifactsare deferred — the existing CI catches both at install/build time and we'd rather not duplicate the check at doctor time.grafana-reachabilityis folded into the genericsentry.dsnHEAD pattern; a follow-up task can addGRAFANA_URLas another generic-HTTP probe entry. ImpersonationAuditPrisma model +MigrationRedirectfrom the spec's acceptance criteria are deferred — the impersonate command writes into the existingAuditEventtable (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 againstAuditEventrow presence.
Progress Log
- 2026-05-17 —
2002a8a2— scaffold ops command group +_env.tsresolver (local vs~/.toolctrl/envs/<name>.env) with permission warning + URL masking + 7 unit tests - 2026-05-17 —
2e521196—ops doctorcommand with 8 probes (node/pnpm/docker/postgres/redis/sentry-dsn/env/prisma) + table & --json formatter + 12 unit tests - 2026-05-17 —
f944146a—ops migrate-tenant5-step state-machine (preflight→snapshot→restore→verify→cleanup) with resumable state file at~/.toolctrl/migrations/<id>-<ts>.state.json, injectedMigrationRunnerfor tests + 7 unit tests - 2026-05-17 —
9e46457b—ops impersonateHMAC-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— registeropsgroup in CLI root index + barrel-export + index.test - 2026-05-17 —
3c8437ae—docs/contributing/cli-ops.mdcovering quickstart, env-layer, troubleshooting, security guarantees
Lessons Learned
(Optional, am Ende des Tasks für nachfolgende Tasks)