@colinmollenhour/occtl 1.0.0

package/dist/commands/worktree.js

@@ -0,0 +1,359 @@
+import { Command } from "commander";
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { resolve, basename } from "path";
+import { ensureServer } from "../client.js";
+import { formatJSON, formatMessage } from "../format.js";
+import { startStream } from "../sse.js";
+import { waitForIdle } from "../wait-util.js";
+function getRepoRoot() {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf-8",
+            timeout: 5000,
+        }).trim();
+    }
+    catch {
+        console.error("Error: Not inside a git repository.");
+        process.exit(1);
+    }
+}
+function parseWorktreeList() {
+    try {
+        const output = execFileSync("git", ["worktree", "list", "--porcelain"], {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        const worktrees = [];
+        let current = {};
+        for (const line of output.split("\n")) {
+            if (line.startsWith("worktree ")) {
+                if (current.path)
+                    worktrees.push(current);
+                current = { path: line.slice(9) };
+            }
+            else if (line.startsWith("HEAD ")) {
+                current.head = line.slice(5);
+            }
+            else if (line.startsWith("branch ")) {
+                current.branch = line.slice(7).replace("refs/heads/", "");
+            }
+            else if (line === "bare") {
+                current.bare = true;
+            }
+            else if (line === "detached") {
+                current.branch = "(detached)";
+            }
+        }
+        if (current.path)
+            worktrees.push(current);
+        return worktrees;
+    }
+    catch {
+        console.error("Error: Failed to list git worktrees.");
+        process.exit(1);
+    }
+}
+function getWorktreeDir() {
+    const root = getRepoRoot();
+    return resolve(root, ".occtl", "worktrees");
+}
+/**
+ * Create a git worktree. Uses execFileSync (no shell) to prevent injection.
+ */
+function createWorktree(wtPath, branch, base) {
+    try {
+        execFileSync("git", ["worktree", "add", wtPath, "-b", branch, base], {
+            encoding: "utf-8",
+            stdio: "pipe",
+            timeout: 30000,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("already exists")) {
+            try {
+                execFileSync("git", ["worktree", "add", wtPath, branch], {
+                    encoding: "utf-8",
+                    stdio: "pipe",
+                    timeout: 30000,
+                });
+            }
+            catch (err2) {
+                const msg2 = err2 instanceof Error ? err2.message : String(err2);
+                console.error(`Failed to create worktree: ${msg2}`);
+                process.exit(1);
+            }
+        }
+        else {
+            console.error(`Failed to create worktree: ${msg}`);
+            process.exit(1);
+        }
+    }
+}
+// ─── list ──────────────────────────────────────────────
+export function worktreeListCommand() {
+    return new Command("list")
+        .alias("ls")
+        .description("List git worktrees and any associated sessions")
+        .option("-j, --json", "Output as JSON")
+        .action(async (opts) => {
+        const worktrees = parseWorktreeList();
+        if (opts.json) {
+            console.log(formatJSON(worktrees));
+            return;
+        }
+        if (worktrees.length === 0) {
+            console.log("No worktrees found.");
+            return;
+        }
+        console.log("PATH\tBRANCH\tHEAD");
+        for (const wt of worktrees) {
+            console.log(`${wt.path}\t${wt.branch || "(bare)"}\t${(wt.head || "").slice(0, 8)}`);
+        }
+    });
+}
+// ─── create ────────────────────────────────────────────
+export function worktreeCreateCommand() {
+    return new Command("create")
+        .description("Create a git worktree and optionally a session in it")
+        .argument("<name>", "Worktree name (used as directory and branch name)")
+        .option("-b, --branch <branch>", "Branch name (defaults to worktree-<name>)")
+        .option("--base <ref>", "Base ref to branch from (defaults to HEAD)")
+        .option("--no-session", "Don't create a session in the worktree")
+        .option("-j, --json", "Output as JSON")
+        .option("-q, --quiet", "Only output the worktree path")
+        .action(async (name, opts) => {
+        const wtDir = getWorktreeDir();
+        const wtPath = resolve(wtDir, name);
+        const branch = opts.branch || `worktree-${name}`;
+        const base = opts.base || "HEAD";
+        if (existsSync(wtPath)) {
+            console.error(`Worktree already exists at ${wtPath}`);
+            process.exit(1);
+        }
+        createWorktree(wtPath, branch, base);
+        const result = {
+            path: wtPath,
+            branch,
+            name,
+        };
+        // Optionally create a session in the worktree directory
+        if (opts.session !== false) {
+            try {
+                const client = await ensureServer();
+                const session = await client.session.create({
+                    body: { title: `worktree: ${name}` },
+                    query: { directory: wtPath },
+                });
+                if (session.data) {
+                    result.sessionID = session.data.id;
+                }
+            }
+            catch {
+                // Server might not be running — that's OK, just skip session
+            }
+        }
+        if (opts.quiet) {
+            console.log(wtPath);
+            return;
+        }
+        if (opts.json) {
+            console.log(formatJSON(result));
+            return;
+        }
+        console.log(`Created worktree: ${wtPath}`);
+        console.log(`Branch: ${branch}`);
+        if (result.sessionID) {
+            console.log(`Session: ${result.sessionID}`);
+        }
+    });
+}
+// ─── remove ────────────────────────────────────────────
+export function worktreeRemoveCommand() {
+    return new Command("remove")
+        .alias("rm")
+        .description("Remove a git worktree")
+        .argument("<name>", "Worktree name or path")
+        .option("-f, --force", "Force removal even if dirty")
+        .action(async (name, opts) => {
+        let wtPath;
+        const candidate = resolve(getWorktreeDir(), name);
+        if (existsSync(candidate)) {
+            wtPath = candidate;
+        }
+        else if (existsSync(name)) {
+            wtPath = resolve(name);
+        }
+        else {
+            const worktrees = parseWorktreeList();
+            const match = worktrees.find((wt) => basename(wt.path) === name || wt.path.endsWith(`/${name}`));
+            if (match) {
+                wtPath = match.path;
+            }
+            else {
+                console.error(`Worktree not found: ${name}`);
+                process.exit(1);
+            }
+        }
+        const args = ["worktree", "remove", wtPath];
+        if (opts.force)
+            args.push("--force");
+        try {
+            execFileSync("git", args, {
+                encoding: "utf-8",
+                stdio: "pipe",
+                timeout: 30000,
+            });
+            console.log(`Removed worktree: ${wtPath}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Failed to remove worktree: ${msg}`);
+            process.exit(1);
+        }
+    });
+}
+// ─── run ───────────────────────────────────────────────
+export function worktreeRunCommand() {
+    return new Command("run")
+        .description("Create a worktree, start a session, send a prompt, and optionally wait")
+        .argument("<name>", "Worktree name")
+        .argument("<message...>", "Prompt message to send")
+        .option("-b, --branch <branch>", "Branch name (defaults to worktree-<name>)")
+        .option("--base <ref>", "Base ref to branch from (defaults to HEAD)")
+        .option("-w, --wait", "Block until the session goes idle, then show the result")
+        .option("--auto-approve", "Auto-approve all permission requests")
+        .option("--model <model>", "Model to use (format: provider/model)")
+        .option("--agent <agent>", "Agent to use")
+        .option("-j, --json", "Output as JSON")
+        .option("-t, --text-only", "Show only text content")
+        .option("--stdin", "Read message from stdin")
+        .action(async (name, messageParts, opts) => {
+        const client = await ensureServer();
+        // Create the worktree
+        const wtDir = getWorktreeDir();
+        const wtPath = resolve(wtDir, name);
+        const branch = opts.branch || `worktree-${name}`;
+        const base = opts.base || "HEAD";
+        if (!existsSync(wtPath)) {
+            createWorktree(wtPath, branch, base);
+            console.error(`Created worktree: ${wtPath} (branch: ${branch})`);
+        }
+        else {
+            console.error(`Using existing worktree: ${wtPath}`);
+        }
+        // Create a session in the worktree directory
+        const session = await client.session.create({
+            body: { title: `worktree: ${name}` },
+            query: { directory: wtPath },
+        });
+        if (!session.data) {
+            console.error("Failed to create session.");
+            process.exit(1);
+        }
+        const sid = session.data.id;
+        console.error(`Session: ${sid}`);
+        // Build the message
+        let messageText;
+        if (opts.stdin) {
+            const chunks = [];
+            for await (const chunk of process.stdin) {
+                chunks.push(chunk);
+            }
+            messageText = Buffer.concat(chunks).toString("utf-8").trim();
+        }
+        else {
+            messageText = messageParts.join(" ");
+        }
+        // Parse model
+        let model;
+        if (opts.model) {
+            const parts = opts.model.split("/");
+            if (parts.length === 2 && parts[0] && parts[1]) {
+                model = { providerID: parts[0], modelID: parts[1] };
+            }
+        }
+        const body = {
+            parts: [{ type: "text", text: messageText }],
+            ...(model && { model }),
+            ...(opts.agent && { agent: opts.agent }),
+        };
+        // Start auto-approve in background if requested.
+        // Uses startStream which returns a cancel handle.
+        let approveHandle;
+        if (opts.autoApprove) {
+            approveHandle = startStream(sid, async (event) => {
+                if (event.type !== "permission.updated")
+                    return;
+                const props = event.properties;
+                if (props.status && props.status !== "pending")
+                    return;
+                try {
+                    await client.postSessionIdPermissionsPermissionId({
+                        path: { id: sid, permissionID: props.id },
+                        body: { response: "once" },
+                    });
+                    console.error(`Auto-approved: ${props.id}`);
+                }
+                catch (err) {
+                    console.error(`Failed to auto-approve ${props.id}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            });
+        }
+        // Send the prompt
+        await client.session.promptAsync({
+            path: { id: sid },
+            body,
+        });
+        console.error("Prompt sent.");
+        if (!opts.wait) {
+            const output = { sessionID: sid, worktree: wtPath, branch };
+            if (opts.json) {
+                console.log(formatJSON(output));
+            }
+            else {
+                console.log(`Session ${sid} started in ${wtPath}`);
+                if (approveHandle) {
+                    console.log("Auto-approve is active. Press Ctrl+C to stop.");
+                    // Keep running — the auto-approve stream keeps the event loop alive
+                    return;
+                }
+            }
+            // Clean up auto-approve if not keeping it running
+            approveHandle?.cancel();
+            return;
+        }
+        // --wait: use race-safe waitForIdle
+        const waitResult = await waitForIdle(client, sid);
+        // Clean up auto-approve
+        approveHandle?.cancel();
+        if (!waitResult.idle) {
+            if (waitResult.reason === "disconnected") {
+                console.error("Error: lost connection to OpenCode server.");
+            }
+            process.exit(1);
+        }
+        // Fetch the last assistant message
+        const msgs = await client.session.messages({
+            path: { id: sid },
+        });
+        const messages = msgs.data ?? [];
+        const last = messages.filter((m) => m.info.role === "assistant").pop();
+        if (!last) {
+            console.error("No assistant response.");
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(formatJSON({
+                sessionID: sid,
+                worktree: wtPath,
+                branch,
+                response: last,
+            }));
+            return;
+        }
+        const textOnly = opts.textOnly !== false;
+        console.log(formatMessage(last.info, last.parts, { textOnly }));
+    });
+}

package/dist/format.d.ts

@@ -0,0 +1,19 @@
+import type { Session, Message, Part, AssistantMessage, UserMessage } from "@opencode-ai/sdk";
+export declare function formatTime(ts: number): string;
+export declare function formatTimeAgo(ts: number): string;
+export declare function truncate(str: string, max: number): string;
+export declare function formatSession(session: Session): string;
+export declare function formatSessionDetailed(session: Session): string;
+export declare function isUserMessage(msg: Message): msg is UserMessage;
+export declare function isAssistantMessage(msg: Message): msg is AssistantMessage;
+export declare function extractText(parts: Part[]): string;
+export declare function extractToolCalls(parts: Part[]): Array<{
+    tool: string;
+    status: string;
+    title?: string;
+}>;
+export declare function formatMessage(msg: Message, parts: Part[], opts?: {
+    verbose?: boolean;
+    textOnly?: boolean;
+}): string;
+export declare function formatJSON(data: unknown): string;

package/dist/format.js

@@ -0,0 +1,115 @@
+export function formatTime(ts) {
+    return new Date(ts).toLocaleString();
+}
+export function formatTimeAgo(ts) {
+    const diff = Math.max(0, Date.now() - ts);
+    const seconds = Math.floor(diff / 1000);
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+export function truncate(str, max) {
+    if (str.length <= max)
+        return str;
+    return str.slice(0, max - 3) + "...";
+}
+export function formatSession(session) {
+    const parts = [
+        session.id,
+        truncate(session.title || "(untitled)", 50),
+        formatTimeAgo(session.time.updated),
+    ];
+    return parts.join("\t");
+}
+export function formatSessionDetailed(session) {
+    const lines = [];
+    lines.push(`ID:        ${session.id}`);
+    lines.push(`Title:     ${session.title || "(untitled)"}`);
+    lines.push(`Directory: ${session.directory}`);
+    lines.push(`Created:   ${formatTime(session.time.created)}`);
+    lines.push(`Updated:   ${formatTime(session.time.updated)}`);
+    if (session.parentID) {
+        lines.push(`Parent:    ${session.parentID}`);
+    }
+    if (session.share?.url) {
+        lines.push(`Share URL: ${session.share.url}`);
+    }
+    if (session.summary) {
+        lines.push(`Changes:   +${session.summary.additions} -${session.summary.deletions} (${session.summary.files} files)`);
+    }
+    return lines.join("\n");
+}
+export function isUserMessage(msg) {
+    return msg.role === "user";
+}
+export function isAssistantMessage(msg) {
+    return msg.role === "assistant";
+}
+export function extractText(parts) {
+    const textParts = parts.filter((p) => p.type === "text");
+    return textParts.map((p) => p.text).join("\n");
+}
+export function extractToolCalls(parts) {
+    return parts
+        .filter((p) => p.type === "tool")
+        .map((p) => {
+        const toolPart = p;
+        return {
+            tool: toolPart.tool,
+            status: toolPart.state?.status ?? "unknown",
+            title: toolPart.state?.title,
+        };
+    });
+}
+export function formatMessage(msg, parts, opts = {}) {
+    const lines = [];
+    const role = msg.role.toUpperCase();
+    const time = formatTime(msg.time.created);
+    if (opts.textOnly) {
+        const text = extractText(parts);
+        if (text)
+            lines.push(text);
+        return lines.join("\n");
+    }
+    lines.push(`--- ${role} [${time}] ---`);
+    if (isAssistantMessage(msg)) {
+        lines.push(`Model: ${msg.providerID}/${msg.modelID}`);
+        if (msg.cost > 0) {
+            lines.push(`Cost: $${msg.cost.toFixed(6)}`);
+        }
+        if (msg.tokens) {
+            lines.push(`Tokens: in=${msg.tokens.input} out=${msg.tokens.output}` +
+                (msg.tokens.reasoning ? ` reasoning=${msg.tokens.reasoning}` : "") +
+                (msg.tokens.cache.read ? ` cache_read=${msg.tokens.cache.read}` : ""));
+        }
+        if (msg.error) {
+            lines.push(`Error: ${msg.error.name}`);
+        }
+    }
+    const text = extractText(parts);
+    if (text) {
+        lines.push("");
+        lines.push(text);
+    }
+    if (opts.verbose) {
+        const tools = extractToolCalls(parts);
+        if (tools.length > 0) {
+            lines.push("");
+            lines.push("Tool calls:");
+            for (const t of tools) {
+                lines.push(`  - ${t.tool} [${t.status}]${t.title ? ` ${t.title}` : ""}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+export function formatJSON(data) {
+    return JSON.stringify(data, null, 2);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { sessionListCommand } from "./commands/session-list.js";
+import { sessionGetCommand } from "./commands/session-get.js";
+import { sessionMessagesCommand } from "./commands/session-messages.js";
+import { sessionLastCommand } from "./commands/session-last.js";
+import { sessionStatusCommand } from "./commands/session-status.js";
+import { sessionWatchCommand } from "./commands/session-watch.js";
+import { sessionSendCommand } from "./commands/session-send.js";
+import { sessionRespondCommand } from "./commands/session-respond.js";
+import { sessionTodoCommand } from "./commands/session-todo.js";
+import { sessionAbortCommand } from "./commands/session-abort.js";
+import { sessionDiffCommand } from "./commands/session-diff.js";
+import { sessionChildrenCommand } from "./commands/session-children.js";
+import { sessionCreateCommand } from "./commands/session-create.js";
+import { sessionShareCommand, sessionUnshareCommand } from "./commands/session-share.js";
+import { sessionWaitForTextCommand } from "./commands/session-wait-for-text.js";
+import { sessionWaitForIdleCommand, sessionWaitAnyCommand, sessionIsIdleCommand, } from "./commands/session-wait.js";
+import { sessionSummaryCommand } from "./commands/session-summary.js";
+import { worktreeListCommand, worktreeCreateCommand, worktreeRemoveCommand, worktreeRunCommand, } from "./commands/worktree.js";
+import { installSkillCommand, viewSkillCommand } from "./commands/skill.js";
+const program = new Command();
+program
+    .name("occtl")
+    .description("Extended CLI for managing OpenCode sessions.\n\n" +
+    "Auto-detects running OpenCode server, or set:\n" +
+    "  OPENCODE_SERVER_HOST  (default: 127.0.0.1)\n" +
+    "  OPENCODE_SERVER_PORT  (default: 4096)")
+    .version("1.0.0");
+// Session commands (top-level)
+program.addCommand(sessionListCommand());
+program.addCommand(sessionCreateCommand());
+program.addCommand(sessionGetCommand());
+program.addCommand(sessionMessagesCommand());
+program.addCommand(sessionLastCommand());
+program.addCommand(sessionStatusCommand());
+program.addCommand(sessionWatchCommand());
+program.addCommand(sessionSendCommand());
+program.addCommand(sessionRespondCommand());
+program.addCommand(sessionTodoCommand());
+program.addCommand(sessionAbortCommand());
+program.addCommand(sessionDiffCommand());
+program.addCommand(sessionChildrenCommand());
+program.addCommand(sessionShareCommand());
+program.addCommand(sessionUnshareCommand());
+program.addCommand(sessionWaitForTextCommand());
+program.addCommand(sessionWaitForIdleCommand());
+program.addCommand(sessionWaitAnyCommand());
+program.addCommand(sessionIsIdleCommand());
+program.addCommand(sessionSummaryCommand());
+// Worktree subcommand group
+const worktree = program
+    .command("worktree")
+    .alias("wt")
+    .description("Manage git worktrees for parallel session isolation");
+worktree.addCommand(worktreeListCommand());
+worktree.addCommand(worktreeCreateCommand());
+worktree.addCommand(worktreeRemoveCommand());
+worktree.addCommand(worktreeRunCommand());
+// Skill management (top-level)
+program.addCommand(installSkillCommand());
+program.addCommand(viewSkillCommand());
+program.parse();

package/dist/resolve.d.ts

@@ -0,0 +1,6 @@
+import type { OpencodeClient } from "@opencode-ai/sdk";
+/**
+ * Resolve a session ID. If none is provided, returns the most recently updated session.
+ * Also supports partial ID matching.
+ */
+export declare function resolveSession(client: OpencodeClient, sessionId?: string): Promise<string>;

package/dist/resolve.js

@@ -0,0 +1,47 @@
+/**
+ * Resolve a session ID. If none is provided, returns the most recently updated session.
+ * Also supports partial ID matching.
+ */
+export async function resolveSession(client, sessionId) {
+    if (!sessionId) {
+        // Get most recent session
+        const result = await client.session.list();
+        const sessions = (result.data ?? []).filter((s) => !s.parentID);
+        if (sessions.length === 0) {
+            console.error("No sessions found.");
+            process.exit(1);
+        }
+        // Sessions are sorted by most recently updated
+        return sessions[0].id;
+    }
+    // Try exact match first
+    try {
+        const result = await client.session.get({
+            path: { id: sessionId },
+        });
+        if (result.data) {
+            return result.data.id;
+        }
+    }
+    catch {
+        // Fall through to partial match
+    }
+    // Try partial match
+    const result = await client.session.list();
+    const sessions = result.data ?? [];
+    const matches = sessions.filter((s) => s.id.startsWith(sessionId) ||
+        s.id.includes(sessionId) ||
+        (s.title && s.title.toLowerCase().includes(sessionId.toLowerCase())));
+    if (matches.length === 0) {
+        console.error(`No session found matching: ${sessionId}`);
+        process.exit(1);
+    }
+    if (matches.length > 1) {
+        console.error(`Ambiguous session ID "${sessionId}", matches:`);
+        for (const m of matches.slice(0, 5)) {
+            console.error(`  ${m.id}  ${m.title || "(untitled)"}`);
+        }
+        process.exit(1);
+    }
+    return matches[0].id;
+}

package/dist/sse.d.ts

@@ -0,0 +1,40 @@
+import type { Event } from "@opencode-ai/sdk";
+export type StreamResult = "stopped" | "disconnected";
+/**
+ * Extract the session ID from an event, checking all known locations.
+ */
+export declare function getEventSessionId(event: Event): string | undefined;
+/**
+ * Check if an SSE event belongs to a given session.
+ */
+export declare function isSessionEvent(event: Event, sessionId: string): boolean;
+/**
+ * Connect to the OpenCode SSE event stream and invoke a callback for each
+ * parsed event that matches the given session.
+ *
+ * Returns "stopped" if the callback returned "stop", or "disconnected" if
+ * the stream ended unexpectedly.
+ */
+export declare function streamEvents(sessionId: string, onEvent: (event: Event) => void | "stop" | Promise<void | "stop">): Promise<StreamResult>;
+export interface StreamHandle {
+    /** Promise that resolves when the stream ends. */
+    result: Promise<StreamResult>;
+    /** Cancel the stream. */
+    cancel: () => void;
+    /** Resolves when the SSE connection is established. */
+    connected: Promise<void>;
+}
+/**
+ * Connect to the SSE stream and return a handle with cancel + connected signal.
+ * This is the low-level version for callers that need to coordinate startup.
+ */
+export declare function startStream(sessionId: string, onEvent: (event: Event) => void | "stop" | Promise<void | "stop">): StreamHandle;
+/**
+ * Start an SSE stream (unfiltered) and return a handle with cancel + connected signal.
+ */
+export declare function startAllStream(onEvent: (event: Event) => void | "stop" | Promise<void | "stop">): StreamHandle;
+/**
+ * Connect to the SSE stream and invoke callback for ALL events (unfiltered).
+ * Returns "stopped" or "disconnected".
+ */
+export declare function streamAllEvents(onEvent: (event: Event) => void | "stop" | Promise<void | "stop">): Promise<StreamResult>;