ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

docs: add OpenCode preservation to merge-upstream workflow 

Extends merge-upstream workflow to preserve OpenCode integration during
upstream merges alongside existing installer modification preservation.

Changes:
- Add Serena memory: CRITICAL-opencode-fork-integration
- Create claudedocs/opencode-integration-reference.md
  * Complete recovery procedures
  * Verification commands (3-tier checking)
  * Integration with merge workflow
- Update bmad/workflows/merge-upstream/instructions.md
  * Step 3: Document both modifications
  * Step 4: Verify both before merge
  * Step 7: Verify both after merge (7a installer, 7b OpenCode)
  * Step 8: Update both Serena memories

OpenCode Preservation Strategy:
✅ Additive modification (new file) = lower risk than inline changes
✅ 3-tier verification: file existence, dependency, runtime discovery
✅ Recovery: restore from backup branch
✅ Dependencies: comment-json in package.json

Files to Preserve:
- tools/cli/installers/lib/ide/opencode.js (602 lines)
- "comment-json": "^4.2.5" in package.json
- OPENCODE_INTEGRATION_SUMMARY.md (documentation)

Verification Commands:
1. test -f tools/cli/installers/lib/ide/opencode.js
2. grep -q "comment-json" package.json
3. Node runtime check via IDE manager

Recovery: Restore files from backup-before-pull-* branch

🤖 Generated with Claude Code
https://claude.com/claude-code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Sallvainian 2025-10-20 00:38:22 -04:00
parent b3975f628f
commit 0544964a87
2 changed files with 428 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
bmad/workflows/merge-upstream/instructions.md
View File

