git.stella-ops.org/docs/setup/setup-wizard-sprint-plan.md

# 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 |