plugin-gentleman 1.0.0

package/README.md

@@ -0,0 +1,315 @@
+# plugin-gentleman
+
+OpenCode TUI plugin featuring **Mustachi** — an animated ASCII mascot with eyes, mustache, and optional motivational phrases during busy states.
+
+## What This Is
+
+A TUI plugin for OpenCode that:
+- 🎭 Shows **Mustachi** (ASCII mascot) in your home logo
+- 👀 Subtle **eye animations** (optional, low-frequency)
+- 💬 **Motivational phrases** during busy/loading states (Rioplatense Spanish style)
+- 🎨 Installs and applies the **Gentleman theme** automatically
+- 🖥️ Detects and displays your **OS and LLM providers**
+- ⚙️ Fully **configurable** via `opencode.json`
+
+## Installation
+
+### Method 1: Local Testing with Tarball (Recommended First)
+
+```bash
+npm pack
+npm install -g ./plugin-gentleman-1.0.0.tgz
+```
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["plugin-gentleman"]
+}
+```
+
+Restart OpenCode:
+
+```bash
+opencode
+```
+
+### Method 2: Development with npm link
+
+```bash
+npm link
+```
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["plugin-gentleman"]
+}
+```
+
+Restart OpenCode.
+
+### Method 3: npm Registry (After Publishing)
+
+```bash
+npm install -g plugin-gentleman
+opencode plugin install plugin-gentleman
+```
+
+## Features
+
+### Mustachi Mascot
+
+Mustachi is an ASCII character with:
+- Two large eyes that occasionally look in different directions
+- A prominent mustache rendered in theme colors
+- A tongue that appears during busy/loading states
+- Motivational phrases in Rioplatense Spanish style
+
+Example phrases shown during busy states:
+- "Ponete las pilas, hermano..."
+- "Dale que va, dale que va..."
+- "Ya casi, ya casi..."
+- "Ahí vamos, loco..."
+- "Un toque más y listo..."
+- "Aguantá que estoy pensando..."
+
+### Animation Behavior
+
+**Low complexity, low frequency** — designed to be subtle and non-intrusive:
+
+1. **Eye Direction Animation** (when `animations: true`)
+   - Every ~4 seconds, Mustachi's eyes may look in a random direction
+   - 20% chance of eye movement per interval
+   - Returns to neutral position most of the time
+
+2. **Busy State Animation** (when `animations: true`)
+   - Tongue appears when OpenCode is processing
+   - Motivational phrase rotates every 3 seconds
+   - Only active during detected busy states
+
+3. **No Animation** (when `animations: false`)
+   - Mustachi stays in neutral position
+   - No eye movement
+   - No tongue or phrases during busy states
+
+### Theme
+
+The plugin bundles the **Gentleman theme** with a refined dark color palette:
+- Background: Deep navy (`#06080f`)
+- Primary: Soft blue (`#7FB4CA`)
+- Accent: Warm gold (`#E0C15A`)
+- Text: Clean white (`#F3F6F9`)
+
+Mustachi uses a 3-tone gradient:
+- **Top**: Accent (gold)
+- **Middle**: Primary (blue)
+- **Bottom**: Error/pink (`#CB7C94`)
+
+### Environment Detection
+
+The plugin shows a "Detected" line with:
+- **OS Detection**: Reads distro name on Linux, shows "macOS" or "Windows" on other platforms
+- **Provider Detection**: Lists active LLM providers (OpenAI, Copilot, Google, etc.)
+
+Both are fully configurable and can be hidden.
+
+## Configuration
+
+All options are set via plugin tuple syntax in `opencode.json`:
+
+### Default Configuration
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "plugin-gentleman",
+      {
+        "enabled": true,
+        "theme": "gentleman",
+        "set_theme": true,
+        "show_detected": true,
+        "show_os": true,
+        "show_providers": true,
+        "animations": true
+      }
+    ]
+  ]
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable/disable the plugin entirely |
+| `theme` | string | `"gentleman"` | Name of the bundled theme to install |
+| `set_theme` | boolean | `true` | Automatically activate the theme on load |
+| `show_detected` | boolean | `true` | Show the "Detected" environment info line |
+| `show_os` | boolean | `true` | Show detected operating system name |
+| `show_providers` | boolean | `true` | Show detected LLM providers |
+| `animations` | boolean | `true` | Enable Mustachi animations (eyes, busy state) |
+
+### Example: Disable Animations
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["plugin-gentleman", { "animations": false }]
+  ]
+}
+```
+
+Mustachi will remain static with neutral eyes and no busy-state expressions.
+
+### Example: Logo Only (No Detection)
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["plugin-gentleman", { "show_detected": false }]
+  ]
+}
+```
+
+Shows only Mustachi and the OpenCode branding, no OS/provider info.
+
+### Example: Show Only OS
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "plugin-gentleman",
+      {
+        "show_detected": true,
+        "show_os": true,
+        "show_providers": false
+      }
+    ]
+  ]
+}
+```
+
+## How It Works
+
+1. **Theme Installation**: On load, installs `gentleman.json` into OpenCode themes
+2. **Theme Activation**: If `set_theme: true`, switches to the gentleman theme
+3. **Logo Slot**: Registers `home_logo` slot with Mustachi ASCII art
+4. **Environment Detection Slot**: Registers `home_prompt_after` slot with OS/provider info
+5. **Animation Loop**: If `animations: true`, starts interval timers for eye variations and busy-state detection
+6. **Busy State Detection**: Attempts to read `api.state.session.running` (best-effort; may not be exposed by all OpenCode versions)
+
+### Technical Details
+
+- **No Build Step**: Plain TSX transpiled at runtime by OpenCode
+- **Solid.js Reactivity**: Uses `createSignal` and `createEffect` for animations
+- **Safe Detection**: All OS/provider detection wrapped in try-catch blocks
+- **Cleanup**: Uses `onCleanup` to clear intervals when component unmounts
+
+## Supported Providers
+
+The plugin maps these provider IDs to friendly names:
+
+| Provider ID | Display Name |
+|-------------|--------------|
+| `openai` | OpenAI |
+| `google` | Google |
+| `github-copilot` | Copilot |
+| `opencode-go` | OpenCode GO |
+| `anthropic` | Claude |
+| `deepseek` | DeepSeek |
+| `openrouter` | OpenRouter |
+| `mistral` | Mistral |
+| `groq` | Groq |
+| `cohere` | Cohere |
+| `together` | Together |
+| `perplexity` | Perplexity |
+
+Unknown provider IDs display the configured name or raw ID.
+
+## Local Testing Limitations
+
+**IMPORTANT**: This is a **TUI plugin** for npm installation. 
+
+If you try to use this as a local system plugin (copying `.ts` files to `~/.config/opencode/plugins/`):
+- ❌ **NO visual changes** — system plugins cannot modify the TUI
+- ❌ **NO Mustachi** — only TUI plugins can register slot components
+- ❌ **NO animations** — JSX/Solid.js components only work in TUI plugins
+
+**For full features, use npm installation** (tarball or link method above).
+
+## Repository Structure
+
+```
+oc-plugin-gentleman/
+├── tui.tsx              # TUI plugin entry point (main implementation) ✅ npm
+├── gentleman.json       # Gentleman theme definition ✅ npm
+├── package.json         # npm package manifest with exports ✅ npm
+├── README.md            # This file ✅ npm (auto-included)
+├── gentleman-local.ts   # Legacy local system plugin (repo-only, not in npm package)
+├── install-local-real.sh # Install script for local plugin (repo-only)
+├── install-local.sh     # Install script for local plugin (repo-only)
+└── mustachi examples/   # PNG reference images (repo-only)
+```
+
+**Files included in npm package** (via `files` field in package.json):
+- `tui.tsx` — main plugin implementation
+- `gentleman.json` — theme definition
+- `package.json` — auto-included by npm
+- `README.md` — auto-included by npm
+
+**Local-only files** (excluded from npm, kept in repo for development/reference):
+- `gentleman-local.ts` — legacy local system plugin with limited features
+- `install-local-real.sh`, `install-local.sh` — local installation scripts
+- `mustachi examples/` — reference images
+oc-plugin-gentleman/
+├── tui.tsx              # TUI plugin entry point (main implementation)
+├── gentleman.json       # Gentleman theme definition
+├── package.json         # npm package manifest with exports
+├── gentleman-local.ts   # Legacy local system plugin (limited features)
+├── install-local-real.sh # Install script for local system plugin
+├── mustachi examples/   # PNG reference images (not used in final plugin)
+└── README.md            # This file
+```
+
+## Caveats Before Publishing
+
+1. **Busy State Detection**: The plugin attempts to detect busy states via `api.state.session.running`, but this may not be exposed in all OpenCode versions. If unavailable, busy-state animations won't trigger (eye animations still work).
+
+2. **Animation Frequency**: Currently set to low frequency (4s for eyes, 3s for phrase rotation). If this feels too fast or too slow in real usage, adjust the intervals in `tui.tsx`.
+
+3. **Sidebar Support**: OpenCode TUI may or may not support sidebar slots. Currently, Mustachi only appears in the `home_logo` slot. If sidebar slots become available, this can be added in a future version.
+
+4. **Theme Compatibility**: The plugin installs and optionally activates the Gentleman theme. If the user has a custom theme they prefer, they should set `set_theme: false`.
+
+## Development
+
+To modify the plugin:
+
+1. Edit `tui.tsx` (main implementation)
+2. Test locally with `npm link` or `npm pack`
+3. No build step needed — OpenCode transpiles TSX at runtime
+4. Restart OpenCode to see changes
+
+To add new eye variations:
+- Edit the `eyeVariations` array in `tui.tsx`
+
+To add new busy phrases:
+- Edit the `busyPhrases` array in `tui.tsx`
+
+To change animation timings:
+- Adjust `setInterval` durations in the `Home` component
+
+## License
+
+ISC

