11 KiB

Raw Blame History

TODO List: Issue #478 - Fix Status Command Installation Detection

Project: Fix v6 for #478 - No BMad installation found in current directory tree

Status: Not Started Priority: High Issue URL: https://github.com/bmad-code-org/BMAD-METHOD/issues/478

PHASE 1: ISSUE DETECTION & ANALYSIS

Goal: Understand the root cause and current behavior

Task 1.1: Locate Key Source Files

Find findInstallation() function location
- Check: tools/cli/lib/detector.js
- Check: tools/cli/installers/lib/core/detector.js
- Check: tools/cli/commands/status.js
Document function signature and parameters
Identify where originalCwd is available

Task 1.2: Understand Current Implementation

Review how status command invokes findInstallation()
Check if originalCwd is being captured anywhere
Review how .bmad-* folders are searched
Identify the working directory at each step
Document current flow in detection report

Task 1.3: Create Detection Report

Document current behavior (bug reproduction)
Show code snippets of problematic areas
Explain why bug occurs (cwd vs originalCwd mismatch)
Propose initial fix approach
Deliverable: DETECTION-REPORT.md

Time Estimate: 45-60 minutes Difficulty: Low Owner: TBD

PHASE 2: CREATE DETECTION TESTS

Goal: Create tests that reproduce the bug and identify exact failure points

Task 2.1: Create Unit Tests for findInstallation()

File: test/unit/find-installation.test.js (NEW)

Test suite: "findInstallation() with originalCwd"
- Should find .bmad-core/ in current directory
- Should find .bmad-core/ in parent directory
- Should NOT find installation when it doesn't exist
- Should find closest installation in directory tree
- Should respect originalCwd parameter over process.cwd()
Test suite: "findInstallation() directory search behavior"
- Verify search starts from originalCwd
- Verify search traverses up directory tree
- Verify hidden folders are detected
- Verify multiple installations pick closest one
- Verify returns null when no installation found
Test suite: "findInstallation() with mocked filesystem"
- Mock different project structures
- Test with nested BMAD installations
- Test with various folder names (.bmad-, .bmad-core, etc.)

Time Estimate: 60-75 minutes Difficulty: Medium

Task 2.2: Create Integration Tests for Status Command

File: test/integration/status-command-detection.test.js (NEW)

Test suite: "Status command in project with BMAD installation"
- Create fixture: project with .bmad-core/ folder
- Run status command, verify it detects installation
- Run status from subdirectory, verify detection
- Run status via npx, verify detection
Test suite: "Status command current directory handling"
- Test from project root
- Test from nested subdirectory
- Test from sibling directory
- Test with symlinked folders

Time Estimate: 45-60 minutes Difficulty: Medium

Task 2.3: Create Test Fixtures

Folder: test/fixtures/bmad-project-478/

Create project structure:

test/fixtures/bmad-project-478/
├── .bmad-core/
│   ├── config.yaml
│   └── agents/
├── src/
│   └── index.js
└── package.json

Create nested subdirectory structure for testing
Create multiple installations for edge case testing

Time Estimate: 15-20 minutes Difficulty: Low

Cumulative Time: ~2-2.5 hours Milestone: Tests that fail and demonstrate the bug

PHASE 3: IMPLEMENT THE FIX

Goal: Fix the root cause - ensure originalCwd is properly used

Task 3.1: Analyze Current findInstallation() Implementation

Read full implementation of findInstallation()
Identify all places using process.cwd()
Check function call signature
Verify parameter handling
Document analysis in code comments

Task 3.2: Update findInstallation() Function

File: tools/cli/lib/detector.js (or identified location)

Modify function signature to require originalCwd parameter
Replace process.cwd() with originalCwd in search logic
Ensure path.resolve() uses originalCwd as base
Add JSDoc comments explaining originalCwd parameter
Validate path resolution on Windows and Unix

Code Change Checklist:

Function accepts originalCwd parameter
Search logic uses originalCwd
Relative paths resolved from originalCwd
Path normalization handled correctly
Backward compatibility considered

Task 3.3: Update Status Command

File: tools/cli/commands/status.js (or identified location)

Capture originalCwd at command entry point
Pass originalCwd to findInstallation()
Verify all callers of findInstallation() are updated
Add error handling for missing originalCwd

Task 3.4: Review All Callers

Find all places where findInstallation() is called
Update each caller to pass originalCwd
Ensure originalCwd is available at each call site
Add comments explaining the parameter

Task 3.5: Code Review & Testing

Run linting on modified files
Run formatting check
Verify syntax correctness
Check for any new linting violations

Time Estimate: 45-60 minutes Difficulty: Low-Medium

Cumulative Time: ~2.5-3.5 hours Milestone: Fix implemented and linted

PHASE 4: VALIDATION TESTS

Goal: Create comprehensive tests to verify the fix works

Task 4.1: Enhance Existing Tests

Update/enhance any existing detection tests
Ensure tests pass with the fix in place
Add comments explaining what each test validates

Task 4.2: Create Fix Validation Test Suite

File: test/integration/status-fix-validation.test.js (NEW)

Test suite: "Status command AFTER fix"
- Verify status detects .bmad-core/ correctly
- Verify status works via npx
- Verify status works from subdirectories
- Verify status output is correct
- Verify error handling when no installation
Test suite: "Status command with originalCwd"
- Test with explicit originalCwd parameter
- Test with different originalCwd vs process.cwd()
- Verify correct installation is found

Time Estimate: 60-75 minutes Difficulty: Medium

Task 4.3: Regression Test Suite

File: Add to test/integration/regression-tests.test.js (NEW or existing)

Test that other commands still work:
- npx bmad-method install
- npx bmad-method list
- npx bmad-method status (various scenarios)
Verify no changes to existing command behavior
Ensure performance not degraded

Time Estimate: 45-60 minutes Difficulty: Medium

Cumulative Time: ~3.5-4.5 hours Milestone: All validation tests created and passing

PHASE 5: EXECUTION & VALIDATION

Goal: Run full test suite and verify everything works

Task 5.1: Run Unit Tests

npm test -- test/unit/find-installation.test.js

All tests pass
No errors or warnings
Test coverage adequate (80%+)

Time: 10-15 minutes

Task 5.2: Run Integration Tests

npm test -- test/integration/status-command-detection.test.js
npm test -- test/integration/status-fix-validation.test.js

All tests pass
Status command works correctly
originalCwd handling verified

Time: 10-15 minutes

Task 5.3: Run Full Test Suite

npm test

All tests pass
No regressions
0 failures

Time: 15-20 minutes

Task 5.4: Linting & Formatting

npm run lint
npm run format:check

0 linting errors
All files properly formatted

Time: 5-10 minutes

Task 5.5: Schema Validation

npm run validate:schemas

All schemas valid
No validation errors

Time: 5 minutes

Task 5.6: Manual Testing

Create test project directory
Create .bmad-core/ folder manually
Run npx bmad-method status
Verify output shows installation found
Test from subdirectory
Test from different directory levels

Time: 20-30 minutes

Task 5.7: Documentation Updates

Update issue #478 with fix description
Add comments to modified code
Create COMPLETION-REPORT.md
Document any breaking changes (if any)