BMAD-METHOD/claudedocs/opencode-integration-reference.md

OpenCode Integration - Fork Modification Reference

Overview

This document serves as the authoritative reference for preserving the OpenCode integration during upstream merges. OpenCode support is a fork-specific feature not present in the upstream BMAD-METHOD repository.

⚠️ CRITICAL: Fork-Only Feature

OpenCode integration exists ONLY in this fork and will NEVER be published to npm.

• The published npm package bmad-method@6.0.0-alpha.0 does NOT include OpenCode
• Running npx bmad-method install will download the published version WITHOUT OpenCode
• You MUST use local development commands to access OpenCode functionality

See: docs/V6_LOCAL_DEVELOPMENT.md for complete local development instructions.

Critical Information

• Modification Type: Additive (new files + dependency)
• Risk Level: Low-Medium (new files unlikely to conflict, dependency may need verification)
• Recovery Method: Restore from backup branch
• Serena Memory: CRITICAL-opencode-fork-integration
• Development Requirement: Must use local CLI execution (not npx)

Files Affected

1. New Files (Additive)

tools/cli/installers/lib/ide/opencode.js

• Lines: 602 (entire file)
• Purpose: OpenCode IDE installer implementation
• Status: Must be present for OpenCode functionality

Verification:

test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ Present" || echo "❌ MISSING"

Recovery:

git checkout <backup-branch> -- tools/cli/installers/lib/ide/opencode.js

OPENCODE_INTEGRATION_SUMMARY.md

• Lines: 231 (entire file)
• Purpose: Implementation documentation and architecture details
• Status: Documentation only (optional but recommended to preserve)

Recovery:

git checkout <backup-branch> -- OPENCODE_INTEGRATION_SUMMARY.md

2. Modified Files

package.json

• Modification: Added comment-json dependency
• Location: dependencies section
• Code:

  "comment-json": "^4.2.5",
  

• Purpose: Required for parsing JSONC files with comments

Verification:

grep -q '"comment-json"' package.json && echo "✅ Present" || echo "❌ MISSING"

Manual Recovery (if needed):

{
  "dependencies": {
    // ... other dependencies ...
    "comment-json": "^4.2.5"
    // ... more dependencies ...
  }
}

Then run:

npm install

Verification Checklist

Run these commands after every upstream merge:

✅ Quick Verification (30 seconds)

# 1. File existence
test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ opencode.js" || echo "❌ opencode.js MISSING"

# 2. Dependency check
grep -q '"comment-json"' package.json && echo "✅ comment-json" || echo "❌ comment-json MISSING"

✅ Thorough Verification (1 minute)

# 3. Runtime IDE discovery check
node -e "
const {IdeManager} = require('./tools/cli/installers/lib/ide/manager');
const manager = new IdeManager();
const ides = manager.getAvailableIdes();
const opencode = ides.find(i => i.value === 'opencode');
if (opencode) {
  console.log('✅ OpenCode discoverable:', opencode.name);
  console.log('   Preferred:', opencode.preferred ? 'Yes' : 'No');
} else {
  console.log('❌ OpenCode NOT in IDE list');
  console.log('Available IDEs:', ides.map(i => i.value).join(', '));
}
"

# 4. Dependency installation check
npm list comment-json 2>/dev/null && echo "✅ comment-json installed" || echo "⚠️  Run: npm install"

✅ Full Integration Test (2 minutes)

# 5. Test OpenCode installer can be instantiated
node -e "
const {OpenCodeSetup} = require('./tools/cli/installers/lib/ide/opencode');
const setup = new OpenCodeSetup();
console.log('✅ OpenCode installer instantiated');
console.log('   Name:', setup.name);
console.log('   Display Name:', setup.displayName);
"

Recovery Procedures

Scenario 1: opencode.js Missing

Symptoms:

• File check fails
• IDE manager doesn't list OpenCode
• Error when trying to install with OpenCode

Recovery:

# 1. Find latest backup branch
BACKUP=$(git branch -a | grep backup-before | tail -1 | xargs)

# 2. Restore the file
git checkout $BACKUP -- tools/cli/installers/lib/ide/opencode.js

# 3. Verify
test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ Restored"

# 4. Stage and commit
git add tools/cli/installers/lib/ide/opencode.js
git commit -m "chore: restore OpenCode integration after upstream merge"

Scenario 2: comment-json Dependency Missing

Symptoms:

• OpenCode installer throws "Cannot find module 'comment-json'" error
• IDE manager shows warning about loading OpenCode

Recovery:

# Option A: Restore from backup
BACKUP=$(git branch -a | grep backup-before | tail -1 | xargs)
git checkout $BACKUP -- package.json

# Option B: Manual edit
# Add to package.json dependencies:
#   "comment-json": "^4.2.5",

# Then install
npm install

# Verify
npm list comment-json

Scenario 3: Both Files Missing (Complete Loss)

Recovery:

# 1. Find backup branch
BACKUP=$(git branch -a | grep backup-before | tail -1 | xargs)
echo "Using backup: $BACKUP"