@ -35,36 +35,68 @@
<critical>This backup branch is essential for recovery if the merge encounters unexpected issues</critical> <critical>This backup branch is essential for recovery if the merge encounters unexpected issues</critical>
</step> </step>
<step n="3" goal="Document critical modification for reference"> <step n="3" goal="Document critical modifications for reference">
<action>Create or update the modification reference file in claudedocs/ directory</action> <action>Create or update modification reference files in claudedocs/ directory</action>
<action>Document the exact code that must be preserved during merge</action> <action>Document all fork-specific modifications that must be preserved during merge</action>
<action>Include file path, line numbers, and the critical code snippet</action> <action>Include file paths, line numbers, and critical code snippets</action>
<action>Add insertion point details and recovery instructions</action> <action>Add insertion point details and recovery instructions</action>
<action>Save verification commands for post-merge checking</action> <action>Save verification commands for post-merge checking</action>
<example> <example>
Reference file should include: Reference files should include:
- File: tools/cli/installers/lib/core/installer.js
- Lines: 913-916 1. Installer Skip Block (claudedocs/installer-modification-reference.md):
- Code: Skip block for workflow instructions.md - File: tools/cli/installers/lib/core/installer.js
- Verification: grep command to check presence - Lines: 913-916
- Code: Skip block for workflow instructions.md
- Verification: grep command to check presence
2. OpenCode Integration (claudedocs/opencode-integration-reference.md):
- File: tools/cli/installers/lib/ide/opencode.js (entire file)
- Type: Additive modification (new file)
- Dependency: comment-json in package.json
- Verification: File existence + dependency check + runtime check
</example> </example>
</step> </step>
<step n="4" goal="Verify modification exists before merge"> <step n="4" goal="Verify modifications exist before merge">
<action>Execute verification command to confirm critical modification is present</action> <action>Execute verification commands to confirm all critical modifications are present</action>
<substep n="4a" goal="Verify Installer Modification">
<action>Use grep to search for the modification signature in the target file</action> <action>Use grep to search for the modification signature in the target file</action>
<critical>Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js</critical> <critical>Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js</critical>
<check if="modification not found"> <check if="modification not found">
<action>Alert user that critical modification is missing from current codebase</action> <action>Alert user that critical installer modification is missing from current codebase</action>
<action>Provide guidance on restoring the modification before attempting merge</action> <action>Provide guidance on restoring the modification before attempting merge</action>
<goto step="1">Halt until modification is restored</goto> <goto step="1">Halt until modification is restored</goto>
</check> </check>
<action>Confirm modification present at expected location</action> <action>Confirm installer modification present at expected location</action>
<action>Record current line numbers for post-merge comparison</action> <action>Record current line numbers for post-merge comparison</action>
</substep>
<substep n="4b" goal="Verify OpenCode Integration">
<action>Execute OpenCode pre-merge verification checks</action>
<critical>Commands:
1. test -f tools/cli/installers/lib/ide/opencode.js
2. grep -q "comment-json" package.json
3. node -e "const {IdeManager}=require('./tools/cli/installers/lib/ide/manager');console.log(new IdeManager().getAvailableIdes().find(i=>i.value==='opencode')?'present':'missing')"
</critical>
<check if="any opencode check fails">
<action>Alert user that OpenCode integration is incomplete or missing</action>
<action>Provide recovery steps from claudedocs/opencode-integration-reference.md</action>
<action>Suggest restoring from previous backup or commit</action>
<goto step="1">Halt until OpenCode integration is restored</goto>
</check>
<action>Confirm OpenCode integration is complete and functional</action>
</substep>
<action>All fork modifications verified and ready for merge</action>
</step> </step>
<step n="5" goal="Fetch upstream changes"> <step n="5" goal="Fetch upstream changes">
@ -104,32 +136,75 @@ Reference file should include:
<action>Display merge statistics: files changed, insertions, deletions</action> <action>Display merge statistics: files changed, insertions, deletions</action>
</step> </step>
<step n="7" goal="Verify modification preservation"> <step n="7" goal="Verify fork modifications preservation">
<action>Execute post-merge verification to confirm critical modification survived</action> <action>Execute post-merge verification to confirm all critical fork modifications survived</action>
<substep n="7a" goal="Verify Installer Skip Block">
<critical>Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js</critical> <critical>Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js</critical>
<check if="modification not found"> <check if="modification not found">
<action>Alert user that critical modification was lost during merge</action> <action>Alert user that critical installer modification was lost during merge</action>
<action>Load recovery instructions from reference documentation</action> <action>Load recovery instructions from reference documentation</action>
<action>Guide user to manually re-insert the 4-line modification after config.yaml skip block</action> <action>Guide user to manually re-insert the 4-line modification after config.yaml skip block</action>
<action>Verify manual restoration before continuing</action> <action>Verify manual restoration before continuing</action>
</check> </check>
<action>Confirm modification exists at same or nearby line numbers</action> <action>Confirm modification exists at same or nearby line numbers</action>
<action>Verify git status shows clean merge completion</action>
<action>Check that all expected modules still have install-menu-config.yaml files</action> <action>Check that all expected modules still have install-menu-config.yaml files</action>
<critical>Verification: find src/modules -name "install-menu-config.yaml" should show all modules intact</critical> <critical>Verification: find src/modules -name "install-menu-config.yaml" should show all modules intact</critical>
</substep>
<substep n="7b" goal="Verify OpenCode Integration">
<action>Execute OpenCode verification checks to confirm fork-specific feature survived</action>
<critical>Quick Verification Commands:</critical>
<action>Check 1 - OpenCode installer file exists</action>
<critical>Command: test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ OpenCode present" || echo "❌ MISSING"</critical>
<check if="opencode.js not found">
<action>Alert user that OpenCode integration was lost during merge</action>
<action>Identify most recent backup branch: git branch -a | grep backup-before | tail -1</action>
<action>Restore OpenCode: git checkout [backup-branch] -- tools/cli/installers/lib/ide/opencode.js</action>
<action>Verify restoration successful</action>
</check>
<action>Check 2 - comment-json dependency exists in package.json</action>
<critical>Command: grep -q "comment-json" package.json && echo "✅ Dependency present" || echo "❌ MISSING"</critical>
<check if="dependency not found">
<action>Alert user that comment-json dependency was lost during merge</action>
<action>Restore package.json from backup OR manually add: "comment-json": "^4.2.5"</action>
<action>Run: npm install</action>
<action>Verify: npm list comment-json</action>
</check>
<action>Check 3 - OpenCode is discoverable by IDE manager (runtime check)</action>
<critical>Command: node -e "const {IdeManager}=require('./tools/cli/installers/lib/ide/manager');const opencode=new IdeManager().getAvailableIdes().find(i=>i.value==='opencode');console.log(opencode?'✅ OpenCode discoverable':'❌ MISSING from IDE list')"</critical>
<check if="opencode not discoverable">
<action>Alert user about runtime discovery failure</action>
<action>Verify both opencode.js file AND comment-json dependency are present</action>
<action>Check for syntax errors: node -c tools/cli/installers/lib/ide/opencode.js</action>
<action>If file is corrupted, restore from backup branch</action>
</check>
<action>Confirm all three OpenCode checks passed</action>
<action>Reference: Full recovery procedures in claudedocs/opencode-integration-reference.md</action>
</substep>
<action>Verify git status shows clean merge completion with all modifications intact</action>
</step> </step>
<step n="8" goal="Update cross-session memories"> <step n="8" goal="Update cross-session memories">
<action>Prepare comprehensive memory update for Serena MCP with merge details</action> <action>Prepare comprehensive memory updates for Serena MCP with merge details</action>
<action>Include merge date, commit hash, backup branch name, verification results</action> <action>Include merge date, commit hash, backup branch name, verification results for all modifications</action>
<action>Document any conflicts encountered and how they were resolved</action> <action>Document any conflicts encountered and how they were resolved</action>
<action>Update merge workflow history and success metrics</action> <action>Update merge workflow history and success metrics</action>
<action>Write updated memory to Serena: CRITICAL-installer-fork-modification</action> <action>Write updated memory to Serena: CRITICAL-installer-fork-modification</action>
<action>Write updated memory to Serena: CRITICAL-opencode-fork-integration</action>
<action>Prepare episode for Graphiti MCP knowledge graph</action> <action>Prepare episode for Graphiti MCP knowledge graph</action>
<action>Include merge context, upstream commits pulled, modification preservation status</action> <action>Include merge context, upstream commits pulled, modification preservation status</action>

334
claudedocs/opencode-integration-reference.md Normal file
View File

@ -0,0 +1,334 @@
# 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