@ag-eco/agentplate-cli 0.13.0

package/src/runtimes/opencode.test.ts

@@ -0,0 +1,325 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import type { ResolvedModel } from "../types.ts";
+import { OpenCodeRuntime } from "./opencode.ts";
+import type { SpawnOpts } from "./types.ts";
+
+describe("OpenCodeRuntime", () => {
+	const runtime = new OpenCodeRuntime();
+
+	describe("id and instructionPath", () => {
+		test("id is 'opencode'", () => {
+			expect(runtime.id).toBe("opencode");
+		});
+
+		test("instructionPath is AGENTS.md", () => {
+			expect(runtime.instructionPath).toBe("AGENTS.md");
+		});
+	});
+
+	describe("buildSpawnCommand", () => {
+		test("includes --model flag", () => {
+			const opts: SpawnOpts = {
+				model: "sonnet",
+				permissionMode: "bypass",
+				cwd: "/tmp/worktree",
+				env: {},
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toBe("opencode --model sonnet");
+		});
+
+		test("permissionMode is ignored (opencode has no permission flag)", () => {
+			const bypass: SpawnOpts = {
+				model: "opus",
+				permissionMode: "bypass",
+				cwd: "/tmp",
+				env: {},
+			};
+			const ask: SpawnOpts = { ...bypass, permissionMode: "ask" };
+			expect(runtime.buildSpawnCommand(bypass)).toBe("opencode --model opus");
+			expect(runtime.buildSpawnCommand(ask)).toBe("opencode --model opus");
+		});
+
+		test("appendSystemPrompt is ignored (opencode has no such flag)", () => {
+			const opts: SpawnOpts = {
+				model: "sonnet",
+				permissionMode: "bypass",
+				cwd: "/tmp/worktree",
+				env: {},
+				appendSystemPrompt: "You are a builder agent.",
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toBe("opencode --model sonnet");
+			expect(cmd).not.toContain("append-system-prompt");
+			expect(cmd).not.toContain("You are a builder agent");
+		});
+
+		test("appendSystemPromptFile is ignored (opencode has no such flag)", () => {
+			const opts: SpawnOpts = {
+				model: "opus",
+				permissionMode: "bypass",
+				cwd: "/project",
+				env: {},
+				appendSystemPromptFile: "/project/.agentplate/specs/task.md",
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toBe("opencode --model opus");
+			expect(cmd).not.toContain("task.md");
+		});
+
+		test("cwd and env are not embedded in command string", () => {
+			const opts: SpawnOpts = {
+				model: "sonnet",
+				permissionMode: "bypass",
+				cwd: "/some/specific/path",
+				env: { OPENAI_API_KEY: "sk-test-123" },
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).not.toContain("/some/specific/path");
+			expect(cmd).not.toContain("sk-test-123");
+			expect(cmd).not.toContain("OPENAI_API_KEY");
+		});
+
+		test("all model names pass through unchanged", () => {
+			for (const model of ["sonnet", "opus", "haiku", "gpt-4o", "openrouter/gpt-5"]) {
+				const opts: SpawnOpts = {
+					model,
+					permissionMode: "bypass",
+					cwd: "/tmp",
+					env: {},
+				};
+				const cmd = runtime.buildSpawnCommand(opts);
+				expect(cmd).toContain(`--model ${model}`);
+			}
+		});
+
+		test("produces identical output for same inputs (deterministic)", () => {
+			const opts: SpawnOpts = {
+				model: "sonnet",
+				permissionMode: "bypass",
+				cwd: "/tmp/worktree",
+				env: {},
+			};
+			expect(runtime.buildSpawnCommand(opts)).toBe(runtime.buildSpawnCommand(opts));
+		});
+	});
+
+	describe("buildPrintCommand", () => {
+		test("basic command without model includes --prompt and --format json", () => {
+			const argv = runtime.buildPrintCommand("Summarize this diff");
+			expect(argv).toEqual(["opencode", "--prompt", "Summarize this diff", "--format", "json"]);
+		});
+
+		test("command with model override appends --model flag", () => {
+			const argv = runtime.buildPrintCommand("Classify this error", "haiku");
+			expect(argv).toEqual([
+				"opencode",
+				"--prompt",
+				"Classify this error",
+				"--format",
+				"json",
+				"--model",
+				"haiku",
+			]);
+		});
+
+		test("model undefined omits --model flag", () => {
+			const argv = runtime.buildPrintCommand("Hello", undefined);
+			expect(argv).not.toContain("--model");
+			expect(argv).toContain("--format");
+			expect(argv).toContain("json");
+		});
+
+		test("prompt is passed verbatim as a single argv element", () => {
+			const prompt = "Fix the bug in src/foo.ts line 42";
+			const argv = runtime.buildPrintCommand(prompt);
+			const promptIdx = argv.indexOf("--prompt");
+			expect(promptIdx).toBeGreaterThan(-1);
+			expect(argv[promptIdx + 1]).toBe(prompt);
+		});
+	});
+
+	describe("detectReady (stub)", () => {
+		test("returns loading for empty pane", () => {
+			expect(runtime.detectReady("")).toEqual({ phase: "loading" });
+		});
+
+		test("returns loading for any content (stub always returns loading)", () => {
+			expect(runtime.detectReady("OpenCode v1.0\n> ")).toEqual({ phase: "loading" });
+			expect(runtime.detectReady("ready")).toEqual({ phase: "loading" });
+			expect(runtime.detectReady("opencode started")).toEqual({ phase: "loading" });
+		});
+
+		test("never returns dialog phase", () => {
+			const state = runtime.detectReady("trust this folder?");
+			expect(state.phase).not.toBe("dialog");
+		});
+	});
+
+	describe("parseTranscript (stub)", () => {
+		let tempDir: string;
+
+		beforeEach(async () => {
+			tempDir = await mkdtemp(join(tmpdir(), "agentplate-opencode-transcript-test-"));
+		});
+
+		afterEach(async () => {
+			await cleanupTempDir(tempDir);
+		});
+
+		test("returns null for non-existent file", async () => {
+			const result = await runtime.parseTranscript(join(tempDir, "does-not-exist.jsonl"));
+			expect(result).toBeNull();
+		});
+
+		test("returns null for existing file (format not yet verified)", async () => {
+			const transcriptPath = join(tempDir, "session.jsonl");
+			await Bun.write(transcriptPath, `${JSON.stringify({ type: "result", tokens: 100 })}\n`);
+			const result = await runtime.parseTranscript(transcriptPath);
+			expect(result).toBeNull();
+		});
+
+		test("returns null for empty file", async () => {
+			const transcriptPath = join(tempDir, "empty.jsonl");
+			await Bun.write(transcriptPath, "");
+			const result = await runtime.parseTranscript(transcriptPath);
+			expect(result).toBeNull();
+		});
+	});
+
+	describe("getTranscriptDir (stub)", () => {
+		test("returns null (location not yet verified)", () => {
+			expect(runtime.getTranscriptDir("/some/project")).toBeNull();
+		});
+
+		test("returns null regardless of project root", () => {
+			expect(runtime.getTranscriptDir("/home/user/project")).toBeNull();
+			expect(runtime.getTranscriptDir("/tmp/test")).toBeNull();
+		});
+	});
+
+	describe("buildEnv", () => {
+		test("returns empty object when model has no env", () => {
+			const model: ResolvedModel = { model: "sonnet" };
+			expect(runtime.buildEnv(model)).toEqual({});
+		});
+
+		test("returns model.env when present", () => {
+			const model: ResolvedModel = {
+				model: "gpt-4o",
+				env: { OPENAI_API_KEY: "sk-test-123", OPENCODE_API_URL: "https://api.openai.com" },
+			};
+			expect(runtime.buildEnv(model)).toEqual({
+				OPENAI_API_KEY: "sk-test-123",
+				OPENCODE_API_URL: "https://api.openai.com",
+			});
+		});
+
+		test("returns empty object when model.env is undefined", () => {
+			const model: ResolvedModel = { model: "opus", env: undefined };
+			expect(runtime.buildEnv(model)).toEqual({});
+		});
+
+		test("env is safe to spread into session env", () => {
+			const model: ResolvedModel = { model: "sonnet" };
+			const env = runtime.buildEnv(model);
+			const combined = { ...env, AGENTPLATE_AGENT_NAME: "builder-1" };
+			expect(combined).toEqual({ AGENTPLATE_AGENT_NAME: "builder-1" });
+		});
+	});
+
+	describe("deployConfig", () => {
+		let tempDir: string;
+
+		beforeEach(async () => {
+			tempDir = await mkdtemp(join(tmpdir(), "agentplate-opencode-test-"));
+		});
+
+		afterEach(async () => {
+			await cleanupTempDir(tempDir);
+		});
+
+		test("writes overlay to AGENTS.md when provided", async () => {
+			const worktreePath = join(tempDir, "worktree");
+
+			await runtime.deployConfig(
+				worktreePath,
+				{ content: "# Agent Instructions\nYou are a builder." },
+				{ agentName: "test-builder", capability: "builder", worktreePath },
+			);
+
+			const content = await Bun.file(join(worktreePath, "AGENTS.md")).text();
+			expect(content).toBe("# Agent Instructions\nYou are a builder.");
+		});
+
+		test("creates worktree directory if it does not exist", async () => {
+			const worktreePath = join(tempDir, "new-worktree");
+
+			await runtime.deployConfig(
+				worktreePath,
+				{ content: "# Instructions" },
+				{ agentName: "test", capability: "builder", worktreePath },
+			);
+
+			const exists = await Bun.file(join(worktreePath, "AGENTS.md")).exists();
+			expect(exists).toBe(true);
+		});
+
+		test("skips overlay write when overlay is undefined", async () => {
+			const worktreePath = join(tempDir, "worktree");
+
+			await runtime.deployConfig(worktreePath, undefined, {
+				agentName: "coordinator",
+				capability: "coordinator",
+				worktreePath,
+			});
+
+			const exists = await Bun.file(join(worktreePath, "AGENTS.md")).exists();
+			expect(exists).toBe(false);
+		});
+
+		test("does not write settings.local.json (no hook deployment)", async () => {
+			const worktreePath = join(tempDir, "worktree");
+
+			await runtime.deployConfig(
+				worktreePath,
+				{ content: "# Instructions" },
+				{ agentName: "test-builder", capability: "builder", worktreePath },
+			);
+
+			const settingsExists = await Bun.file(
+				join(worktreePath, ".claude", "settings.local.json"),
+			).exists();
+			expect(settingsExists).toBe(false);
+		});
+
+		test("overwrites existing AGENTS.md", async () => {
+			const worktreePath = join(tempDir, "worktree");
+			await mkdir(worktreePath, { recursive: true });
+			await Bun.write(join(worktreePath, "AGENTS.md"), "old content");
+
+			await runtime.deployConfig(
+				worktreePath,
+				{ content: "new content" },
+				{ agentName: "test", capability: "builder", worktreePath },
+			);
+
+			const content = await Bun.file(join(worktreePath, "AGENTS.md")).text();
+			expect(content).toBe("new content");
+		});
+	});
+});
+
+describe("OpenCodeRuntime integration: registry resolves 'opencode'", () => {
+	test("getRuntime('opencode') returns OpenCodeRuntime", async () => {
+		const { getRuntime } = await import("./registry.ts");
+		const rt = getRuntime("opencode");
+		expect(rt).toBeInstanceOf(OpenCodeRuntime);
+		expect(rt.id).toBe("opencode");
+		expect(rt.instructionPath).toBe("AGENTS.md");
+	});
+});

package/src/runtimes/opencode.ts

@@ -0,0 +1,188 @@
+// OpenCode runtime adapter for agentplate's AgentRuntime interface.
+// Implements the AgentRuntime contract for the `opencode` CLI (SST OpenCode).
+//
+// Key differences from Claude/Pi adapters:
+// - Uses `opencode` CLI for interactive sessions
+// - Instruction file: AGENTS.md (unverified — needs confirmation against real OpenCode install)
+// - No hooks: OpenCode does not support Claude Code's hook mechanism
+// - detectReady is stubbed: real TUI patterns not yet observed
+// - parseTranscript returns null: output format not yet verified
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { ResolvedModel } from "../types.ts";
+import type {
+	AgentRuntime,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/**
+ * OpenCode runtime adapter.
+ *
+ * Implements AgentRuntime for the `opencode` CLI (SST OpenCode coding agent).
+ * Key differences from Claude Code:
+ * - Uses `--model` flag for model selection
+ * - Instruction file lives at `AGENTS.md` (unverified — confirm against real install)
+ * - No hooks deployment (OpenCode has no Claude Code hook mechanism)
+ * - `detectReady` is a stub — real TUI ready patterns not yet observed in tmux
+ * - `parseTranscript` returns null — `opencode` output format not yet verified
+ *
+ * TODO: Once a real OpenCode installation is available:
+ * 1. Verify `instructionPath` — run `opencode` and check which file it reads
+ * 2. Fill in `detectReady` — capture tmux pane content and match actual strings
+ * 3. Fill in `parseTranscript` — run `opencode run --format json` and inspect output
+ * 4. Fill in `getTranscriptDir` — check where OpenCode writes session files
+ */
+export class OpenCodeRuntime implements AgentRuntime {
+	/** Unique identifier for this runtime. */
+	readonly id = "opencode";
+
+	/** Stability level. OpenCode adapter is experimental — not fully validated. */
+	readonly stability = "experimental" as const;
+
+	/**
+	 * Relative path to the instruction file within a worktree.
+	 *
+	 * @stub Unverified — `AGENTS.md` is a common convention for terminal coding agents
+	 * but has not been confirmed against a real OpenCode installation.
+	 * Verify with `opencode --help` or OpenCode documentation before relying on this.
+	 */
+	readonly instructionPath = "AGENTS.md";
+
+	/**
+	 * Build the shell command string to spawn an interactive OpenCode agent in a tmux pane.
+	 *
+	 * Maps SpawnOpts to `opencode` CLI flags:
+	 * - `model` → `--model <model>`
+	 * - `permissionMode`, `appendSystemPrompt`, `appendSystemPromptFile` are IGNORED —
+	 *   the `opencode` CLI has no equivalent flags.
+	 *
+	 * The `cwd` and `env` fields of SpawnOpts are handled by the tmux session
+	 * creator, not embedded in the command string.
+	 *
+	 * @param opts - Spawn options (model used; others ignored)
+	 * @returns Shell command string suitable for tmux new-session -c
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		// permissionMode, appendSystemPrompt, appendSystemPromptFile are intentionally ignored.
+		// OpenCode has no equivalent flags for these options.
+		return `opencode --model ${opts.model}`;
+	}
+
+	/**
+	 * Build the argv array for a headless one-shot OpenCode invocation.
+	 *
+	 * Returns an argv array suitable for `Bun.spawn()`. The `--prompt` flag passes
+	 * the prompt and `--format json` requests structured JSON output.
+	 *
+	 * Used by merge/resolver.ts and watchdog/triage.ts for AI-assisted operations.
+	 *
+	 * @stub `--prompt` and `--format json` flags are unverified against real OpenCode CLI.
+	 * Run `opencode --help` to confirm flag names before use in production.
+	 *
+	 * @param prompt - The prompt to pass via `--prompt`
+	 * @param model - Optional model override
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["opencode", "--prompt", prompt, "--format", "json"];
+		if (model !== undefined) {
+			cmd.push("--model", model);
+		}
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions to a worktree.
+	 *
+	 * For OpenCode this writes only the instruction file:
+	 * - `AGENTS.md` — the agent's task-specific overlay.
+	 *   Skipped when overlay is undefined.
+	 *
+	 * The `hooks` parameter is unused — OpenCode does not support Claude Code's
+	 * hook mechanism, so no settings file is deployed.
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content to write as AGENTS.md, or undefined to skip
+	 * @param _hooks - Unused for OpenCode runtime
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		_hooks: HooksDef,
+	): Promise<void> {
+		if (overlay) {
+			await mkdir(worktreePath, { recursive: true });
+			await Bun.write(join(worktreePath, "AGENTS.md"), overlay.content);
+		}
+
+		// No hook deployment for OpenCode — the runtime has no hook mechanism.
+	}
+
+	/**
+	 * Detect OpenCode TUI readiness from a tmux pane content snapshot.
+	 *
+	 * @stub This method always returns `{ phase: "loading" }` because the real
+	 * TUI startup strings for OpenCode have not been observed in a live tmux session.
+	 * To implement: run `opencode` in tmux, capture pane content at startup, and
+	 * match strings unique to the ready state (version header, prompt character,
+	 * status bar content, etc.).
+	 *
+	 * @param _paneContent - Captured tmux pane content (unused until patterns are known)
+	 * @returns Always `{ phase: "loading" }` until real patterns are observed
+	 */
+	detectReady(_paneContent: string): ReadyState {
+		// STUB: Real OpenCode TUI ready patterns have not been observed.
+		// Fill in once someone runs OpenCode in tmux and captures the pane content.
+		return { phase: "loading" };
+	}
+
+	/**
+	 * Parse an OpenCode session transcript into normalized token usage.
+	 *
+	 * @stub Returns null unconditionally because the `opencode run --format json`
+	 * output format has not been verified. Do NOT guess at the format.
+	 * To implement: run `opencode run --format json` against a real OpenCode install,
+	 * inspect the NDJSON output, then add parsing logic here.
+	 *
+	 * @param _path - Path to transcript file (unused until format is known)
+	 * @returns Always null until transcript format is verified
+	 */
+	async parseTranscript(_path: string): Promise<TranscriptSummary | null> {
+		// STUB: OpenCode transcript format not yet verified.
+		// Fill in once `opencode run --format json` output is inspected.
+		return null;
+	}
+
+	/**
+	 * Return the transcript directory for OpenCode sessions.
+	 *
+	 * @stub Returns null because the location of OpenCode session files has not
+	 * been verified. Check where OpenCode writes session/history files
+	 * (e.g. `~/.opencode/`, `<project>/.opencode/`, or similar).
+	 *
+	 * @param _projectRoot - Absolute path to the project root (unused until known)
+	 * @returns Always null until transcript location is verified
+	 */
+	getTranscriptDir(_projectRoot: string): string | null {
+		// STUB: OpenCode transcript directory location not yet verified.
+		return null;
+	}
+
+	/**
+	 * Build runtime-specific environment variables for model/provider routing.
+	 *
+	 * Returns the provider environment variables from the resolved model, or an
+	 * empty object if none are set.
+	 *
+	 * @param model - Resolved model with optional provider env vars
+	 * @returns Environment variable map (may be empty)
+	 */
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return model.env ?? {};
+	}
+}