toc-ocra 0.2.0

package/dist/src/runtime/cli/hydrate-shell-path.js

@@ -0,0 +1,173 @@
+import { spawn } from 'node:child_process';
+import { delimiter } from 'node:path';
+// Why: GUI-launched Electron on macOS/Linux inherits a minimal PATH from launchd
+// that does not include dirs appended by the user's shell rc files (~/.zshrc,
+// ~/.bashrc). Tools installed into ~/.opencode/bin, ~/.cargo/bin, pyenv/volta
+// shims, and countless other user-local locations end up invisible to our
+// `which` probe even though they work fine from Terminal (see stablyai/orca#829).
+//
+// Rather than play whack-a-mole adding every agent's install dir to a hardcoded
+// list, we spawn the user's login shell once per app session and read the PATH
+// it would export. This matches the behavior of every popular Electron app that
+// handles this problem (Hyper, VS Code, Cursor, etc. via shell-env/fix-path) —
+// we implement it inline to avoid adding a dependency.
+const DELIMITER = '__ORCA_SHELL_PATH__';
+const SPAWN_TIMEOUT_MS = 5000;
+// ANSI escape sequences can leak into the captured output when the user's rc
+// files print banners or set colored prompts. Strip them before parsing.
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/g; // eslint-disable-line no-control-regex
+let cached = null;
+/** @internal - tests need a clean hydration cache between cases. */
+export function _resetHydrateShellPathCache() {
+    cached = null;
+}
+function pickShell() {
+    if (process.platform === 'win32') {
+        return null;
+    }
+    const shell = process.env.SHELL;
+    if (shell && shell.length > 0) {
+        return shell;
+    }
+    return process.platform === 'darwin' ? '/bin/zsh' : '/bin/bash';
+}
+function parseCapturedPath(stdout) {
+    const cleaned = stdout.replace(ANSI_RE, '');
+    const first = cleaned.indexOf(DELIMITER);
+    if (first < 0) {
+        return [];
+    }
+    const second = cleaned.indexOf(DELIMITER, first + DELIMITER.length);
+    if (second < 0) {
+        return [];
+    }
+    const value = cleaned.slice(first + DELIMITER.length, second).trim();
+    if (!value) {
+        return [];
+    }
+    // Why: Set preserves insertion order, and PATH resolution is first-match-wins,
+    // so de-duping this way keeps the user's rc-file ordering intact.
+    return [
+        ...new Set(value
+            .split(delimiter)
+            .map((s) => s.trim())
+            .filter(Boolean))
+    ];
+}
+function spawnShellAndReadPath(shell) {
+    return new Promise((resolve) => {
+        // Why: printing $PATH between delimiters is resilient to rc-file banners,
+        // MOTDs, and `echo` invocations that shells like fish print unprompted.
+        // `-ilc` runs the shell as a login+interactive so both .profile/.zprofile
+        // and .bashrc/.zshrc are sourced — matches what `which` in Terminal sees.
+        const command = `printf '%s' '${DELIMITER}'; printf '%s' "$PATH"; printf '%s' '${DELIMITER}'`;
+        let finished = false;
+        let stdout = '';
+        let timer = null;
+        const child = spawn(shell, ['-ilc', command], {
+            // Why: inherit current env so the shell sees the same baseline, then let
+            // it layer its own rc files on top. Do NOT forward stdio — some shells
+            // (oh-my-zsh setups, powerlevel10k) print a lot to stderr on startup,
+            // and we don't want that in Orca's console.
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            detached: false
+        });
+        const cleanup = () => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            child.stdout.off('data', onStdoutData);
+            child.off('error', onError);
+            child.off('close', onClose);
+        };
+        const finish = (result) => {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            cleanup();
+            resolve(result);
+        };
+        timer = setTimeout(() => {
+            // Why: slow rc files (corporate env setup, nvm eager init) can exceed
+            // our budget. Kill the shell and fall back to process.env rather than
+            // blocking the Agents pane indefinitely.
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // ignore
+            }
+            finish({ segments: [], ok: false, failureReason: 'timeout' });
+        }, SPAWN_TIMEOUT_MS);
+        const onStdoutData = (chunk) => {
+            stdout += chunk.toString('utf8');
+        };
+        const onError = () => {
+            finish({ segments: [], ok: false, failureReason: 'spawn_error' });
+        };
+        const onClose = () => {
+            const segments = parseCapturedPath(stdout);
+            if (segments.length === 0) {
+                finish({ segments: [], ok: false, failureReason: 'empty_path' });
+                return;
+            }
+            finish({ segments, ok: true, failureReason: 'none' });
+        };
+        child.stdout.on('data', onStdoutData);
+        child.on('error', onError);
+        child.on('close', onClose);
+    });
+}
+/**
+ * Spawn the user's login shell once and return the PATH it would export.
+ * Caches the promise for the lifetime of the process — call
+ * `_resetHydrateShellPathCache()` in tests or `hydrateShellPath({ force: true })`
+ * when the user asks to re-probe (e.g. after installing a new CLI).
+ */
+export function hydrateShellPath(options = {}) {
+    if (cached && !options.force) {
+        return cached;
+    }
+    const shell = options.shellOverride !== undefined ? options.shellOverride : pickShell();
+    if (!shell) {
+        // Windows uses cmd/PowerShell rather than a POSIX login shell — the
+        // `patchPackagedProcessPath` static list is sufficient there.
+        cached = Promise.resolve({ segments: [], ok: false, failureReason: 'no_shell' });
+        return cached;
+    }
+    cached = (options.spawner ?? spawnShellAndReadPath)(shell);
+    return cached;
+}
+/**
+ * Promote shell-discovered PATH segments to the front of process.env.PATH,
+ * preserving shell ordering and avoiding duplicates. Returns the segments that
+ * were newly added so callers can log/telemetry on nontrivial hydrations.
+ */
+export function mergePathSegments(segments) {
+    if (segments.length === 0) {
+        return [];
+    }
+    const current = process.env.PATH ?? '';
+    const currentSegments = current.split(delimiter).filter(Boolean);
+    const shellSegments = [...new Set(segments)];
+    const shellSegmentSet = new Set(shellSegments);
+    const existing = new Set(currentSegments);
+    const added = shellSegments.filter((segment) => !existing.has(segment));
+    const merged = [
+        ...shellSegments,
+        ...currentSegments.filter((segment) => !shellSegmentSet.has(segment))
+    ];
+    const next = merged.join(delimiter);
+    if (next === current) {
+        return [];
+    }
+    // Why: shell-provided entries must win over hardcoded packaged-app fallbacks.
+    // A seeded fallback can point at a stale CLI while the user's shell resolves
+    // a healthy one from the same directory list in a different order.
+    process.env.PATH = next;
+    return added;
+}
+//# sourceMappingURL=hydrate-shell-path.js.map

