From 0544964a87b57cdfbf5f3f7a6b81e0d515071dbc Mon Sep 17 00:00:00 2001 From: Sallvainian Date: Mon, 20 Oct 2025 00:38:22 -0400 Subject: [PATCH] docs: add OpenCode preservation to merge-upstream workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- bmad/workflows/merge-upstream/instructions.md | 113 +++++- claudedocs/opencode-integration-reference.md | 334 ++++++++++++++++++ 2 files changed, 428 insertions(+), 19 deletions(-) create mode 100644 claudedocs/opencode-integration-reference.md diff --git a/bmad/workflows/merge-upstream/instructions.md b/bmad/workflows/merge-upstream/instructions.md index f4e80113..b8b5e881 100644 --- a/bmad/workflows/merge-upstream/instructions.md +++ b/bmad/workflows/merge-upstream/instructions.md @@ -35,36 +35,68 @@ This backup branch is essential for recovery if the merge encounters unexpected issues - -Create or update the modification reference file in claudedocs/ directory -Document the exact code that must be preserved during merge -Include file path, line numbers, and the critical code snippet + +Create or update modification reference files in claudedocs/ directory +Document all fork-specific modifications that must be preserved during merge +Include file paths, line numbers, and critical code snippets Add insertion point details and recovery instructions Save verification commands for post-merge checking -Reference file should include: -- File: tools/cli/installers/lib/core/installer.js -- Lines: 913-916 -- Code: Skip block for workflow instructions.md -- Verification: grep command to check presence +Reference files should include: + +1. Installer Skip Block (claudedocs/installer-modification-reference.md): + - File: tools/cli/installers/lib/core/installer.js + - 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 - -Execute verification command to confirm critical modification is present + +Execute verification commands to confirm all critical modifications are present + + Use grep to search for the modification signature in the target file Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js - Alert user that critical modification is missing from current codebase + Alert user that critical installer modification is missing from current codebase Provide guidance on restoring the modification before attempting merge Halt until modification is restored -Confirm modification present at expected location +Confirm installer modification present at expected location Record current line numbers for post-merge comparison + + + +Execute OpenCode pre-merge verification checks + +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')" + + + + Alert user that OpenCode integration is incomplete or missing + Provide recovery steps from claudedocs/opencode-integration-reference.md + Suggest restoring from previous backup or commit + Halt until OpenCode integration is restored + + +Confirm OpenCode integration is complete and functional + + +All fork modifications verified and ready for merge @@ -104,32 +136,75 @@ Reference file should include: Display merge statistics: files changed, insertions, deletions - -Execute post-merge verification to confirm critical modification survived + +Execute post-merge verification to confirm all critical fork modifications survived + Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js - Alert user that critical modification was lost during merge + Alert user that critical installer modification was lost during merge Load recovery instructions from reference documentation Guide user to manually re-insert the 4-line modification after config.yaml skip block Verify manual restoration before continuing Confirm modification exists at same or nearby line numbers -Verify git status shows clean merge completion Check that all expected modules still have install-menu-config.yaml files Verification: find src/modules -name "install-menu-config.yaml" should show all modules intact + + + +Execute OpenCode verification checks to confirm fork-specific feature survived + +Quick Verification Commands: + +Check 1 - OpenCode installer file exists +Command: test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ OpenCode present" || echo "❌ MISSING" + + + Alert user that OpenCode integration was lost during merge + Identify most recent backup branch: git branch -a | grep backup-before | tail -1 + Restore OpenCode: git checkout [backup-branch] -- tools/cli/installers/lib/ide/opencode.js + Verify restoration successful + + +Check 2 - comment-json dependency exists in package.json +Command: grep -q "comment-json" package.json && echo "✅ Dependency present" || echo "❌ MISSING" + + + Alert user that comment-json dependency was lost during merge + Restore package.json from backup OR manually add: "comment-json": "^4.2.5" + Run: npm install + Verify: npm list comment-json + + +Check 3 - OpenCode is discoverable by IDE manager (runtime check) +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')" + + + Alert user about runtime discovery failure + Verify both opencode.js file AND comment-json dependency are present + Check for syntax errors: node -c tools/cli/installers/lib/ide/opencode.js + If file is corrupted, restore from backup branch + + +Confirm all three OpenCode checks passed +Reference: Full recovery procedures in claudedocs/opencode-integration-reference.md + + +Verify git status shows clean merge completion with all modifications intact -Prepare comprehensive memory update for Serena MCP with merge details -Include merge date, commit hash, backup branch name, verification results +Prepare comprehensive memory updates for Serena MCP with merge details +Include merge date, commit hash, backup branch name, verification results for all modifications Document any conflicts encountered and how they were resolved Update merge workflow history and success metrics Write updated memory to Serena: CRITICAL-installer-fork-modification +Write updated memory to Serena: CRITICAL-opencode-fork-integration Prepare episode for Graphiti MCP knowledge graph Include merge context, upstream commits pulled, modification preservation status diff --git a/claudedocs/opencode-integration-reference.md b/claudedocs/opencode-integration-reference.md new file mode 100644 index 00000000..7987d029 --- /dev/null +++ b/claudedocs/opencode-integration-reference.md @@ -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 -- 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 -- 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