214 lines
6.9 KiB
Markdown
214 lines
6.9 KiB
Markdown
# Issue #478 Fix Plan: Status Command Not Detecting BMAD Installations
|
|
|
|
## Problem Statement
|
|
|
|
The `npx bmad-method status` command fails to detect existing BMAD installations (e.g., `.bmad-core/` folders) in the project directory tree, even though they exist and were created during installation.
|
|
|
|
## Root Cause
|
|
|
|
The `findInstallation()` function does not properly handle the original working directory (`originalCwd`). When the command is run via `npx`, the current working directory may be different from where the command was originally invoked, causing the search to look in the wrong location.
|
|
|
|
## Solution Overview
|
|
|
|
1. **Identify the issue** in the codebase by locating `findInstallation()` function
|
|
2. **Create detection tests** to reproduce the bug
|
|
3. **Implement the fix** by properly using `originalCwd`
|
|
4. **Create validation tests** to ensure the fix works
|
|
5. **Execute full test suite** to verify no regressions
|
|
|
|
---
|
|
|
|
## Phase 1: Issue Detection & Analysis
|
|
|
|
### 1.1 Locate Key Functions
|
|
|
|
- [ ] Find `findInstallation()` function in codebase
|
|
- [ ] Find `status` command implementation
|
|
- [ ] Identify where `originalCwd` is captured/available
|
|
- [ ] Check how current working directory is used in search logic
|
|
|
|
### 1.2 Code Review
|
|
|
|
- [ ] Review how `.bmad-*` folders are created during installation
|
|
- [ ] Review how status command searches for installations
|
|
- [ ] Identify the disconnect between creation path and search path
|
|
- [ ] Document the flow: install → create folder → status → search
|
|
|
|
### 1.3 Reproduce the Bug
|
|
|
|
- [ ] Create test project structure with `.bmad-core/` folder
|
|
- [ ] Run status command from different directories
|
|
- [ ] Confirm the bug: status fails to detect nearby BMAD installations
|
|
- [ ] Document exact failure scenarios
|
|
|
|
---
|
|
|
|
## Phase 2: Create Detection Tests
|
|
|
|
### 2.1 Unit Tests for findInstallation()
|
|
|
|
- [ ] Test `findInstallation()` with `.bmad-core/` in current directory
|
|
- [ ] Test `findInstallation()` with `.bmad-*` in parent directories
|
|
- [ ] Test `findInstallation()` with `.bmad-*` in deeply nested directories
|
|
- [ ] Test `findInstallation()` when no installation exists
|
|
- [ ] Test `findInstallation()` with multiple BMAD installations in tree
|
|
- [ ] Test `findInstallation()` with correct `originalCwd` parameter
|
|
- [ ] Test `findInstallation()` with different `originalCwd` vs current working directory
|
|
|
|
### 2.2 Integration Tests for Status Command
|
|
|
|
- [ ] Test status command in project with `.bmad-core/` folder
|
|
- [ ] Test status command in subdirectory of BMAD project
|
|
- [ ] Test status command via `npx` (simulating real usage)
|
|
- [ ] Test status command with hidden folders
|
|
- [ ] Test status command output format
|
|
|
|
### 2.3 Test File Location
|
|
|
|
- `test/unit/find-installation.test.js` (new)
|
|
- `test/integration/status-command.test.js` (new or enhance existing)
|
|
|
|
---
|
|
|
|
## Phase 3: Implement the Fix
|
|
|
|
### 3.1 Code Changes Required
|
|
|
|
**File**: `tools/cli/commands/status.js` (or similar)
|
|
|
|
- Ensure `originalCwd` is passed to `findInstallation()`
|
|
- Verify working directory handling
|
|
|
|
**File**: `tools/cli/lib/detector.js` (or find-installation module)
|
|
|
|
- Update `findInstallation()` to accept and use `originalCwd`
|
|
- Change search logic to start from `originalCwd` instead of `process.cwd()`
|
|
- Handle relative path resolution correctly
|
|
|
|
### 3.2 Implementation Checklist
|
|
|
|
- [ ] Modify function signature to include `originalCwd` parameter
|
|
- [ ] Update search algorithm to use `originalCwd` as starting point
|
|
- [ ] Handle path resolution correctly (relative vs absolute)
|
|
- [ ] Test with trailing slashes, symlinks, etc.
|
|
- [ ] Ensure backward compatibility if function is called elsewhere
|
|
- [ ] Update all callers of `findInstallation()` to pass `originalCwd`
|
|
|
|
---
|
|
|
|
## Phase 4: Create Validation Tests
|
|
|
|
### 4.1 Fix Verification Tests
|
|
|
|
- [ ] Test that status detects `.bmad-core/` in current directory
|
|
- [ ] Test that status detects `.bmad-*` in parent directories
|
|
- [ ] Test that status works via `npx bmad-method status`
|
|
- [ ] Test that status works from subdirectories
|
|
- [ ] Test that fix doesn't break existing functionality
|
|
|
|
### 4.2 Regression Tests
|
|
|
|
- [ ] Ensure all existing tests still pass
|
|
- [ ] Ensure other commands (install, list, etc.) still work
|
|
- [ ] Verify no performance degradation
|
|
|
|
### 4.3 Edge Case Tests
|
|
|
|
- [ ] Test with `.bmad-` prefixed folders at different nesting levels
|
|
- [ ] Test with multiple BMAD installations (select correct one)
|
|
- [ ] Test with symlinked directories
|
|
- [ ] Test on different OS (Windows path handling)
|
|
- [ ] Test with spaces in directory names
|
|
|
|
---
|
|
|
|
## Phase 5: Execute & Validate
|
|
|
|
### 5.1 Run Test Suite
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
- [ ] All unit tests pass
|
|
- [ ] All integration tests pass
|
|
- [ ] No linting errors
|
|
- [ ] No formatting issues
|
|
|
|
### 5.2 Manual Testing
|
|
|
|
- [ ] Create fresh test project
|
|
- [ ] Run installer to create `.bmad-core/`
|
|
- [ ] Run `npx bmad-method status` from project root
|
|
- [ ] Verify status output shows "BMad installation found"
|
|
- [ ] Test from subdirectories
|
|
- [ ] Test with multiple installations
|
|
|
|
### 5.3 Full Validation
|
|
|
|
- [ ] Run `npm run validate:schemas`
|
|
- [ ] Run `npm run lint`
|
|
- [ ] Run `npm run format:check`
|
|
- [ ] Run `npm test`
|
|
- [ ] Run `npm run test:coverage`
|
|
|
|
---
|
|
|
|
## Files to Modify
|
|
|
|
### Production Code
|
|
|
|
- `tools/cli/lib/detector.js` - Update `findInstallation()` function
|
|
- `tools/cli/commands/status.js` - Pass `originalCwd` to finder
|
|
- `tools/cli/installers/lib/core/detector.js` - If separate instance exists
|
|
|
|
### Test Code (New/Modified)
|
|
|
|
- `test/unit/find-installation.test.js` - NEW
|
|
- `test/integration/status-command.test.js` - NEW or ENHANCE
|
|
- `test/fixtures/bmad-project/` - Test fixtures with `.bmad-*` folders
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
✅ **All of the following must be true:**
|
|
|
|
1. Status command detects BMAD installations in project directory
|
|
2. Status command works via `npx bmad-method status`
|
|
3. Status command works from subdirectories of BMAD project
|
|
4. All existing tests pass
|
|
5. New tests validate the fix
|
|
6. No linting or formatting issues
|
|
7. Documentation updated if needed
|
|
|
|
---
|
|
|
|
## Estimated Effort
|
|
|
|
| Phase | Time | Complexity |
|
|
| ---------------------- | -------------- | ---------- |
|
|
| Detection & Analysis | 30-45 min | Low |
|
|
| Create Tests | 45-60 min | Medium |
|
|
| Implement Fix | 30-45 min | Low-Medium |
|
|
| Validation Tests | 45-60 min | Medium |
|
|
| Execution & Validation | 30-45 min | Low |
|
|
| **TOTAL** | **~3-4 hours** | **Medium** |
|
|
|
|
---
|
|
|
|
## Related Issues/PRs
|
|
|
|
- Issue #478: Status command not detecting installations
|
|
- PR #480: Honor original working directory (related context)
|
|
- Comments by: @dracic, @manjaroblack, @moyger
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- The core issue is the use of `process.cwd()` vs the actual directory where the command was invoked
|
|
- `originalCwd` should be captured at CLI entry point and passed through the call chain
|
|
- Consider using Node.js `__dirname` and relative path resolution patterns
|
|
- May need to normalize paths for cross-platform compatibility
|