@khalilgharbaoui/opencode-claude-code-plugin 0.4.16 → 0.4.18

package/README.md

@@ -319,30 +319,68 @@ Set `permissionMode: "plan"` to forward `--permission-mode plan` to Claude. The
 - **Lazy `cwd`.** The working directory is re-resolved at every request, so opencode's project-aware behavior works without restarting the plugin.
 - **Variants survive merge.** opencode recalculates variant lists after the plugin loads; the plugin re-injects defaults into runtime config so your variants don't disappear.
 
-## Debug logging
+## Logging
 
-Two independent knobs:
+Configure via `opencode.jsonc` (launch-method-independent) or env vars
+(temporary override for a single process). The plugin has four orthogonal
+knobs:
 
-```bash
-# Verbose logging to stderr (opencode surfaces stderr as UI warnings):
-DEBUG=opencode-claude-code opencode
+| Field | Values | Default | Effect |
+|---|---|---|---|
+| `file` | `true \| false` | `false` | Persist log entries to disk |
+| `dir` | path string | `~/.local/share/opencode-claude-code/` | Custom file location |
+| `mode` | `"silent" \| "debug"` | `"silent"` | TUI policy |
+| `level` | `"debug" \| "info" \| "notice" \| "warn" \| "error"` | `"info"` | Minimum level to emit |
+
+Rails-style threshold: anything below `level` is dropped before either
+destination decides what to do. `mode: "silent"` routes DEBUG/INFO/NOTICE
+to file only and lets WARN/ERROR bubble in the TUI (they always do).
+`mode: "debug"` additionally echoes every emitted level to the TUI (which
+opencode surfaces as warning bubbles).
+
+**Recommended dev setup** — capture audit trail to disk, keep TUI quiet:
+
+```jsonc
+"@khalilgharbaoui/opencode-claude-code-plugin": {
+  "logging": { "file": true }
+}
+```
+
+**Full firehose for deep debugging** (every DEBUG stream event captured):
+
+```jsonc
+"logging": { "file": true, "level": "debug" }
+```
 
-# Persistent file log (default: OFF — file is not created at all):
-OPENCODE_CLAUDE_CODE_LOG_FILE=1 opencode
+**Live TUI noise** (everything echoes to opencode's stderr → warning bubbles):
 
-# Both:
-DEBUG=opencode-claude-code OPENCODE_CLAUDE_CODE_LOG_FILE=1 opencode
+```jsonc
+"logging": { "file": true, "mode": "debug" }
 ```
 
-When `OPENCODE_CLAUDE_CODE_LOG_FILE` is set to any truthy value (`1`,
-`true`, `yes`, `on`), the plugin writes NOTICE/WARN/ERROR (plus INFO and
-DEBUG when `DEBUG=opencode-claude-code` is also set) to
-`~/.local/share/opencode-claude-code/plugin.log` with 5MB rotation. Override
-the directory with `OPENCODE_CLAUDE_CODE_LOG_DIR=/custom/path`.
+### Env-var overrides
+
+Set explicitly to override config for one process — useful for one-off
+debugging without editing `opencode.jsonc`:
+
+```bash
+OPENCODE_CLAUDE_CODE_LOG_FILE=1 opencode          # file on
+OPENCODE_CLAUDE_CODE_LOG_FILE=0 opencode          # file off (overrides config:true)
+OPENCODE_CLAUDE_CODE_LOG_DIR=/tmp/cc opencode     # custom dir
+OPENCODE_CLAUDE_CODE_LOG_LEVEL=debug opencode     # capture every level
+DEBUG=opencode-claude-code opencode               # promote to mode:"debug"
+```
+
+Boolean env vars accept `1/true/on/yes` for on and `0/false/no/off` for
+off; empty / unset falls through to config. Invalid `level` values fall
+through to config.
+
+### Default behavior (no config, no env)
 
-Default is off so the plugin doesn't accrete a log file on every user's
-disk. Opt in when you need to inspect auto-continue decisions, broker
-state, or other plugin internals.
+Nothing persists; only WARN and ERROR bubble in the TUI. The plugin
+doesn't accrete a log file on every user's disk by default — opt in when
+you need to inspect auto-continue decisions, broker state, or other
+plugin internals.
 
 ## Known limitations
 

package/dist/index.d.ts

@@ -96,6 +96,9 @@ type OpenCodeHooks = {
 };
 type OpenCodePlugin = (input: unknown, options?: Record<string, unknown>) => Promise<OpenCodeHooks>;
 
+type LogLevel = "debug" | "info" | "notice" | "warn" | "error";
+type LogMode = "silent" | "debug";
+
 interface ClaudeCodeConfig {
     provider: string;
     cliPath: string;
@@ -117,6 +120,35 @@ interface ClaudeCodeConfig {
     proxyOpencodeMcpTools?: boolean;
     multiStepContinuation?: boolean;
     autoContinueIncompleteTurns?: boolean | "smart";
+    logging?: LoggingConfig;
+}
+interface LoggingConfig {
+    /**
+     * Persist log activity (DEBUG / INFO / NOTICE / WARN / ERROR — those
+     * passing `level`) to a file. Default: `false`. When `false`, entries
+     * below WARN vanish entirely; WARN / ERROR still surface in the TUI via
+     * stderr. Set to `true` to capture the audit trail to disk for review
+     * via `tail` / `grep`.
+     */
+    file?: boolean;
+    /**
+     * Optional custom directory for the file log. Defaults to
+     * `~/.local/share/opencode-claude-code/`. Has no effect when `file:false`.
+     */
+    dir?: string;
+    /**
+     * TUI policy. `"silent"` (default) routes DEBUG / INFO / NOTICE to file
+     * only; WARN / ERROR still bubble in the TUI as they always do. `"debug"`
+     * additionally echoes every emitted level to stderr (which opencode's TUI
+     * surfaces as warning bubbles).
+     */
+    mode?: LogMode;
+    /**
+     * Minimum level to emit anywhere. Anything below the threshold is dropped
+     * before either destination decides what to do. Order:
+     * `debug` < `info` < `notice` < `warn` < `error`. Default: `"info"`.
+     */
+    level?: LogLevel;
 }
 type WebSearchRouting = "claude" | "disabled" | (string & {});
 interface ClaudeCodeProviderSettings {
@@ -233,6 +265,14 @@ interface ClaudeCodeProviderSettings {
      * Set to `false` to disable.
      */
     autoContinueIncompleteTurns?: boolean | "smart";
+    /**
+     * Logger configuration. See `LoggingConfig` for fields. Env vars
+     * (`OPENCODE_CLAUDE_CODE_LOG_FILE`, `OPENCODE_CLAUDE_CODE_LOG_DIR`,
+     * `OPENCODE_CLAUDE_CODE_LOG_LEVEL`, `DEBUG=opencode-claude-code`) override
+     * these values when explicitly set, so a developer can flip behavior for
+     * one process without editing opencode.jsonc.
+     */
+    logging?: LoggingConfig;
 }
 type PermissionMode = "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";
 type ControlRequestBehavior = "allow" | "deny";

package/dist/index.js

@@ -5,34 +5,80 @@ import { generateId } from "@ai-sdk/provider-utils";
 import { appendFileSync, mkdirSync, renameSync, statSync } from "fs";
 import { homedir } from "os";
 import { dirname, join } from "path";
-var DEBUG = process.env.DEBUG?.includes("opencode-claude-code") ?? false;
-var LOG_DIR = process.env.OPENCODE_CLAUDE_CODE_LOG_DIR ?? join(homedir(), ".local", "share", "opencode-claude-code");
-var LOG_FILE = join(LOG_DIR, "plugin.log");
+var LEVEL_RANK = {
+  debug: 0,
+  info: 1,
+  notice: 2,
+  warn: 3,
+  error: 4
+};
 var MAX_LOG_BYTES = 5 * 1024 * 1024;
-function isTruthyEnv(v) {
-  if (v == null) return false;
+var DEFAULT_DIR = join(homedir(), ".local", "share", "opencode-claude-code");
+var DEFAULT_CONFIG = {
+  file: false,
+  dir: null,
+  mode: "silent",
+  level: "info"
+};
+function parseBoolEnv(v) {
+  if (v == null) return void 0;
+  const s = v.toLowerCase().trim();
+  if (s === "") return void 0;
+  if (s === "0" || s === "false" || s === "no" || s === "off") return false;
+  return true;
+}
+function parseLevelEnv(v) {
+  if (v == null) return void 0;
   const s = v.toLowerCase().trim();
-  if (s === "") return false;
-  return s !== "0" && s !== "false" && s !== "no" && s !== "off";
+  if (s === "") return void 0;
+  if (s === "debug" || s === "info" || s === "notice" || s === "warn" || s === "error") {
+    return s;
+  }
+  return void 0;
 }
-var LOG_FILE_ENABLED = isTruthyEnv(process.env.OPENCODE_CLAUDE_CODE_LOG_FILE);
+function parseModeFromDebugEnv(v) {
+  if (v == null || v === "") return void 0;
+  return v.includes("opencode-claude-code") ? "debug" : void 0;
+}
+function withEnvOverrides(base) {
+  const result = { ...base };
+  const envFile = parseBoolEnv(process.env.OPENCODE_CLAUDE_CODE_LOG_FILE);
+  if (envFile !== void 0) result.file = envFile;
+  const envDir = process.env.OPENCODE_CLAUDE_CODE_LOG_DIR;
+  if (envDir !== void 0 && envDir !== "") result.dir = envDir;
+  const envMode = parseModeFromDebugEnv(process.env.DEBUG);
+  if (envMode !== void 0) result.mode = envMode;
+  const envLevel = parseLevelEnv(process.env.OPENCODE_CLAUDE_CODE_LOG_LEVEL);
+  if (envLevel !== void 0) result.level = envLevel;
+  return result;
+}
+var activeConfig = withEnvOverrides(DEFAULT_CONFIG);
 var fileLoggingDisabled = false;
-function rotateIfNeeded() {
+function configureLogger(input) {
+  const merged = { ...DEFAULT_CONFIG, ...input };
+  activeConfig = withEnvOverrides(merged);
+  fileLoggingDisabled = false;
+}
+function resolvedLogFile() {
+  return join(activeConfig.dir ?? DEFAULT_DIR, "plugin.log");
+}
+function rotateIfNeeded(logFile) {
   try {
-    const stat = statSync(LOG_FILE);
+    const stat = statSync(logFile);
     if (stat.size > MAX_LOG_BYTES) {
-      renameSync(LOG_FILE, `${LOG_FILE}.1`);
+      renameSync(logFile, `${logFile}.1`);
     }
   } catch {
   }
 }
 function writeToFile(line) {
-  if (!LOG_FILE_ENABLED) return;
+  if (!activeConfig.file) return;
   if (fileLoggingDisabled) return;
   try {
-    mkdirSync(dirname(LOG_FILE), { recursive: true });
-    rotateIfNeeded();
-    appendFileSync(LOG_FILE, line + "\n", "utf8");
+    const logFile = resolvedLogFile();
+    mkdirSync(dirname(logFile), { recursive: true });
+    rotateIfNeeded(logFile);
+    appendFileSync(logFile, line + "\n", "utf8");
   } catch {
     fileLoggingDisabled = true;
   }
@@ -45,30 +91,36 @@ function fmt(level, msg, data) {
   }
   return base;
 }
-function emit(level, msg, data, alwaysStderr = false) {
-  const line = fmt(level, msg, data);
-  if (alwaysStderr || DEBUG) {
+function shouldEmit(level) {
+  return LEVEL_RANK[level] >= LEVEL_RANK[activeConfig.level];
+}
+function shouldTui(level) {
+  if (level === "warn" || level === "error") return true;
+  return activeConfig.mode === "debug";
+}
+function emit(level, msg, data) {
+  if (!shouldEmit(level)) return;
+  const line = fmt(level.toUpperCase(), msg, data);
+  if (shouldTui(level)) {
     console.error(line);
   }
   writeToFile(line);
 }
 var log = {
+  debug(msg, data) {
+    emit("debug", msg, data);
+  },
   info(msg, data) {
-    if (DEBUG) emit("INFO", msg, data);
-    else writeToFile(fmt("INFO", msg, data));
+    emit("info", msg, data);
   },
   notice(msg, data) {
-    emit("NOTICE", msg, data, false);
+    emit("notice", msg, data);
   },
   warn(msg, data) {
-    emit("WARN", msg, data, true);
+    emit("warn", msg, data);
   },
   error(msg, data) {
-    emit("ERROR", msg, data, true);
-  },
-  debug(msg, data) {
-    if (DEBUG) emit("DEBUG", msg, data);
-    else writeToFile(fmt("DEBUG", msg, data));
+    emit("error", msg, data);
   }
 };
 
@@ -3791,6 +3843,14 @@ function pickOpencodeDirectory(input) {
   return void 0;
 }
 function createClaudeCode(settings = {}) {
+  if (settings.logging) {
+    configureLogger({
+      file: settings.logging.file ?? false,
+      dir: settings.logging.dir ?? null,
+      mode: settings.logging.mode ?? "silent",
+      level: settings.logging.level ?? "info"
+    });
+  }
   const cliPath = settings.cliPath ?? process.env.CLAUDE_CLI_PATH ?? "claude";
   const providerName = settings.providerID ?? settings.name ?? "claude-code";
   const proxyTools = settings.proxyTools ?? ["Bash", "Edit", "Write", "WebFetch"];