package/dist/src/runtime/cli/hydrate-shell-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate-shell-path.js","sourceRoot":"","sources":["../../../../src/runtime/cli/hydrate-shell-path.ts"],"names":[],"mappings":"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"}

package/dist/src/session/terminal-line-sanitizer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Terminal row sanitization. The escape, control-byte and credential patterns
+ * live here so there is a single place to audit what can leave the device when
+ * terminal text is read on demand.
+ */
+/** Strip escapes and control bytes, redact credential-shaped values, drop cell padding. */
+export declare function sanitizeTerminalLine(line: string): string;

package/dist/src/session/terminal-line-sanitizer.js

@@ -0,0 +1,21 @@
+/**
+ * Terminal row sanitization. The escape, control-byte and credential patterns
+ * live here so there is a single place to audit what can leave the device when
+ * terminal text is read on demand.
+ */
+// CSI (`ESC [ … final`), terminated OSC (`ESC ] … BEL/ST`) and two-character escapes.
+const TERMINAL_ESCAPE = /\u001b(?:\][^\u0007]*?(?:\u0007|\u001b\\)|\[[0-?]*[ -/]*[@-~]|[@-Z\\-_])/g;
+// Everything unprintable except tab.
+const CONTROL_CHARACTER = /[\u0000-\u0008\u000b-\u001f\u007f]/g;
+// A labeled key redacts to end of line: `Authorization: Bearer <token>` would
+// otherwise stop at the scheme and leave the token itself in the output.
+const SENSITIVE_VALUE = /\b(?:sk|rk|pk|ghp|github_pat)_[A-Za-z0-9._-]+|\bBearer\s+\S+|\b(?:api[_-]?key|token|authorization|x-mcp-token)\s*[:=]\s*\S[^\r\n]*/gi;
+/** Strip escapes and control bytes, redact credential-shaped values, drop cell padding. */
+export function sanitizeTerminalLine(line) {
+    return line
+        .replace(TERMINAL_ESCAPE, '')
+        .replace(CONTROL_CHARACTER, '')
+        .replace(SENSITIVE_VALUE, '[redacted]')
+        .replace(/\s+$/, '');
+}
+//# sourceMappingURL=terminal-line-sanitizer.js.map

