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
parent
b3975f628f
commit
0544964a87
|
|
@ -35,36 +35,68 @@
|
|||
<critical>This backup branch is essential for recovery if the merge encounters unexpected issues</critical>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Document critical modification for reference">
|
||||
<action>Create or update the modification reference file in claudedocs/ directory</action>
|
||||
<action>Document the exact code that must be preserved during merge</action>
|
||||
<action>Include file path, line numbers, and the critical code snippet</action>
|
||||
<step n="3" goal="Document critical modifications for reference">
|
||||
<action>Create or update modification reference files in claudedocs/ directory</action>
|
||||
<action>Document all fork-specific modifications that must be preserved during merge</action>
|
||||
<action>Include file paths, line numbers, and critical code snippets</action>
|
||||
<action>Add insertion point details and recovery instructions</action>
|
||||
<action>Save verification commands for post-merge checking</action>
|
||||
|
||||
<example>
|
||||
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
|
||||
</example>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Verify modification exists before merge">
|
||||
<action>Execute verification command to confirm critical modification is present</action>
|
||||
<step n="4" goal="Verify modifications exist before merge">
|
||||
<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>
|
||||
|
||||
<critical>Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js</critical>
|
||||
|
||||
<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>
|
||||
<goto step="1">Halt until modification is restored</goto>
|
||||
</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>
|
||||
</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 n="5" goal="Fetch upstream changes">
|
||||
|
|
@ -104,32 +136,75 @@ Reference file should include:
|
|||
<action>Display merge statistics: files changed, insertions, deletions</action>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Verify modification preservation">
|
||||
<action>Execute post-merge verification to confirm critical modification survived</action>
|
||||
<step n="7" goal="Verify fork modifications preservation">
|
||||
<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>
|
||||
|
||||
<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>Guide user to manually re-insert the 4-line modification after config.yaml skip block</action>
|
||||
<action>Verify manual restoration before continuing</action>
|
||||
</check>
|
||||
|
||||
<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>
|
||||
|
||||
<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 n="8" goal="Update cross-session memories">
|
||||
<action>Prepare comprehensive memory update for Serena MCP with merge details</action>
|
||||
<action>Include merge date, commit hash, backup branch name, verification results</action>
|
||||
<action>Prepare comprehensive memory updates for Serena MCP with merge details</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>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-opencode-fork-integration</action>
|
||||
|
||||
<action>Prepare episode for Graphiti MCP knowledge graph</action>
|
||||
<action>Include merge context, upstream commits pulled, modification preservation status</action>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue