audit, advisories and doctors/setup work

2026-01-13 18:53:39 +02:00
parent 9ca7cb183e
commit d7be6ba34b
811 changed files with 54242 additions and 4056 deletions
--- a/docs/setup/setup-wizard-sprint-plan.md
+++ b/docs/setup/setup-wizard-sprint-plan.md
@@ -0,0 +1,811 @@
+# Setup Wizard - Sprint Plan
+
+This document defines the implementation plan for the Stella Ops Setup Wizard feature.
+
+## 1. Epic Overview
+
+| Epic ID | Name | Description | Priority |
+|---------|------|-------------|----------|
+| **E1** | Doctor Remediation Engine | Extend Doctor to generate runtime-specific fix commands | P0 |
+| **E2** | CLI Setup Command | Implement `stella setup` interactive command | P0 |
+| **E3** | UI Setup Wizard | Angular wizard component with first-run blocking | P1 |
+| **E4** | Integration Connectors | Multi-connector support with default suggestions | P1 |
+| **E5** | Configuration Pane | Post-setup reconfiguration UI | P2 |
+
+---
+
+## 2. Sprint Sequence
+
+### Sprint 1: Foundation (E1)
+**Focus:** Doctor remediation engine and runtime detection
+
+### Sprint 2: CLI Core (E2)
+**Focus:** CLI setup command with infrastructure steps
+
+### Sprint 3: CLI Integrations (E2, E4)
+**Focus:** CLI integration steps and multi-connector support
+
+### Sprint 4: UI Wizard (E3)
+**Focus:** Angular wizard component and first-run blocking
+
+### Sprint 5: UI Integrations (E3, E4)
+**Focus:** UI integration steps with connector management
+
+### Sprint 6: Polish (E5)
+**Focus:** Configuration pane and documentation
+
+---
+
+## 3. Epic 1: Doctor Remediation Engine
+
+### 3.1 Features
+
+| Feature | Description |
+|---------|-------------|
+| F1.1 | Runtime environment detection |
+| F1.2 | Remediation command templates |
+| F1.3 | Placeholder resolution system |
+| F1.4 | Verification command execution |
+| F1.5 | Secret redaction |
+
+### 3.2 User Stories
+
+#### F1.1 Runtime Detection
+
+**US-1.1.1: Detect Docker Compose environment**
+```
+As a setup wizard
+I need to detect Docker Compose environments
+So that I can suggest Docker Compose-specific fix commands
+
+Acceptance Criteria:
+- Detect presence of docker compose command
+- Detect docker-compose.yml in standard locations
+- Detect COMPOSE_PROJECT_NAME environment variable
+- Return DockerCompose runtime type
+
+Files to modify:
+- src/__Libraries/StellaOps.Doctor/Detection/RuntimeDetector.cs (new)
+- src/__Libraries/StellaOps.Doctor/Detection/IRuntimeDetector.cs (new)
+```
+
+**US-1.1.2: Detect Kubernetes context**
+```
+As a setup wizard
+I need to detect Kubernetes environments
+So that I can suggest kubectl-based fix commands
+
+Acceptance Criteria:
+- Detect KUBERNETES_SERVICE_HOST environment variable
+- Detect kubeconfig file presence
+- Extract current namespace from context
+- Return Kubernetes runtime type
+```
+
+**US-1.1.3: Detect systemd-managed services**
+```
+As a setup wizard
+I need to detect systemd-managed PostgreSQL/Valkey
+So that I can suggest systemctl commands
+
+Acceptance Criteria:
+- Detect systemctl command availability
+- Check if postgresql.service exists
+- Check if valkey.service or redis.service exists
+- Return Systemd runtime type
+```
+
+#### F1.2 Remediation Templates
+
+**US-1.2.1: Define remediation command model**
+```
+As a setup wizard
+I need a data model for remediation commands
+So that checks can return actionable fixes
+
+Acceptance Criteria:
+- RemediationCommand record with runtime, command, description
+- Support for placeholders in commands
+- Support for sudo flag
+- Support for dangerous flag
+
+Files to modify:
+- src/__Libraries/StellaOps.Doctor/Models/RemediationCommand.cs (new)
+- src/__Libraries/StellaOps.Doctor/Models/CheckResult.cs (extend)
+```
+
+**US-1.2.2: Implement database connectivity remediations**
+```
+As a user with database connection failure
+I need runtime-specific fix commands
+So that I can quickly resolve the issue
+
+Acceptance Criteria:
+- Docker Compose: docker compose up -d postgres
+- Kubernetes: kubectl get pods -l app=postgres
+- Systemd: sudo systemctl start postgresql
+- Bare: pg_isready verification command
+```
+
+**US-1.2.3: Implement Valkey connectivity remediations**
+```
+As a user with Valkey connection failure
+I need runtime-specific fix commands
+So that I can quickly resolve the issue
+
+Acceptance Criteria:
+- Docker Compose: docker compose up -d valkey
+- Kubernetes: kubectl get pods -l app=valkey
+- Systemd: sudo systemctl start valkey
+- Bare: redis-cli PING verification
+```
+
+#### F1.3 Placeholder Resolution
+
+**US-1.3.1: Implement placeholder resolver**
+```
+As a setup wizard
+I need to resolve placeholders in commands
+So that users see contextual values
+
+Acceptance Criteria:
+- Resolve {{HOST}}, {{PORT}} from user input
+- Resolve {{NAMESPACE}} from Kubernetes context
+- Resolve {{COMPOSE_FILE}} from detection
+- Support default values with {{VAR:-default}} syntax
+
+Files to modify:
+- src/__Libraries/StellaOps.Doctor/Remediation/PlaceholderResolver.cs (new)
+```
+
+#### F1.4 Verification Execution
+
+**US-1.4.1: Execute verification commands**
+```
+As a setup wizard
+I need to run verification commands
+So that I can confirm fixes were applied
+
+Acceptance Criteria:
+- Execute shell command with timeout
+- Capture exit code and output
+- Return success/failure result
+- Handle command not found gracefully
+```
+
+#### F1.5 Secret Redaction
+
+**US-1.5.1: Redact secrets in displayed commands**
+```
+As a setup wizard
+I must never display actual secret values
+So that secrets are not exposed in logs or UI
+
+Acceptance Criteria:
+- PASSWORD, TOKEN, SECRET_KEY placeholders never resolved for display
+- Display shows placeholder syntax
+- Copy-to-clipboard preserves placeholders
+- Log output redacts secrets
+```
+
+---
+
+## 4. Epic 2: CLI Setup Command
+
+### 4.1 Features
+
+| Feature | Description |
+|---------|-------------|
+| F2.1 | Command registration and structure |
+| F2.2 | Interactive prompts for each step |
+| F2.3 | Non-interactive mode with config file |
+| F2.4 | Resume and reconfigure support |
+| F2.5 | Step validation with Doctor checks |
+
+### 4.2 User Stories
+
+#### F2.1 Command Registration
+
+**US-2.1.1: Register stella setup command**
+```
+As a CLI user
+I need a stella setup command
+So that I can configure Stella Ops interactively
+
+Acceptance Criteria:
+- Command registered in CommandFactory
+- Global options: --config, --non-interactive, --resume, --reconfigure
+- Step selection options: --step, --skip
+- Help text describes all options
+
+Files to modify:
+- src/Cli/StellaOps.Cli/Commands/Setup/SetupCommandGroup.cs (new)
+- src/Cli/StellaOps.Cli/Commands/CommandFactory.cs
+```
+
+**US-2.1.2: Implement setup command handler**
+```
+As a CLI user
+I need the setup command to orchestrate all steps
+So that I can complete configuration end-to-end
+
+Acceptance Criteria:
+- Detect first-run vs reconfigure mode
+- Load existing configuration if present
+- Execute steps in sequence
+- Save progress after each step
+
+Files to modify:
+- src/Cli/StellaOps.Cli/Commands/Setup/SetupCommandHandler.cs (new)
+```
+
+#### F2.2 Interactive Prompts
+
+**US-2.2.1: Implement database setup prompts**
+```
+As a CLI user
+I need interactive prompts for database configuration
+So that I can enter connection details
+
+Acceptance Criteria:
+- Prompt for host, port, database, username, password
+- Password input masked
+- Default values shown in brackets
+- Input validation before proceeding
+```
+
+**US-2.2.2: Implement Valkey setup prompts**
+```
+As a CLI user
+I need interactive prompts for Valkey configuration
+So that I can enter connection details
+
+Acceptance Criteria:
+- Prompt for host, port, password (optional)
+- TLS toggle option
+- Database index selection
+```
+
+**US-2.2.3: Implement admin bootstrap prompts**
+```
+As a CLI user
+I need prompts to create admin user
+So that I can access the system after setup
+
+Acceptance Criteria:
+- Prompt for username, email, password
+- Password confirmation
+- Password complexity validation
+- Display created user info
+```
+
+**US-2.2.4: Implement vault integration prompts**
+```
+As a CLI user
+I need prompts to configure vault integration
+So that I can set up secrets management
+
+Acceptance Criteria:
+- Show detected vault (if any)
+- Prompt for vault type selection
+- Type-specific prompts (token, AppRole, etc.)
+- Test connection before saving
+```
+
+**US-2.2.5: Implement SCM integration prompts**
+```
+As a CLI user
+I need prompts to configure SCM integration
+So that I can connect source control
+
+Acceptance Criteria:
+- Provider selection (GitHub, GitLab, etc.)
+- Provider-specific prompts
+- Support for adding multiple providers
+- Test connection before saving
+```
+
+#### F2.3 Non-Interactive Mode
+
+**US-2.3.1: Parse YAML configuration file**
+```
+As a DevOps engineer
+I need to provide configuration via YAML file
+So that I can automate setup in CI/CD
+
+Acceptance Criteria:
+- Parse setup.yaml with all step configurations
+- Support environment variable substitution
+- Validate required fields present
+- Fail on missing required values
+
+Files to modify:
+- src/Cli/StellaOps.Cli/Commands/Setup/SetupConfigParser.cs (new)
+```
+
+**US-2.3.2: Execute non-interactive setup**
+```
+As a DevOps engineer
+I need non-interactive mode to fail on missing input
+So that automated setups don't hang
+
+Acceptance Criteria:
+- --non-interactive flag enables mode
+- Exit with error if required input missing
+- Progress output shows step completion
+- Final status summary
+```
+
+#### F2.4 Resume Support
+
+**US-2.4.1: Save setup progress**
+```
+As a CLI user
+I need my progress saved automatically
+So that I can resume if interrupted
+
+Acceptance Criteria:
+- Save completed steps to ~/.stellaops/setup-state.json
+- Save step-specific configuration
+- Track skipped steps with reasons
+- Save timestamp of last update
+
+Files to modify:
+- src/Cli/StellaOps.Cli/Commands/Setup/SetupStateStore.cs (new)
+```
+
+**US-2.4.2: Resume interrupted setup**
+```
+As a CLI user
+I need to resume from where I left off
+So that I don't repeat completed steps
+
+Acceptance Criteria:
+- --resume flag loads previous state
+- Show completed steps as already done
+- Start from first incomplete step
+- Allow going back to previous steps
+```
+
+#### F2.5 Step Validation
+
+**US-2.5.1: Run Doctor checks after each step**
+```
+As a CLI user
+I need validation after configuration
+So that I know if setup succeeded
+
+Acceptance Criteria:
+- Run step-specific Doctor checks
+- Display pass/warn/fail for each check
+- On failure, show remediations
+- Block progression on critical failures
+```
+
+**US-2.5.2: Display remediation commands**
+```
+As a CLI user
+I need to see fix commands when checks fail
+So that I can resolve issues
+
+Acceptance Criteria:
+- Display likely causes numbered by priority
+- Show runtime-specific commands
+- Include copy-pasteable command text
+- Prompt for retry after fix
+```
+
+---
+
+## 5. Epic 3: UI Setup Wizard
+
+### 5.1 Features
+
+| Feature | Description |
+|---------|-------------|
+| F3.1 | First-run detection and blocking |
+| F3.2 | Wizard component with stepper |
+| F3.3 | Step form components |
+| F3.4 | Connection testing UI |
+| F3.5 | Doctor check results panel |
+| F3.6 | Remediation display with copy |
+
+### 5.2 User Stories
+
+#### F3.1 First-Run Blocking
+
+**US-3.1.1: Detect first-run state**
+```
+As the UI application
+I need to detect if setup is incomplete
+So that I can redirect to the wizard
+
+Acceptance Criteria:
+- Call backend setup status endpoint
+- Check for Operational threshold met
+- Store state in session
+
+Files to modify:
+- src/Web/StellaOps.Web/src/app/core/services/setup-status.service.ts (new)
+```
+
+**US-3.1.2: Implement first-run route guard**
+```
+As the UI application
+I need to block access to main app until setup complete
+So that users configure before using
+
+Acceptance Criteria:
+- CanActivate guard on main routes
+- Redirect to /setup if not Operational
+- Allow /setup route always
+- Clear guard after setup complete
+```
+
+#### F3.2 Wizard Component
+
+**US-3.2.1: Create wizard container component**
+```
+As a UI user
+I need a wizard interface
+So that I can complete setup step by step
+
+Acceptance Criteria:
+- Stepper showing all steps
+- Current step highlighted
+- Completed steps show checkmark
+- Skipped steps show dash
+- Click to navigate (completed steps only)
+
+Files to modify:
+- src/Web/StellaOps.Web/src/app/features/setup-wizard/setup-wizard.component.ts (new)
+- src/Web/StellaOps.Web/src/app/features/setup-wizard/setup-wizard.routes.ts (new)
+```
+
+**US-3.2.2: Implement step navigation**
+```
+As a UI user
+I need navigation controls
+So that I can move between steps
+
+Acceptance Criteria:
+- Continue button proceeds to next step
+- Skip button (optional steps) moves forward
+- Back button returns to previous step
+- Keyboard navigation support
+```
+
+#### F3.3 Step Forms
+
+**US-3.3.1: Database setup form component**
+```
+As a UI user
+I need a form to configure database connection
+So that I can set up PostgreSQL
+
+Acceptance Criteria:
+- Form fields for host, port, database, username, password
+- SSL mode dropdown
+- Password field with show/hide toggle
+- Field validation
+- Test Connection button
+
+Files to modify:
+- src/Web/StellaOps.Web/src/app/features/setup-wizard/steps/database-step.component.ts (new)
+```
+
+**US-3.3.2: Valkey setup form component**
+```
+As a UI user
+I need a form to configure Valkey connection
+So that I can set up caching and queues
+
+Acceptance Criteria:
+- Form fields for host, port, password
+- TLS toggle
+- Database index selector
+- Test Connection button
+```
+
+**US-3.3.3: Admin bootstrap form component**
+```
+As a UI user
+I need a form to create admin account
+So that I can access the system
+
+Acceptance Criteria:
+- Form fields for username, email, password, confirm password
+- Password strength indicator
+- Validation messages
+```
+
+**US-3.3.4: Vault integration form component**
+```
+As a UI user
+I need a form to configure vault
+So that I can set up secrets management
+
+Acceptance Criteria:
+- Provider type selector (cards)
+- Dynamic form based on provider
+- Add another provider button
+- List of configured providers
+```
+
+**US-3.3.5: SCM integration form component**
+```
+As a UI user
+I need a form to configure SCM
+So that I can connect source control
+
+Acceptance Criteria:
+- Provider type selector
+- Dynamic form based on provider
+- Multiple providers support
+- Test connection for each
+```
+
+#### F3.4 Connection Testing
+
+**US-3.4.1: Connection test component**
+```
+As a UI user
+I need visual feedback during connection tests
+So that I know the status
+
+Acceptance Criteria:
+- Loading spinner during test
+- Progress steps shown
+- Success state with details
+- Failure state with error message
+```
+
+#### F3.5 Doctor Results Panel
+
+**US-3.5.1: Check results display**
+```
+As a UI user
+I need to see validation results
+So that I know if configuration is correct
+
+Acceptance Criteria:
+- List of checks with pass/warn/fail icons
+- Expandable details per check
+- Evidence data shown
+- Filter by status
+```
+
+#### F3.6 Remediation Display
+
+**US-3.6.1: Remediation command display**
+```
+As a UI user
+I need to see fix commands when checks fail
+So that I can resolve issues
+
+Acceptance Criteria:
+- Likely causes listed
+- Commands in code blocks
+- Copy button per command
+- Runtime-specific tabs
+- Retry button after applying fix
+```
+
+---
+
+## 6. Epic 4: Integration Connectors
+
+### 6.1 Features
+
+| Feature | Description |
+|---------|-------------|
+| F4.1 | Default connector detection |
+| F4.2 | Multi-connector management |
+| F4.3 | Connector preference persistence |
+
+### 6.2 User Stories
+
+**US-4.1.1: Detect default vault provider**
+```
+As a setup wizard
+I need to detect the most likely vault provider
+So that I can suggest it to the user
+
+Acceptance Criteria:
+- Check VAULT_ADDR environment variable
+- Check Azure IMDS endpoint
+- Check AWS metadata endpoint
+- Return detected provider or null
+```
+
+**US-4.2.1: Support multiple vault integrations**
+```
+As a user
+I need to configure multiple vault providers
+So that I can use different vaults for different purposes
+
+Acceptance Criteria:
+- Add up to 5 vault integrations
+- Each has unique name
+- List shows all configured
+- Edit/remove individual integrations
+```
+
+**US-4.3.1: Persist connector preferences**
+```
+As a user
+I need my last selected connector saved
+So that reconfiguration shows my preferences
+
+Acceptance Criteria:
+- Save last used connector per category
+- Load preferences on reconfigure
+- Pre-select last used connector
+```
+
+---
+
+## 7. Epic 5: Configuration Pane
+
+### 7.1 Features
+
+| Feature | Description |
+|---------|-------------|
+| F5.1 | Configuration pane route and component |
+| F5.2 | Health status display |
+| F5.3 | Reconfigure individual steps |
+
+### 7.2 User Stories
+
+**US-5.1.1: Configuration pane component**
+```
+As a user
+I need a configuration pane in settings
+So that I can reconfigure after initial setup
+
+Acceptance Criteria:
+- Route: /settings/configuration
+- Menu entry in Settings
+- Show all configuration categories
+- Last configured timestamp
+```
+
+**US-5.2.1: Display current health status**
+```
+As a user
+I need to see health status per configuration
+So that I know if anything needs attention
+
+Acceptance Criteria:
+- Health badge per category (Healthy, Degraded, Unhealthy)
+- Click to see Doctor check details
+- Refresh button to re-run checks
+```
+
+**US-5.3.1: Reconfigure individual step**
+```
+As a user
+I need to reconfigure a specific step
+So that I can update settings without full wizard
+
+Acceptance Criteria:
+- Manage button per category
+- Opens step form pre-populated
+- Test and save functionality
+- Run Doctor checks after save
+```
+
+---
+
+## 8. Technical Spikes
+
+| Spike | Question | Output |
+|-------|----------|--------|
+| **TS-1** | How should setup state be persisted across CLI sessions? | Design doc for state storage |
+| **TS-2** | How to share validation logic between CLI and UI? | Shared library design |
+| **TS-3** | How to handle long-running migrations in wizard? | Progress reporting design |
+| **TS-4** | How to test runtime detection across platforms? | Test strategy doc |
+
+---
+
+## 9. Definition of Done
+
+### 9.1 Code Quality
+
+- [ ] All new code has unit tests (>80% coverage)
+- [ ] Integration tests for Doctor check integration
+- [ ] E2E tests for CLI interactive flow (Playwright)
+- [ ] E2E tests for UI wizard (Playwright)
+- [ ] No new compiler warnings
+- [ ] Code reviewed and approved
+
+### 9.2 Documentation
+
+- [ ] CLI help text complete and accurate
+- [ ] Quickstart guide updated with wizard
+- [ ] API documentation for new endpoints
+- [ ] Architecture doc updated
+
+### 9.3 Accessibility
+
+- [ ] UI meets WCAG 2.1 AA
+- [ ] Keyboard navigation works
+- [ ] Screen reader tested
+
+### 9.4 Feature Flags
+
+- [ ] Wizard behind feature flag initially
+- [ ] Flag documented in operations guide
+- [ ] Rollout plan defined
+
+---
+
+## 10. Test Strategy
+
+### 10.1 Unit Tests
+
+| Component | Test Focus |
+|-----------|------------|
+| RuntimeDetector | Mock file system and environment |
+| PlaceholderResolver | Various placeholder patterns |
+| SetupStateStore | State persistence and loading |
+| SetupConfigParser | YAML parsing and validation |
+
+### 10.2 Integration Tests
+
+| Scenario | Setup |
+|----------|-------|
+| Database check flow | Testcontainers PostgreSQL |
+| Valkey check flow | Testcontainers Valkey |
+| Migration execution | In-memory database |
+| Vault integration | Mock vault server |
+
+### 10.3 E2E Tests
+
+| Flow | Tool |
+|------|------|
+| CLI interactive setup | Bash script with expect |
+| CLI non-interactive | YAML config files |
+| UI wizard complete | Playwright |
+| UI first-run blocking | Playwright |
+
+---
+
+## 11. Rollout Strategy
+
+### Phase 1: Internal Testing
+- Feature flag enabled for dev team
+- Dogfooding in internal environments
+- Bug fixes and polish
+
+### Phase 2: Beta
+- Feature flag enabled for opt-in users
+- Documentation available
+- Feedback collection
+
+### Phase 3: General Availability
+- Feature flag removed
+- Default wizard enabled
+- Migration guide for existing installations
+
+---
+
+## 12. Dependencies
+
+| Dependency | Status | Owner |
+|------------|--------|-------|
+| Doctor Plugin API stable | Done | Platform team |
+| Authority admin bootstrap API | In progress | Auth team |
+| Integration connectors API | Done | Integration team |
+| Notify channel test endpoint | Needed | Notify team |
+
+---
+
+## 13. Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Runtime detection unreliable | Medium | High | Fallback to "Bare" with manual commands |
+| Long migration blocking UI | Medium | Medium | Background job with progress |
+| Secret handling complexity | Low | High | Strict redaction policy, security review |
+| Cross-platform CLI issues | Medium | Medium | CI matrix testing on all platforms |