package/dist/src/session/terminal-line-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-line-sanitizer.js","sourceRoot":"","sources":["../../../src/session/terminal-line-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,sFAAsF;AACtF,MAAM,eAAe,GAAG,2EAA2E,CAAA;AACnG,qCAAqC;AACrC,MAAM,iBAAiB,GAAG,qCAAqC,CAAA;AAC/D,8EAA8E;AAC9E,yEAAyE;AACzE,MAAM,eAAe,GACnB,sIAAsI,CAAA;AAExI,2FAA2F;AAC3F,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,IAAI;SACR,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;SAC5B,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC;SAC9B,OAAO,CAAC,eAAe,EAAE,YAAY,CAAC;SACtC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;AACxB,CAAC"}

package/dist/src/session/terminal-tail-buffer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Bounded terminal tail with absolute line cursors, so a client can read the
+ * newest rows and then page backwards without re-reading what it already has.
+ *
+ * Mirrors Orca's split between a line-oriented tail and the still-unterminated
+ * partial line. Two properties matter for cost:
+ *
+ * - Appends are O(chunk). The naive `output = (output + chunk).slice(-N)` form
+ *   re-materializes the whole retained tail on every PTY chunk, which is O(N)
+ *   per write; a busy CLI turns that into a per-keystroke copy of 128 KiB.
+ * - Reads are O(requested lines). Escape stripping and redaction run on the
+ *   returned rows only, never on the whole buffer.
+ *
+ * Retained rows are raw. Sanitizing on read keeps escape sequences that straddle
+ * a chunk boundary intact until the full sequence has arrived.
+ */
+/** Retained completed rows. Matches Orca's `MAX_TAIL_LINES`. */
+export declare const MAX_TAIL_LINES = 2000;
+/** Retained characters across completed rows. Matches Orca's `MAX_TAIL_CHARS`. */
+export declare const MAX_TAIL_CHARS: number;
+/** A CLI that redraws a spinner without ever emitting a newline cannot grow past this. */
+export declare const MAX_TAIL_PARTIAL_CHARS = 4000;
+/** Rows returned when the caller does not ask for a specific count. */
+export declare const DEFAULT_TAIL_READ_LIMIT = 120;
+export declare const MAX_TAIL_READ_LIMIT = 2000;
+/** Character budget applied after the row limit, so wide rows cannot blow up a response. */
+export declare const MAX_TAIL_READ_CHARS: number;
+export type TerminalTailReadOptions = {
+    /** Rows to return, clamped to `MAX_TAIL_READ_LIMIT`. */
+    limit?: number;
+    /** Absolute cursor to read backwards from. Omit for the newest rows. */
+    beforeCursor?: number;
+};
+export type TerminalTailRead = {
+    lines: string[];
+    /** Absolute index of `lines[0]`. Pass it back as `beforeCursor` to page further up. */
+    startCursor: number;
+    /** Absolute index just past the last completed row returned. */
+    nextCursor: number;
+    /** Oldest absolute index still retained. `startCursor` cannot go below it. */
+    oldestCursor: number;
+    /** Absolute count of rows completed so far. */
+    latestCursor: number;
+    /** More retained rows exist above `startCursor`. */
+    hasMore: boolean;
+    /** Rows older than `oldestCursor` were dropped to stay within the caps. */
+    truncated: boolean;
+    /** The character budget clipped the response. */
+    limited: boolean;
+    /** Milliseconds since the CLI last wrote anything, or undefined if it never did. */
+    idleMs: number | undefined;
+};
+export declare class TerminalTailBuffer {
+    /** Completed rows, raw. Dropped head slots are blanked, then compacted in batches. */
+    private lines;
+    private head;
+    private chars;
+    /** Absolute count of completed rows, including dropped ones. Defines cursor space. */
+    private completedCount;
+    private partial;
+    private droppedRows;
+    private lastOutputAt;
+    get lastWriteAt(): number | undefined;
+    append(chunk: string, at?: number): void;
+    read(options?: TerminalTailReadOptions, now?: number): TerminalTailRead;
+    private appendPartial;
+    private commitPartial;
+    private trim;
+    private dropHead;
+}

package/dist/src/session/terminal-tail-buffer.js

