@opencode/client 0.0.0-reserved → 2.0.1

package/dist/service-contender.js

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+const stderrLimit = 8 * 1024;
+export function spawnServiceContender(command, args, env) {
+    const child = spawn(command, args, {
+        detached: true,
+        stdio: ["ignore", "ignore", "pipe"],
+        env: { ...process.env, ...env },
+    });
+    let error;
+    let closed = false;
+    let stderr = Buffer.alloc(0);
+    const onStderr = (chunk) => {
+        const tail = chunk.subarray(-stderrLimit);
+        stderr =
+            tail.length === stderrLimit
+                ? Buffer.from(tail)
+                : Buffer.concat([stderr.subarray(-(stderrLimit - tail.length)), tail]);
+    };
+    child.stderr?.on("data", onStderr);
+    if (child.stderr !== null && "unref" in child.stderr && typeof child.stderr.unref === "function")
+        child.stderr.unref();
+    child.once("error", (cause) => {
+        error = new Error("Failed to start server", { cause });
+    });
+    child.once("close", () => {
+        closed = true;
+    });
+    child.unref();
+    return {
+        child,
+        error: () => error,
+        closed: () => closed,
+        stderr: () => stderr.toString("utf8").trim(),
+        release: () => {
+            child.stderr?.off("data", onStderr);
+            child.stderr?.resume();
+            stderr = Buffer.alloc(0);
+        },
+    };
+}
+export function contenderFailure(contender) {
+    const error = contender.error();
+    if (error !== undefined)
+        return error;
+    if (contender.child.exitCode !== null && contender.child.exitCode !== 0)
+        return startupError(`Server process exited with code ${contender.child.exitCode}`, contender.stderr());
+    if (contender.child.signalCode !== null)
+        return startupError(`Server process terminated by ${contender.child.signalCode}`, contender.stderr());
+    return undefined;
+}
+export function contenderFinished(contender) {
+    return contender.error() !== undefined || contender.closed();
+}
+function startupError(message, stderr) {
+    return new Error(stderr ? `${message}\n${stderr}` : message);
+}

package/dist/service-timing.d.ts

@@ -0,0 +1,13 @@
+export type EnsureTiming = {
+    readonly pollInterval: number;
+    readonly attempts: number;
+    readonly requestTimeout: number;
+    readonly spawnDelay: number;
+    readonly maxSpawnDelay: number;
+    readonly promiseTimeout: number;
+    readonly stopPollInterval: number;
+    readonly stopPollAttempts: number;
+};
+export declare const defaultEnsureTiming: EnsureTiming;
+export declare function ensureTiming(options: object): EnsureTiming;
+export declare function withEnsureTiming<A extends object>(options: A, overrides: Partial<EnsureTiming>): A;

package/dist/service-timing.js

@@ -0,0 +1,19 @@
+const timings = new WeakMap();
+export const defaultEnsureTiming = {
+    pollInterval: 100,
+    attempts: 1_200,
+    requestTimeout: 2_000,
+    spawnDelay: 5_000,
+    maxSpawnDelay: 30_000,
+    promiseTimeout: 120_000,
+    stopPollInterval: 50,
+    stopPollAttempts: 100,
+};
+export function ensureTiming(options) {
+    return timings.get(options) ?? defaultEnsureTiming;
+}
+// Keep test timing out of the public lifecycle option types.
+export function withEnsureTiming(options, overrides) {
+    timings.set(options, { ...defaultEnsureTiming, ...overrides });
+    return options;
+}

package/dist/service-version.d.ts

@@ -0,0 +1,2 @@
+import type { DiscoverOptions } from "./service.js";
+export declare function matchesVersion(version: string | undefined, options: DiscoverOptions): boolean;

package/dist/service-version.js

@@ -0,0 +1,9 @@
+export function matchesVersion(version, options) {
+    if (options.version === undefined)
+        return true;
+    if (version === undefined)
+        return false;
+    if (typeof options.version === "function")
+        return options.version(version);
+    return version === options.version;
+}

package/dist/service.d.ts