# 2. Restore all OpenCode files
git checkout $BACKUP -- \
  tools/cli/installers/lib/ide/opencode.js \
  OPENCODE_INTEGRATION_SUMMARY.md \
  package.json

# 3. Install dependencies
npm install

# 4. Verify everything
bash -c '
test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ opencode.js" || echo "❌ Failed"
grep -q comment-json package.json && echo "✅ dependency" || echo "❌ Failed"
npm list comment-json >/dev/null 2>&1 && echo "✅ installed" || echo "❌ Failed"
'

# 5. Stage and commit
git add tools/cli/installers/lib/ide/opencode.js OPENCODE_INTEGRATION_SUMMARY.md package.json package-lock.json
git commit -m "chore: restore complete OpenCode integration after upstream merge

- Restored tools/cli/installers/lib/ide/opencode.js
- Restored comment-json dependency
- Restored documentation

Fork-specific feature not present in upstream."

Integration with Merge Workflow

Pre-Merge Checklist

Before merging upstream changes:

1. ✅ Run quick verification to confirm OpenCode is present
2. ✅ Verify backup branch will be created
3. ✅ Note current commit hash for reference

Post-Merge Checklist

After merging upstream changes:

1. ✅ Run quick verification
2. ✅ If any checks fail, run recovery procedures
3. ✅ Run thorough verification
4. ✅ Test basic functionality (optional)

Testing OpenCode After Merge

CRITICAL: Do NOT use npx bmad-method to test - it downloads the published version!

# ✅ CORRECT - Test with local version
cd /path/to/test/project
node /path/to/BMAD-METHOD/tools/cli/bmad-cli.js install

# Or use npm script from BMAD-METHOD directory
npm run dev:install

# Verify OpenCode appears in IDE selection menu
# Verify opencode.json/opencode.jsonc is created correctly

See: docs/V6_LOCAL_DEVELOPMENT.md for complete testing guide. 5. ✅ Update Serena memory with merge date

Workflow Integration

The bmad/workflows/merge-upstream/ workflow includes OpenCode checks:

Step 7.5 (added to existing workflow):

- name: 'Verify OpenCode Integration'
  action: 'Run OpenCode verification commands'
  verification:
    - 'File existence check'
    - 'Dependency check'
    - 'IDE manager discovery check'
  on_failure:
    - 'Alert about missing OpenCode integration'
    - 'Provide recovery instructions'
    - 'Link to this reference document'

Architecture Details

How OpenCode Integration Works

1. Auto-Discovery: IDE manager scans tools/cli/installers/lib/ide/ for .js files
2. Class Instantiation: Each file exports a class extending BaseIdeSetup
3. Registration: Manager calls constructor which sets this.name = 'opencode'
4. Availability: OpenCode appears in IDE selection list

Why It's Low-Risk

• New file: Doesn't modify existing upstream code
• Self-contained: All logic in one file
• Auto-discovery: No manual registration needed
• Dependency: Only one new dependency, isolated in package.json

Potential Conflicts

⚠️ Unlikely but possible:

1. Upstream adds OpenCode: Compare implementations, merge if needed
2. package.json conflicts: Manually preserve comment-json entry
3. IDE manager changes: Verify auto-discovery still works

Testing Commands

Quick Functionality Test

# Create a test project and verify OpenCode can be selected
mkdir -p /tmp/opencode-test
cd /tmp/opencode-test
npm init -y

# Note: Full interactive install test would require user input
# So we just verify the installer can be loaded
node -e "
const {OpenCodeSetup} = require('$PWD/tools/cli/installers/lib/ide/opencode');
const setup = new OpenCodeSetup();
console.log('✅ OpenCode installer loads successfully');
console.log('Name:', setup.name);
"

Maintenance Notes

When to Update This Document

• After any changes to OpenCode implementation
• After successful upstream merges (update "Last Verified" in Serena memory)
• If recovery procedures change
• If new verification methods are discovered

Version History

• 2025-10-20: Initial creation with OpenCode integration
• Commit: b3975f6

Quick Reference Card

Files to Watch:

• ✅ tools/cli/installers/lib/ide/opencode.js (must exist)
• ✅ "comment-json": "^4.2.5" in package.json

Quick Check:

test -f tools/cli/installers/lib/ide/opencode.js && \
grep -q comment-json package.json && \
echo "✅ All good" || echo "❌ Needs recovery"

Quick Recovery:

BACKUP=$(git branch -a | grep backup-before | tail -1 | xargs)
git checkout $BACKUP -- tools/cli/installers/lib/ide/opencode.js package.json
npm install

Related Documentation

• Serena Memory: .serena/memories/CRITICAL-opencode-fork-integration.md
• Implementation Details: OPENCODE_INTEGRATION_SUMMARY.md
• Merge Workflow: bmad/workflows/merge-upstream/instructions.md
• User Documentation: docs/opencode-integration.md (if exists)

---

Last Updated: 2025-10-20 Maintained By: Fork maintainers Upstream Status: Not present in upstream BMAD-METHOD