184 lines
4.6 KiB
Markdown
184 lines
4.6 KiB
Markdown
# V6 Local Development Guide
|
|
|
|
## Running Local Development Version
|
|
|
|
When developing on the V6 fork, **DO NOT use** `npx bmad-method` - this downloads the published npm package which does not include fork-specific features like OpenCode integration.
|
|
|
|
### Direct Node Execution (Recommended)
|
|
|
|
```bash
|
|
# Install BMAD to a project
|
|
node tools/cli/bmad-cli.js install
|
|
|
|
# Check installation status
|
|
node tools/cli/bmad-cli.js status
|
|
|
|
# List available modules
|
|
node tools/cli/bmad-cli.js list
|
|
|
|
# Uninstall BMAD from a project
|
|
node tools/cli/bmad-cli.js uninstall
|
|
```
|
|
|
|
### Using npm Scripts
|
|
|
|
The following npm scripts are available for convenience:
|
|
|
|
```bash
|
|
# Development scripts (uses local version)
|
|
npm run dev:install # Run installer
|
|
npm run dev:status # Check status
|
|
npm run dev:list # List modules
|
|
npm run dev:uninstall # Uninstall
|
|
|
|
# Legacy aliases (also use local version)
|
|
npm run bmad:install # Same as dev:install
|
|
npm run bmad:status # Same as dev:status
|
|
npm run install:bmad # Same as dev:install
|
|
```
|
|
|
|
### Using npm link (Optional)
|
|
|
|
For extended testing where you want the `bmad` command available system-wide:
|
|
|
|
```bash
|
|
# From the BMAD-METHOD directory
|
|
npm link
|
|
|
|
# Now you can use 'bmad' anywhere
|
|
bmad install
|
|
bmad status
|
|
|
|
# Unlink when done
|
|
npm unlink -g bmad-method
|
|
```
|
|
|
|
**Note:** You must re-run `npm link` after:
|
|
|
|
- Installing/updating dependencies
|
|
- Checking out different branches
|
|
- Major code changes to the CLI
|
|
|
|
## Why This Matters
|
|
|
|
### Problem: npx Downloads Published Version
|
|
|
|
```bash
|
|
# ❌ WRONG - Downloads published version from npm
|
|
npx bmad-method install
|
|
|
|
# What actually happens:
|
|
# 1. npx checks npm registry
|
|
# 2. Downloads bmad-method@6.0.0-alpha.0 (published version)
|
|
# 3. Published version does NOT include fork changes like OpenCode
|
|
# 4. Your local OpenCode integration gets overwritten/broken
|
|
```
|
|
|
|
### Solution: Direct Execution
|
|
|
|
```bash
|
|
# ✅ CORRECT - Uses your local version
|
|
node tools/cli/bmad-cli.js install
|
|
|
|
# What actually happens:
|
|
# 1. Node runs your local CLI file directly
|
|
# 2. Uses your local code with all fork features
|
|
# 3. OpenCode integration works correctly
|
|
```
|
|
|
|
## Fork-Specific Features
|
|
|
|
The following features exist ONLY in the fork and will NOT work with the published npm package:
|
|
|
|
- **OpenCode Integration** (`tools/cli/installers/lib/ide/opencode.js`)
|
|
- File reference-based configuration
|
|
- Agent and command merging
|
|
- AGENTS.md generation
|
|
- Prefix customization
|
|
|
|
- **Installer Skip Block** (modify install flow)
|
|
- Custom pre-installation logic
|
|
- Modified dependency resolution
|
|
|
|
## Testing Your Changes
|
|
|
|
### Before Testing
|
|
|
|
```bash
|
|
# Ensure dependencies are installed
|
|
npm install
|
|
|
|
# Verify your changes are present
|
|
test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ OpenCode present" || echo "❌ Missing"
|
|
```
|
|
|
|
### Testing Installation
|
|
|
|
```bash
|
|
# Create a test directory
|
|
mkdir -p ~/test-bmad-install
|
|
cd ~/test-bmad-install
|
|
|
|
# Run local installer
|
|
node ~/dev/tools/BMAD-METHOD/tools/cli/bmad-cli.js install
|
|
|
|
# Select OpenCode as IDE
|
|
# Verify opencode.json/opencode.jsonc is created with file references
|
|
```
|
|
|
|
### Testing After Changes
|
|
|
|
```bash
|
|
# Make your code changes...
|
|
|
|
# Test immediately (no rebuild needed for most changes)
|
|
node tools/cli/bmad-cli.js install
|
|
```
|
|
|
|
## Published vs Fork Versions
|
|
|
|
| Feature | Published npm | Fork (Local) |
|
|
| --------------------- | ------------- | ------------ |
|
|
| Base V6 installer | ✅ | ✅ |
|
|
| Standard IDEs (15) | ✅ | ✅ |
|
|
| OpenCode integration | ❌ | ✅ |
|
|
| Installer skip block | ❌ | ✅ |
|
|
| Latest upstream fixes | ✅ | Needs merge |
|
|
| Fork improvements | ❌ | ✅ |
|
|
|
|
## Quick Reference Card
|
|
|
|
```bash
|
|
# ✅ CORRECT - Local development
|
|
node tools/cli/bmad-cli.js install
|
|
npm run dev:install
|
|
bmad install # (after npm link)
|
|
|
|
# ❌ WRONG - Downloads published version
|
|
npx bmad-method install
|
|
npx bmad install
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Command not found: bmad"
|
|
|
|
- You haven't run `npm link`
|
|
- Use direct node execution instead: `node tools/cli/bmad-cli.js install`
|
|
|
|
### "OpenCode not appearing in IDE list"
|
|
|
|
- You're using `npx bmad-method` instead of local version
|
|
- Solution: Use `node tools/cli/bmad-cli.js install`
|
|
|
|
### "Changes not reflected when running installer"
|
|
|
|
- You're using `npx` or a globally installed version
|
|
- Solution: Use direct node execution
|
|
- Verify: `which bmad` should show your linked local version, not a global install
|
|
|
|
### "Cannot find module 'comment-json'"
|
|
|
|
- Dependencies not installed
|
|
- Solution: `npm install` from BMAD-METHOD directory
|