@colinmollenhour/occtl 1.0.0

package/dist/commands/session-share.js

@@ -0,0 +1,53 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { formatJSON } from "../format.js";
+export function sessionShareCommand() {
+    return new Command("share")
+        .description("Share a session and get a public URL")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output as JSON")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const result = await client.session.share({
+            path: { id: resolved },
+        });
+        if (!result.data) {
+            console.error("Failed to share session.");
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(formatJSON(result.data));
+            return;
+        }
+        if (result.data.share?.url) {
+            console.log(result.data.share.url);
+        }
+        else {
+            console.log(`Session ${resolved} shared.`);
+        }
+    });
+}
+export function sessionUnshareCommand() {
+    return new Command("unshare")
+        .description("Remove sharing from a session")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output as JSON")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const result = await client.session.unshare({
+            path: { id: resolved },
+        });
+        if (!result.data) {
+            console.error("Failed to unshare session.");
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(formatJSON(result.data));
+            return;
+        }
+        console.log(`Session ${resolved} unshared.`);
+    });
+}

package/dist/commands/session-status.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionStatusCommand(): Command;

package/dist/commands/session-status.js

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { formatJSON } from "../format.js";
+import { resolveSession } from "../resolve.js";
+export function sessionStatusCommand() {
+    return new Command("status")
+        .description("Get the status of sessions (idle, busy, retry)")
+        .argument("[session-id]", "Session ID (defaults to showing all statuses)")
+        .option("-j, --json", "Output as JSON")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const result = await client.session.status();
+        const statuses = result.data ?? {};
+        if (opts.json) {
+            if (sessionId) {
+                const resolved = await resolveSession(client, sessionId);
+                console.log(formatJSON(statuses[resolved] ?? { type: "idle" }));
+            }
+            else {
+                console.log(formatJSON(statuses));
+            }
+            return;
+        }
+        if (sessionId) {
+            const resolved = await resolveSession(client, sessionId);
+            const status = statuses[resolved];
+            if (!status) {
+                console.log(`${resolved}: idle`);
+            }
+            else {
+                console.log(`${resolved}: ${status.type}`);
+            }
+            return;
+        }
+        const entries = Object.entries(statuses);
+        if (entries.length === 0) {
+            console.log("No active session statuses.");
+            return;
+        }
+        console.log("SESSION\tSTATUS");
+        for (const [id, status] of entries) {
+            console.log(`${id}\t${status.type}`);
+        }
+    });
+}

package/dist/commands/session-summary.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionSummaryCommand(): Command;

package/dist/commands/session-summary.js

