@grympler/opencode-tmux-handover 1.0.0

package/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,529 @@
+# Implementation Guide: Adding Configuration to tt-plugin
+
+This guide walks through the step-by-step process of implementing user-configurable command availability in the tt-plugin.
+
+---
+
+## Quick Start: Add Plugin Configuration
+
+### Step 1: Create Configuration Module
+
+Create `src/config.ts`:
+
+```typescript
+import { readFileSync } from "fs"
+import { homedir } from "os"
+import { join } from "path"
+
+export interface PluginConfig {
+  enabledCommands: string[]
+  defaultTerminal?: string
+  sessionPrefix?: string
+}
+
+const DEFAULT_CONFIG: PluginConfig = {
+  enabledCommands: ["tmux", "tmux-oc", "tmux-claude", "tmux-copilot"],
+  defaultTerminal: "auto",
+  sessionPrefix: "oc"
+}
+
+export function loadConfig(): PluginConfig {
+  const configPath = join(homedir(), ".config", "opencode", "tt-plugin-config.json")
+
+  try {
+    const fileContent = readFileSync(configPath, "utf-8")
+    const userConfig = JSON.parse(fileContent)
+
+    return {
+      ...DEFAULT_CONFIG,
+      ...userConfig
+    }
+  } catch {
+    // Config file doesn't exist or is invalid - use defaults
+    return DEFAULT_CONFIG
+  }
+}
+
+export function getConfigPath(): string {
+  return join(homedir(), ".config", "opencode", "tt-plugin-config.json")
+}
+```
+
+### Step 2: Update Plugin to Use Configuration
+
+Update `src/index.ts`:
+
+```typescript
+import type { Plugin } from "@opencode-ai/plugin"
+import { join } from "path"
+import { loadConfig } from "./config"
+
+export const TmuxLauncher: Plugin = async ({ $, directory }) => {
+  const config = loadConfig()
+
+  return {
+    "command.execute.before": async (input, output) => {
+      const commandName = input.command || ""
+
+      // Check if command is in enabled list
+      if (!config.enabledCommands.includes(commandName)) {
+        return
+      }
+
+      if (!commandName.startsWith("tmux")) return
+
+      const scriptMap: Record<string, string> = {
+        "tmux": "opencode-tmux.sh",
+        "tmux-oc": "opencode-tmux-oc.sh",
+        "tmux-claude": "opencode-tmux-claude.sh",
+        "tmux-copilot": "opencode-tmux-copilot.sh"
+      }
+
+      const scriptName = scriptMap[commandName]
+      if (!scriptName) return
+
+      const scriptPath = join(import.meta.dirname, "..", "scripts", scriptName)
+
+      try {
+        await $`bash ${scriptPath}`.cwd(directory)
+        output.parts = []
+      } catch (err) {
+        console.error("tt-plugin:", err)
+      }
+    }
+  }
+}
+```
+
+### Step 3: Create Configuration Script
+
+Create `src/scripts/opencode-tt-config.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CONFIG_DIR="$HOME/.config/opencode"
+CONFIG_FILE="$CONFIG_DIR/tt-plugin-config.json"
+
+# Ensure config directory exists
+mkdir -p "$CONFIG_DIR"
+
+# Show current configuration
+if [ -f "$CONFIG_FILE" ]; then
+  echo "Current tt-plugin configuration:"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  cat "$CONFIG_FILE" | head -20
+  echo ""
+  echo "Location: $CONFIG_FILE"
+  echo ""
+else
+  echo "No tt-plugin configuration found."
+  echo "Creating default configuration at: $CONFIG_FILE"
+  echo ""
+fi
+
+# Create or show default configuration
+cat > "$CONFIG_FILE" << 'EOF'
+{
+  "enabledCommands": ["tmux", "tmux-oc", "tmux-claude", "tmux-copilot"],
+  "defaultTerminal": "auto",
+  "sessionPrefix": "oc"
+}
+EOF
+
+echo "Configuration saved!"
+echo ""
+echo "Available options:"
+echo "  enabledCommands: Array of command names to enable"
+echo "    Options: tmux, tmux-oc, tmux-claude, tmux-copilot"
+echo ""
+echo "  defaultTerminal: Preferred terminal emulator"
+echo "    Options: auto, gnome-terminal, terminator, konsole, alacritty, kitty, xterm"
+echo ""
+echo "  sessionPrefix: Prefix for tmux session names"
+echo "    Default: oc"
+echo ""
+echo "Edit with: ${EDITOR:-nano} $CONFIG_FILE"
+```
+
+### Step 4: Add Configuration Command
+
+Create `src/commands/tt-configure.md`:
+
+```markdown
+---
+description: Configure tt-plugin settings
+---
+
+Open and configure the tt-plugin settings, including which tmux commands to enable and terminal preferences.
+```
+
+### Step 5: Update Installation Script
+
+Update `install.sh` to include the config script:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ... existing code ...
+
+# Add to symlink creation loop
+CONFIG_SCRIPT_SRC="${PLUGIN_DIR}/src/scripts/opencode-tt-config.sh"
+CONFIG_SCRIPT_DST="$COMMANDS_DIR/tt-configure"
+
+# Create symlink for configuration script
+mkdir -p "$COMMANDS_DIR"
+ln -sf "$CONFIG_SCRIPT_SRC" "$CONFIG_SCRIPT_DST" || true
+
+# Make executable
+chmod +x "$CONFIG_SCRIPT_SRC"
+
+echo "✓ Configuration command installed: tt-configure"
+```
+
+---
+
+## Usage Guide for Users
+
+### First Time Setup
+
+1. Install the plugin
+2. Run the configuration command:
+   ```
+   /tt-configure
+   ```
+3. Edit the generated config file:
+   ```bash
+   # ~/.config/opencode/tt-plugin-config.json
+   {
+     "enabledCommands": ["tmux", "tmux-oc"],
+     "defaultTerminal": "alacritty",
+     "sessionPrefix": "myproject"
+   }
+   ```
+
+### Common Configurations
+
+#### Only Use OpenCode Integration
+```json
+{
+  "enabledCommands": ["tmux-oc"]
+}
+```
+
+#### Use Claude Split
+```json
+{
+  "enabledCommands": ["tmux", "tmux-claude"]
+}
+```
+
+#### All Commands, Specific Terminal
+```json
+{
+  "enabledCommands": ["tmux", "tmux-oc", "tmux-claude", "tmux-copilot"],
+  "defaultTerminal": "kitty"
+}
+```
+
+#### Minimal Setup (Just Tmux)
+```json
+{
+  "enabledCommands": ["tmux"]
+}
+```
+
+---
+
+## Publishing as npm Package
+
+### Step 1: Update package.json for Publishing
+
+```json
+{
+  "name": "tt-plugin",
+  "version": "1.0.0",
+  "description": "OpenCode plugin for launching tmux with AI assistants in split panes",
+  "main": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "install": "bash install.sh",
+    "uninstall": "bash uninstall.sh",
+    "test": "bash -n src/scripts/*.sh && npx tsc --noEmit src/index.ts"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "tmux",
+    "terminal",
+    "ai",
+    "assistant"
+  ],
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/yourname/tt-plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourname/tt-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourname/tt-plugin/issues"
+  },
+  "engines": {
+    "opencode": ">=dev",
+    "tmux": ">=3.0",
+    "bash": ">=4.0",
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "install.sh",
+    "uninstall.sh",
+    "README.md",
+    "DISTRIBUTION_AND_CONFIG.md",
+    "IMPLEMENTATION_GUIDE.md",
+    "package.json"
+  ]
+}
+```
+
+### Step 2: Setup npm Publishing
+
+```bash
+# Create npm account
+npm adduser
+
+# Verify you're logged in
+npm whoami
+
+# Tag version (if not already done)
+npm version patch  # or minor, major
+
+# Publish to npm
+npm publish
+
+# Verify it's published
+npm view tt-plugin
+```
+
+### Step 3: Users Can Install From npm
+
+Users add to their `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["tt-plugin"]
+}
+```
+
+OpenCode will automatically install it!
+
+---
+
+## Advanced Configuration
+
+### Adding Configuration Validation
+
+Update `src/config.ts`:
+
+```typescript
+export function validateConfig(config: any): PluginConfig {
+  const validCommands = ["tmux", "tmux-oc", "tmux-claude", "tmux-copilot"]
+  const validTerminals = [
+    "auto",
+    "gnome-terminal",
+    "terminator",
+    "konsole",
+    "alacritty",
+    "kitty",
+    "xterm"
+  ]
+
+  // Validate enabledCommands
+  if (Array.isArray(config.enabledCommands)) {
+    const invalid = config.enabledCommands.filter(
+      cmd => !validCommands.includes(cmd)
+    )
+    if (invalid.length > 0) {
+      console.warn(
+        `tt-plugin: Invalid commands ignored: ${invalid.join(", ")}`
+      )
+      config.enabledCommands = config.enabledCommands.filter(
+        cmd => validCommands.includes(cmd)
+      )
+    }
+  }
+
+  // Validate defaultTerminal
+  if (config.defaultTerminal && !validTerminals.includes(config.defaultTerminal)) {
+    console.warn(
+      `tt-plugin: Invalid terminal "${config.defaultTerminal}", using "auto"`
+    )
+    config.defaultTerminal = "auto"
+  }
+
+  return config as PluginConfig
+}
+```
+
+### Configuration with Environment Variables
+
+Users can override config with environment variables:
+
+```bash
+# Override enabled commands via environment
+export TT_PLUGIN_COMMANDS="tmux,tmux-oc"
+
+# Use in plugin
+const enabledCommands =
+  process.env.TT_PLUGIN_COMMANDS?.split(",") ||
+  config.enabledCommands
+```
+
+---
+
+## File Structure After Implementation
+
+```
+tt-plugin/
+├── src/
+│   ├── index.ts                    # Main plugin (reads config)
+│   ├── config.ts                   # Configuration management
+│   ├── commands/
+│   │   ├── tmux.md
+│   │   ├── tmux-oc.md
+│   │   ├── tmux-claude.md
+│   │   ├── tmux-copilot.md
+│   │   └── tt-configure.md         # NEW: Configuration command
+│   └── scripts/
+│       ├── opencode-tmux.sh
+│       ├── opencode-tmux-oc.sh
+│       ├── opencode-tmux-claude.sh
+│       ├── opencode-tmux-copilot.sh
+│       └── opencode-tt-config.sh   # NEW: Configuration helper
+├── scripts/
+│   ├── register-plugin.js
+│   └── unregister-plugin.js
+├── install.sh                      # Updated to symlink config script
+├── uninstall.sh
+├── package.json                    # Updated with new files
+├── README.md
+├── DISTRIBUTION_AND_CONFIG.md      # NEW: This file
+├── IMPLEMENTATION_GUIDE.md         # NEW: Implementation steps
+└── .git/
+```
+
+---
+
+## Testing Configuration
+
+### Manual Test
+
+```bash
+# 1. Create test config
+mkdir -p ~/.config/opencode
+cat > ~/.config/opencode/tt-plugin-config.json << 'EOF'
+{
+  "enabledCommands": ["tmux", "tmux-oc"],
+  "defaultTerminal": "alacritty"
+}
+EOF
+
+# 2. Verify config loads
+npm test
+
+# 3. Test with OpenCode
+opencode
+# Run: /tmux          # Should work
+# Run: /tmux-claude   # Should be silently ignored
+# Run: /tt-configure  # Should show configuration
+```
+
+### Validation Test
+
+```bash
+# Test invalid configuration
+cat > ~/.config/opencode/tt-plugin-config.json << 'EOF'
+{
+  "enabledCommands": ["tmux", "invalid-command"],
+  "defaultTerminal": "invalid-terminal"
+}
+EOF
+
+# Should warn but still work with filtered commands
+opencode
+```
+
+---
+
+## Troubleshooting
+
+### Configuration Not Loading
+
+```bash
+# Check if config file exists
+ls -la ~/.config/opencode/tt-plugin-config.json
+
+# Check for JSON syntax errors
+cat ~/.config/opencode/tt-plugin-config.json | jq .
+
+# Check OpenCode logs
+# The plugin logs to OpenCode's debug logs
+```
+
+### Commands Still Not Working
+
+```bash
+# Verify plugin is loaded
+grep "tt-plugin" ~/.config/opencode/opencode.json
+
+# Verify command registration
+ls -la ~/.config/opencode/commands/ | grep tmux
+
+# Run plugin directly to check for errors
+node -e "import('./src/index.ts').then(m => console.log(m))"
+```
+
+### Publishing Issues
+
+```bash
+# Verify npm account
+npm whoami
+
+# Check package.json syntax
+npm run test
+
+# Dry run publish
+npm publish --dry-run
+
+# Check what will be published
+npm pack --dry-run
+```
+
+---
+
+## Next Steps
+
+After implementing configuration:
+
+1. **Add telemetry** - Track which commands users enable
+2. **Add more settings** - Terminal colors, session names, etc.
+3. **Create web UI** - Build a configuration interface
+4. **Add CLI config** - Let users configure via command line
+5. **Documentation** - Update README with configuration examples
+
+---
+
+## Related Files
+
+- `DISTRIBUTION_AND_CONFIG.md` - Conceptual guide
+- `AGENTS.md` - Developer guidelines
+- `README.md` - User documentation
+- `src/index.ts` - Main plugin entry point
+- `package.json` - Package manifest