@@ -0,0 +1,52 @@
+/** Connection details for a local OpenCode service. */
+export type Endpoint = {
+    /** Base URL of the service. */
+    readonly url: string;
+    /** Authentication required by the service, when configured. */
+    readonly auth?: {
+        /** HTTP authentication scheme. */
+        readonly type: "basic";
+        /** Basic authentication username. */
+        readonly username: string;
+        /** Basic authentication password. */
+        readonly password: string;
+    };
+};
+/** Options used to discover the local OpenCode service. */
+export type DiscoverOptions = {
+    /** Absolute registration file path. Defaults to the XDG state directory. */
+    readonly file?: string;
+    /** Required exact service version or compatibility predicate. */
+    readonly version?: string | ((version: string) => boolean);
+};
+/** Reason ensuring the service requires a new process. */
+export type EnsureReason = "missing" | "version-mismatch";
+/** Options used to ensure the local OpenCode service is running. */
+export type EnsureOptions = DiscoverOptions & {
+    /** Service command and arguments. Defaults to `opencode serve --service`. */
+    readonly command?: ReadonlyArray<string>;
+    /** Environment variables added to the inherited service process environment. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Called once before spawning a new service process. */
+    readonly onStart?: (reason: EnsureReason, previousVersion?: string) => void;
+};
+/** Options used to stop the local OpenCode service. */
+export type StopOptions = {
+    /** Absolute registration file path. Defaults to the XDG state directory. */
+    readonly file?: string;
+    /** How to handle persistent terminals before stopping the service. */
+    readonly pty?: "clear" | "handoff";
+};
+/** Contents of the local service registration file. */
+export type Info = {
+    /** Unique service instance identifier. */
+    readonly id?: string;
+    /** OpenCode version served by the process. */
+    readonly version?: string;
+    /** Base URL advertised by the service. */
+    readonly url: string;
+    /** Operating system process identifier. */
+    readonly pid: number;
+    /** Private service password, when authentication is enabled. */
+    readonly password?: string;
+};

package/dist/shared-events.d.ts

@@ -0,0 +1,11 @@
+export * as SharedEvents from "./shared-events.js";
+export type SubscribeOptions = {
+    readonly signal?: AbortSignal;
+    /** Reports transport activity on the shared stream, including keepalive frames that carry no event. */
+    readonly onActivity?: () => void;
+};
+export declare function make<A extends {
+    readonly type: string;
+}>(connect: (signal: AbortSignal, onActivity: () => void) => AsyncIterable<A>): {
+    subscribe(options?: SubscribeOptions): AsyncIterable<A>;
+};

package/dist/shared-events.js