@@ -0,0 +1,149 @@
+import { sanitizeTerminalLine } from './terminal-line-sanitizer.js';
+/**
+ * Bounded terminal tail with absolute line cursors, so a client can read the
+ * newest rows and then page backwards without re-reading what it already has.
+ *
+ * Mirrors Orca's split between a line-oriented tail and the still-unterminated
+ * partial line. Two properties matter for cost:
+ *
+ * - Appends are O(chunk). The naive `output = (output + chunk).slice(-N)` form
+ *   re-materializes the whole retained tail on every PTY chunk, which is O(N)
+ *   per write; a busy CLI turns that into a per-keystroke copy of 128 KiB.
+ * - Reads are O(requested lines). Escape stripping and redaction run on the
+ *   returned rows only, never on the whole buffer.
+ *
+ * Retained rows are raw. Sanitizing on read keeps escape sequences that straddle
+ * a chunk boundary intact until the full sequence has arrived.
+ */
+/** Retained completed rows. Matches Orca's `MAX_TAIL_LINES`. */
+export const MAX_TAIL_LINES = 2_000;
+/** Retained characters across completed rows. Matches Orca's `MAX_TAIL_CHARS`. */
+export const MAX_TAIL_CHARS = 256 * 1024;
+/** A CLI that redraws a spinner without ever emitting a newline cannot grow past this. */
+export const MAX_TAIL_PARTIAL_CHARS = 4_000;
+/** Rows returned when the caller does not ask for a specific count. */
+export const DEFAULT_TAIL_READ_LIMIT = 120;
+export const MAX_TAIL_READ_LIMIT = MAX_TAIL_LINES;
+/** Character budget applied after the row limit, so wide rows cannot blow up a response. */
+export const MAX_TAIL_READ_CHARS = 32 * 1024;
+/** Empty head slots tolerated before the backing array is compacted. */
+const HEAD_COMPACT_THRESHOLD = 1_024;
+export class TerminalTailBuffer {
+    /** Completed rows, raw. Dropped head slots are blanked, then compacted in batches. */
+    lines = [];
+    head = 0;
+    chars = 0;
+    /** Absolute count of completed rows, including dropped ones. Defines cursor space. */
+    completedCount = 0;
+    partial = '';
+    droppedRows = false;
+    lastOutputAt;
+    get lastWriteAt() {
+        return this.lastOutputAt;
+    }
+    append(chunk, at = Date.now()) {
+        if (!chunk)
+            return;
+        this.lastOutputAt = at;
+        let index = 0;
+        for (;;) {
+            const newline = chunk.indexOf('\n', index);
+            if (newline === -1) {
+                this.appendPartial(chunk.slice(index));
+                return;
+            }
+            // Trim the CR of a CRLF pair so it does not survive as a row rewrite.
+            const end = newline > index && chunk.charCodeAt(newline - 1) === 13 ? newline - 1 : newline;
+            this.appendPartial(chunk.slice(index, end));
+            this.commitPartial();
+            index = newline + 1;
+        }
+    }
+    read(options = {}, now = Date.now()) {
+        const limit = clampLimit(options.limit);
+        const retained = this.lines.length - this.head;
+        const oldestCursor = this.completedCount - retained;
+        const latestCursor = this.completedCount;
+        // A preview read shows what the screen shows, including the row being written.
+        const includePartial = options.beforeCursor === undefined && this.partial.length > 0;
+        const endCursor = options.beforeCursor === undefined
+            ? latestCursor
+            : Math.min(Math.max(options.beforeCursor, oldestCursor), latestCursor);
+        const rowBudget = Math.max(0, limit - (includePartial ? 1 : 0));
+        const startCursor = Math.max(oldestCursor, endCursor - rowBudget);
+        const rows = [];
+        for (let cursor = startCursor; cursor < endCursor; cursor += 1) {
+            rows.push(sanitizeTerminalLine(this.lines[this.head + (cursor - oldestCursor)] ?? ''));
+        }
+        if (includePartial)
+            rows.push(sanitizeTerminalLine(this.partial));
+        const clipped = clipToCharacterBudget(rows, MAX_TAIL_READ_CHARS);
+        return {
+            lines: clipped.lines,
+            startCursor,
+            nextCursor: endCursor,
+            oldestCursor,
+            latestCursor,
+            hasMore: startCursor > oldestCursor,
+            truncated: this.droppedRows,
+            limited: clipped.limited,
+            idleMs: this.lastOutputAt === undefined ? undefined : Math.max(0, now - this.lastOutputAt)
+        };
+    }
+    appendPartial(text) {
+        if (!text)
+            return;
+        const carriage = text.lastIndexOf('\r');
+        // A bare CR rewrites the current row on a real terminal; keep only what would stay visible.
+        const next = carriage === -1 ? `${this.partial}${text}` : text.slice(carriage + 1);
+        this.partial =
+            next.length > MAX_TAIL_PARTIAL_CHARS ? next.slice(-MAX_TAIL_PARTIAL_CHARS) : next;
+    }
+    commitPartial() {
+        const line = this.partial;
+        this.partial = '';
+        this.lines.push(line);
+        this.chars += line.length;
+        this.completedCount += 1;
+        this.trim();
+    }
+    trim() {
+        while (this.lines.length - this.head > MAX_TAIL_LINES)
+            this.dropHead();
+        while (this.head < this.lines.length && this.chars > MAX_TAIL_CHARS)
+            this.dropHead();
+        if (this.head >= HEAD_COMPACT_THRESHOLD) {
+            this.lines = this.lines.slice(this.head);
+            this.head = 0;
+        }
+    }
+    dropHead() {
+        const line = this.lines[this.head];
+        if (line === undefined)
+            return;
+        this.chars -= line.length;
+        // Release the row before compaction so a large tail is not pinned by an empty slot.
+        this.lines[this.head] = '';
+        this.head += 1;
+        this.droppedRows = true;
+    }
+}
+function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return DEFAULT_TAIL_READ_LIMIT;
+    return Math.max(1, Math.min(Math.floor(limit), MAX_TAIL_READ_LIMIT));
+}
+/**
+ * Apply the character budget from the newest row backwards, so the rows closest
+ * to what the CLI is doing now are the ones that survive.
+ */
+function clipToCharacterBudget(rows, budget) {
+    let total = 0;
+    for (let index = rows.length - 1; index >= 0; index -= 1) {
+        total += rows[index].length + 1;
+        if (total > budget)
+            return { lines: rows.slice(index + 1), limited: true };
+    }
+    return { lines: rows, limited: false };
+}
+//# sourceMappingURL=terminal-tail-buffer.js.map

