@sjawhar/opencode-legion-envoy 0.1.10 → 0.2.1

package/src/__tests__/log.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { createLogger } from "../log";
+
+let logDir: string;
+
+beforeEach(async () => {
+  logDir = await mkdtemp(path.join(tmpdir(), "envoy-plugin-log-"));
+});
+
+afterEach(async () => {
+  await rm(logDir, { recursive: true, force: true });
+});
+
+describe("envoy-plugin logger", () => {
+  // The whole point of this module: plugins run in-process with OpenCode's
+  // TUI, so any console.warn/console.error byte goes straight to the terminal
+  // and corrupts the render. Plugin diagnostics must go to a file instead.
+  it("writes warn/error/info to the configured log file, NOT to console", async () => {
+    const consoleWarn = mock(() => {});
+    const consoleError = mock(() => {});
+    const consoleLog = mock(() => {});
+    const originalWarn = console.warn;
+    const originalError = console.error;
+    const originalLog = console.log;
+    console.warn = consoleWarn;
+    console.error = consoleError;
+    console.log = consoleLog;
+    try {
+      const logger = createLogger({ logDir });
+      logger.warn("a-warn");
+      logger.error("an-error");
+      logger.info("some-info");
+      await logger.flush();
+
+      expect(consoleWarn).not.toHaveBeenCalled();
+      expect(consoleError).not.toHaveBeenCalled();
+      expect(consoleLog).not.toHaveBeenCalled();
+
+      const logFile = path.join(logDir, "envoy-plugin.log");
+      const contents = await readFile(logFile, "utf-8");
+      expect(contents).toContain("a-warn");
+      expect(contents).toContain("an-error");
+      expect(contents).toContain("some-info");
+      expect(contents).toContain("WARN");
+      expect(contents).toContain("ERROR");
+      expect(contents).toContain("INFO");
+    } finally {
+      console.warn = originalWarn;
+      console.error = originalError;
+      console.log = originalLog;
+    }
+  });
+
+  it("creates the log directory if it doesn't exist", async () => {
+    const nested = path.join(logDir, "deeply", "nested");
+    const logger = createLogger({ logDir: nested });
+    logger.warn("hello");
+    await logger.flush();
+    const contents = await readFile(path.join(nested, "envoy-plugin.log"), "utf-8");
+    expect(contents).toContain("hello");
+  });
+
+  it("prefixes each line with an ISO timestamp so logs are sortable", async () => {
+    const logger = createLogger({ logDir });
+    logger.warn("x");
+    await logger.flush();
+    const contents = await readFile(path.join(logDir, "envoy-plugin.log"), "utf-8");
+    // Match leading ISO-8601 datetime like 2026-05-30T22:35:01.123Z
+    expect(contents).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z /);
+  });
+
+  it("appends across calls instead of truncating", async () => {
+    const logger = createLogger({ logDir });
+    logger.warn("first");
+    logger.warn("second");
+    await logger.flush();
+    const contents = await readFile(path.join(logDir, "envoy-plugin.log"), "utf-8");
+    expect(contents).toContain("first");
+    expect(contents).toContain("second");
+    expect(contents.split("\n").filter((l) => l.length > 0).length).toBe(2);
+  });
+
+  it("never throws on logging errors — diagnostics must not crash the host", async () => {
+    // Point at a path that cannot be created (a parent that exists as a file).
+    const blockingFile = path.join(logDir, "blocker");
+    const fs = await import("node:fs/promises");
+    await fs.writeFile(blockingFile, "");
+    const logger = createLogger({ logDir: path.join(blockingFile, "child") });
+    expect(() => logger.warn("x")).not.toThrow();
+    await expect(logger.flush()).resolves.toBeUndefined();
+  });
+});
+
+describe("no console.* in plugin source (regression guard)", () => {
+  // Plugins load in-process with OpenCode's TUI; any direct console.warn /
+  // console.error / console.log write goes straight to the terminal and
+  // corrupts the render. All diagnostics must route through the file logger.
+  it("does not write to console anywhere outside __tests__ and log.ts", async () => {
+    const { readdir, readFile, stat } = await import("node:fs/promises");
+    const root = path.resolve(import.meta.dir, "..");
+
+    async function walk(dir: string): Promise<string[]> {
+      const entries = await readdir(dir);
+      const out: string[] = [];
+      for (const name of entries) {
+        if (name === "__tests__" || name === "node_modules") continue;
+        const full = path.join(dir, name);
+        const s = await stat(full);
+        if (s.isDirectory()) out.push(...(await walk(full)));
+        else if (name.endsWith(".ts") || name.endsWith(".tsx")) out.push(full);
+      }
+      return out;
+    }
+
+    const files = await walk(root);
+    const offenders: Array<{ file: string; line: number; text: string }> = [];
+    for (const file of files) {
+      // log.ts is allowed to mention console in its module docstring — it's
+      // the module explaining the prohibition.
+      if (file.endsWith("/log.ts")) continue;
+      const lines = (await readFile(file, "utf-8")).split("\n");
+      lines.forEach((text, idx) => {
+        if (/^\s*(?:\/\/|\*| \*)/.test(text)) return; // comments are fine
+        if (/\bconsole\.(warn|error|log)\s*\(/.test(text)) {
+          offenders.push({ file: path.relative(root, file), line: idx + 1, text });
+        }
+      });
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/__tests__/tui-port.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "bun:test";
+import {
+  parsePort,
+  resolveCurrentProcessPort,
+  resolveSessionProcessPort,
+  resolveTuiPort,
+} from "../tui-port";
+
+describe("parsePort", () => {
+  it("returns the port from a standard http URL", () => {
+    expect(parsePort("http://localhost:4096")).toBe(4096);
+  });
+
+  it("returns the port from a 127.0.0.1 URL", () => {
+    expect(parsePort("http://127.0.0.1:13381")).toBe(13381);
+  });
+
+  it("returns the port from an https URL with explicit port", () => {
+    expect(parsePort("https://example.com:8443")).toBe(8443);
+  });
+
+  it("returns null when the URL has no explicit port", () => {
+    expect(parsePort("http://localhost")).toBe(null);
+  });
+
+  it("returns null for the empty string", () => {
+    expect(parsePort("")).toBe(null);
+  });
+
+  it("returns null for a non-URL string", () => {
+    expect(parsePort("not a url")).toBe(null);
+  });
+
+  it("returns null for a malformed port", () => {
+    expect(parsePort("http://localhost:abc")).toBe(null);
+  });
+
+  it("returns null for undefined input", () => {
+    expect(parsePort(undefined)).toBe(null);
+  });
+});
+
+describe("resolveCurrentProcessPort", () => {
+  it("returns a listening port for the current process from ss output", () => {
+    const exec = () =>
+      `LISTEN 0 512 127.0.0.1:41895 0.0.0.0:* users:(("opencode",pid=${process.pid},fd=23))`;
+
+    expect(resolveCurrentProcessPort(exec)).toBe(41895);
+  });
+
+  it("returns null when ss has no current process match", () => {
+    const exec = () => 'LISTEN 0 512 127.0.0.1:41895 0.0.0.0:* users:(("opencode",pid=123,fd=23))';
+
+    expect(resolveCurrentProcessPort(exec)).toBe(null);
+  });
+});
+
+describe("resolveTuiPort", () => {
+  it("prefers the base URL port", () => {
+    const exec = () => {
+      throw new Error("should not call ss");
+    };
+
+    expect(resolveTuiPort("http://127.0.0.1:4096", undefined, exec)).toBe(4096);
+  });
+
+  it("falls back to the current process listening port", () => {
+    const exec = () =>
+      `LISTEN 0 512 127.0.0.1:35291 0.0.0.0:* users:(("opencode",pid=${process.pid},fd=23))`;
+
+    expect(resolveTuiPort(undefined, undefined, exec)).toBe(35291);
+  });
+});
+
+describe("resolveSessionProcessPort", () => {
+  it("resolves the listening port for an opencode session process", () => {
+    const sessionID = "ses_test";
+    const exec = (command: string) => {
+      if (command === "ps") return `123 opencode --port 0 -s ${sessionID}`;
+      return 'LISTEN 0 512 127.0.0.1:42823 0.0.0.0:* users:(("opencode",pid=123,fd=23))';
+    };
+
+    expect(resolveSessionProcessPort(sessionID, exec)).toBe(42823);
+  });
+});

package/src/clipboard.ts

@@ -0,0 +1,140 @@
+import { spawnSync } from "node:child_process";
+import { appendFileSync } from "node:fs";
+import { platform } from "node:os";
+
+/**
+ * Build marker. Bump on every change so the debug log proves whether the
+ * running OpenCode process loaded the new module — the TUI plugin is loaded via
+ * `await import()` (cached by URL), so a behavior fix here only takes effect
+ * after a full OpenCode process restart, not just a new TUI session.
+ */
+export const CLIPBOARD_BUILD_ID = "renderer-osc52-2026-06-06-2";
+
+/**
+ * Clipboard copy for the OpenCode TUI plugin.
+ *
+ * Copies MUST go through the renderer's own OSC 52 writer
+ * (api.renderer.copyToClipboardOSC52). opentui's renderer owns the terminal and
+ * serializes all output via its native writer; it also applies tmux/screen DCS
+ * passthrough wrapping and gates on terminal OSC 52 support (see opentui zig
+ * terminal.zig writeClipboard). Writing a raw OSC 52 to process.stdout bypasses
+ * that serialization and races with frame output, so copies landed only
+ * intermittently ("works once right after a native copy, then stops") — that was
+ * the flakiness, now removed.
+ *
+ * A native OS clipboard command is kept as a fallback for terminals without
+ * OSC 52 support; it is a subprocess and never writes to the terminal stream.
+ */
+
+type Runner = (cmd: string, args: string[], text: string) => boolean;
+
+export interface ClipboardRenderer {
+  copyToClipboardOSC52(text: string): boolean;
+}
+
+function debugClipboard(event: Record<string, unknown>): void {
+  const path = process.env.OPENCODE_TUI_CLIPBOARD_DEBUG;
+  if (!path) return;
+  try {
+    appendFileSync(
+      path,
+      `${JSON.stringify({
+        ts: new Date().toISOString(),
+        buildId: CLIPBOARD_BUILD_ID,
+        pid: process.pid,
+        entry: import.meta.url,
+        isTTY: process.stdout.isTTY ?? null,
+        term: process.env.TERM ?? null,
+        tmux: Boolean(process.env.TMUX),
+        sty: Boolean(process.env.STY),
+        display: Boolean(process.env.DISPLAY),
+        wayland: Boolean(process.env.WAYLAND_DISPLAY),
+        ...event,
+      })}\n`
+    );
+  } catch {
+    // diagnostics must never break copy
+  }
+}
+
+function copyViaRenderer(renderer: ClipboardRenderer | undefined, text: string): boolean {
+  if (!renderer) return false;
+  try {
+    const ok = renderer.copyToClipboardOSC52(text);
+    debugClipboard({ phase: "renderer-osc52", returned: ok });
+    return ok;
+  } catch (error) {
+    debugClipboard({ phase: "renderer-osc52", error: String(error) });
+    return false;
+  }
+}
+
+function defaultWhich(cmd: string): boolean {
+  try {
+    return spawnSync("which", [cmd], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function defaultRun(cmd: string, args: string[], text: string): boolean {
+  try {
+    const result = spawnSync(cmd, args, {
+      input: text,
+      stdio: ["pipe", "ignore", "ignore"],
+      timeout: 1000,
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export interface NativeCopyDeps {
+  which?: (cmd: string) => boolean;
+  run?: Runner;
+  os?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+}
+
+export function copyNative(text: string, deps: NativeCopyDeps = {}): boolean {
+  const which = deps.which ?? defaultWhich;
+  const run = deps.run ?? defaultRun;
+  const os = deps.os ?? platform();
+  const env = deps.env ?? process.env;
+
+  if (os === "darwin" && which("osascript")) {
+    const escaped = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return run("osascript", ["-e", `set the clipboard to "${escaped}"`], "");
+  }
+
+  if (os === "linux") {
+    if (env.WAYLAND_DISPLAY && which("wl-copy")) return run("wl-copy", [], text);
+    if (which("xclip")) return run("xclip", ["-selection", "clipboard"], text);
+    if (which("xsel")) return run("xsel", ["--clipboard", "--input"], text);
+  }
+
+  if (os === "win32") {
+    return run(
+      "powershell.exe",
+      [
+        "-NonInteractive",
+        "-NoProfile",
+        "-Command",
+        "[Console]::InputEncoding = [System.Text.Encoding]::UTF8; Set-Clipboard -Value ([Console]::In.ReadToEnd())",
+      ],
+      text
+    );
+  }
+
+  return false;
+}
+
+export function copyToClipboard(text: string, renderer?: ClipboardRenderer): boolean {
+  debugClipboard({ phase: "copy-start", textLength: text.length });
+  const viaRenderer = copyViaRenderer(renderer, text);
+  const native = viaRenderer ? false : copyNative(text);
+  const ok = viaRenderer || native;
+  debugClipboard({ phase: "copy-result", viaRenderer, native, ok });
+  return ok;
+}

package/src/config/__tests__/index.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { logger } from "../../log";
+import { loadEnvoyConfig } from "..";
+
+describe("loadEnvoyConfig", () => {
+  let homeDir: string;
+  let repoDir: string;
+  let warn: ReturnType<typeof spyOn>;
+
+  beforeEach(async () => {
+    homeDir = await mkdtemp(path.join(tmpdir(), "envoy-home-"));
+    repoDir = await mkdtemp(path.join(tmpdir(), "envoy-repo-"));
+    // Spy on the file logger — plugin diagnostics route there instead of
+    // console to keep stderr clean for the in-process TUI host.
+    warn = spyOn(logger, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+  });
+
+  async function writeJson(filePath: string, value: unknown) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(value));
+  }
+
+  it("loads user-only config", async () => {
+    await writeJson(path.join(homeDir, ".config", "opencode", "envoy.json"), {
+      natsUrls: ["nats://127.0.0.1:4222"],
+      dispatch: { enabled: true, defaultRepo: "sjawhar/legion" },
+    });
+
+    await expect(loadEnvoyConfig(repoDir, { homeDir })).resolves.toEqual({
+      natsUrls: ["nats://127.0.0.1:4222"],
+      dispatch: { enabled: true, defaultRepo: "sjawhar/legion" },
+    });
+  });
+
+  it("loads repo-only config", async () => {
+    await writeJson(path.join(repoDir, ".opencode", "envoy.json"), {
+      dispatch: { serverUrl: "http://localhost:8766" },
+    });
+
+    await expect(loadEnvoyConfig(repoDir, { homeDir })).resolves.toEqual({
+      dispatch: { serverUrl: "http://localhost:8766" },
+    });
+  });
+
+  it("shallow-merges user config with repo config and lets repo dispatch keys win", async () => {
+    await writeJson(path.join(homeDir, ".config", "opencode", "envoy.json"), {
+      natsUrls: ["nats://user:4222"],
+      dispatch: { enabled: false, defaultRepo: "sjawhar/legion" },
+    });
+    await writeJson(path.join(repoDir, ".opencode", "envoy.json"), {
+      dispatch: { enabled: true, serverUrl: "http://localhost:8766" },
+    });
+
+    await expect(loadEnvoyConfig(repoDir, { homeDir })).resolves.toEqual({
+      natsUrls: ["nats://user:4222"],
+      dispatch: {
+        enabled: true,
+        defaultRepo: "sjawhar/legion",
+        serverUrl: "http://localhost:8766",
+      },
+    });
+  });
+
+  it("returns empty config and warns on invalid JSON", async () => {
+    const configPath = path.join(homeDir, ".config", "opencode", "envoy.json");
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, "{");
+
+    await expect(loadEnvoyConfig(repoDir, { homeDir })).resolves.toEqual({});
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it("returns empty config and warns on schema-invalid JSON", async () => {
+    await writeJson(path.join(repoDir, ".opencode", "envoy.json"), {
+      natsUrls: "nats://127.0.0.1:4222",
+    });
+
+    await expect(loadEnvoyConfig(repoDir, { homeDir })).resolves.toEqual({});
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it("returns empty config when files are missing", async () => {
+    await expect(loadEnvoyConfig(repoDir, { homeDir })).resolves.toEqual({});
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

package/src/config/index.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { logger } from "../log";
+import { type EnvoyConfig, EnvoyConfigSchema } from "./schema";
+
+export interface LoadEnvoyConfigOptions {
+  homeDir?: string;
+}
+
+function readConfigFile(filePath: string): EnvoyConfig | null {
+  if (!existsSync(filePath)) return null;
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const raw = JSON.parse(content) as unknown;
+    const parsed = EnvoyConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issues = parsed.error.issues
+        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+        .join(", ");
+      logger.warn(`[envoy-plugin] Invalid config at ${filePath}: ${issues}`);
+      return null;
+    }
+    return parsed.data as EnvoyConfig;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`[envoy-plugin] Failed to load config at ${filePath}: ${message}`);
+    return null;
+  }
+}
+
+function mergeConfig(base: EnvoyConfig, override: EnvoyConfig): EnvoyConfig {
+  return {
+    ...base,
+    ...override,
+    dispatch:
+      base.dispatch || override.dispatch
+        ? {
+            ...base.dispatch,
+            ...override.dispatch,
+          }
+        : undefined,
+  };
+}
+
+export async function loadEnvoyConfig(
+  directory: string,
+  options: LoadEnvoyConfigOptions = {}
+): Promise<EnvoyConfig> {
+  const homeDir = options.homeDir ?? os.homedir();
+  const userConfigPath = path.join(homeDir, ".config", "opencode", "envoy.json");
+  const repoConfigPath = path.join(directory, ".opencode", "envoy.json");
+
+  let merged: EnvoyConfig = {};
+  const userConfig = readConfigFile(userConfigPath);
+  if (userConfig) merged = mergeConfig(merged, userConfig);
+  const repoConfig = readConfigFile(repoConfigPath);
+  if (repoConfig) merged = mergeConfig(merged, repoConfig);
+  return merged;
+}
+
+export type { DispatchConfig, EnvoyConfig } from "./schema";

package/src/config/schema.ts

@@ -0,0 +1,26 @@
+import { tool } from "@opencode-ai/plugin";
+
+const z = tool.schema;
+
+export const DispatchConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    serverUrl: z.string().url().optional(),
+    defaultRepo: z
+      .string()
+      .regex(/^[^/]+\/[^/]+$/)
+      .optional(),
+    appClientId: z.string().optional(),
+  })
+  .strict();
+
+export const EnvoyConfigSchema = z
+  .object({
+    $schema: z.string().optional(),
+    natsUrls: z.array(z.string()).optional(),
+    dispatch: DispatchConfigSchema.optional(),
+  })
+  .passthrough();
+
+export type DispatchConfig = ReturnType<typeof DispatchConfigSchema.parse>;
+export type EnvoyConfig = ReturnType<typeof EnvoyConfigSchema.parse>;