package/gentleman.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://opencode.ai/theme.json",
+  "theme": {
+    "background": "none",
+    "backgroundPanel": "#06080f",
+    "backgroundElement": "#06080f",
+    "text": "#F3F6F9",
+    "textMuted": "#5C6170",
+    "primary": "#7FB4CA",
+    "secondary": "#A3B5D6",
+    "accent": "#E0C15A",
+    "error": "#CB7C94",
+    "warning": "#DEBA87",
+    "success": "#B7CC85",
+    "info": "#7FB4CA",
+    "border": "#313342",
+    "borderActive": "#7FB4CA",
+    "borderSubtle": "#232A40",
+    "diffAdded": "#B7CC85",
+    "diffRemoved": "#CB7C94",
+    "diffContext": "#5C6170",
+    "diffHunkHeader": "#8394A3",
+    "diffHighlightAdded": "#D1E8A9",
+    "diffHighlightRemoved": "#DE8FA8",
+    "diffAddedBg": "#1a2e1a",
+    "diffRemovedBg": "#2e1a1a",
+    "diffContextBg": "#0d0f14",
+    "diffLineNumber": "#8394A3",
+    "diffAddedLineNumberBg": "#1a2e1a",
+    "diffRemovedLineNumberBg": "#2e1a1a",
+    "markdownText": "#F3F6F9",
+    "markdownHeading": "#B5B2D0",
+    "markdownLink": "#7FB4CA",
+    "markdownLinkText": "#79B8EA",
+    "markdownCode": "#B7CC85",
+    "markdownBlockQuote": "#DEBA87",
+    "markdownEmph": "#7CB9DD",
+    "markdownStrong": "#DEBA87",
+    "markdownHorizontalRule": "#5C6170",
+    "markdownListItem": "#7FB4CA",
+    "markdownListEnumeration": "#A3B5D6",
+    "markdownImage": "#7FB4CA",
+    "markdownImageText": "#79B8EA",
+    "markdownCodeBlock": "#F3F6F9",
+    "syntaxComment": "#8394A3",
+    "syntaxKeyword": "#C99AD6",
+    "syntaxFunction": "#B99BF2",
+    "syntaxVariable": "#F3F6F9",
+    "syntaxString": "#DFBD76",
+    "syntaxNumber": "#A4DAA7",
+    "syntaxType": "#8FB8DD",
+    "syntaxOperator": "#DEBA87",
+    "syntaxPunctuation": "#96A2B0"
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "plugin-gentleman",
+  "version": "1.0.0",
+  "description": "OpenCode TUI plugin featuring Mustachi - an animated ASCII mascot with eyes, mustache, and optional motivational phrases during busy states",
+  "type": "module",
+  "exports": {
+    "./tui": {
+      "import": "./tui.tsx",
+      "config": {
+        "enabled": true,
+        "theme": "gentleman",
+        "set_theme": true,
+        "show_detected": true,
+        "show_os": true,
+        "show_providers": true,
+        "animations": true
+      }
+    }
+  },
+  "files": [
+    "tui.tsx",
+    "gentleman.json"
+  ],
+  "engines": {
+    "opencode": ">=1.3.13"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*",
+    "@opentui/core": "*",
+    "@opentui/solid": "*",
+    "solid-js": "*"
+  },
+  "keywords": ["opencode", "plugin", "theme", "gentleman", "tui", "ascii", "mustachi"],
+  "author": "",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IrrealV/plugin-gentleman.git"
+  },
+  "homepage": "https://github.com/IrrealV/plugin-gentleman#readme",
+  "bugs": {
+    "url": "https://github.com/IrrealV/plugin-gentleman/issues"
+  }
+}