@@ -0,0 +1,87 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { formatJSON, extractText, truncate, formatTimeAgo, } from "../format.js";
+export function sessionSummaryCommand() {
+    return new Command("summary")
+        .description("Compact summary of a session: status, todo progress, last message snippet, cost")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output as JSON")
+        .option("-n, --snippet-length <chars>", "Max characters for last message snippet", parseInt, 200)
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        // Fetch session info, status, messages, and todos in parallel
+        const [sessionResult, statusResult, messagesResult, todoResult] = await Promise.all([
+            client.session.get({ path: { id: resolved } }),
+            client.session.status(),
+            client.session.messages({ path: { id: resolved } }),
+            client.session.todo({ path: { id: resolved } }),
+        ]);
+        const session = sessionResult.data;
+        const statuses = statusResult.data ?? {};
+        const messages = messagesResult.data ?? [];
+        const todos = todoResult.data ?? [];
+        // Compute status
+        const statusEntry = statuses[resolved];
+        const status = statusEntry?.type ?? "idle";
+        // Compute todo progress
+        const todoTotal = todos.length;
+        const todoCompleted = todos.filter((t) => t.status === "completed").length;
+        const todoInProgress = todos.filter((t) => t.status === "in_progress").length;
+        // Get last assistant message snippet
+        const assistantMsgs = messages.filter((m) => m.info.role === "assistant");
+        const lastAssistant = assistantMsgs[assistantMsgs.length - 1];
+        let lastSnippet = "";
+        if (lastAssistant) {
+            const text = extractText(lastAssistant.parts).trim();
+            lastSnippet = truncate(text, opts.snippetLength);
+        }
+        // Compute total cost
+        let totalCost = 0;
+        for (const m of messages) {
+            if (m.info.role === "assistant") {
+                const aMsg = m.info;
+                if (aMsg.cost)
+                    totalCost += aMsg.cost;
+            }
+        }
+        // Compute changes
+        const changes = session?.summary
+            ? `+${session.summary.additions} -${session.summary.deletions} (${session.summary.files} files)`
+            : "none";
+        const summary = {
+            sessionID: resolved,
+            title: session?.title || "(untitled)",
+            status,
+            updated: session?.time.updated
+                ? formatTimeAgo(session.time.updated)
+                : "unknown",
+            todos: {
+                total: todoTotal,
+                completed: todoCompleted,
+                inProgress: todoInProgress,
+                pending: todoTotal - todoCompleted - todoInProgress,
+            },
+            cost: `$${totalCost.toFixed(4)}`,
+            changes,
+            lastMessage: lastSnippet,
+        };
+        if (opts.json) {
+            console.log(formatJSON(summary));
+            return;
+        }
+        console.log(`Session:  ${summary.sessionID}`);
+        console.log(`Title:    ${summary.title}`);
+        console.log(`Status:   ${summary.status}`);
+        console.log(`Updated:  ${summary.updated}`);
+        if (todoTotal > 0) {
+            console.log(`Todos:    ${todoCompleted}/${todoTotal} done, ${todoInProgress} in progress`);
+        }
+        console.log(`Cost:     ${summary.cost}`);
+        console.log(`Changes:  ${summary.changes}`);
+        if (lastSnippet) {
+            console.log(`Last msg: ${lastSnippet}`);
+        }
+    });
+}

package/dist/commands/session-todo.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionTodoCommand(): Command;

package/dist/commands/session-todo.js

@@ -0,0 +1,41 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { formatJSON } from "../format.js";
+export function sessionTodoCommand() {
+    return new Command("todo")
+        .description("Get the todo list for a session")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output as JSON")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const result = await client.session.todo({
+            path: { id: resolved },
+        });
+        const todos = result.data ?? [];
+        if (opts.json) {
+            console.log(formatJSON(todos));
+            return;
+        }
+        if (todos.length === 0) {
+            console.log("No todos in session.");
+            return;
+        }
+        for (const todo of todos) {
+            const icon = todo.status === "completed"
+                ? "[x]"
+                : todo.status === "in_progress"
+                    ? "[>]"
+                    : todo.status === "cancelled"
+                        ? "[-]"
+                        : "[ ]";
+            const priority = todo.priority === "high"
+                ? "!"
+                : todo.priority === "low"
+                    ? " "
+                    : " ";
+            console.log(`${icon}${priority} ${todo.content}`);
+        }
+    });
+}

package/dist/commands/session-wait-for-text.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionWaitForTextCommand(): Command;

package/dist/commands/session-wait-for-text.js

