@grympler/opencode-tmux-handover 1.0.0

package/DISTRIBUTION_AND_CONFIG.md

@@ -0,0 +1,514 @@
+# From Local Plugin to Web-Available: Distribution & Configuration Guide
+
+This guide explains how to evolve the `tt-plugin` from a local development plugin to a web-available npm package, and how to add customizable settings for command availability.
+
+---
+
+## Table of Contents
+
+1. [Current Architecture](#current-architecture)
+2. [Distribution Methods](#distribution-methods)
+3. [Publishing to npm](#publishing-to-npm)
+4. [Adding Plugin Configuration](#adding-plugin-configuration)
+5. [Plugin Settings Management](#plugin-settings-management)
+6. [Examples](#examples)
+
+---
+
+## Current Architecture
+
+The `tt-plugin` currently uses a **local installation model**:
+
+```
+tt-plugin (local directory)
+    ├── src/
+    │   ├── index.ts          # Plugin entry point
+    │   ├── commands/         # Command definitions (.md files)
+    │   └── scripts/          # Bash implementations
+    ├── scripts/              # Registration utilities
+    ├── install.sh            # Local installation script
+    └── package.json          # Plugin manifest
+```
+
+**Current Flow:**
+1. User clones repository locally
+2. Runs `npm run install`
+3. Plugin path is added to `~/.config/opencode/opencode.json`
+4. Commands are symlinked to `~/.config/opencode/commands/`
+
+**Limitations:**
+- Requires manual git cloning
+- Must be maintained locally
+- No version management
+- Updates require manual pulling
+- No built-in configuration UI
+
+---
+
+## Distribution Methods
+
+### Option 1: Local Files (Current)
+**Best for:** Personal use, development, testing
+
+```bash
+# Users manually clone and install
+git clone https://github.com/yourname/tt-plugin.git
+cd tt-plugin
+npm run install
+```
+
+**Pros:**
+- Full control over code
+- Easy to debug
+- No build process needed
+
+**Cons:**
+- Manual updates
+- Version conflicts
+- Not discoverable
+
+---
+
+### Option 2: npm Registry (Recommended)
+**Best for:** Wide distribution, discoverability, version management
+
+```bash
+# Users simply add to config
+```
+
+```json
+{
+  "plugin": ["tt-plugin"]
+}
+```
+
+**Pros:**
+- Automatic installation via Bun
+- Version management (semantic versioning)
+- Discoverable in OpenCode ecosystem
+- Easy updates
+- No symlink management
+
+**Cons:**
+- Requires build step
+- Must publish to npm
+- Less flexible for local development
+
+---
+
+### Option 3: GitHub Package Registry
+**Best for:** Organizations, private packages
+
+```json
+{
+  "plugin": ["@yourorg/tt-plugin"]
+}
+```
+
+Similar to npm but hosted on GitHub.
+
+---
+
+## Publishing to npm
+
+### Step 1: Prepare Package
+
+Update your `package.json`:
+
+```json
+{
+  "name": "tt-plugin",
+  "version": "1.0.0",
+  "description": "OpenCode plugin for launching tmux with AI assistants",
+  "main": "src/index.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/tt-plugin"
+  },
+  "keywords": ["opencode", "plugin", "tmux", "terminal"],
+  "author": "Your Name",
+  "license": "MIT",
+  "engines": {
+    "opencode": ">=dev",
+    "tmux": ">=3.0",
+    "bash": ">=4.0"
+  }
+}
+```
+
+**Important fields:**
+- `name`: Must be lowercase, can include scopes (`@org/name`)
+- `version`: Follows semantic versioning (1.0.0)
+- `main`: Entry point (TypeScript supported by Bun)
+- `type`: "module" for ES modules
+- `files`: Include only necessary files
+
+### Step 2: Build (Optional)
+
+If you need to transpile TypeScript:
+
+```bash
+# In your build process
+npx tsc src/index.ts --outDir dist/
+```
+
+Update `package.json` main field:
+```json
+"main": "dist/index.js"
+```
+
+**For this plugin:** No build needed! Bun natively supports TypeScript.
+
+### Step 3: Create npm Account
+
+```bash
+npm login
+# Enter credentials
+```
+
+Or sign up at https://www.npmjs.com/signup
+
+### Step 4: Publish
+
+```bash
+# First time publish
+npm publish
+
+# Subsequent updates (bump version first)
+npm version minor  # or major, patch
+npm publish
+```
+
+### Step 5: Verify Installation
+
+Users can then use it:
+
+```json
+{
+  "plugin": ["tt-plugin"]
+}
+```
+
+OpenCode will automatically install it to `~/.cache/opencode/node_modules/tt-plugin`. This includes all bundled files (specifically `src/scripts/*.sh`), ensuring the bash scripts are available locally for the plugin to execute.
+
+---
+
+## Adding Plugin Configuration
+
+OpenCode plugins can accept configuration through two mechanisms:
+
+### Method 1: Config File Settings
+
+Store configuration in `opencode.json`:
+
+```json
+{
+  "plugin": [
+    {
+      "path": "tt-plugin",
+      "config": {
+        "enabledCommands": ["tmux", "tmux-oc"],
+        "defaultTerminal": "alacritty",
+        "sessionPrefix": "oc"
+      }
+    }
+  ]
+}
+```
+
+**Note:** Current OpenCode plugin system doesn't natively support this structure. This would require either:
+1. Custom environment variables
+2. Reading a separate config file
+3. Extending the plugin API (future feature)
+
+### Method 2: Environment Variables
+
+Users can set environment variables to control behavior:
+
+```bash
+export TT_PLUGIN_COMMANDS="tmux,tmux-oc,tmux-claude"
+export TT_PLUGIN_DEFAULT_TERMINAL="alacritty"
+```
+
+Modify your plugin to read these:
+
+```typescript
+// src/index.ts
+const enabledCommands = (process.env.TT_PLUGIN_COMMANDS || "tmux,tmux-oc,tmux-claude,tmux-copilot").split(",")
+```
+
+---
+
+## Plugin Settings Management
+
+### Approach: JSON Configuration File
+
+Create a configuration system that reads from `~/.config/opencode/tt-plugin-config.json`:
+
+#### 1. Update Plugin to Read Config
+
+```typescript
+// src/index.ts
+import type { Plugin } from "@opencode-ai/plugin"
+import { readFileSync } from "fs"
+import { homedir } from "os"
+import { join } from "path"
+
+interface PluginConfig {
+  enabledCommands: string[]
+  defaultTerminal?: string
+  sessionPrefix?: string
+}
+
+function loadConfig(): PluginConfig {
+  const configPath = join(homedir(), ".config", "opencode", "tt-plugin-config.json")
+  
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf-8"))
+    return {
+      enabledCommands: ["tmux", "tmux-oc", "tmux-claude", "tmux-copilot"],
+      ...config
+    }
+  } catch {
+    // Return defaults if no config file
+    return {
+      enabledCommands: ["tmux", "tmux-oc", "tmux-claude", "tmux-copilot"]
+    }
+  }
+}
+
+export const TmuxLauncher: Plugin = async ({ $, directory }) => {
+  const config = loadConfig()
+
+  return {
+    "command.execute.before": async (input, output) => {
+      const commandName = input.command || ""
+      
+      // Check if command is enabled
+      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)
+      }
+    }
+  }
+}
+```
+
+#### 2. Create Setup/Configuration Command
+
+Add a command to help users configure the plugin:
+
+```bash
+#!/usr/bin/env bash
+# scripts/opencode-tt-configure.sh
+
+set -euo pipefail
+
+CONFIG_DIR="$HOME/.config/opencode"
+CONFIG_FILE="$CONFIG_DIR/tt-plugin-config.json"
+
+mkdir -p "$CONFIG_DIR"
+
+# Show current configuration
+if [ -f "$CONFIG_FILE" ]; then
+  echo "Current configuration:"
+  cat "$CONFIG_FILE"
+  echo ""
+fi
+
+# Create default config if it doesn't exist
+if [ ! -f "$CONFIG_FILE" ]; then
+  cat > "$CONFIG_FILE" << 'EOF'
+{
+  "enabledCommands": ["tmux", "tmux-oc", "tmux-claude", "tmux-copilot"],
+  "defaultTerminal": "auto",
+  "sessionPrefix": "oc"
+}
+EOF
+  echo "Created default configuration at: $CONFIG_FILE"
+fi
+
+echo ""
+echo "Edit the configuration file to customize:"
+echo "  - enabledCommands: Which tmux commands to enable"
+echo "  - defaultTerminal: Preferred terminal emulator (auto, gnome-terminal, alacritty, kitty, etc.)"
+echo "  - sessionPrefix: Prefix for tmux session names"
+echo ""
+echo "To edit: $EDITOR $CONFIG_FILE"
+```
+
+#### 3. Add Configuration Command to Plugin
+
+Add to `src/commands/tt-configure.md`:
+
+```markdown
+---
+description: Configure tt-plugin settings
+---
+
+Open the tt-plugin configuration file to customize enabled commands, terminal preference, and session naming.
+```
+
+#### 4. Example Configuration File
+
+`~/.config/opencode/tt-plugin-config.json`:
+
+```json
+{
+  "enabledCommands": [
+    "tmux",
+    "tmux-oc"
+  ],
+  "defaultTerminal": "alacritty",
+  "sessionPrefix": "dev"
+}
+```
+
+---
+
+## Examples
+
+### Example 1: User Only Wants Two Commands
+
+**Scenario:** User only uses `/tmux` and `/tmux-oc`, doesn't want `/tmux-claude` or `/tmux-copilot`
+
+**Configuration:**
+
+```json
+{
+  "enabledCommands": ["tmux", "tmux-oc"],
+  "defaultTerminal": "auto",
+  "sessionPrefix": "oc"
+}
+```
+
+**Result:** Running `/tmux-claude` would be ignored (no error, just silently skipped)
+
+---
+
+### Example 2: NPM Package Installation
+
+**Step 1:** Publish package
+
+```bash
+npm login
+npm version minor
+npm publish
+```
+
+**Step 2:** User adds to config
+
+```bash
+# User updates ~/.config/opencode/opencode.json
+```
+
+```json
+{
+  "plugin": ["tt-plugin"],
+  "command": {
+    "tt-configure": {
+      "template": "Help me configure the tt-plugin settings"
+    }
+  }
+}
+```
+
+**Step 3:** OpenCode installs automatically
+
+```
+At startup, OpenCode runs:
+  bun install --cwd ~/.cache/opencode
+  
+Plugin loads from:
+  ~/.cache/opencode/node_modules/tt-plugin/src/index.ts
+```
+
+---
+
+### Example 3: Scoped Organization Package
+
+If publishing as organization package:
+
+**Update package.json:**
+
+```json
+{
+  "name": "@myorg/tt-plugin",
+  "version": "1.0.0"
+}
+```
+
+**Publish:**
+
+```bash
+npm publish --access public  # Scoped packages require explicit public access
+```
+
+**User config:**
+
+```json
+{
+  "plugin": ["@myorg/tt-plugin"]
+}
+```
+
+---
+
+## Summary: Local → Web Distribution Path
+
+| Phase | Method | Installation | Version Mgmt | Discoverability |
+|-------|--------|--------------|--------------|-----------------|
+| **Development** | Local directory | `git clone` + `npm run install` | Manual | Private |
+| **Testing** | npm (pre-release) | `npm install --save-dev` | Semantic | npm only |
+| **Production** | npm Registry | Config file entry | Automatic | npm registry + ecosystem |
+| **Enterprise** | GitHub Packages | Config file entry | Automatic | Private registry |
+
+---
+
+## Configuration Best Practices
+
+### For Plugin Developers
+
+1. **Provide sensible defaults** - Don't break if config file is missing
+2. **Document configuration** - Include examples in README
+3. **Version config schema** - If changing config format, handle migrations
+4. **Validate configuration** - Check for invalid values at startup
+5. **Log configuration** - Help users debug with clear logs
+
+### For Users
+
+1. **Keep it simple** - Only configure what's necessary
+2. **Follow JSON syntax** - Use JSON validators
+3. **Backup config** - Version control your config file
+4. **Update regularly** - Check for new configuration options
+
+---
+
+## Related Resources
+
+- [OpenCode Plugins Documentation](https://opencode.ai/docs/plugins)
+- [OpenCode Commands Documentation](https://opencode.ai/docs/commands)
+- [npm Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
+- [OpenCode Ecosystem](https://opencode.ai/docs/ecosystem)
+- [semantic-release](https://github.com/semantic-release/semantic-release) - Automated versioning