package/dist/src/session/terminal-tail-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-tail-buffer.js","sourceRoot":"","sources":["../../../src/session/terminal-tail-buffer.ts"],"names":[],"mappings":"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"}

package/dist/src/shared/cli-detection-types.d.ts

@@ -0,0 +1,19 @@
+import type { ShellHydrationFailureReason } from '../runtime/cli/hydrate-shell-path.js';
+export type CliProviderDetection = {
+    id: string;
+    installed: boolean;
+    available: boolean;
+    matchedDetectionCommand?: string;
+    resolvedPath?: string;
+    version?: string;
+    detail?: string;
+};
+export type CliDetectionSnapshot = {
+    providers: CliProviderDetection[];
+    detectedIds: string[];
+    addedPathSegments: string[];
+    shellHydrationOk: boolean;
+    pathSource: 'shell_hydrated' | 'process_path';
+    pathFailureReason: ShellHydrationFailureReason;
+    refreshedAt: string;
+};

package/dist/src/shared/cli-detection-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli-detection-types.js.map

package/dist/src/shared/cli-detection-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-detection-types.js","sourceRoot":"","sources":["../../../src/shared/cli-detection-types.ts"],"names":[],"mappings":""}

package/dist/src/shared/node-cli-command-resolution.d.ts

@@ -0,0 +1,19 @@
+type ResolveCommandOptions = {
+    pathEnv?: string | null;
+    platform?: NodeJS.Platform;
+    homePath?: string;
+};
+export type ResolvedCliCommand = {
+    command: string;
+    found: boolean;
+    path?: string;
+};
+export declare function resolveCliCommand(commandName: string, options?: ResolveCommandOptions): string;
+export declare function findCliCommand(commandName: string, options?: ResolveCommandOptions): string | null;
+/** Resolve without conflating a launch fallback with an installed executable. */
+export declare function resolveCliCommandDetailed(commandName: string, options?: ResolveCommandOptions): ResolvedCliCommand;
+export declare function resolveCliCommands(commandNames: readonly string[], options?: ResolveCommandOptions): Map<string, string>;
+export declare function resolveCodexCommand(options?: ResolveCommandOptions): string;
+export declare function resolveClaudeCommand(options?: ResolveCommandOptions): string;
+export declare function getVersionManagerBinPaths(options?: ResolveCommandOptions): string[];
+export {};