From 13da4ef4aafbb04ae7f17a3ada948b419262f51d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pe=C3=AFo=20Thibault?= Date: Sat, 7 Feb 2026 14:07:55 +0100 Subject: [PATCH] docs: add comprehensive local testing guide for acp-json-error branch --- LOCAL_TESTING_GUIDE.md | 400 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 400 insertions(+) create mode 100644 LOCAL_TESTING_GUIDE.md diff --git a/LOCAL_TESTING_GUIDE.md b/LOCAL_TESTING_GUIDE.md new file mode 100644 index 000000000..439a048be --- /dev/null +++ b/LOCAL_TESTING_GUIDE.md @@ -0,0 +1,400 @@ +# Local Testing Guide: oh-my-opencode acp-json-error Branch + +## Overview + +This guide helps you test the `acp-json-error` branch locally to verify: +1. **TUI functionality** - OpenCode CLI works correctly +2. **ACP integration** - Claude Code Plugin loads and functions properly + +--- + +## Prerequisites + +- Bun installed (`bun --version`) +- OpenCode installed (`opencode --version`) +- Claude Code (if testing ACP integration) + +--- + +## Setup: Install Branch Locally + +### Option 1: Install from GitHub (Recommended) + +```bash +# Install directly from the branch +bun install --global github:potb/oh-my-opencode#acp-json-error + +# Verify installation +oh-my-opencode --version +``` + +### Option 2: Build from Source + +```bash +# Clone and checkout the branch +git clone https://github.com/potb/oh-my-opencode.git +cd oh-my-opencode +git checkout acp-json-error + +# Install dependencies +bun install + +# Build the project +bun run build + +# Link globally for testing +bun link + +# In another directory, link the package +bun link oh-my-opencode +``` + +--- + +## Test 1: TUI Functionality (OpenCode CLI) + +### 1.1 Basic Agent Operations + +Test that agents can be invoked and respond correctly: + +```bash +# Navigate to a test project +cd /path/to/test/project + +# Initialize oh-my-opencode (if not already done) +oh-my-opencode init + +# Test basic agent invocation +opencode "List all TypeScript files in src/" + +# Test background agent +opencode "Run a background task to analyze the codebase" + +# Test delegation +opencode "Delegate a task to the oracle agent" +``` + +**Expected**: Agents respond without JSON Parse errors, tasks complete successfully. + +### 1.2 Hook Behavior + +Test hooks that were modified in this PR: + +```bash +# Test Atlas hook (boulder continuation) +opencode "Create a work plan and start executing it" +# Let it run, then interrupt and resume - should continue from where it left off + +# Test Ralph loop +opencode "Start a ralph loop for continuous development" +# Should iterate without JSON Parse errors + +# Test todo continuation enforcer +opencode "Create a todo list and mark some items incomplete" +# Should inject continuation prompts without errors +``` + +**Expected**: Hooks fire correctly, no JSON Parse errors in logs. + +### 1.3 Background Tasks + +Test background task management: + +```bash +# Launch a background task +opencode "Launch a background task to search the codebase" + +# Check task status +opencode "Show background task status" + +# Cancel a task +opencode "Cancel the background task" +``` + +**Expected**: Background tasks launch, run, and can be cancelled without errors. + +### 1.4 Check Logs for Errors + +```bash +# Monitor OpenCode logs for JSON Parse errors +tail -f ~/.opencode/logs/opencode.log | grep -i "json parse" + +# Should see NO "JSON Parse error: Unexpected EOF" messages +``` + +--- + +## Test 2: ACP Integration (Claude Code Plugin) + +### 2.1 Install Plugin in Claude Code + +**Method 1: Via opencode.json** + +Edit your `~/.config/opencode/opencode.json`: + +```json +{ + "plugins": [ + { + "name": "oh-my-opencode", + "path": "/path/to/oh-my-opencode" // Path to your local build + } + ] +} +``` + +**Method 2: Via CLI** + +```bash +opencode plugin install /path/to/oh-my-opencode +``` + +### 2.2 Verify Plugin Loads + +```bash +# Start Claude Code +opencode + +# In Claude Code, check plugin status +/plugins list + +# Should see "oh-my-opencode" loaded without errors +``` + +### 2.3 Test Plugin Tools + +In Claude Code, test the tools that use `session.prompt()`: + +```bash +# Test delegate_task tool +/delegate "Test task delegation" --category quick + +# Test call_omo_agent tool +/agent oracle "What is the current project structure?" + +# Test background task tool +/background "Analyze codebase in background" + +# Test look_at tool (previously had isJsonParseError band-aid) +/look_at screenshot.png "Describe this image" +``` + +**Expected**: All tools execute without JSON Parse errors. + +### 2.4 Test Hook Integration + +Test hooks in the ACP environment: + +```bash +# Test Atlas hook (boulder continuation) +# Create a work plan, let it run, then check if continuation works + +# Test unstable-agent-babysitter hook +# Use an unstable model (gemini, minimax) and verify reminder fires + +# Test session recovery hook +# Simulate a session crash and verify recovery prompt fires +``` + +**Expected**: Hooks fire correctly in ACP environment, no JSON Parse errors. + +### 2.5 Monitor ACP Logs + +```bash +# Check Claude Code logs for errors +tail -f ~/.config/opencode/logs/plugin-oh-my-opencode.log | grep -i "json parse" + +# Should see NO "JSON Parse error: Unexpected EOF" messages +``` + +--- + +## Test 3: Regression Testing + +### 3.1 Verify No Breaking Changes + +Test existing functionality that should NOT be affected: + +```bash +# Test model suggestion retry (wrapper still works) +opencode "Use a non-existent model" --model "fake-model-123" +# Should get model suggestion error (not JSON Parse error) + +# Test parseModelSuggestion utility +# (Internal function, but verify via model suggestion errors) + +# Test fire-and-forget prompts +# (Background agent spawner, manager - should still catch HTTP errors) +``` + +**Expected**: Existing error handling still works, no regressions. + +### 3.2 Run Test Suite + +```bash +cd /path/to/oh-my-opencode +bun test + +# Focus on migration-specific tests +bun test src/shared/model-suggestion-retry.test.ts +bun test src/hooks/todo-continuation-enforcer.test.ts +``` + +**Expected**: All tests pass (migration tests: 57/57). + +--- + +## Test 4: Specific Scenarios + +### 4.1 Scenario: Background Agent Notification + +```bash +# Start a long-running background task +opencode "Analyze entire codebase and generate report" + +# Wait for completion +# Should receive notification via promptAsync (no JSON Parse error) +``` + +### 4.2 Scenario: Boulder Continuation + +```bash +# Create a work plan with multiple tasks +opencode "Create a plan to refactor the authentication module" + +# Let Atlas start executing +# Interrupt mid-execution (Ctrl+C) + +# Resume +opencode "Continue the work plan" + +# Should inject continuation prompt via promptAsync (no JSON Parse error) +``` + +### 4.3 Scenario: Look At Tool + +```bash +# Test the look_at tool (previously had isJsonParseError band-aid) +opencode "Analyze this diagram" --attach diagram.png + +# Should work without falling back to JSON Parse error handler +``` + +--- + +## Success Criteria + +### ✅ TUI Tests Pass If: +- Agents respond without JSON Parse errors +- Hooks fire correctly (Atlas, Ralph, todo-continuation) +- Background tasks launch and complete +- Logs show NO "JSON Parse error: Unexpected EOF" + +### ✅ ACP Tests Pass If: +- Plugin loads in Claude Code without errors +- All tools execute correctly (delegate_task, call_omo_agent, background, look_at) +- Hooks integrate properly in ACP environment +- Logs show NO "JSON Parse error: Unexpected EOF" + +### ✅ Regression Tests Pass If: +- Existing error handling still works +- Model suggestion errors still provide suggestions +- Fire-and-forget prompts still catch HTTP errors +- Test suite passes (57/57 migration tests) + +--- + +## Reporting Results + +After testing, update the PR with your findings: + +```markdown +## Testing Results + +### TUI Testing +- ✅/❌ Basic agent operations +- ✅/❌ Hook behavior (Atlas, Ralph, todo-continuation) +- ✅/❌ Background tasks +- ✅/❌ No JSON Parse errors in logs + +### ACP Testing +- ✅/❌ Plugin loads successfully +- ✅/❌ Tools execute correctly +- ✅/❌ Hooks integrate properly +- ✅/❌ No JSON Parse errors in logs + +### Regression Testing +- ✅/❌ No breaking changes +- ✅/❌ Test suite passes + +### Issues Found +[List any issues discovered during testing] + +### Recommendation +[Ready for merge / Needs fixes / etc.] +``` + +--- + +## Troubleshooting + +### Issue: "Module not found" after installation + +```bash +# Clear bun cache +rm -rf ~/.bun/install/cache + +# Reinstall +bun install --global github:potb/oh-my-opencode#acp-json-error +``` + +### Issue: Plugin not loading in Claude Code + +```bash +# Check plugin path in opencode.json +cat ~/.config/opencode/opencode.json + +# Verify plugin directory exists +ls -la /path/to/oh-my-opencode + +# Restart Claude Code +opencode restart +``` + +### Issue: Still seeing JSON Parse errors + +```bash +# Verify you're using the correct branch +cd /path/to/oh-my-opencode +git branch --show-current +# Should show: acp-json-error + +# Check for remaining session.prompt() calls +grep -rn 'session\.prompt(' src/ --include='*.ts' | grep -v 'promptAsync' | grep -v '\.test\.' +# Should return: 0 matches +``` + +--- + +## Next Steps After Testing + +1. **If tests pass**: Comment on PR with results, mark as ready for review +2. **If issues found**: Document issues, create follow-up tasks +3. **If ready**: Merge to dev branch (per AGENTS.md: ALL PRs → dev) + +--- + +## Quick Reference + +| Test Area | Command | Expected Result | +|-----------|---------|-----------------| +| Agent invocation | `opencode "List files"` | No JSON Parse error | +| Background task | `opencode "Background analysis"` | Task completes | +| Hook behavior | `opencode "Create work plan"` | Continuation works | +| Plugin load | `opencode plugin list` | oh-my-opencode loaded | +| Tool execution | `/delegate "Test task"` | Tool executes | +| Logs check | `tail -f ~/.opencode/logs/*.log` | No JSON Parse EOF | + +--- + +**Good luck with testing! 🚀**