opencode-branch-memory-manager 0.1.0

package/README.md

@@ -0,0 +1,500 @@
+# 🧠 OpenCode Branch Memory Manager
+
+Automatically manages branch-specific context for OpenCode so you never lose your development context when switching branches.
+
+## ✨ Features
+
+- 🔄 **Automatic Context Loading**: Loads saved context when switching branches (configurable)
+- 💾 **Automatic Saving**: Auto-saves context on tool execution, session updates, and branch changes
+- 🎛️ **Manual Control**: Save/load context with fine-grained filters
+- 💾 **Branch-Specific Storage**: Context saved per git branch
+- 📊 **Status Dashboard**: See all your saved contexts at a glance
+- 🛡️ **Error Resilient**: Automatic backups and recovery from corrupted data
+- 🌐 **Cross-Platform**: Works seamlessly on macOS, Linux, and Windows
+- 📋 **List & Delete**: Manage saved contexts easily
+- 🎯 **Configurable**: Customize auto-save behavior, context loading mode, and storage options
+
+## 🚀 Quick Start
+
+### Installation
+
+#### Option 1: npm Package (Recommended)
+
+**macOS/Linux:**
+```bash
+bunx install @davecodes/opencode-branch-memory-manager
+```
+
+**Windows (PowerShell):**
+```powershell
+bunx install @davecodes/opencode-branch-memory-manager
+```
+
+The plugin and tools will be automatically loaded when you run `opencode`. Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["@davecodes/opencode-branch-memory-manager"]
+}
+```
+
+**Note:** This will add the plugin without removing any existing plugins you have.
+
+#### Option 2: Local Installation
+
+**macOS/Linux:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/Davidcreador/opencode-branch-memory-manager/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/Davidcreador/opencode-branch-memory-manager/main/install.ps1 | iex
+```
+
+The plugin and tools will be automatically loaded when you run `opencode`. No configuration needed.
+
+### Getting Started
+
+```bash
+opencode
+
+# Check status
+@branch-memory_status
+
+# Save current context with filters
+@branch-memory_save --include-messages --include-todos --include-files "Working on user authentication"
+
+# Load context for a specific branch
+@branch-memory_load --branch feature/payment-api
+
+# List all saved contexts
+@branch-memory_list --verbose
+```
+
+## 📖 Commands
+
+### @branch-memory_save
+
+Save current session context for current git branch.
+
+**Arguments:**
+- `--include-messages`: Include conversation messages (default: true)
+- `--include-todos`: Include todo items (default: true)
+- `--include-files`: Include modified files (default: true)
+- `--description`: Description of what you're saving
+
+**Examples:**
+```
+# Save everything
+@branch-memory_save "Adding Stripe integration"
+
+# Save only messages and todos
+@branch-memory_save --include-messages --include-todos "Quick checkpoint"
+
+# Save only files
+@branch-memory_save --include-files "API work"
+```
+
+### @branch-memory_load
+
+Load branch-specific context into current session.
+
+**Arguments:**
+- `--branch`: Branch name (default: current branch)
+
+**Examples:**
+```
+# Load current branch context
+@branch-memory_load
+
+# Load specific branch context
+@branch-memory_load --branch feature/authentication
+```
+
+### @branch-memory_status
+
+Show branch memory status and available contexts.
+
+**Examples:**
+```
+@branch-memory_status
+```
+
+**Output:**
+```
+📊 Branch Memory Status
+═════════════════
+
+Current branch: feature/user-auth
+Current context:
+  📝 Messages: 23
+  ✅ Todos: 7
+  📁 Files: 5
+  💾 Size: 2.3KB
+  ⏰ Saved: 2025-01-01T14:30:00.000Z
+  📄 Description: Adding user authentication with OAuth
+
+Available contexts:
+  → feature/user-auth (2.3KB, 2025-01-01T14:30:00)
+  → feature/payment-api (4.1KB, 2025-01-01T15:45:00)
+    main (1.8KB, 2025-01-01T12:00:00.000Z)
+```
+
+### @branch-memory_deleteContext
+
+Delete saved context for a branch.
+
+**Arguments:**
+- `--branch`: Branch name to delete context for
+
+**Example:**
+```
+@branch-memory_deleteContext --branch old-feature
+```
+
+### @branch-memory_list
+
+List all branches with saved contexts.
+
+**Arguments:**
+- `--verbose`: Show detailed information including message, todo, and file counts
+
+**Examples:**
+```
+@branch-memory_list
+
+# With verbose details
+@branch-memory_list --verbose
+```
+
+**Output (verbose):**
+```
+📋 Branches with saved contexts
+═════════════════
+
+feature/user-auth
+  💾 Size: 2.3KB
+  ⏰ Modified: 2025-01-01T14:30:00
+  📝 Messages: 23
+  ✅ Todos: 7
+  📁 Files: 5
+
+feature/payment-api
+  💾 Size: 4.1KB
+  ⏰ Modified: 2025-01-01T15:45:00
+  📝 Messages: 31
+  ✅ Todos: 12
+  📁 Files: 8
+
+main
+  💾 Size: 1.8KB
+  ⏰ Modified: 2025-01-01T12:00:00
+  📝 Messages: 15
+  ✅ Todos: 3
+  📁 Files: 2
+
+═════════════════
+Total: 3 branch(es)
+```
+
+## ⚙️ Configuration
+
+Configuration is stored in `.opencode/config/branch-memory.json`
+
+### Default Configuration
+
+```json
+{
+  "autoSave": {
+    "enabled": true,
+    "onMessageChange": true,
+    "onBranchChange": true,
+    "onToolExecute": true
+  },
+  "contextLoading": "auto",
+  "context": {
+    "defaultInclude": ["messages", "todos", "files"],
+    "maxMessages": 50,
+    "maxTodos": 20,
+    "compression": false
+  },
+  "storage": {
+    "maxBackups": 5,
+    "retentionDays": 90
+  },
+  "monitoring": {
+    "method": "both",
+    "pollingInterval": 1000
+  }
+}
+```
+
+### Configuration Options
+
+#### autoSave
+- `enabled`: Enable/disable automatic saving (default: `true`)
+- `onMessageChange`: Auto-save when messages change (default: `true`)
+- `onBranchChange`: Auto-save when switching branches (default: `true`)
+- `onToolExecute`: Auto-save before running tools (default: `true`)
+
+#### contextLoading
+- `"auto"`: Automatically load context when switching branches
+- `"ask"`: Prompt user before loading context
+- `"manual"`: Don't auto-load; use `@branch-memory_load` manually
+
+#### context
+- `defaultInclude`: Array of data types to include by default
+- `maxMessages`: Maximum number of messages to save (default: 50)
+- `maxTodos`: Maximum number of todos to save (default: 20)
+- `compression`: Enable compression (not yet implemented)
+
+#### storage
+- `maxBackups`: Number of backups to keep (default: 5)
+- `retentionDays`: Days to keep old contexts (default: 90)
+
+#### monitoring
+- `"watcher"`: Use file watcher only (fast, uses chokidar)
+- `"polling"`: Use polling only (reliable, slower)
+- `"both"`: Use watcher with polling fallback (default)
+
+## 🔧 How It Works
+
+1. **Initialization**: Plugin loads configuration from `.opencode/config/branch-memory.json`
+2. **Automatic Features** (when plugin is loaded):
+    - Auto-loads context when a new session starts (configurable)
+    - Auto-saves before tool execution
+    - Auto-saves on session updates (throttled)
+    - Monitors for git branch changes and auto-loads/saves
+3. **Manual Saving**: Use `@branch-memory_save` to save context:
+    - Saves conversation messages
+    - Saves todo items
+    - Saves modified file references
+4. **Manual Loading**: Use `@branch-memory_load` to restore context:
+    - Loads messages and todos
+    - Shows what was saved
+5. **Status Checking**: Use `@branch-memory_status` to see:
+    - Current branch and context
+    - All saved contexts
+    - Metadata (size, dates, counts)
+6. **Error Recovery**: Automatic backups prevent data loss
+7. **Management**: Use `@branch-memory_list` and `@branch-memory_deleteContext` to manage saved contexts
+
+## 🐛 Troubleshooting
+
+### Tools not available
+
+1. Check if tools are in `opencode.json`:
+```json
+{
+  "tools": ["@branch-memory_save", "@branch-memory_load", "@branch-memory_status", "@branch-memory_list", "@branch-memory_deleteContext"]
+}
+```
+
+2. Verify dependencies are installed:
+```bash
+cd .opencode
+bun install
+```
+
+### Context not saving
+
+1. Check if in a git repository:
+```bash
+git status
+```
+
+2. Check configuration:
+```bash
+cat .opencode/config/branch-memory.json
+```
+
+3. Check logs for errors:
+```bash
+# Look for emoji indicators:
+# ✅ = success
+# ⚠️  = warning
+# ❌ = error
+```
+
+### Branch changes not detected
+
+1. Verify git repository:
+```bash
+git rev-parse --git-dir
+```
+
+2. Check `.git/HEAD` file exists and is being updated
+
+3. Try both monitoring modes:
+```json
+{
+  "monitoring": {
+    "method": "watcher"  // or "polling"
+  }
+}
+```
+
+### Corrupted context files
+
+The system automatically restores from backups. If issues persist:
+
+1. Check backup files:
+```bash
+ls -la .opencode/branch-memory/
+```
+
+2. Manual cleanup:
+```bash
+@branch-memory_deleteContext --branch broken-branch
+```
+
+### Permission errors
+
+1. Check file permissions:
+```bash
+ls -la .opencode/branch-memory/
+```
+
+2. Ensure write access:
+```bash
+chmod -R u+w .opencode/branch-memory/
+```
+
+## 📁 File Structure
+
+```
+.opencode/
+├── plugin/
+│   └── branch-memory-plugin.ts   # Event hooks for auto-save/load
+├── tool/
+│   └── branch-memory.ts          # User-facing tools
+├── branch-memory/
+│   ├── index.ts                  # Exports
+│   ├── storage.ts                # Context persistence
+│   ├── git.ts                   # Git operations
+│   ├── monitor.ts                # Branch monitoring
+│   ├── collector.ts             # Context collection
+│   ├── injector.ts              # Context injection
+│   ├── types.ts                 # TypeScript types
+│   └── config.ts                # Configuration
+├── config/
+│   └── branch-memory.json        # Configuration file
+└── package.json                  # Dependencies
+```
+
+## 🚀 Advanced Usage
+
+### Custom Configuration
+
+Edit `.opencode/config/branch-memory.json` to customize behavior:
+
+```json
+{
+  "autoSave": {
+    "enabled": true,
+    "onMessageChange": true,
+    "onBranchChange": true,
+    "onToolExecute": true
+  },
+  "contextLoading": "ask",
+  "context": {
+    "defaultInclude": ["messages", "todos", "files"],
+    "maxMessages": 100,
+    "maxTodos": 50
+  }
+}
+```
+
+### Workflow Example
+
+1. **Start working on a feature:**
+```bash
+git checkout -b feature/user-profile
+opencode
+```
+
+2. **Context auto-loads on session start (if contextLoading is "auto"):**
+```
+🚀 Session created - checking for saved context...
+📥 Found context for branch 'feature/user-profile'
+   Use @branch-memory_load to restore it
+```
+
+3. **Work on feature - context auto-saves as you work:**
+```bash
+# Plugin auto-saves before tool execution and periodically
+@branch-memory_save "Adding user profile feature"
+```
+
+4. **Switch to main to work on bug fix:**
+```bash
+git checkout main
+# Plugin detects branch change
+🔄 Branch changed: feature/user-profile → main
+💾 Saved context for old branch 'feature/user-profile'
+📥 Found context for branch 'main'
+```
+
+5. **Switch back to feature - context auto-loads:**
+```bash
+git checkout feature/user-profile
+# Plugin detects branch change
+🔄 Branch changed: main → feature/user-profile
+📥 Found context for branch 'feature/user-profile'
+   Use @branch-memory_load to restore it
+```
+
+6. **Or manually load context:**
+```bash
+@branch-memory_load
+
+# Context is restored - messages and todos are back
+```
+
+## 🛠️ Development
+
+### Build
+
+```bash
+bun install
+bun run build
+```
+
+This compiles TypeScript files from `src/` to `dist/`.
+
+### Type Check
+
+```bash
+bun run typecheck
+```
+
+### Testing
+
+```bash
+bun test
+```
+
+## 📦 Publishing to npm
+
+1. Update version in `package.json`
+2. Build: `bun run build`
+3. Publish: `npm publish`
+
+Make sure you're logged in to npm: `npm whoami`
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 🐛 Issues
+
+Found a bug? Have a feature request? Please open an issue on GitHub.
+
+---
+
+Made with ❤️ for the OpenCode community

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "opencode-branch-memory-manager",
+  "version": "0.1.0",
+  "description": "Automatically manages branch-specific context for OpenCode with auto-save, auto-load, and git workflow integration",
+  "author": "Davidcreador",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Davidcreador/opencode-branch-memory-manager.git"
+  },
+  "homepage": "https://github.com/Davidcreador/opencode-branch-memory-manager#readme",
+  "bugs": {
+    "url": "https://github.com/Davidcreador/opencode-branch-memory-manager/issues"
+  },
+  "files": [
+    ".opencode"
+  ],
+  "scripts": {
+    "build": "npm run build:local",
+    "build:npm": "cd src && bun install --no-lockfile && bun build index.ts --outdir ../dist --target node",
+    "build:local": "bun build .opencode/tool/branch-memory.ts --outdir .opencode/dist --target node",
+    "typecheck": "tsc --noEmit --project tsconfig.typecheck.json --skipLibCheck",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "eslint src tests --ext .ts",
+    "lint:fix": "eslint src tests --ext .ts --fix",
+    "clean": "rm -rf dist node_modules src/node_modules",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "branch-memory",
+    "context",
+    "git",
+    "auto-save",
+    "workspace"
+  ],
+  "dependencies": {
+    "chokidar": "^4.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.0.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  },
+  "directories": {
+    "test": "tests"
+  }
+}