package/tui.tsx

@@ -0,0 +1,305 @@
+// @ts-nocheck
+/** @jsxImportSource @opentui/solid */
+import { readFileSync } from "node:fs"
+import type { TuiPlugin, TuiPluginModule, TuiThemeCurrent } from "@opencode-ai/plugin/tui"
+import { createSignal, onCleanup, createEffect } from "solid-js"
+
+const id = "gentleman"
+
+// Mustachi ASCII art - inspired by mustachi examples (eyes, mustache, optional tongue)
+// Base state: neutral look
+const mustachiBase = [
+  "",
+  "    ╭─────╮       ╭─────╮    ",
+  "   │ ● ● │       │ ○ ○ │    ",
+  "    ╰─────╯       ╰─────╯    ",
+  "       ╲           ╱         ",
+  "        ╲         ╱          ",
+  "   ╭─────═════════─────╮     ",
+  "  ╱   ╭───────────╮   ╲      ",
+  " ╱    │ ~~~~~~~~~ │    ╲     ",
+  "╱     ╰───────────╯     ╲    ",
+  "╲                       ╱    ",
+  " ╲                     ╱     ",
+  "  ╰───────────────────╯      ",
+  "",
+]
+
+// Eye variations for subtle animation
+const eyeVariations = [
+  { left: "● ●", right: "○ ○" },  // neutral
+  { left: "◐ ●", right: "○ ○" },  // left eye looking left
+  { left: "● ◑", right: "○ ○" },  // left eye looking right
+  { left: "● ●", right: "◐ ○" },  // right eye looking left
+  { left: "● ●", right: "○ ◑" },  // right eye looking right
+]
+
+// Busy/loading state with tongue and motivational phrases
+const busyPhrases = [
+  "Ponete las pilas, hermano...",
+  "Dale que va, dale que va...",
+  "Ya casi, ya casi...",
+  "Ahí vamos, loco...",
+  "Un toque más y listo...",
+  "Aguantá que estoy pensando...",
+  "Momento, momento...",
+  "Ya te lo traigo, tranqui...",
+]
+
+type Cfg = {
+  enabled: boolean
+  theme: string
+  set_theme: boolean
+  show_detected: boolean
+  show_os: boolean
+  show_providers: boolean
+  animations: boolean
+}
+
+type Api = Parameters<TuiPlugin>[0]
+
+const rec = (value: unknown) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return
+  return Object.fromEntries(Object.entries(value))
+}
+
+const pick = (value: unknown, fallback: string) => {
+  if (typeof value !== "string") return fallback
+  if (!value.trim()) return fallback
+  return value
+}
+
+const bool = (value: unknown, fallback: boolean) => {
+  if (typeof value !== "boolean") return fallback
+  return value
+}
+
+const cfg = (opts: Record<string, unknown> | undefined): Cfg => {
+  return {
+    enabled: bool(opts?.enabled, true),
+    theme: pick(opts?.theme, "gentleman"),
+    set_theme: bool(opts?.set_theme, true),
+    show_detected: bool(opts?.show_detected, true),
+    show_os: bool(opts?.show_os, true),
+    show_providers: bool(opts?.show_providers, true),
+    animations: bool(opts?.animations, true),
+  }
+}
+
+// Helper to detect OS name
+const getOSName = (): string => {
+  try {
+    const platform = typeof process !== "undefined" ? process.platform : "unknown"
+    switch (platform) {
+      case "linux":
+        try {
+          const osRelease = readFileSync("/etc/os-release", "utf8")
+          const match = osRelease.match(/^NAME="?([^"\n]+)"?/m)
+          if (match) return match[1]
+        } catch {
+        }
+        return "Linux"
+      case "darwin":
+        return "macOS"
+      case "win32":
+        return "Windows"
+      default:
+        return platform
+    }
+  } catch {
+    return "Unknown"
+  }
+}
+
+// Map provider IDs to friendly display names
+const providerDisplayNames: Record<string, string> = {
+  "openai": "OpenAI",
+  "google": "Google",
+  "github-copilot": "Copilot",
+  "opencode-go": "OpenCode GO",
+  "anthropic": "Claude",
+  "deepseek": "DeepSeek",
+  "openrouter": "OpenRouter",
+  "mistral": "Mistral",
+  "groq": "Groq",
+  "cohere": "Cohere",
+  "together": "Together",
+  "perplexity": "Perplexity",
+}
+
+// Helper to detect active providers from OpenCode state
+const getProviders = (providers: ReadonlyArray<{ id: string; name: string }> | undefined): string => {
+  if (!providers || providers.length === 0) {
+    return "No providers configured"
+  }
+  
+  // Map provider IDs to friendly names and deduplicate
+  const names = new Set<string>()
+  for (const provider of providers) {
+    const displayName = providerDisplayNames[provider.id] || provider.name || provider.id
+    names.add(displayName)
+  }
+  
+  // Return compact comma-separated list
+  return Array.from(names).sort().join(", ")
+}
+
+const Home = (props: { theme: TuiThemeCurrent; config: Cfg; isBusy?: boolean }) => {
+  const [eyeIndex, setEyeIndex] = createSignal(0)
+  const [showTongue, setShowTongue] = createSignal(false)
+  const [busyPhrase, setBusyPhrase] = createSignal("")
+  
+  // Animation: subtle eye variation every 3-5 seconds
+  createEffect(() => {
+    if (!props.config.animations) return
+    
+    const interval = setInterval(() => {
+      // Randomly change eyes occasionally (20% chance)
+      if (Math.random() < 0.2) {
+        setEyeIndex((Math.floor(Math.random() * eyeVariations.length)))
+      } else {
+        setEyeIndex(0) // back to neutral
+      }
+    }, 4000) // check every 4 seconds
+    
+    onCleanup(() => clearInterval(interval))
+  })
+  
+  // Busy state animation: show tongue + rotate phrases
+  createEffect(() => {
+    if (!props.config.animations || !props.isBusy) {
+      setShowTongue(false)
+      setBusyPhrase("")
+      return
+    }
+    
+    setShowTongue(true)
+    
+    let phraseIdx = 0
+    setBusyPhrase(busyPhrases[phraseIdx])
+    
+    const interval = setInterval(() => {
+      phraseIdx = (phraseIdx + 1) % busyPhrases.length
+      setBusyPhrase(busyPhrases[phraseIdx])
+    }, 3000) // rotate every 3 seconds
+    
+    onCleanup(() => clearInterval(interval))
+  })
+  
+  // Build Mustachi with current eye state
+  const currentEyes = eyeVariations[eyeIndex()]
+  const mustachi = mustachiBase.map((line, idx) => {
+    // Replace eyes in line 2
+    if (idx === 2) {
+      return `   │ ${currentEyes.left} │       │ ${currentEyes.right} │    `
+    }
+    return line
+  })
+  
+  // Add tongue if busy
+  if (showTongue()) {
+    mustachi.push("         ╲ ● ╱              ")
+    mustachi.push("           v                ")
+  }
+  
+  const topColor = props.theme.accent || "#E0C15A"
+  const midColor = props.theme.primary || "#7FB4CA"
+  const bottomColor = props.theme.error || "#CB7C94"
+  
+  return (
+    <box flexDirection="column" alignItems="center">
+      {/* Mustachi with 3-tone gradient */}
+      {mustachi.map((line, idx) => {
+        const totalLines = mustachi.length
+        let color = midColor
+        if (idx < totalLines / 3) {
+          color = topColor
+        } else if (idx >= (2 * totalLines) / 3) {
+          color = bottomColor
+        }
+        return <text fg={color}>{line}</text>
+      })}
+      
+      {/* OpenCode branding */}
+      <box flexDirection="row" gap={0}>
+        <text fg={props.theme.textMuted} dimColor={true}>╭</text>
+        <text fg={props.theme.primary} dimColor={false}> OpenCode </text>
+        <text fg={props.theme.textMuted} dimColor={true}>╮</text>
+      </box>
+      
+      {/* Busy phrase if loading */}
+      {busyPhrase() && (
+        <text fg={props.theme.warning}>{busyPhrase()}</text>
+      )}
+      
+      <text> </text>
+    </box>
+  )
+}
+
+const DetectedEnv = (props: { 
+  theme: TuiThemeCurrent
+  providers: ReadonlyArray<{ id: string; name: string }> | undefined
+  config: Cfg
+}) => {
+  if (!props.config.show_detected) return null
+  
+  const os = props.config.show_os ? getOSName() : null
+  const providers = props.config.show_providers ? getProviders(props.providers) : null
+  
+  // Don't render if nothing to show
+  if (!os && !providers) return null
+  
+  return (
+    <box flexDirection="row" gap={1}>
+      <text fg={props.theme.textMuted}>Detected:</text>
+      {os && <text fg={props.theme.text}>{os}</text>}
+      {os && providers && <text fg={props.theme.textMuted}>•</text>}
+      {providers && <text fg={props.theme.text}>{providers}</text>}
+    </box>
+  )
+}
+
+const tui: TuiPlugin = async (api, options) => {
+  const boot = cfg(rec(options))
+  if (!boot.enabled) return
+
+  const [value] = createSignal(boot)
+  const [isBusy, setIsBusy] = createSignal(false)
+
+  await api.theme.install("./gentleman.json")
+  if (value().set_theme) {
+    api.theme.set(value().theme)
+  }
+
+  // Detect busy state if API exposes it
+  // This is a best-effort detection - OpenCode TUI may or may not expose this
+  createEffect(() => {
+    try {
+      // Check if there's a running agent or session state
+      const hasRunningSession = api.state?.session?.running
+      setIsBusy(!!hasRunningSession)
+    } catch {
+      // If API doesn't expose this, animations will just use idle state
+      setIsBusy(false)
+    }
+  })
+
+  api.slots.register({
+    slots: {
+      home_logo(ctx) {
+        return <Home theme={ctx.theme.current} config={value()} isBusy={isBusy()} />
+      },
+      home_prompt_after(ctx) {
+        return <DetectedEnv theme={ctx.theme.current} providers={api.state.provider} config={value()} />
+      },
+    },
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = {
+  id,
+  tui,
+}
+
+export default plugin