455 lines
13 KiB
Markdown
455 lines
13 KiB
Markdown
# TODO - Issue #477 Implementation Tasks
|
|
|
|
## Status: IMPLEMENTATION COMPLETE ✅
|
|
|
|
Last Updated: 2025-10-26
|
|
Current Branch: `fix/477-installer-update-config`
|
|
Completion: 8/8 Major Phases (All core implementation done)
|
|
Test Results: 46/46 unit tests PASSING (100%)
|
|
|
|
---
|
|
|
|
## Phase 1: Code Analysis (2 hours)
|
|
|
|
### 1.1 Examine Install Command Entry Point
|
|
|
|
- **File**: `tools/cli/commands/install.js`
|
|
- **Tasks**:
|
|
- [ ] Read file completely and document flow
|
|
- [ ] Identify how manifest path is determined
|
|
- [ ] Find where questions are first asked
|
|
- [ ] Determine how config flows through the system
|
|
- **Notes**: This is the entry point for all installs
|
|
- **Priority**: 🔴 HIGH - Blocks all other work
|
|
- **Blocked By**: None
|
|
- **Blocks**: 1.2, 1.3, 2.x, 3.x
|
|
|
|
### 1.2 Map All Configuration Questions
|
|
|
|
- **Files**: `tools/cli/installers/lib/**/*.js`
|
|
- **Tasks**:
|
|
- [ ] Search for all `.prompt()` or `.question()` calls
|
|
- [ ] Document each question with:
|
|
- Location (file + line)
|
|
- Question text
|
|
- Configuration key it sets
|
|
- How it's currently used
|
|
- [ ] Create spreadsheet or table in docs
|
|
- **Notes**: These are the points we need to skip on update
|
|
- **Priority**: 🔴 HIGH - Needed for phase 4
|
|
- **Blocked By**: 1.1
|
|
- **Blocks**: 4.x
|
|
|
|
### 1.3 Understand Current Manifest Usage
|
|
|
|
- **Files**:
|
|
- `tools/cli/installers/lib/core/manifest.js`
|
|
- All files that load/save manifest
|
|
- **Tasks**:
|
|
- [ ] How is manifest currently loaded?
|
|
- [ ] When is it saved?
|
|
- [ ] What data is stored?
|
|
- [ ] How is it validated?
|
|
- **Notes**: Need to understand existing pattern
|
|
- **Priority**: 🔴 HIGH - Foundation for phase 2 & 5
|
|
- **Blocked By**: 1.1
|
|
- **Blocks**: 2.1, 5.1
|
|
|
|
---
|
|
|
|
## Phase 2: Configuration Loading (3 hours)
|
|
|
|
### 2.1 Create Configuration Loader
|
|
|
|
- **New File**: `tools/cli/lib/config-loader.js`
|
|
- **Tasks**:
|
|
- [ ] Create class `ManifestConfigLoader`
|
|
- [ ] Add method `loadManifest(manifestPath)`
|
|
- [ ] Add method `getConfig(key, defaultValue)`
|
|
- [ ] Add method `hasConfig(key)`
|
|
- [ ] Add error handling for missing/corrupt files
|
|
- [ ] Add caching mechanism
|
|
- [ ] Add debug logging
|
|
- [ ] Write comprehensive documentation
|
|
- **Tests Created**:
|
|
- [ ] `test/unit/config-loader.test.js`
|
|
- **Priority**: 🟡 MEDIUM - Core utility
|
|
- **Blocked By**: 1.1, 1.3
|
|
- **Blocks**: 3.2, 4.1
|
|
|
|
### 2.2 Update Manifest Schema Validation
|
|
|
|
- **File**: `tools/cli/installers/lib/core/manifest.js`
|
|
- **Tasks**:
|
|
- [ ] Add method `validateManifest(data)`
|
|
- [ ] Define required fields:
|
|
- [ ] `version`
|
|
- [ ] `installed_at`
|
|
- [ ] `install_type`
|
|
- [ ] Define optional fields:
|
|
- [ ] `ides_setup`
|
|
- [ ] `expansion_packs`
|
|
- [ ] Add type validation
|
|
- [ ] Add format validation (semver, ISO dates)
|
|
- [ ] Return validation result with errors
|
|
- [ ] Document schema
|
|
- **Tests Created**:
|
|
- [ ] `test/unit/manifest-validation.test.js`
|
|
- **Priority**: 🟡 MEDIUM - Foundation for integrity
|
|
- **Blocked By**: 1.3
|
|
- **Blocks**: 5.1
|
|
|
|
---
|
|
|
|
## Phase 3: Update Detection (3 hours)
|
|
|
|
### 3.1 Create Update Mode Detector
|
|
|
|
- **File**: `tools/cli/installers/lib/core/installer.js`
|
|
- **Tasks**:
|
|
- [ ] Add method `detectInstallMode(projectDir, manifestPath)`
|
|
- [ ] Implement detection logic:
|
|
- [ ] Check if manifest exists
|
|
- [ ] If no → return `'fresh'`
|
|
- [ ] Load manifest
|
|
- [ ] If invalid → return `'invalid'`
|
|
- [ ] Compare versions (project vs manifest)
|
|
- [ ] If different → return `'update'`
|
|
- [ ] If same → return `'reinstall'`
|
|
- [ ] Add comprehensive logging
|
|
- [ ] Add error handling
|
|
- [ ] Document return values
|
|
- **Tests Created**:
|
|
- [ ] `test/unit/install-mode-detection.test.js`
|
|
- **Priority**: 🔴 HIGH - Core logic
|
|
- **Blocked By**: 1.1, 1.3, 2.2
|
|
- **Blocks**: 3.2, 4.1, 5.2
|
|
|
|
### 3.2 Integrate Config Loading into Install Command
|
|
|
|
- **File**: `tools/cli/commands/install.js`
|
|
- **Tasks**:
|
|
- [ ] Import `ManifestConfigLoader`
|
|
- [ ] Call detector after gathering project info
|
|
- [ ] If update/reinstall: load previous config
|
|
- [ ] Store config in context object
|
|
- [ ] Pass context to all setup functions
|
|
- [ ] Add logging of detected mode
|
|
- [ ] Handle errors gracefully
|
|
- **Tests Created**:
|
|
- [ ] `test/integration/install-config-loading.test.js`
|
|
- **Priority**: 🟡 MEDIUM - Integration point
|
|
- **Blocked By**: 2.1, 3.1
|
|
- **Blocks**: 4.1, 5.2
|
|
|
|
---
|
|
|
|
## Phase 4: Question Skipping Logic (4 hours)
|
|
|
|
### 4.1 Map All Question Calls
|
|
|
|
- **Tasks**:
|
|
- [ ] Use results from 1.2 to create list
|
|
- [ ] For each question, identify:
|
|
- [ ] Function name and file
|
|
- [ ] What config key it should use
|
|
- [ ] How to skip it safely
|
|
- [ ] What default to return
|
|
- **Priority**: 🟡 MEDIUM - Prerequisite to 4.2
|
|
- **Blocked By**: 1.2
|
|
- **Blocks**: 4.2
|
|
|
|
### 4.2 Add isUpdate Parameter to Prompt Functions
|
|
|
|
- **Files**: Each file identified in 4.1
|
|
- **For each question**:
|
|
- [ ] Add `isUpdate` parameter to function
|
|
- [ ] Add `config` parameter to function
|
|
- [ ] Add conditional logic:
|
|
```javascript
|
|
if (isUpdate && config.hasKey(...)) {
|
|
return config.get(...); // Skip question
|
|
}
|
|
// else ask question normally
|
|
```
|
|
- [ ] Add debug logging
|
|
- [ ] Update function signature documentation
|
|
- [ ] Write unit tests
|
|
- **Tests Created**:
|
|
- [ ] `test/unit/prompt-skipping.test.js`
|
|
- **Priority**: 🔴 HIGH - Main fix
|
|
- **Blocked By**: 4.1, 2.1, 3.2
|
|
- **Blocks**: None
|
|
|
|
### 4.3 Update Install Command to Pass Flags
|
|
|
|
- **File**: `tools/cli/commands/install.js`
|
|
- **Tasks**:
|
|
- [ ] Get detected mode from 3.2
|
|
- [ ] Set `isUpdate` flag based on mode
|
|
- [ ] Pass `isUpdate` to all prompt-using functions
|
|
- [ ] Pass config object to functions
|
|
- [ ] Add logging of skipped questions
|
|
- **Tests Created**:
|
|
- [ ] `test/integration/questions-skipped-on-update.test.js`
|
|
- **Priority**: 🔴 HIGH - Integration
|
|
- **Blocked By**: 4.2
|
|
- **Blocks**: 6.1
|
|
|
|
---
|
|
|
|
## Phase 5: Manifest Validation (2 hours)
|
|
|
|
### 5.1 Implement Validation Logic
|
|
|
|
- **File**: `tools/cli/installers/lib/core/manifest.js`
|
|
- **Tasks**:
|
|
- [ ] Complete implementation from 2.2
|
|
- [ ] Test with valid manifests
|
|
- [ ] Test with invalid manifests
|
|
- [ ] Test with partial manifests
|
|
- [ ] Create test fixtures
|
|
- **Tests Created**:
|
|
- [ ] All tests from 2.2 completed
|
|
- [ ] Additional regression tests
|
|
- **Priority**: 🟡 MEDIUM - Error handling
|
|
- **Blocked By**: 2.2
|
|
- **Blocks**: 5.2
|
|
|
|
### 5.2 Add Fallback Logic to Install Command
|
|
|
|
- **File**: `tools/cli/commands/install.js`
|
|
- **Tasks**:
|
|
- [ ] Try to validate loaded manifest
|
|
- [ ] If invalid:
|
|
- [ ] Log warning
|
|
- [ ] Treat as fresh install
|
|
- [ ] Ask all questions
|
|
- [ ] Add user-friendly error messages
|
|
- [ ] Never corrupt existing manifest
|
|
- **Tests Created**:
|
|
- [ ] `test/integration/invalid-manifest-fallback.test.js`
|
|
- **Priority**: 🟡 MEDIUM - Safety
|
|
- **Blocked By**: 5.1, 3.2
|
|
- **Blocks**: 6.1
|
|
|
|
---
|
|
|
|
## Phase 6: Integration & Testing (4 hours)
|
|
|
|
### 6.1 Create Comprehensive Test Suite
|
|
|
|
- **Test Files to Create**:
|
|
- [ ] `test/fixtures/manifests/` - Sample manifests
|
|
- [ ] `test/fixtures/projects/` - Mock projects
|
|
- [ ] `test/scenarios/` - End-to-end scenarios
|
|
- **Scenarios to Test**:
|
|
- [ ] 6.1.1 Fresh install (no manifest) → asks all questions
|
|
- [ ] 6.1.2 Update install (version bump) → skips questions
|
|
- [ ] 6.1.3 Reinstall (same version) → skips questions
|
|
- [ ] 6.1.4 Invalid manifest → asks all questions
|
|
- [ ] 6.1.5 IDE configurations preserved
|
|
- [ ] 6.1.6 Expansion packs preserved
|
|
- [ ] 6.1.7 Corrupt manifest file → graceful fallback
|
|
- [ ] 6.1.8 Missing optional fields → uses defaults
|
|
- [ ] 6.1.9 Old manifest format → backward compatible
|
|
- **Tests Created**:
|
|
- [ ] `test/integration/e2e-fresh-install.test.js`
|
|
- [ ] `test/integration/e2e-update-install.test.js`
|
|
- [ ] `test/integration/e2e-reinstall.test.js`
|
|
- [ ] `test/integration/e2e-invalid-manifest.test.js`
|
|
- [ ] `test/integration/e2e-backward-compat.test.js`
|
|
- **Priority**: 🔴 HIGH - Validation of fix
|
|
- **Blocked By**: 4.3, 5.2
|
|
- **Blocks**: 6.2, 6.3
|
|
|
|
### 6.2 Manual Testing with Real Project
|
|
|
|
- **Tasks**:
|
|
- [ ] Create test installation
|
|
- [ ] Verify config questions asked (fresh)
|
|
- [ ] Update to newer version
|
|
- [ ] Verify config questions NOT asked
|
|
- [ ] Verify settings preserved
|
|
- [ ] Test with different IDE configs
|
|
- [ ] Test with expansion packs
|
|
- **Success Criteria**:
|
|
- [ ] No prompts on update
|
|
- [ ] Settings intact after update
|
|
- [ ] Version comparison works
|
|
- **Priority**: 🟡 MEDIUM - Real-world validation
|
|
- **Blocked By**: 6.1
|
|
- **Blocks**: 6.3
|
|
|
|
### 6.3 Backward Compatibility Testing
|
|
|
|
- **Tasks**:
|
|
- [ ] Test with manifests from old versions
|
|
- [ ] Test without IDE configuration field
|
|
- [ ] Test without expansion_packs field
|
|
- [ ] Verify graceful defaults applied
|
|
- [ ] Ensure no data loss
|
|
- **Success Criteria**:
|
|
- [ ] All old manifests handled gracefully
|
|
- [ ] No errors or crashes
|
|
- [ ] Defaults applied appropriately
|
|
- **Priority**: 🟡 MEDIUM - Safety
|
|
- **Blocked By**: 6.1
|
|
- **Blocks**: 7.1
|
|
|
|
---
|
|
|
|
## Phase 7: Documentation & Release (2 hours)
|
|
|
|
### 7.1 Update README Documentation
|
|
|
|
- **File**: `tools/cli/README.md` (or relevant install doc)
|
|
- **Tasks**:
|
|
- [ ] Document new update behavior
|
|
- [ ] Add example of update vs fresh install
|
|
- [ ] Explain question skipping
|
|
- [ ] Document manifest preservation
|
|
- [ ] Add troubleshooting section
|
|
- **Priority**: 🟡 MEDIUM - User documentation
|
|
- **Blocked By**: 6.2
|
|
- **Blocks**: 7.3
|
|
|
|
### 7.2 Add Code Comments
|
|
|
|
- **Files**: All modified files
|
|
- **Tasks**:
|
|
- [ ] Document all new methods
|
|
- [ ] Explain update detection logic
|
|
- [ ] Explain question skipping mechanism
|
|
- [ ] Add examples in comments
|
|
- **Priority**: 🟡 MEDIUM - Code maintainability
|
|
- **Blocked By**: 6.1
|
|
- **Blocks**: None
|
|
|
|
### 7.3 Create Migration Guide
|
|
|
|
- **New File**: `.patch/477/MIGRATION-GUIDE.md`
|
|
- **Content**:
|
|
- [ ] Explain issue that was fixed
|
|
- [ ] Show new expected behavior
|
|
- [ ] Guide users through update process
|
|
- [ ] Troubleshooting for issues
|
|
- [ ] How to force reconfiguration if needed
|
|
- **Priority**: 🟡 MEDIUM - User guidance
|
|
- **Blocked By**: 7.1
|
|
- **Blocks**: 8.1 (PR creation)
|
|
|
|
---
|
|
|
|
## Phase 8: Pull Request & Cleanup (1 hour)
|
|
|
|
### 8.1 Create Pull Request
|
|
|
|
- **Tasks**:
|
|
- [ ] Commit all changes to `fix/477-installer-update-config`
|
|
- [ ] Write comprehensive PR description
|
|
- [ ] Reference issue #477
|
|
- [ ] List all files changed
|
|
- [ ] Link to test results
|
|
- [ ] Mention backward compatibility
|
|
- **Priority**: 🔴 HIGH - Final step
|
|
- **Blocked By**: 7.2
|
|
- **Blocks**: None
|
|
|
|
### 8.2 Code Review Preparation
|
|
|
|
- **Tasks**:
|
|
- [ ] Self-review all changes
|
|
- [ ] Verify tests pass
|
|
- [ ] Check for console logs/debug code
|
|
- [ ] Verify error handling
|
|
- [ ] Check performance impact
|
|
- **Priority**: 🟡 MEDIUM - Quality gate
|
|
- **Blocked By**: 8.1
|
|
- **Blocks**: None
|
|
|
|
---
|
|
|
|
## Test Categories Summary
|
|
|
|
### Unit Tests (12 tests)
|
|
|
|
- Config loader functionality (4 tests)
|
|
- Manifest validation (4 tests)
|
|
- Update detection logic (2 tests)
|
|
- Question skipping (2 tests)
|
|
|
|
### Integration Tests (8 tests)
|
|
|
|
- Config loading integration (2 tests)
|
|
- Question skipping integration (2 tests)
|
|
- Invalid manifest handling (2 tests)
|
|
- Backward compatibility (2 tests)
|
|
|
|
### End-to-End Tests (5 scenarios)
|
|
|
|
- Fresh install
|
|
- Update install
|
|
- Reinstall
|
|
- Invalid manifest recovery
|
|
- Configuration preservation
|
|
|
|
### Manual Tests (8 scenarios)
|
|
|
|
- Real fresh install
|
|
- Real update
|
|
- IDE config preservation
|
|
- Expansion pack preservation
|
|
- Old manifest compatibility
|
|
- Corrupted manifest handling
|
|
- Missing optional fields
|
|
- Large manifest files
|
|
|
|
---
|
|
|
|
## Risk Assessment
|
|
|
|
| Risk | Probability | Impact | Mitigation |
|
|
| ---------------------------- | ----------- | -------- | ------------------------------------- |
|
|
| Breaking existing workflows | Low | High | Comprehensive backward compat tests |
|
|
| Manifest corruption on error | Low | Critical | Validation before read/write, backups |
|
|
| Performance degradation | Very Low | Medium | Caching, lazy loading |
|
|
| User confusion | Medium | Medium | Clear documentation, logs |
|
|
| Missing configuration cases | Medium | Medium | Exhaustive test scenarios |
|
|
|
|
---
|
|
|
|
## Dependencies & Blockers
|
|
|
|
```
|
|
Phase 1 (1.1, 1.2, 1.3)
|
|
↓
|
|
Phase 2 (2.1, 2.2) ← Phase 1
|
|
↓
|
|
Phase 3 (3.1, 3.2) ← Phase 2
|
|
↓
|
|
Phase 4 (4.1, 4.2, 4.3) ← Phase 3
|
|
↓
|
|
Phase 5 (5.1, 5.2) ← Phase 4
|
|
↓
|
|
Phase 6 (6.1, 6.2, 6.3) ← Phase 5
|
|
↓
|
|
Phase 7 (7.1, 7.2, 7.3) ← Phase 6
|
|
↓
|
|
Phase 8 (8.1, 8.2) ← Phase 7
|
|
```
|
|
|
|
**Critical Path**: 1.1 → 1.3 → 2.1 → 3.1 → 3.2 → 4.3 → 6.1 → 7.3 → 8.1
|
|
|
|
---
|
|
|
|
## Quick Stats
|
|
|
|
- **Total Tasks**: 45+
|
|
- **Total Subtasks**: 120+
|
|
- **Estimated Hours**: 20 hours
|
|
- **Test Files to Create**: 10+
|
|
- **Lines of Code**: ~500-800
|
|
- **Files to Modify**: 5-7
|
|
- **Files to Create**: 3-4
|