@@ -0,0 +1,119 @@
+import { Command } from "commander";
+import { ensureServer, getClient } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { startStream } from "../sse.js";
+import { extractText } from "../format.js";
+export function sessionWaitForTextCommand() {
+    return new Command("wait-for-text")
+        .description("Silently wait until a message contains the given text, then output everything after it and exit 0")
+        .argument("<text>", "Text to wait for")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-t, --timeout <seconds>", "Timeout in seconds (exit 1 if not found)", parseInt)
+        .option("--no-check-existing", "Skip checking existing messages (only watch for new ones)")
+        .action(async (text, sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        // Shared found flag to prevent duplicate output from concurrent paths
+        let found = false;
+        const emitAndExit = (after) => {
+            if (found)
+                return;
+            found = true;
+            if (timer)
+                clearTimeout(timer);
+            process.stdout.write(after);
+            process.exit(0);
+        };
+        // Set up timeout if requested
+        let timer;
+        if (opts.timeout && opts.timeout > 0) {
+            timer = setTimeout(() => {
+                if (!found) {
+                    console.error("Timeout: text not found.");
+                    process.exit(1);
+                }
+            }, opts.timeout * 1000);
+        }
+        // Check existing messages first (default) to avoid race conditions.
+        if (opts.checkExisting !== false) {
+            const result = await client.session.messages({
+                path: { id: resolved },
+            });
+            const messages = result.data ?? [];
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const fullText = extractText(messages[i].parts);
+                const idx = fullText.indexOf(text);
+                if (idx !== -1) {
+                    emitAndExit(fullText.slice(idx + text.length).trimStart());
+                    return;
+                }
+            }
+        }
+        // Track how many times the session has gone idle without finding the text.
+        // After the session goes idle and a full message check finds nothing,
+        // exit with failure rather than hanging forever.
+        let idleCheckPending = false;
+        // Accumulate text per message to detect markers split across deltas
+        const messageBuffers = new Map();
+        const handle = startStream(resolved, (event) => {
+            if (found)
+                return "stop";
+            if (event.type === "message.part.updated") {
+                const props = event.properties;
+                if (props.part.type !== "text" || !props.delta)
+                    return;
+                const msgId = props.part.messageID;
+                const current = (messageBuffers.get(msgId) ?? "") + props.delta;
+                messageBuffers.set(msgId, current);
+                const idx = current.indexOf(text);
+                if (idx !== -1) {
+                    emitAndExit(current.slice(idx + text.length).trimStart());
+                    return "stop";
+                }
+            }
+            // When the session goes idle, do a full API check as fallback
+            if (event.type === "session.idle" && !idleCheckPending) {
+                idleCheckPending = true;
+                checkAllMessages(resolved, text).then((after) => {
+                    idleCheckPending = false;
+                    if (after !== null) {
+                        emitAndExit(after);
+                    }
+                    // If text not found after idle, the session might restart.
+                    // If it doesn't, the stream will eventually end or timeout
+                    // will fire.
+                }).catch(() => {
+                    idleCheckPending = false;
+                });
+            }
+        });
+        const streamResult = await handle.result;
+        if (!found) {
+            // Stream ended without finding the text
+            if (streamResult === "disconnected") {
+                console.error("Error: lost connection to OpenCode server.");
+            }
+            else {
+                console.error("Stream ended without finding text.");
+            }
+            if (timer)
+                clearTimeout(timer);
+            process.exit(1);
+        }
+    });
+}
+async function checkAllMessages(sessionId, text) {
+    const client = getClient();
+    const result = await client.session.messages({
+        path: { id: sessionId },
+    });
+    const messages = result.data ?? [];
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const fullText = extractText(messages[i].parts);
+        const idx = fullText.indexOf(text);
+        if (idx !== -1) {
+            return fullText.slice(idx + text.length).trimStart();
+        }
+    }
+    return null;
+}

package/dist/commands/session-wait.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+export declare function sessionWaitForIdleCommand(): Command;
+export declare function sessionWaitAnyCommand(): Command;
+export declare function sessionIsIdleCommand(): Command;

package/dist/commands/session-wait.js

