opencode-plugin-auto-update 0.1.1

package/README.md

@@ -0,0 +1,127 @@
+# Opencode Plugin Auto-Update
+
+[![npm version](https://img.shields.io/npm/v/opencode-plugin-auto-update.svg)](https://www.npmjs.com/package/opencode-plugin-auto-update)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Automatically updates OpenCode plugins in the background on startup. No prompts, no blocking IO, and minimal logging by default.
+
+## 🚀 Overview
+
+- Runs a background update pass on startup
+- Throttled to once every 24 hours
+- Uses a lock file to prevent concurrent runs
+- Updates to latest by default (optional pin-preserving mode)
+
+## ✨ Features
+
+- Zero startup delay (async, detached update)
+- Bun-first installs with npm fallback
+- Silent by default; debug logging via env
+- Skips local/path/git plugins
+
+## 📦 Installation
+
+### 🤖 Let an LLM do it (Recommended)
+
+Paste this into any LLM agent (OpenCode, Claude Code, Cursor, etc.):
+
+```text
+Install the opencode-plugin-auto-update plugin by following: https://raw.githubusercontent.com/AnganSamadder/opencode-plugin-auto-update/main/README.md
+```
+
+<details>
+<summary><b>Instructions for LLM Agents</b></summary>
+
+To install this plugin, please perform the following steps for the user:
+
+1. **Install the NPM package globally:**
+   ```bash
+   bun add -g opencode-plugin-auto-update
+   # or
+   npm install -g opencode-plugin-auto-update
+   ```
+
+2. **Configure OpenCode:**
+   Add `"opencode-plugin-auto-update"` to the `plugin` array in the user's config file (usually `~/.config/opencode/opencode.json`).
+
+   ```json
+    {
+      "plugin": [
+        "opencode-plugin-auto-update"
+      ]
+    }
+   ```
+
+3. **Verify & Finalize:**
+   Tell the user: **"Installation complete! Your OpenCode plugins will now update automatically in the background."**
+
+</details>
+
+### 👤 For Humans (Manual)
+
+1. **Install:**
+   ```bash
+   bun add -g opencode-plugin-auto-update
+   # or
+   npm install -g opencode-plugin-auto-update
+   ```
+
+2. **Enable the plugin:**
+   Add `"opencode-plugin-auto-update"` to `~/.config/opencode/opencode.json`:
+   ```json
+    {
+      "plugin": [
+        "opencode-plugin-auto-update"
+      ]
+    }
+   ```
+
+3. **Restart OpenCode:**
+   The plugin runs on the next OpenCode startup.
+
+## 🛠️ How it works
+
+1. On startup, schedules a background update task.
+2. Applies a 24h throttle and lock to avoid repeated updates.
+3. Installs latest versions into `~/.config/opencode/node_modules`.
+4. Rewrites `opencode.json` plugin versions to the latest (unless pinned).
+
+## ⚙️ Configuration
+
+Configure via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCODE_AUTO_UPDATE_DISABLED` | `false` | Disable all updates when `true` |
+| `OPENCODE_AUTO_UPDATE_INTERVAL_HOURS` | `24` | Throttle interval in hours |
+| `OPENCODE_AUTO_UPDATE_DEBUG` | `false` | Enable debug logs |
+| `OPENCODE_AUTO_UPDATE_PINNED` | `false` | Preserve pinned versions |
+| `OPENCODE_AUTO_UPDATE_BYPASS_THROTTLE` | `false` | Ignore throttle (useful for testing) |
+
+### CLI Flags
+
+- `opencode --log-level DEBUG`: enable debug mode for OpenCode and trigger verbose update logs with throttle bypass.
+
+## ❓ Troubleshooting
+
+1. **Updates not running**: ensure `OPENCODE_AUTO_UPDATE_DISABLED` is not set to `true`.
+2. **No logs**: run `opencode --log-level DEBUG` or set `OPENCODE_AUTO_UPDATE_DEBUG=true` for verbose output.
+3. **Plugin not loading**: check the `plugin` array in `~/.config/opencode/opencode.json`.
+4. **Testing updates**: run `opencode --log-level DEBUG` to bypass the 24h throttle and see detailed update logs.
+
+## 🚀 Release Process
+
+1. Update version in `package.json`
+2. Update `CHANGELOG.md`
+3. `bun run build`
+4. `npm publish`
+5. `git tag vX.Y.Z && git push --tags`
+6. `gh release create vX.Y.Z --notes "..."`
+
+## 📄 License
+
+MIT
+
+## 🙏 Acknowledgements
+
+Inspired by opencode-agent-tmux and the OpenCode plugin ecosystem.

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+interface PluginInput {
+    directory: string;
+    serverUrl?: URL | string;
+    client: {
+        session: {
+            status(): Promise<{
+                data?: Record<string, {
+                    type: string;
+                }>;
+            }>;
+            subscribe(callback: (event: {
+                type: string;
+                properties?: unknown;
+            }) => void): () => void;
+        };
+    };
+}
+interface PluginOutput {
+    name: string;
+    event?: (input: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+    tool?: Record<string, unknown>;
+    config?: unknown;
+}
+declare function export_default(ctx: PluginInput): Promise<PluginOutput>;
+
+export { export_default as default };

package/dist/index.js

@@ -0,0 +1,386 @@
+// src/update.ts
+import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
+import { dirname, join as join2 } from "path";
+import { homedir as homedir2 } from "os";
+import { spawn } from "child_process";
+
+// src/lock.ts
+import { readFile, writeFile, unlink, mkdir } from "fs/promises";
+import { join } from "path";
+import { homedir, hostname as osHostname } from "os";
+var DEFAULT_CONFIG_DIR = join(homedir(), ".config", "opencode");
+var STALE_LOCK_MS = 2 * 60 * 60 * 1e3;
+function resolvePaths(configDir) {
+  const resolvedConfigDir = configDir ?? DEFAULT_CONFIG_DIR;
+  return {
+    configDir: resolvedConfigDir,
+    lockFile: join(resolvedConfigDir, ".auto-update.lock"),
+    throttleFile: join(resolvedConfigDir, ".auto-update.json")
+  };
+}
+async function isLockStale(lockPath) {
+  try {
+    const content = await readFile(lockPath, "utf-8");
+    const lockData = JSON.parse(content);
+    const age = Date.now() - lockData.timestamp;
+    return age > STALE_LOCK_MS;
+  } catch (error) {
+    return false;
+  }
+}
+async function acquireLock(options = {}) {
+  const { force = false, debug = false, configDir } = options;
+  const { configDir: resolvedConfigDir, lockFile } = resolvePaths(configDir);
+  try {
+    await mkdir(resolvedConfigDir, { recursive: true });
+    try {
+      const existingLock = await readFile(lockFile, "utf-8");
+      const lockData2 = JSON.parse(existingLock);
+      const stale = await isLockStale(lockFile);
+      if (stale && force) {
+        if (debug) {
+          console.log(`[lock] Stale lock detected (pid: ${lockData2.pid}), forcing acquisition`);
+        }
+      } else if (!stale) {
+        if (debug) {
+          console.log(`[lock] Lock already held by pid ${lockData2.pid}`);
+        }
+        return false;
+      } else {
+        if (debug) {
+          console.log(`[lock] Stale lock exists but force=false`);
+        }
+        return false;
+      }
+    } catch (error) {
+    }
+    const lockData = {
+      pid: process.pid,
+      timestamp: Date.now(),
+      hostname: await getHostname()
+    };
+    await writeFile(lockFile, JSON.stringify(lockData, null, 2), "utf-8");
+    if (debug) {
+      console.log(`[lock] Lock acquired by pid ${process.pid}`);
+    }
+    return true;
+  } catch (error) {
+    if (debug) {
+      console.error("[lock] Failed to acquire lock:", error);
+    }
+    return false;
+  }
+}
+async function releaseLock(options = {}) {
+  const { debug = false, configDir } = options;
+  const { lockFile } = resolvePaths(configDir);
+  try {
+    await unlink(lockFile);
+    if (debug) {
+      console.log(`[lock] Lock released by pid ${process.pid}`);
+    }
+  } catch (error) {
+    if (debug && error.code !== "ENOENT") {
+      console.error("[lock] Failed to release lock:", error);
+    }
+  }
+}
+async function readThrottleState(options = {}) {
+  const { configDir } = options;
+  const { throttleFile } = resolvePaths(configDir);
+  try {
+    const data = await readFile(throttleFile, "utf-8");
+    return JSON.parse(data);
+  } catch (error) {
+    return {};
+  }
+}
+async function writeThrottleState(state, options = {}) {
+  const { debug = false, configDir } = options;
+  const { configDir: resolvedConfigDir, throttleFile } = resolvePaths(configDir);
+  try {
+    await mkdir(resolvedConfigDir, { recursive: true });
+    await writeFile(throttleFile, JSON.stringify(state, null, 2), "utf-8");
+    if (debug) {
+      console.log("[throttle] State written:", state);
+    }
+  } catch (error) {
+    if (debug) {
+      console.error("[throttle] Failed to write state:", error);
+    }
+    throw error;
+  }
+}
+async function getHostname() {
+  try {
+    return osHostname();
+  } catch {
+    return "unknown";
+  }
+}
+
+// src/update.ts
+var DEFAULT_CONFIG_DIR2 = join2(homedir2(), ".config", "opencode");
+async function runAutoUpdate(options = {}) {
+  const disabled = options.disabled ?? envFlag("OPENCODE_AUTO_UPDATE_DISABLED");
+  if (disabled) {
+    return;
+  }
+  const debug = options.debug ?? envFlag("OPENCODE_AUTO_UPDATE_DEBUG");
+  const ignoreThrottle = options.ignoreThrottle ?? envFlag("OPENCODE_AUTO_UPDATE_BYPASS_THROTTLE");
+  const intervalHours = options.intervalHours ?? envNumber("OPENCODE_AUTO_UPDATE_INTERVAL_HOURS", 24);
+  const preservePinned = options.preservePinned ?? envFlag("OPENCODE_AUTO_UPDATE_PINNED");
+  const configDir = options.configDir ?? DEFAULT_CONFIG_DIR2;
+  const configPath = join2(configDir, "opencode.json");
+  const log = (...args) => {
+    if (debug) {
+      console.log(...args);
+    }
+  };
+  const error = (...args) => {
+    if (debug) {
+      console.error(...args);
+    }
+  };
+  const lockAcquired = await acquireLock({ debug, configDir });
+  if (!lockAcquired) {
+    log("[auto-update] Lock already held, skipping.");
+    return;
+  }
+  try {
+    const state = await readThrottleState({ configDir });
+    const now = Date.now();
+    const intervalMs = Math.max(intervalHours, 1) * 60 * 60 * 1e3;
+    if (!ignoreThrottle && state.lastRun && now - state.lastRun < intervalMs) {
+      log("[auto-update] Throttled, skipping update.");
+      return;
+    }
+    await writeThrottleState({ ...state, lastRun: now }, { debug, configDir });
+    const config = await readConfig(configPath);
+    const { plugins, key } = getPluginList(config);
+    if (!plugins || plugins.length === 0 || !key) {
+      log("[auto-update] No plugins found to update.");
+      return;
+    }
+    const useBun = await commandExists("bun");
+    log("[auto-update] Starting update", {
+      pluginCount: plugins.length,
+      useBun,
+      preservePinned,
+      ignoreThrottle
+    });
+    const updateResult = await updatePlugins({
+      plugins,
+      configDir,
+      preservePinned,
+      useBun,
+      log,
+      error
+    });
+    if (updateResult.changed) {
+      const updatedConfig = { ...config, [key]: updateResult.plugins };
+      await writeConfig(configPath, updatedConfig);
+    }
+    await writeThrottleState(
+      { ...state, lastRun: now, lastSuccess: Date.now() },
+      { debug, configDir }
+    );
+    log("[auto-update] Update complete.");
+  } catch (err) {
+    error("[auto-update] Failed to update plugins:", err);
+  } finally {
+    await releaseLock({ debug, configDir });
+  }
+}
+async function readConfig(configPath) {
+  try {
+    const contents = await readFile2(configPath, "utf-8");
+    return JSON.parse(contents);
+  } catch {
+    return null;
+  }
+}
+async function writeConfig(configPath, config) {
+  await mkdir2(dirname(configPath), { recursive: true });
+  const contents = JSON.stringify(config, null, 2);
+  await writeFile2(configPath, `${contents}
+`, "utf-8");
+}
+function getPluginList(config) {
+  if (!config) {
+    return { plugins: null, key: null };
+  }
+  if (Array.isArray(config.plugin)) {
+    return { plugins: config.plugin, key: "plugin" };
+  }
+  if (Array.isArray(config.plugins)) {
+    return { plugins: config.plugins, key: "plugins" };
+  }
+  return { plugins: null, key: null };
+}
+async function updatePlugins(options) {
+  const { plugins, configDir, preservePinned, useBun, log, error } = options;
+  const updated = [];
+  let changed = false;
+  for (const entry of plugins) {
+    if (isNonRegistryPlugin(entry)) {
+      log("[auto-update] Skipping non-registry plugin:", entry);
+      updated.push(entry);
+      continue;
+    }
+    const { name, version } = parsePackageSpec(entry);
+    if (preservePinned && version) {
+      log("[auto-update] Preserving pinned plugin:", entry);
+      updated.push(entry);
+      continue;
+    }
+    log("[auto-update] Updating plugin:", name);
+    const installedVersion = await installLatest({
+      name,
+      configDir,
+      useBun,
+      log,
+      error
+    });
+    if (!installedVersion) {
+      updated.push(entry);
+      continue;
+    }
+    const nextEntry = `${name}@${installedVersion}`;
+    log("[auto-update] Installed:", nextEntry);
+    updated.push(nextEntry);
+    if (nextEntry !== entry) {
+      changed = true;
+    }
+  }
+  return { plugins: updated, changed };
+}
+async function installLatest(options) {
+  const { name, configDir, useBun, log, error } = options;
+  await mkdir2(configDir, { recursive: true });
+  if (useBun) {
+    const result = await runCommand("bun", ["add", `${name}@latest`, "--cwd", configDir]);
+    if (result.code !== 0) {
+      error("[auto-update] bun add failed:", result.stderr || result.stdout);
+      return null;
+    }
+  } else {
+    const result = await runCommand("npm", [
+      "install",
+      `${name}@latest`,
+      "--prefix",
+      configDir,
+      "--no-save"
+    ]);
+    if (result.code !== 0) {
+      error("[auto-update] npm install failed:", result.stderr || result.stdout);
+      return null;
+    }
+  }
+  const version = await readInstalledVersion(name, configDir);
+  if (!version) {
+    log("[auto-update] Unable to read installed version for", name);
+  }
+  return version;
+}
+async function readInstalledVersion(name, configDir) {
+  try {
+    const packagePath = name.startsWith("@") ? join2(configDir, "node_modules", ...name.split("/"), "package.json") : join2(configDir, "node_modules", name, "package.json");
+    const data = await readFile2(packagePath, "utf-8");
+    const parsed = JSON.parse(data);
+    return parsed.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function isNonRegistryPlugin(spec) {
+  const trimmed = spec.trim();
+  if (!trimmed) {
+    return true;
+  }
+  const lower = trimmed.toLowerCase();
+  if (lower.startsWith("file:") || lower.startsWith("git+") || lower.startsWith("git:") || lower.startsWith("ssh://") || lower.startsWith("http://") || lower.startsWith("https://") || lower.startsWith("github:") || lower.startsWith("workspace:")) {
+    return true;
+  }
+  return trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("/") || trimmed.startsWith("~");
+}
+function parsePackageSpec(spec) {
+  if (spec.startsWith("@")) {
+    const secondAt = spec.indexOf("@", 1);
+    if (secondAt === -1) {
+      return { name: spec };
+    }
+    return {
+      name: spec.slice(0, secondAt),
+      version: spec.slice(secondAt + 1) || void 0
+    };
+  }
+  const at = spec.lastIndexOf("@");
+  if (at <= 0) {
+    return { name: spec };
+  }
+  return {
+    name: spec.slice(0, at),
+    version: spec.slice(at + 1) || void 0
+  };
+}
+async function commandExists(command) {
+  const result = await runCommand(command, ["--version"]);
+  return result.code === 0;
+}
+async function runCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (err) => {
+      resolve({ code: 1, stdout, stderr: `${stderr}${err.message}` });
+    });
+    child.on("close", (code) => {
+      resolve({ code: code ?? 0, stdout, stderr });
+    });
+  });
+}
+function envFlag(name) {
+  return process.env[name]?.toLowerCase() === "true";
+}
+function envNumber(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) {
+    return fallback;
+  }
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+// src/index.ts
+async function src_default(ctx) {
+  const args = process.argv ?? [];
+  const debugLevelFlag = args.includes("--log-level") && args.includes("DEBUG");
+  const envDebug = process.env.OPENCODE_AUTO_UPDATE_DEBUG?.toLowerCase() === "true";
+  const envBypassThrottle = process.env.OPENCODE_AUTO_UPDATE_BYPASS_THROTTLE?.toLowerCase() === "true";
+  const debug = debugLevelFlag || envDebug;
+  const ignoreThrottle = debugLevelFlag || envBypassThrottle;
+  setTimeout(() => {
+    runAutoUpdate({ debug, ignoreThrottle }).catch((error) => {
+      if (debug) {
+        console.error("[opencode-plugin-auto-update] Update check failed:", error);
+      }
+    });
+  }, 0);
+  return {
+    name: "opencode-plugin-auto-update"
+  };
+}
+export {
+  src_default as default
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "opencode-plugin-auto-update",
+  "version": "0.1.1",
+  "description": "OpenCode plugin that auto-updates plugins in the background",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "auto-update",
+    "dependencies"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AnganSamadder/opencode-plugin-auto-update.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AnganSamadder/opencode-plugin-auto-update/issues"
+  },
+  "homepage": "https://github.com/AnganSamadder/opencode-plugin-auto-update#readme",
+  "author": "Angan Samadder",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "^1.2.4",
+    "@types/node": "^25.0.10",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  }
+}