@@ -0,0 +1,137 @@
+export * as SharedEvents from "./shared-events.js";
+export function make(connect) {
+    let current;
+    const capacity = 4_096;
+    function stop(connection) {
+        connection.connected = undefined;
+        connection.controller.abort();
+        if (current === connection)
+            current = undefined;
+    }
+    async function run(connection) {
+        let iterator;
+        let completion = {};
+        try {
+            if (connection.controller.signal.aborted)
+                return;
+            iterator = connect(connection.controller.signal, () => {
+                connection.subscribers.forEach((subscriber) => subscriber.activity?.());
+            })[Symbol.asyncIterator]();
+            while (!connection.controller.signal.aborted) {
+                const item = await iterator.next();
+                if (item.done || connection.controller.signal.aborted)
+                    break;
+                if (item.value.type === "server.connected")
+                    connection.connected = item.value;
+                connection.subscribers.forEach((subscriber) => subscriber.push(item.value));
+            }
+        }
+        catch (error) {
+            completion = { error };
+        }
+        finally {
+            stop(connection);
+            try {
+                await iterator?.return?.();
+            }
+            catch (error) {
+                if (!("error" in completion))
+                    completion = { error };
+            }
+            connection.subscribers.forEach((subscriber) => subscriber.finish(completion));
+        }
+    }
+    return {
+        subscribe(options) {
+            return {
+                [Symbol.asyncIterator]() {
+                    const pending = [];
+                    const queued = [];
+                    let started = false;
+                    let completion;
+                    let connection;
+                    function finish(result, discard = true) {
+                        completion = result;
+                        if (discard)
+                            queued.length = 0;
+                        options?.signal?.removeEventListener("abort", abort);
+                        if (connection?.subscribers.delete(subscriber) && !connection.subscribers.size)
+                            stop(connection);
+                        pending.splice(0).forEach((request) => {
+                            if ("error" in result)
+                                request.reject(result.error);
+                            else
+                                request.resolve({ done: true, value: undefined });
+                        });
+                    }
+                    function abort() {
+                        finish({});
+                    }
+                    const subscriber = {
+                        activity: options?.onActivity,
+                        finish(result) {
+                            finish(result, false);
+                        },
+                        push(value) {
+                            if (completion)
+                                return;
+                            const request = pending.shift();
+                            if (request) {
+                                request.resolve({ done: false, value });
+                                return;
+                            }
+                            if (queued.length === capacity) {
+                                finish({ error: new Error(`Event subscriber exceeded its ${capacity}-event capacity`) });
+                                return;
+                            }
+                            queued.push(value);
+                        },
+                    };
+                    function start() {
+                        if (completion)
+                            return;
+                        const fresh = !current;
+                        connection = current ?? {
+                            controller: new AbortController(),
+                            subscribers: new Set(),
+                        };
+                        current = connection;
+                        connection.subscribers.add(subscriber);
+                        if (connection.connected)
+                            void subscriber.push(connection.connected);
+                        if (fresh)
+                            void run(connection);
+                    }
+                    return {
+                        next() {
+                            const value = queued.shift();
+                            if (value)
+                                return Promise.resolve({ done: false, value });
+                            if (completion) {
+                                if ("error" in completion)
+                                    return Promise.reject(completion.error);
+                                return Promise.resolve({ done: true, value: undefined });
+                            }
+                            if (options?.signal?.aborted) {
+                                abort();
+                                return Promise.resolve({ done: true, value: undefined });
+                            }
+                            const request = Promise.withResolvers();
+                            pending.push(request);
+                            if (!started) {
+                                started = true;
+                                options?.signal?.addEventListener("abort", abort, { once: true });
+                                start();
+                            }
+                            return request.promise;
+                        },
+                        return() {
+                            finish({});
+                            return Promise.resolve({ done: true, value: undefined });
+                        },
+                    };
+                },
+            };
+        },
+    };
+}

package/dist/solid/connection.d.ts

@@ -0,0 +1,37 @@
+import type { OpenCodeClient, OpenCodeEvent } from "../promise";
+export type ClientConnectionStatus = "connected" | "connecting" | "reconnecting";
+export type ClientConnectionEvent = {
+    readonly type: "client.connection";
+    readonly created: number;
+    readonly data: {
+        readonly status: "connecting" | "connected" | "disconnected" | "reconnecting";
+        readonly attempt: number;
+        readonly error?: string;
+    };
+};
+export type ClientConnectionOptions = {
+    readonly reconnect?: (signal: AbortSignal) => Promise<OpenCodeClient>;
+    readonly onEvent: (event: OpenCodeEvent) => void;
+    readonly flushInterval?: number;
+    readonly pageLifecycle?: boolean;
+    /**
+     * Abort and reconnect a stream that receives no bytes for this long. The server writes a keepalive
+     * comment every 15 seconds, so a quiet but healthy stream never trips this.
+     */
+    readonly idleTimeout?: number;
+    readonly log?: {
+        readonly debug?: (message: string, data?: Readonly<Record<string, unknown>>) => void;
+        readonly info?: (message: string, data?: Readonly<Record<string, unknown>>) => void;
+    };
+};
+export declare const defaultIdleTimeout = 45000;
+export declare const foregroundIdleThreshold = 20000;
+export declare function createClientConnection(initialApi: OpenCodeClient, options: ClientConnectionOptions): {
+    status: () => ClientConnectionStatus;
+    attempt: () => number;
+    error: () => string | undefined;
+    internal: {
+        history: () => ClientConnectionEvent[];
+        resync: (reason: string) => void;
+    };
+};

package/dist/solid/connection.js

