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

## 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**:
```bash
test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ Present" || echo "❌ MISSING"
```

**Recovery**:
```bash
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**:
```bash
git checkout <backup-branch> -- OPENCODE_INTEGRATION_SUMMARY.md
```

### 2. Modified Files

#### `package.json`
- **Modification**: Added `comment-json` dependency
- **Location**: `dependencies` section
- **Code**:
  ```json
  "comment-json": "^4.2.5",
  ```
- **Purpose**: Required for parsing JSONC files with comments

**Verification**:
```bash
grep -q '"comment-json"' package.json && echo "✅ Present" || echo "❌ MISSING"
```

**Manual Recovery** (if needed):
```json
{
  "dependencies": {
    // ... other dependencies ...
    "comment-json": "^4.2.5",
    // ... more dependencies ...
  }
}
```

Then run:
```bash
npm install
```

## Verification Checklist

Run these commands **after every upstream merge**:

### ✅ Quick Verification (30 seconds)

```bash
# 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)

```bash
# 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)

```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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)
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):
```yaml
- 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

```bash
# 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**:
```bash
test -f tools/cli/installers/lib/ide/opencode.js && \
grep -q comment-json package.json && \
echo "✅ All good" || echo "❌ Needs recovery"
```

**Quick Recovery**:
```bash
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