12 KiB

Raw Blame History

Issue #477 - Complete Planning Package

Executive Summary

This package contains comprehensive documentation for fixing issue #477: "Installer asks configuration questions during update instead of using existing settings"

Current Status: Planning Phase Complete Branch: fix/477-installer-update-config Estimated Effort: 20 hours Current Date: 2025-01-15

IMPLEMENTATION-PLAN.md - Detailed 7-phase implementation roadmap
TODO.md - Actionable task list with priorities and dependencies
TEST-SPECIFICATIONS.md - Comprehensive test strategy
issue-desc-477.md - Original issue context from GitHub

Problem Statement

What's Wrong

When users run npx bmad-method install on an existing installation with a different version, the installer asks all configuration questions again instead of using the settings stored in install-manifest.yaml.

Example

# First installation (Fresh Install)
$ npx bmad-method install
? Will the PRD be sharded? (Y/n) Y
? Will the Architecture be sharded? (Y/n) Y
? Document Organization Settings? (Y/n) Y
[...installation proceeds...]
✓ Installation complete

# Later: New version released (v4.36.2 → v4.39.2)
$ npx bmad-method install
? Will the PRD be sharded? (Y/n) Y        ← SHOULD NOT ASK!
? Will the Architecture be sharded? (Y/n) Y  ← SHOULD NOT ASK!
? Document Organization Settings? (Y/n) Y   ← SHOULD NOT ASK!
[...should reuse answers from first install...]

Root Cause

The installer doesn't load the existing install-manifest.yaml file
Update detection logic is missing or not functional
No mechanism to pass cached config to question prompts
Questions are asked unconditionally for all installations

Impact

Frustration: Users have to re-answer questions they answered before
Inconsistency: Contradicts documented behavior (update should be idempotent)
Risk: Users might answer differently and create inconsistent configurations
Time: Wastes user time on every update

Solution Overview

5-Component Architecture

Configuration Loader
- Reads install-manifest.yaml
- Parses YAML safely with error handling
- Caches configuration in memory
- Gracefully handles missing/corrupted files
Update Detection System
- Detects fresh install (no manifest → ask questions)
- Detects update (manifest exists, different version → skip questions)
- Detects reinstall (manifest exists, same version → skip questions)
- Handles invalid/corrupted manifest → ask questions
Question Skipping Logic
- Adds isUpdate flag to all prompt functions
- Checks if configuration exists before prompting
- Returns cached value if available
- Falls back to prompting if needed
Manifest Validation
- Validates manifest structure and fields
- Ensures data integrity
- Provides helpful error messages
- Enables graceful fallback on errors
Backward Compatibility
- Handles old manifest formats
- Gracefully handles missing optional fields
- Works with existing installations
- No breaking changes

Key Files to Modify

File	Type	Changes	Priority
`tools/cli/commands/install.js`	Modify	Add update detection, config loading, integration	🔴 HIGH
`tools/cli/lib/config.js`	Modify	Add manifest loading methods	🔴 HIGH
`tools/cli/installers/lib/core/installer.js`	Modify	Add detectInstallMode() method	🔴 HIGH
`tools/cli/installers/lib/core/manifest.js`	Modify	Add validation logic	🟡 MEDIUM
All prompt functions in `tools/cli/installers/lib/`	Modify	Add isUpdate flag and config params	🔴 HIGH
`tools/cli/lib/config-loader.js`	Create	New configuration loader class	🟡 MEDIUM

Implementation Phases

Phase 1: Code Analysis (2 hours)

Examine installer entry point
Map all configuration questions
Understand current manifest usage
Dependency: None

Phase 2: Configuration Loading (3 hours)

Create configuration loader utility
Update manifest schema with validation
Dependency: Phase 1

Phase 3: Update Detection (3 hours)

Create update mode detector
Integrate config loading into install command
Dependency: Phase 2

Phase 4: Question Skipping (4 hours)

Map all question calls
Add isUpdate parameter to functions
Update install command to pass flags
Dependency: Phase 3

Phase 5: Manifest Validation (2 hours)

Implement validation logic
Add fallback logic for errors
Dependency: Phase 2

Phase 6: Integration & Testing (4 hours)

Create comprehensive test suite
Perform manual testing
Test backward compatibility
Dependency: Phase 5

Phase 7: Documentation & Release (2 hours)

Update README documentation
Add code comments
Create migration guide
Dependency: Phase 6

Success Criteria

All of these must be met for the fix to be considered complete:

