ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/.patch/477/TODO.md

13 KiB
Raw Blame History

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