opencode-gemiterm-skills 0.5.0

package/assets/skills/gemiterm/REFERENCE.md

@@ -0,0 +1,392 @@
+# GemiTerm CLI Reference
+
+Complete command reference for GemiTerm CLI. Loaded on demand by [SKILL.md](SKILL.md).
+
+## Contents
+
+- [Commands](#commands)
+  - [`gemiterm auth`](#gemiterm-auth)
+  - [`gemiterm list`](#gemiterm-list)
+  - [`gemiterm fetch <chat_id>`](#gemiterm-fetch-chat_id)
+  - [`gemiterm export <chat_id>`](#gemiterm-export-chat_id)
+  - [`gemiterm export-all`](#gemiterm-export-all)
+  - [`gemiterm delete <chat_id>`](#gemiterm-delete-chat_id)
+  - [`gemiterm status`](#gemiterm-status)
+  - [`gemiterm profile`](#gemiterm-profile)
+  - [`gemiterm continue <chat_id>`](#gemiterm-continue-chat_id)
+  - [`gemiterm install-browser`](#gemiterm-install-browser)
+- [Global Flags](#global-flags)
+- [Exit Codes](#exit-codes)
+- [Environment Variables](#environment-variables)
+- [Config File](#config-file)
+- [Rate Limits](#rate-limits)
+
+---
+
+## Commands
+
+### `gemiterm auth`
+
+Authenticate with Google Gemini API.
+
+**Usage:**
+```bash
+gemiterm auth
+```
+
+**Notes:**
+- Interactive command requiring browser
+- Opens OAuth flow in default browser
+- Must be run once per profile
+- Not automation-friendly
+
+**Flags:** None
+
+---
+
+### `gemiterm list`
+
+List all chats.
+
+**Usage:**
+```bash
+gemiterm list [options]
+```
+
+**Flags:**
+- `--format json|text` - Output format (default: text)
+- `--limit N` - Maximum number of chats to return
+- `--reverse` - Reverse sort order
+- `--all-profiles` - List chats across all configured profiles
+- `--sort recent|oldest|alpha` - Sort order (default: recent)
+
+**Examples:**
+```bash
+gemiterm list
+gemiterm list --format json
+gemiterm list --format json --limit 10
+gemiterm list --format json --limit 5 --reverse
+gemiterm list --all-profiles --limit 10 --format json
+gemiterm list --sort oldest --format json
+gemiterm list --all-profiles --sort alpha --format json
+```
+
+**Output (JSON):**
+```json
+[
+  {
+    "id": "abc123def456",
+    "title": "Python debugging help",
+    "created_at": "2025-05-15T10:30:00Z",
+    "updated_at": "2025-05-15T11:45:00Z",
+    "message_count": 42
+  }
+]
+```
+
+---
+
+### `gemiterm fetch <chat_id>`
+
+Fetch transcript for a specific chat.
+
+**Usage:**
+```bash
+gemiterm fetch <chat_id> [options]
+```
+
+**Arguments:**
+- `chat_id` - The Gemini chat_id (required)
+
+**Flags:**
+- `--format json|text` - Output format (default: text)
+
+**Examples:**
+```bash
+gemiterm fetch abc123def456
+gemiterm fetch abc123def456 --format json
+```
+
+**Output (JSON):**
+```json
+{
+  "id": "abc123def456",
+  "title": "Python debugging help",
+  "created_at": "2025-05-15T10:30:00Z",
+  "updated_at": "2025-05-15T11:45:00Z",
+  "messages": [
+    {
+      "role": "user",
+      "content": "How do I debug this?",
+      "timestamp": "2025-05-15T10:30:00Z"
+    },
+    {
+      "role": "model",
+      "content": "Let me help you...",
+      "timestamp": "2025-05-15T10:30:05Z"
+    }
+  ]
+}
+```
+
+---
+
+### `gemiterm export <chat_id>`
+
+Export a chat to a file.
+
+**Usage:**
+```bash
+gemiterm export <chat_id> --output <path>
+```
+
+**Arguments:**
+- `chat_id` - The Gemini chat_id (required)
+
+**Flags:**
+- `--output <path>` - Output file path (required)
+- `--format md|txt` - Export format (default: md)
+
+**Examples:**
+```bash
+gemiterm export abc123def456 --output /tmp/chat.md
+gemiterm export abc123def456 --output /tmp/chat.txt --format txt
+```
+
+**Output Format (Markdown):**
+```markdown
+# Python debugging help
+
+## User (2025-05-15 10:30)
+How do I debug this?
+
+## Model (2025-05-15 10:30)
+Let me help you...
+```
+
+---
+
+### `gemiterm export-all`
+
+Export all chats to a directory.
+
+**Usage:**
+```bash
+gemiterm export-all --output <directory>
+```
+
+**Flags:**
+- `--output <directory>` - Output directory path (required)
+- `--format md|txt` - Export format (default: md)
+- `--parallel N` - Number of parallel exports (default: 4)
+
+**Examples:**
+```bash
+gemiterm export-all --output /tmp/gemini/
+gemiterm export-all --output /tmp/chats/ --format txt
+gemiterm export-all --output /tmp/backup/ --parallel 2
+```
+
+**Output Structure:**
+```
+/tmp/gemini/
+├── chat_abc123.md
+├── chat_def456.md
+└── chat_ghi789.md
+```
+
+---
+
+### `gemiterm delete <chat_id>`
+
+Delete a chat.
+
+**Usage:**
+```bash
+gemiterm delete <chat_id>
+```
+
+**Arguments:**
+- `chat_id` - The Gemini chat_id (required)
+
+**Flags:**
+- `--confirm` - Skip confirmation prompt
+
+**Examples:**
+```bash
+gemiterm delete abc123def456
+gemiterm delete abc123def456 --confirm
+```
+
+**Warning:** This operation is irreversible.
+
+---
+
+### `gemiterm status`
+
+Check authentication status and profile information.
+
+**Usage:**
+```bash
+gemiterm status
+```
+
+**Flags:**
+- `--format json|text` - Output format (default: text)
+
+**Examples:**
+```bash
+gemiterm status
+gemiterm status --format json
+```
+
+**Output (Text):**
+```
+Authenticated: Yes
+Profile: default
+Email: user@gmail.com
+Token expires: 2025-06-15T10:30:00Z
+```
+
+**Output (JSON):**
+```json
+{
+  "authenticated": true,
+  "profile": "default",
+  "email": "user@gmail.com",
+  "token_expires": "2025-06-15T10:30:00Z"
+}
+```
+
+---
+
+### `gemiterm profile`
+
+Manage Gemini profiles.
+
+**Usage:**
+```bash
+gemiterm profile [options]
+```
+
+**Flags:**
+- `--set <name>` - Switch to profile
+- `--list` - List all profiles
+- `--create <name>` - Create new profile
+- `--delete <name>` - Delete profile
+
+**Examples:**
+```bash
+gemiterm profile --list
+gemiterm profile --set work
+gemiterm profile --create personal
+gemiterm profile --delete old-profile
+```
+
+---
+
+### `gemiterm continue <chat_id>`
+
+Continue a chat (interactive mode).
+
+**Usage:**
+```bash
+gemiterm continue <chat_id>
+```
+
+**Arguments:**
+- `chat_id` - The Gemini chat_id (required)
+
+**Notes:**
+- Interactive command not suitable for automation
+- Opens REPL for continued chat
+- Requires manual input
+
+---
+
+### `gemiterm install-browser`
+
+Install browser for authentication.
+
+**Usage:**
+```bash
+gemiterm install-browser
+```
+
+**Flags:**
+- `--browser chrome|firefox|edge` - Browser to install (default: chrome)
+
+**Notes:**
+- Run once during setup
+- Installs Playwright browser
+- Required for `gemiterm auth`
+
+---
+
+## Global Flags
+
+These flags work with all commands:
+
+- `--config <path>` - Custom config file path
+- `--profile <name>` - Use specific profile
+- `--verbose` - Enable verbose output
+- `--quiet` - Suppress non-error output
+- `--help` - Show help message
+- `--version` - Show version info
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Authentication required |
+| 3 | Chat not found |
+| 4 | Invalid arguments |
+| 5 | Rate limit exceeded |
+| 6 | Network error |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GEMITERM_CONFIG` | Config file path | `~/.config/gemiterm/config.json` |
+| `GEMITERM_DATA_DIR` | Data directory | `~/.local/share/gemiterm/` |
+| `GEMITERM_CACHE_DIR` | Cache directory | `~/.cache/gemiterm/` |
+| `GEMITERM_LOG_LEVEL` | Logging level | `INFO` |
+| `BROWSER` | Browser for auth | System default |
+
+## Config File
+
+Location: `~/.config/gemiterm/config.json`
+
+```json
+{
+  "profiles": {
+    "default": {
+      "email": "user@gmail.com",
+      "access_token": "...",
+      "refresh_token": "...",
+      "token_expires": "2025-06-15T10:30:00Z"
+    }
+  },
+  "current_profile": "default",
+  "api_key": "...",
+  "timeout": 60,
+  "max_retries": 3
+}
+```
+
+## Rate Limits
+
+Google Gemini API enforces rate limits on the free tier:
+
+| Limit | Default |
+|-------|---------|
+| Requests per minute | 60 |
+| Requests per day | 1500 |
+| Tokens per request | 2,000,000 |
+
+> Reflects Gemini free-tier defaults at time of writing; verify with the latest Google AI docs.
+
+GemiTerm implements automatic retry with exponential backoff.

package/assets/skills/gemiterm/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: gemiterm
+description: Google Gemini Terminal CLI wrapper for listing chats, fetching transcripts, exporting conversations, and managing profiles via the gemiterm Python CLI. Use when the user asks to read, list, export, or interact with Gemini chat history from a terminal, or invokes "gemiterm" commands.
+license: MIT
+compatibility: opencode
+metadata:
+  tool: gemiterm
+---
+
+# GemiTerm — Google Gemini Terminal CLI
+
+GemiTerm provides terminal access to Google Gemini chat history: list, fetch, export, delete, and manage profiles. Commands that emit `--format json` are automation-friendly; `auth` and `continue` require interactive flows.
+
+## Install check
+
+```bash
+gemiterm --version
+```
+
+If missing:
+
+```bash
+pipx install gemiterm
+gemiterm install-browser
+gemiterm auth
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `gemiterm list [--all-profiles] [--limit N] [--sort recent\|oldest\|alpha] [--format json]` | List chats with metadata |
+| `gemiterm fetch <chat_id> [--format json]` | Fetch full transcript for one chat |
+| `gemiterm export <chat_id> --output <path> [--format md\|txt]` | Export one chat to a file |
+| `gemiterm export-all --output <dir> [--format md\|txt] [--parallel N]` | Bulk export all chats to a directory |
+| `gemiterm delete <chat_id> [--confirm]` | Delete one chat (irreversible) |
+| `gemiterm status [--format json]` | Show auth status and active profile |
+| `gemiterm profile list\|default <name>\|add <name>\|delete <name>\|rename <name> <new_name>` | Manage Gemini profiles |
+| `gemiterm continue <chat_id>` | Resume chat interactively (not automation-friendly) |
+| `gemiterm auth` | Run OAuth flow (interactive, not automation-friendly) |
+| `gemiterm install-browser [--browser chrome\|firefox\|edge]` | Install Playwright browser for auth |
+
+**Interactive commands** (`auth`, `continue`) open a browser or REPL — run manually, never from a script.
+
+## Output formats
+
+| Flag | Effect |
+|------|--------|
+| `--format json` | Machine-readable JSON for automation |
+| `--format text` | Human-readable text (default for most commands) |
+| `--output <path>` | Write export to file (Markdown by default) |
+| `--format md\|txt` | Export format for `export` and `export-all` (default: `md`) |
+
+## Common patterns
+
+**Find a chat by keyword:**
+```bash
+gemiterm list --format json | jq '.[] | select(.title | test("keyword"))'
+```
+
+**Export one chat:**
+```bash
+gemiterm fetch <chat_id> --format json > /tmp/chat.json
+gemiterm export <chat_id> --output /tmp/chat.md
+```
+
+**Bulk analyze:**
+```bash
+gemiterm list --format json | jq -r '.[].id' | xargs -I {} gemiterm fetch {} --format json
+```
+
+**List recent chats across all profiles:**
+```bash
+gemiterm list --all-profiles --limit 10 --format json
+```
+
+## Troubleshooting
+
+- **Auth errors:** run `gemiterm auth` manually to complete the OAuth flow.
+- **Expired tokens:** GemiTerm refreshes automatically; re-run `auth` if it fails.
+- **Rate limits:** space out bulk operations; see [REFERENCE.md](REFERENCE.md) for limits and retry behaviour.
+- **UNAUTHENTICATED warnings:** Profile cookies may need refresh — run `gemiterm auth` to re-authenticate the affected profile.
+
+## References
+
+- [REFERENCE.md](REFERENCE.md) — flags, JSON schemas, env vars, exit codes, rate limits
+- Project: https://github.com/expert-vision-software/gemiterm

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./plugin.ts";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "opencode-gemiterm-skills",
+  "version": "0.5.0",
+  "type": "module",
+  "module": "index.ts",
+  "description": "OpenCode plugin bundling the gemiterm and debate-with-gemini skills.",
+  "license": "MIT",
+  "publisher": "Expert Vision Software",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-skills",
+    "gemiterm",
+    "gemini",
+    "debate"
+  ],
+  "bin": {
+    "opencode-gemiterm-skills": "./src/cli.ts"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "sideEffects": false,
+  "files": [
+    "index.ts",
+    "plugin.ts",
+    "src",
+    "assets",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run check && bun test"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.16.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Expert-Vision-Software/opencode-gemiterm-skills.git"
+  },
+  "homepage": "https://github.com/Expert-Vision-Software/opencode-gemiterm-skills#readme",
+  "bugs": {
+    "url": "https://github.com/Expert-Vision-Software/opencode-gemiterm-skills/issues",
+    "email": "support@expertvisionsoftware.com"
+  },
+  "author": "Expert Vision Software",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.ts

@@ -0,0 +1,33 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { install, getPackageVersion, getGlobalConfigPath } from "./src/installer.ts";
+import { join } from "node:path";
+
+const plugin: Plugin = async ({ directory }) => ({
+  config: async () => {
+    const version = await getPackageVersion();
+    const globalConfigPath = getGlobalConfigPath();
+
+    const isGlobal =
+      directory === globalConfigPath || directory.startsWith(globalConfigPath + "/") ||
+      directory.startsWith(globalConfigPath + "\\");
+
+    const scope = isGlobal ? "global" : "local";
+    const versionMarker = join(
+      isGlobal ? globalConfigPath : directory,
+      "skills",
+      "gemiterm",
+      ".version",
+    );
+
+    try {
+      const installed = (await Bun.file(versionMarker).text()).trim();
+      if (installed === version) return;
+    } catch {
+      // Not installed, proceed
+    }
+
+    await install(scope, directory);
+  },
+});
+
+export default plugin;

package/src/cli.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { installCommand } from "./commands/install.ts";
+import { uninstallCommand } from "./commands/uninstall.ts";
+import { statusCommand } from "./commands/status.ts";
+import type { Scope } from "./installer.ts";
+
+const VERSION = JSON.parse(
+  await Bun.file(join(fileURLToPath(new URL("../", import.meta.url)), "package.json")).text(),
+).version;
+
+function printHelp(): void {
+  console.log(`
+opencode-gemiterm-skills v${VERSION}
+
+Commands:
+  install     Copy skills to .opencode/skills/ and register in opencode.json
+  uninstall   Remove installed skills from .opencode/skills/
+  status      Check installation status
+
+Options:
+  -s, --scope <scope>    Installation scope: "local" (default) or "global"
+  -h, --help             Show this help message
+  -v, --version          Show version
+
+Examples:
+  bunx opencode-gemiterm-skills install
+  bunx opencode-gemiterm-skills install --scope global
+  bunx opencode-gemiterm-skills uninstall --scope local
+  bunx opencode-gemiterm-skills status
+`);
+}
+
+async function main(): Promise<void> {
+  const { positionals, values } = parseArgs({
+    options: {
+      scope: { type: "string", short: "s" },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+
+  if (values.version) {
+    console.log(`opencode-gemiterm-skills v${VERSION}`);
+    process.exit(0);
+  }
+
+  if (values.help || positionals.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const command = positionals[0];
+  const scope: Scope | undefined = values.scope as Scope | undefined;
+
+  if (scope && scope !== "local" && scope !== "global") {
+    console.error(`Invalid scope: ${scope}. Must be "local" or "global".`);
+    process.exit(1);
+  }
+
+  try {
+    switch (command) {
+      case "install":
+        await installCommand({ scope });
+        break;
+      case "uninstall":
+        await uninstallCommand({ scope });
+        break;
+      case "status":
+        await statusCommand();
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        process.exit(1);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/commands/install.ts

@@ -0,0 +1,21 @@
+import { install, type Scope } from "../installer.ts";
+
+interface InstallOptions {
+  scope?: Scope;
+  force?: boolean;
+}
+
+export async function installCommand(options: InstallOptions = {}): Promise<void> {
+  const scope = options.scope ?? "local";
+  const result = await install(scope);
+
+  console.log(
+    `opencode-gemiterm-skills installed ${scope === "global" ? "globally" : "locally"}:`,
+  );
+  for (const p of result.skillPaths) {
+    console.log(`  ${p}`);
+  }
+  if (result.migrated) {
+    console.log("  Migrated: opencode.json → .opencode/opencode.json");
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,15 @@
+import { status } from "../installer.ts";
+
+export async function statusCommand(): Promise<void> {
+  const result = await status();
+
+  if (!result.installed) {
+    console.log("opencode-gemiterm-skills is not installed.");
+    return;
+  }
+
+  console.log(`opencode-gemiterm-skills [${result.scope}]`);
+  console.log(`  Installed: yes`);
+  if (result.version) console.log(`  Version: ${result.version}`);
+  console.log(`  Plugin in config: ${result.pluginInConfig ? "yes" : "no"}`);
+}