@@ -0,0 +1,85 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { waitForIdle, waitForAnyIdle } from "../wait-util.js";
+import { formatJSON } from "../format.js";
+// ─── wait-for-idle ─────────────────────────────────────
+export function sessionWaitForIdleCommand() {
+    return new Command("wait-for-idle")
+        .description("Block until a session goes idle. Exits 0 when idle, 1 on timeout.")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-t, --timeout <seconds>", "Timeout in seconds (exit 1 if not idle in time)", parseInt)
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const timeoutMs = opts.timeout ? opts.timeout * 1000 : undefined;
+        const result = await waitForIdle(client, resolved, timeoutMs);
+        if (result.idle) {
+            process.exit(0);
+        }
+        if (result.reason === "timeout") {
+            console.error("Timeout: session did not go idle in time.");
+        }
+        else if (result.reason === "disconnected") {
+            console.error("Error: lost connection to OpenCode server.");
+        }
+        process.exit(1);
+    });
+}
+// ─── wait-any ──────────────────────────────────────────
+export function sessionWaitAnyCommand() {
+    return new Command("wait-any")
+        .description("Wait for the first of multiple sessions to go idle. Outputs the session ID that finished.")
+        .argument("<session-ids...>", "Two or more session IDs to watch")
+        .option("-t, --timeout <seconds>", "Timeout in seconds (exit 1 if none finish)", parseInt)
+        .option("-j, --json", "Output as JSON")
+        .action(async (sessionIds, opts) => {
+        const client = await ensureServer();
+        // Resolve all session IDs
+        const resolved = [];
+        for (const sid of sessionIds) {
+            resolved.push(await resolveSession(client, sid));
+        }
+        const timeoutMs = opts.timeout ? opts.timeout * 1000 : undefined;
+        const result = await waitForAnyIdle(client, resolved, timeoutMs);
+        if (result.sessionID) {
+            if (opts.json) {
+                console.log(formatJSON({ sessionID: result.sessionID, reason: result.reason }));
+            }
+            else {
+                console.log(result.sessionID);
+            }
+            process.exit(0);
+        }
+        if (result.reason === "timeout") {
+            console.error("Timeout: no session went idle in time.");
+        }
+        else if (result.reason === "disconnected") {
+            console.error("Error: lost connection to OpenCode server.");
+        }
+        process.exit(1);
+    });
+}
+// ─── is-idle ───────────────────────────────────────────
+export function sessionIsIdleCommand() {
+    return new Command("is-idle")
+        .description("Check if a session is idle (non-blocking). Exit 0 = idle, exit 1 = busy.")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output status as JSON")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const statusResult = await client.session.status();
+        const statuses = statusResult.data ?? {};
+        const current = statuses[resolved];
+        const isIdle = !current || current.type === "idle";
+        if (opts.json) {
+            console.log(formatJSON({
+                sessionID: resolved,
+                idle: isIdle,
+                status: current?.type ?? "idle",
+            }));
+        }
+        process.exit(isIdle ? 0 : 1);
+    });
+}

package/dist/commands/session-watch.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function sessionWatchCommand(): Command;

package/dist/commands/session-watch.js

@@ -0,0 +1,101 @@
+import { Command } from "commander";
+import { ensureServer } from "../client.js";
+import { resolveSession } from "../resolve.js";
+import { streamEvents } from "../sse.js";
+export function sessionWatchCommand() {
+    return new Command("watch")
+        .description("Watch a session for real-time updates")
+        .argument("[session-id]", "Session ID (defaults to most recent)")
+        .option("-j, --json", "Output events as JSON")
+        .option("-e, --events <types>", "Comma-separated event types to filter (e.g. message.updated,session.idle)")
+        .option("-t, --text-only", "Only show text content as it streams")
+        .action(async (sessionId, opts) => {
+        const client = await ensureServer();
+        const resolved = await resolveSession(client, sessionId);
+        const filterTypes = opts.events
+            ? opts.events.split(",").map((s) => s.trim())
+            : null;
+        console.error(`Watching session ${resolved}...`);
+        console.error("Press Ctrl+C to stop.\n");
+        const result = await streamEvents(resolved, (event) => {
+            if (filterTypes && !filterTypes.includes(event.type))
+                return;
+            if (opts.json) {
+                console.log(JSON.stringify(event));
+                return;
+            }
+            if (opts.textOnly) {
+                handleTextOnly(event);
+                return;
+            }
+            handleEvent(event);
+        });
+        if (result === "disconnected") {
+            console.error("\nConnection lost.");
+            process.exit(1);
+        }
+    });
+}
+function handleTextOnly(event) {
+    if (event.type === "message.part.updated") {
+        const props = event.properties;
+        if (props.part.type === "text" && props.delta) {
+            process.stdout.write(props.delta);
+        }
+    }
+}
+function handleEvent(event) {
+    const time = new Date().toLocaleTimeString();
+    switch (event.type) {
+        case "message.updated": {
+            const props = event.properties;
+            console.log(`[${time}] message.updated: ${props.info.role} ${props.info.id}`);
+            break;
+        }
+        case "message.part.updated": {
+            const props = event.properties;
+            if (props.part.type === "text" && props.delta) {
+                process.stdout.write(props.delta);
+            }
+            else if (props.part.type === "tool") {
+                console.log(`[${time}] tool: ${props.part.tool} [${props.part.state?.status}]`);
+            }
+            break;
+        }
+        case "session.status": {
+            const props = event.properties;
+            console.log(`[${time}] session.status: ${props.status.type}`);
+            break;
+        }
+        case "session.idle": {
+            console.log(`\n[${time}] session.idle`);
+            break;
+        }
+        case "permission.updated": {
+            const props = event.properties;
+            console.log(`\n[${time}] PERMISSION REQUEST: ${props.title} (id: ${props.id}, type: ${props.type})`);
+            break;
+        }
+        case "todo.updated": {
+            const props = event.properties;
+            console.log(`[${time}] todo.updated:`);
+            for (const todo of props.todos) {
+                const icon = todo.status === "completed"
+                    ? "[x]"
+                    : todo.status === "in_progress"
+                        ? "[>]"
+                        : "[ ]";
+                console.log(`  ${icon} ${todo.content}`);
+            }
+            break;
+        }
+        case "session.error": {
+            const props = event.properties;
+            console.log(`[${time}] ERROR: ${props.error?.name || "unknown"}`);
+            break;
+        }
+        default: {
+            console.log(`[${time}] ${event.type}`);
+        }
+    }
+}

