20 KiB
20 KiB
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 |