@@ -0,0 +1,246 @@
+import { batch, onCleanup } from "solid-js";
+import { createStore } from "solid-js/store";
+const connectTimeout = 2_000;
+const reconnectDelay = 1_000;
+const connectionHistoryLimit = 50;
+export const defaultIdleTimeout = 45_000;
+// Longer than one server keepalive interval: a stream that is silent this long when the page
+// returns to the foreground is probably half-open after the device slept.
+export const foregroundIdleThreshold = 20_000;
+export function createClientConnection(initialApi, options) {
+    const abort = new AbortController();
+    const history = [];
+    const idleTimeout = options.idleTimeout ?? defaultIdleTimeout;
+    const [connection, setConnection] = createStore({ status: "connecting", attempt: 0 });
+    let api = initialApi;
+    let pending = [];
+    let flushTimer;
+    let stream;
+    let current;
+    let run;
+    let started = false;
+    let generation = 0;
+    let lastActivity = 0;
+    let forced = false;
+    function record(status, attempt, error) {
+        history.push({ type: "client.connection", created: Date.now(), data: { status, attempt, error } });
+        if (history.length > connectionHistoryLimit)
+            history.shift();
+    }
+    function publish(event) {
+        pending.push(event);
+        if (flushTimer)
+            return;
+        flushTimer = setTimeout(() => {
+            flushTimer = undefined;
+            const events = pending;
+            pending = [];
+            batch(() => events.forEach(options.onEvent));
+        }, options.flushInterval ?? 10);
+    }
+    async function connect(signal, attempt) {
+        let connectedAt;
+        const request = new AbortController();
+        current = request;
+        const cancel = () => request.abort(signal.reason);
+        const timeout = setTimeout(() => request.abort(new Error("Timed out connecting to server")), connectTimeout);
+        signal.addEventListener("abort", cancel, { once: true });
+        // Any received bytes, including keepalive comments, push the stall deadline out. A timer whose
+        // deadline passed while the page was suspended fires as soon as the page resumes.
+        let watchdog;
+        const touch = () => {
+            lastActivity = Date.now();
+            if (connectedAt === undefined)
+                return;
+            clearTimeout(watchdog);
+            watchdog = setTimeout(() => request.abort(new Error("Event stream stalled")), idleTimeout);
+        };
+        try {
+            record(attempt === 0 ? "connecting" : "reconnecting", attempt);
+            options.log?.info?.("event stream connecting", { attempt });
+            const iterator = api.event.subscribe({ signal: request.signal, onActivity: touch })[Symbol.asyncIterator]();
+            const first = await iterator.next();
+            if (signal.aborted)
+                return { error: undefined, connectedAt };
+            if (first.done)
+                return {
+                    error: request.signal.reason instanceof Error ? request.signal.reason : new Error("Event stream disconnected"),
+                    connectedAt,
+                };
+            if (first.value.type !== "server.connected")
+                return { error: new Error("Event stream did not start with server.connected"), connectedAt };
+            clearTimeout(timeout);
+            record("connected", attempt);
+            connectedAt = Date.now();
+            touch();
+            options.log?.info?.("event stream connected");
+            publish(first.value);
+            setConnection({ status: "connected", attempt: 0, error: undefined });
+            while (!signal.aborted) {
+                const event = await iterator.next();
+                if (signal.aborted)
+                    return { error: undefined, connectedAt };
+                if (event.done)
+                    return {
+                        error: request.signal.reason instanceof Error ? request.signal.reason : new Error("Event stream disconnected"),
+                        connectedAt,
+                    };
+                touch();
+                if ("durable" in event.value && event.value.durable)
+                    options.log?.debug?.("event", {
+                        type: event.value.type,
+                        aggregateID: event.value.durable.aggregateID,
+                        seq: event.value.durable.seq,
+                    });
+                publish(event.value);
+            }
+            return { error: undefined, connectedAt };
+        }
+        catch (error) {
+            return { error, connectedAt };
+        }
+        finally {
+            request.abort();
+            if (current === request)
+                current = undefined;
+            clearTimeout(timeout);
+            clearTimeout(watchdog);
+            signal.removeEventListener("abort", cancel);
+        }
+    }
+    async function runStream(active) {
+        let attempt = 0;
+        while (!abort.signal.aborted && started && generation === active) {
+            setConnection({ status: attempt === 0 ? "connecting" : "reconnecting", attempt });
+            const controller = new AbortController();
+            stream = controller;
+            const cancel = () => controller.abort(abort.signal.reason);
+            abort.signal.addEventListener("abort", cancel);
+            const result = await connect(controller.signal, attempt);
+            abort.signal.removeEventListener("abort", cancel);
+            if (abort.signal.aborted || !started || generation !== active)
+                return;
+            if (result.connectedAt !== undefined && Date.now() - result.connectedAt >= reconnectDelay)
+                attempt = 0;
+            attempt += 1;
+            const message = errorMessage(result.error);
+            record("disconnected", attempt, message);
+            options.log?.info?.("event stream disconnected", { attempt, error: message });
+            setConnection({ status: "reconnecting", attempt, error: message });
+            if (options.reconnect) {
+                const next = await options.reconnect(controller.signal).catch((error) => {
+                    if (!controller.signal.aborted)
+                        options.log?.info?.("server resolution failed", { attempt, error: errorMessage(error) });
+                });
+                if (abort.signal.aborted || controller.signal.aborted || !started || generation !== active)
+                    return;
+                if (next) {
+                    api = next;
+                    if (attempt === 1)
+                        continue;
+                }
+            }
+            // A deliberate resync already knows the old socket is gone; reconnect without backing off.
+            if (forced) {
+                forced = false;
+                continue;
+            }
+            await wait(reconnectDelay, controller.signal);
+        }
+    }
+    function start() {
+        if (started)
+            return run;
+        started = true;
+        forced = false;
+        const active = ++generation;
+        const previous = run;
+        const current = (async () => {
+            if (previous)
+                await previous;
+            await runStream(active);
+        })().finally(() => {
+            if (run !== current)
+                return;
+            run = undefined;
+        });
+        run = current;
+        return run;
+    }
+    function stop() {
+        if (!started)
+            return;
+        started = false;
+        generation += 1;
+        stream?.abort();
+        // Nothing is listening once stopped, so consumers must treat their data as stale until start() reconnects.
+        setConnection({ status: "connecting", attempt: 0, error: undefined });
+    }
+    // Drop the live request so the reconnect loop replaces it now instead of waiting for the idle watchdog.
+    function resync(reason) {
+        if (!started || connection.status !== "connected")
+            return;
+        options.log?.info?.("event stream resync", { reason, idle: Date.now() - lastActivity });
+        forced = true;
+        current?.abort(new Error(reason));
+    }
+    if (options.pageLifecycle) {
+        const pagehide = () => stop();
+        const pageshow = () => void start();
+        // Locking a phone or switching apps hides the document without a pagehide; the socket usually
+        // dies while the page is suspended, and the browser may never report that on the hung read.
+        const visibility = () => {
+            if (document.visibilityState !== "visible")
+                return;
+            if (Date.now() - lastActivity < foregroundIdleThreshold)
+                return;
+            resync("Page returned to the foreground after the event stream went quiet");
+        };
+        const online = () => resync("Network connection restored");
+        window.addEventListener("pagehide", pagehide);
+        window.addEventListener("pageshow", pageshow);
+        window.addEventListener("online", online);
+        document.addEventListener("visibilitychange", visibility);
+        onCleanup(() => {
+            window.removeEventListener("pagehide", pagehide);
+            window.removeEventListener("pageshow", pageshow);
+            window.removeEventListener("online", online);
+            document.removeEventListener("visibilitychange", visibility);
+        });
+    }
+    void start();
+    onCleanup(() => {
+        stop();
+        abort.abort();
+        if (flushTimer)
+            clearTimeout(flushTimer);
+        pending = [];
+    });
+    return {
+        status: () => connection.status,
+        attempt: () => connection.attempt,
+        error: () => connection.error,
+        internal: {
+            history: () => history.slice(),
+            resync,
+        },
+    };
+}
+function errorMessage(error) {
+    if (error === undefined)
+        return undefined;
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function wait(delay, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, delay);
+        signal.addEventListener("abort", done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+    });
+}