package/dist/commands/skill.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function installSkillCommand(): Command;
+export declare function viewSkillCommand(): Command;

package/dist/commands/skill.js

@@ -0,0 +1,55 @@
+import { Command } from "commander";
+import { readFileSync, mkdirSync, copyFileSync, existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function getSkillPath() {
+    // SKILL.md lives at the package root, two levels up from dist/commands/
+    return resolve(__dirname, "..", "..", "SKILL.md");
+}
+function getInstallDir() {
+    const home = process.env.HOME || process.env.USERPROFILE || "~";
+    return join(home, ".config", "opencode", "skills", "occtl");
+}
+export function installSkillCommand() {
+    return new Command("install-skill")
+        .description("Install the occtl skill as an OpenCode user-level skill")
+        .option("-f, --force", "Overwrite existing skill if present")
+        .action(async (opts) => {
+        const src = getSkillPath();
+        if (!existsSync(src)) {
+            console.error(`SKILL.md not found at ${src}`);
+            process.exit(1);
+        }
+        const destDir = getInstallDir();
+        const dest = join(destDir, "SKILL.md");
+        if (existsSync(dest) && !opts.force) {
+            console.error(`Skill already installed at ${destDir}`);
+            console.error("Use --force to overwrite.");
+            process.exit(1);
+        }
+        mkdirSync(destDir, { recursive: true });
+        copyFileSync(src, dest);
+        console.log(`Installed occtl skill to ${destDir}`);
+        console.log("Restart OpenCode to pick up the new skill.");
+    });
+}
+export function viewSkillCommand() {
+    return new Command("view-skill")
+        .description("Display the occtl SKILL.md contents")
+        .option("--path", "Only print the path to SKILL.md")
+        .action(async (opts) => {
+        const src = getSkillPath();
+        if (!existsSync(src)) {
+            console.error(`SKILL.md not found at ${src}`);
+            process.exit(1);
+        }
+        if (opts.path) {
+            console.log(src);
+            return;
+        }
+        const content = readFileSync(src, "utf-8");
+        console.log(content);
+    });
+}

package/dist/commands/worktree.d.ts

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+export declare function worktreeListCommand(): Command;
+export declare function worktreeCreateCommand(): Command;
+export declare function worktreeRemoveCommand(): Command;
+export declare function worktreeRunCommand(): Command;