No configuration questions asked during update
Existing settings preserved from install-manifest.yaml
Version detection still works (shows update available)
Files properly updated without re-asking questions
All IDE configurations preserved
All expansion packs preserved
Backward compatible with existing installations
Graceful fallback on corrupted manifest
Comprehensive test coverage (unit + integration + e2e)
No performance degradation
Clear error messages when issues occur
Documentation updated

Testing Strategy

Test Coverage by Category

Unit Tests (12 tests)

Configuration loader (4 tests)
Manifest validation (4 tests)
Update detection (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 Scenarios (6 scenarios)

Fresh install
Update install
Reinstall
Invalid manifest recovery
IDE configuration preservation
Expansion packs preservation

Manual Tests (8 scenarios)

Real fresh install
Real update install
Settings preservation verification
Large manifest handling
Corrupted manifest recovery
Upgrade from old version
Performance testing
CLI flag testing (future)

Task Breakdown

High Priority Tasks (Critical Path)

Examine Install Command (2h)
- Read tools/cli/commands/install.js completely
- Document how manifest path is determined
- Find where questions are first asked
Create Configuration Loader (3h)
- Create tools/cli/lib/config-loader.js
- Implement manifest loading with error handling
- Add caching mechanism
Create Update Mode Detector (3h)
- Add detectInstallMode() method
- Implement version comparison logic
- Add comprehensive logging
Integrate Config Loading (2h)
- Modify install command
- Pass config to all handlers
- Add debug logging
Add Question Skipping (4h)
- Modify all prompt functions
- Add isUpdate and config parameters
- Implement skip logic

Supporting Tasks

Implement Manifest Validation (2h)
Create Comprehensive Tests (4h)
Manual Testing (2h)
Documentation Updates (2h)
Pull Request Creation (1h)

Risk Mitigation

Risk	Likelihood	Severity	Mitigation
Break existing workflows	Low	High	Comprehensive backward compat tests before release
Manifest corruption	Low	Critical	Validation logic, read-only during detection
Performance impact	Very Low	Medium	Caching strategy, lazy loading, performance tests
User confusion	Medium	Medium	Clear error messages, updated documentation
Missing config cases	Medium	Medium	Exhaustive test scenarios covering all cases

Timeline & Effort Estimate

Phase 1: Analysis          2 hours  |████                    |
Phase 2: Config Loading    3 hours  |██████                  |
Phase 3: Update Detection  3 hours  |██████                  |
Phase 4: Question Skipping 4 hours  |████████                |
Phase 5: Validation        2 hours  |████                    |
Phase 6: Testing           4 hours  |████████                |
Phase 7: Documentation     2 hours  |████                    |
─────────────────────────────────────────────────────────────
TOTAL:                    20 hours  |████████████████████    |

Recommended Approach:

Sprints of 2-4 hours each
Focus on one phase per session
Test immediately after each phase
Commit after each phase

Getting Started

Next Steps

Open TODO.md
- Start with Phase 1, Task 1.1
- Follow checkboxes in order
- Mark items complete as you go
Refer to IMPLEMENTATION-PLAN.md
- Detailed guidance for each phase
- Files to modify and code structure
- Expected outcomes for each task
Use TEST-SPECIFICATIONS.md
- Create tests before implementing
- Follow TDD approach
- Use test scenarios as acceptance criteria
Maintain this Branch
- All work in fix/477-installer-update-config
- Commit after each phase
- Push when phase complete

Useful Commands

# Check current branch
git branch --show-current

# View changes made
git status

# View specific changes
git diff tools/cli/commands/install.js

# Run tests
npm test -- test/unit/ --verbose

# Create commit for phase
git commit -m "feat(#477): Phase X - [phase-name]"

# Push to remote
git push origin fix/477-installer-update-config

Files in This Package

.patch/477/
├── README.md                      ← This file
├── IMPLEMENTATION-PLAN.md         ← Detailed 7-phase roadmap
├── TODO.md                        ← Actionable task list
├── TEST-SPECIFICATIONS.md         ← Comprehensive test strategy
├── issue-desc-477.md              ← Original GitHub issue context
└── PLAN.md                        ← Original outline (superseded by above)

Contact & Questions

If you have questions about:

Implementation details: See IMPLEMENTATION-PLAN.md
Task breakdown: See TODO.md
Testing approach: See TEST-SPECIFICATIONS.md
Issue context: See issue-desc-477.md

Conclusion

This is a straightforward fix with a well-defined scope and clear success criteria. The systematic approach (Phase 1-7) ensures thorough implementation with minimal risk of breaking existing functionality. Comprehensive testing and backward compatibility validation provide confidence in the solution.

Status: Ready to begin Phase 1: Code Analysis

Start Time: [When you begin implementation] Estimated Completion: [When you finish all phases]

12 KiB Raw Blame History