@textjs/opencode 0.0.0-stage → 1.0.2

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# ▼ @textjs/opencode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local bridge that lets [textjs.org/opencode](https://textjs.org/opencode) talk to the [OpenCode](https://opencode.ai) server on your machine. It has no dependencies and runs on Node 22+ or Bun.
+
+```bash
+bunx @textjs/opencode proxy    # or: npx @textjs/opencode proxy
+```
+
+Leave it running, open [textjs.org/opencode](https://textjs.org/opencode), enter `http://127.0.0.1:4096` and press **Connect**. Allow local network access if Chrome asks. Stop the bridge with Ctrl+C.
+
+Browsers block a public page from reading `http://127.0.0.1` unless the server answers CORS and Private Network Access preflights, and the OpenCode service also requires a password. The bridge adds the headers and the password, and forwards each request to OpenCode.
+
+## Options
+
+| Flag | Description |
+| :-- | :-- |
+| `-p, --port <port>` | Port to listen on (default `4096`) |
+| `--target <url>` | OpenCode server URL. Skips discovery. |
+| `--allow-origin <origin>` | Allow another browser origin, such as `https://example.com` or `http://localhost:*`. Repeatable. |
+| `-v, --version` | Print the version |
+| `-h, --help` | Show help |
+
+Without `--target`, the bridge asks `opencode service status` for the managed service and reads its password with `opencode service get password`. It caches the result for 30 seconds and looks again when OpenCode answers `401` or can't be reached, so it follows a service that restarts with a new port or password.
+
+For a foreground server, pass its URL. If the server already uses port 4096, run the bridge on another port and connect the page to that port:
+
+```bash
+bunx @textjs/opencode proxy --port 4097 --target http://127.0.0.1:4096
+```
+
+For a password-protected foreground server, export `OPENCODE_PASSWORD` in the bridge's shell. `OPENCODE_SERVER_URL` works in place of `--target`.
+
+## Security
+
+- **Loopback only.** The bridge listens on `127.0.0.1` and answers only requests whose `Host` is `localhost`, `127.0.0.1` or `[::1]`, which blocks DNS rebinding.
+- **Origin allowlist.** Browser requests must come from `https://textjs.org`, `https://www.textjs.org`, Text.js preview deployments or `http://localhost`, `127.0.0.1` and `[::1]` on any port. Other origins get a `403`. Add your own with `--allow-origin`.
+- **The password stays on your machine.** The bridge keeps it in memory and adds it to requests it forwards to OpenCode. It isn't logged, written to disk or sent to the browser.
+- **Writes need a custom header.** Requests other than `GET`, `HEAD` and `OPTIONS` must send `x-opencode-client: 1`, a header HTML forms can't set. Request bodies are capped at 4 MB.
+- **Passwords apply to loopback targets only.** `OPENCODE_PASSWORD` is never sent to a non-loopback `--target`, and `--target` rejects URLs that contain credentials, a path, a query or a hash ([TX021](https://textjs.org/errors/TX021)).
+
+## Text.js projects
+
+`@textjs/app` runs the same bridge as `text proxy`, with the same flags.
+
+## Errors
+
+| Code | Meaning |
+| :-- | :-- |
+| [TX021](https://textjs.org/errors/TX021) | `--target` isn't a bare HTTP(S) origin |
+| [TX022](https://textjs.org/errors/TX022) | `--port` is the OpenCode server's own port |
+| [TX023](https://textjs.org/errors/TX023) | A bridge is already running on that port |
+| [TX024](https://textjs.org/errors/TX024) | Something else is using that port |

package/bin/textjs-opencode.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Bun runs the TypeScript sources in this repo. Installed packages, and Node, run the compiled dist/.
+import { existsSync } from "node:fs";
+
+const source = new URL("../src/cli.ts", import.meta.url);
+const compiled = new URL("../dist/cli.js", import.meta.url);
+const entry = typeof process.versions.bun === "string" && existsSync(source) ? source : compiled;
+
+if (entry === compiled && !existsSync(compiled)) {
+  console.error("▼ textjs-opencode: missing dist/cli.js. Run `bun run build`, or run this file with Bun.");
+  process.exitCode = 1;
+} else {
+  const { main } = await import(entry.href);
+  process.exitCode = await main(process.argv.slice(2));
+}

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+export interface ParsedArgs {
+    command: string;
+    port?: number;
+    target?: string;
+    allowOrigins: string[];
+    help: boolean;
+    version: boolean;
+}
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export declare const HELP = "Usage: bunx @textjs/opencode proxy [options]\n\nCommands:\n  proxy  Bridge textjs.org/opencode to the OpenCode server on this machine\n\nOptions:\n  -p, --port <port>        Port (default 4096)\n  --target <url>           OpenCode server URL (default: discover)\n  --allow-origin <origin>  Allow another browser origin (repeatable)\n  -v, --version            Print the version\n  -h, --help               Show this help\n";
+export interface RunProxyOptions {
+    port?: number;
+    target?: string;
+    allowOrigins?: readonly string[];
+}
+/** Start the bridge and keep it running until SIGINT or SIGTERM. */
+export declare function runProxy(options?: RunProxyOptions): Promise<never>;
+export declare function main(argv: readonly string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,81 @@
+import { color } from "./color.js";
+import { DEFAULT_PROXY_PORT, startProxy } from "./proxy.js";
+import { VERSION } from "./version.js";
+export function parseArgs(argv) {
+    const out = { command: "", allowOrigins: [], help: false, version: false };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h" || a === "--help")
+            out.help = true;
+        else if (a === "-v" || a === "--version")
+            out.version = true;
+        else if (a === "-p" || a === "--port")
+            out.port = Number(argv[++i]);
+        else if (a.startsWith("--port="))
+            out.port = Number(a.slice(7));
+        else if (a === "--target")
+            out.target = argv[++i];
+        else if (a.startsWith("--target="))
+            out.target = a.slice(9);
+        else if (a === "--allow-origin") {
+            const v = argv[++i];
+            if (v)
+                out.allowOrigins.push(v);
+        }
+        else if (a.startsWith("--allow-origin="))
+            out.allowOrigins.push(a.slice(15));
+        else
+            positional.push(a);
+    }
+    out.command = positional[0] ?? "";
+    if (out.port !== undefined && !Number.isFinite(out.port))
+        out.port = undefined;
+    return out;
+}
+export const HELP = `Usage: bunx @textjs/opencode proxy [options]
+
+Commands:
+  proxy  Bridge textjs.org/opencode to the OpenCode server on this machine
+
+Options:
+  -p, --port <port>        Port (default ${DEFAULT_PROXY_PORT})
+  --target <url>           OpenCode server URL (default: discover)
+  --allow-origin <origin>  Allow another browser origin (repeatable)
+  -v, --version            Print the version
+  -h, --help               Show this help
+`;
+/** Start the bridge and keep it running until SIGINT or SIGTERM. */
+export async function runProxy(options = {}) {
+    const bridge = await startProxy({ port: options.port ?? DEFAULT_PROXY_PORT, target: options.target, allowOrigins: options.allowOrigins });
+    const stop = async () => {
+        await bridge.close();
+        process.exit(0);
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    return new Promise(() => undefined);
+}
+export async function main(argv) {
+    const args = parseArgs(argv);
+    if (args.version) {
+        console.log(`@textjs/opencode v${VERSION}`);
+        return 0;
+    }
+    if (args.help || args.command === "" || args.command === "help") {
+        console.log(HELP);
+        return args.command === "" && !args.help ? 1 : 0;
+    }
+    if (args.command !== "proxy") {
+        console.error(` ${color.red("⨯")} Unknown command ${color.bold(args.command)}.\n`);
+        console.log(HELP);
+        return 1;
+    }
+    try {
+        return await runProxy(args);
+    }
+    catch (error) {
+        console.error(` ${color.red("⨯")} ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}

package/dist/color.d.ts

@@ -0,0 +1,7 @@
+export declare const color: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    gray: (s: string) => string;
+};

package/dist/color.js

@@ -0,0 +1,15 @@
+const enabled = () => {
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "")
+        return false;
+    if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0")
+        return true;
+    return Boolean(process.stdout?.isTTY);
+};
+const wrap = (open, close) => (s) => enabled() ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+export const color = {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    yellow: wrap(33, 39),
+    gray: wrap(90, 39),
+};

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The Text.js error codes the bridge throws, copied from `@textjs/core` so this
+ * package has no dependencies. `test/errors.test.ts` keeps them identical.
+ */
+export declare const ERRORS_URL = "https://textjs.org/errors";
+export declare const TX_MESSAGES: {
+    readonly TX021: "Use an HTTP(S) server origin without credentials for --target or OPENCODE_SERVER_URL.";
+    readonly TX022: "The OpenCode server already uses port %s. Pick another with --port.";
+    readonly TX023: "Bridge already running at %s. Connect to %s (or pass --port %s).";
+    readonly TX024: "Port %s is already in use. Run bunx @textjs/opencode proxy --port %s and connect to %s.";
+};
+export type TxCode = keyof typeof TX_MESSAGES;
+export interface TextJsError extends Error {
+    code: TxCode;
+}
+export declare function txMessage(code: TxCode, ...args: unknown[]): string;
+export declare function txError(code: TxCode, ...args: unknown[]): TextJsError;

package/dist/errors.js

@@ -0,0 +1,23 @@
+/**
+ * The Text.js error codes the bridge throws, copied from `@textjs/core` so this
+ * package has no dependencies. `test/errors.test.ts` keeps them identical.
+ */
+export const ERRORS_URL = "https://textjs.org/errors";
+export const TX_MESSAGES = {
+    TX021: "Use an HTTP(S) server origin without credentials for --target or OPENCODE_SERVER_URL.",
+    TX022: "The OpenCode server already uses port %s. Pick another with --port.",
+    TX023: "Bridge already running at %s. Connect to %s (or pass --port %s).",
+    TX024: "Port %s is already in use. Run bunx @textjs/opencode proxy --port %s and connect to %s.",
+};
+function formatTemplate(template, args) {
+    let i = 0;
+    return template.replace(/%s/g, () => (i < args.length ? String(args[i++]) : "…"));
+}
+export function txMessage(code, ...args) {
+    return `Text.js error ${code}: ${formatTemplate(TX_MESSAGES[code], args)} ${ERRORS_URL}/${code}`;
+}
+export function txError(code, ...args) {
+    const error = new Error(txMessage(code, ...args));
+    error.code = code;
+    return error;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./proxy.js";
+export { HELP, main, parseArgs, runProxy, type ParsedArgs, type RunProxyOptions } from "./cli.js";
+export { TX_MESSAGES, txError, txMessage, type TextJsError, type TxCode } from "./errors.js";
+export { VERSION } from "./version.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./proxy.js";
+export { HELP, main, parseArgs, runProxy } from "./cli.js";
+export { TX_MESSAGES, txError, txMessage } from "./errors.js";
+export { VERSION } from "./version.js";

package/dist/proxy.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `bunx @textjs/opencode proxy` (and `text proxy`): a loopback bridge that lets
+ * https://textjs.org (and local dev origins) talk to the OpenCode server running
+ * on this machine.
+ *
+ * Browsers block a public page from reading `http://127.0.0.1` unless the
+ * server answers CORS and Private Network Access preflights, and the desktop
+ * daemon additionally requires Basic auth. The bridge adds both, while
+ * rejecting every other origin. The daemon password is read into memory only:
+ * it is never logged, never returned to the browser and never written to disk.
+ */
+import { type Server } from "node:http";
+export declare const DEFAULT_PROXY_PORT = 4096;
+export declare const BRIDGE_HEADER = "x-textjs-bridge";
+export declare const CLIENT_HEADER = "x-opencode-client";
+export declare const MAX_BODY_BYTES: number;
+export declare const DEFAULT_ALLOWED_ORIGINS: readonly string[];
+export interface BridgeTarget {
+    url: string;
+    /** How the target was found. */
+    source: "service" | "flag" | "env";
+    /** `Basic …` header value; memory only. */
+    authorization?: string;
+}
+export interface BridgeOptions {
+    port?: number;
+    host?: string;
+    /** Explicit OpenCode server URL (skips daemon discovery). */
+    target?: string;
+    /** Extra allowed browser origins (`https://example.com`, `http://localhost:*`). */
+    allowOrigins?: readonly string[];
+    /** Override discovery (tests). */
+    discover?: () => Promise<BridgeTarget | null>;
+    /** Re-run discovery after this long (default 30s). */
+    cacheMs?: number;
+    log?: boolean;
+}
+/** Strip the port from a `Host` header: `localhost:4096` → `localhost`, `[::1]:4096` → `[::1]`. */
+export declare function hostnameOf(host: string): string;
+/** Whether a browser `Origin` may use the bridge. */
+export declare function isAllowedOrigin(origin: string, extra?: readonly string[]): boolean;
+/** CORS + Private Network Access headers for an allowed origin. */
+export declare function corsHeaders(origin: string): Record<string, string>;
+/** `http://0.0.0.0:49374` → `http://127.0.0.1:49374`; picks the first URL in CLI output. */
+export declare function normalizeTargetUrl(raw: string): string | null;
+/** Loopback aliases (`localhost`, `127.0.0.1`, `[::1]`) with the same port select the trusted target, while requests still go to `trusted`. */
+export declare function selectsTarget(origin: string, trusted: string): boolean;
+/** An explicit target wins. Never apply a foreground server's password to a browser-selected URL. */
+export declare function discoverOpencode(target?: string): Promise<BridgeTarget | null>;
+/** A Vite/SPA fallback can return 200 HTML for *every* path. Verify the API, not just the status. */
+export declare function probeOpenCode(t: {
+    url: string;
+    authorization?: string;
+}): Promise<number>;
+export interface BridgeHandler {
+    (request: Request): Promise<Response>;
+    /** The current (cached) target, discovering it if needed. */
+    target(force?: boolean): Promise<BridgeTarget | null>;
+}
+/** The bridge as a Web `Request → Response` handler. */
+export declare function createBridgeHandler(options?: BridgeOptions): BridgeHandler;
+export interface StartedBridge {
+    server: Server;
+    url: string;
+    target: BridgeTarget | null;
+    close(): Promise<void>;
+}
+/** Start the bridge on `127.0.0.1:<port>`. */
+export declare function startProxy(options?: BridgeOptions): Promise<StartedBridge>;

package/dist/proxy.js

@@ -0,0 +1,466 @@
+/**
+ * `bunx @textjs/opencode proxy` (and `text proxy`): a loopback bridge that lets
+ * https://textjs.org (and local dev origins) talk to the OpenCode server running
+ * on this machine.
+ *
+ * Browsers block a public page from reading `http://127.0.0.1` unless the
+ * server answers CORS and Private Network Access preflights, and the desktop
+ * daemon additionally requires Basic auth. The bridge adds both, while
+ * rejecting every other origin. The daemon password is read into memory only:
+ * it is never logged, never returned to the browser and never written to disk.
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { color } from "./color.js";
+import { txError } from "./errors.js";
+export const DEFAULT_PROXY_PORT = 4096;
+export const BRIDGE_HEADER = "x-textjs-bridge";
+export const CLIENT_HEADER = "x-opencode-client";
+export const MAX_BODY_BYTES = 4 * 1024 * 1024;
+export const DEFAULT_ALLOWED_ORIGINS = [
+    "https://textjs.org",
+    "https://www.textjs.org",
+    "https://textjs-avg.pages.dev",
+    "https://*.textjs-avg.pages.dev",
+    "http://localhost:*",
+    "http://127.0.0.1:*",
+    "http://[::1]:*",
+];
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const FORWARD_REQUEST_HEADERS = ["accept", "content-type", "last-event-id", "x-opencode-directory"];
+const FORWARD_RESPONSE_HEADERS = ["content-type", "location", "x-request-id"];
+/** Strip the port from a `Host` header: `localhost:4096` → `localhost`, `[::1]:4096` → `[::1]`. */
+export function hostnameOf(host) {
+    const h = host.trim().toLowerCase();
+    if (h.startsWith("[")) {
+        const end = h.indexOf("]");
+        return end > 0 ? h.slice(0, end + 1) : h;
+    }
+    return h.replace(/:\d*$/, "");
+}
+function matchOrigin(origin, pattern) {
+    if (pattern === origin)
+        return true;
+    let o;
+    try {
+        o = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    const m = /^(https?):\/\/(\*\.)?(\[[^\]]+\]|[^:/]+)(?::(\*|\d+))?$/.exec(pattern);
+    if (!m)
+        return false;
+    const [, scheme, wildcard, host, port] = m;
+    if (o.protocol !== `${scheme}:`)
+        return false;
+    if (wildcard ? !o.hostname.endsWith(`.${host}`) : o.hostname !== host)
+        return false;
+    if (port === "*")
+        return true;
+    return o.port === (port ?? "");
+}
+/** Whether a browser `Origin` may use the bridge. */
+export function isAllowedOrigin(origin, extra = []) {
+    if (origin === "null")
+        return false;
+    for (const p of DEFAULT_ALLOWED_ORIGINS)
+        if (matchOrigin(origin, p))
+            return true;
+    for (const p of extra)
+        if (matchOrigin(origin, p))
+            return true;
+    return false;
+}
+/** CORS + Private Network Access headers for an allowed origin. */
+export function corsHeaders(origin) {
+    return {
+        "access-control-allow-origin": origin,
+        "access-control-allow-private-network": "true",
+        "access-control-allow-methods": "GET, HEAD, POST, PATCH, PUT, DELETE, OPTIONS",
+        "access-control-allow-headers": `Content-Type, Accept, Last-Event-ID, x-opencode-directory, ${CLIENT_HEADER}`,
+        "access-control-expose-headers": BRIDGE_HEADER,
+        "access-control-max-age": "86400",
+        vary: "Origin",
+    };
+}
+/** `http://0.0.0.0:49374` → `http://127.0.0.1:49374`; picks the first URL in CLI output. */
+export function normalizeTargetUrl(raw) {
+    const word = raw.split(/\s+/).find((s) => /^https?:\/\//i.test(s));
+    if (!word)
+        return null;
+    try {
+        const u = new URL(word);
+        if (u.hostname === "0.0.0.0" || u.hostname === "[::]")
+            u.hostname = "127.0.0.1";
+        return u.origin;
+    }
+    catch {
+        return null;
+    }
+}
+function opencodeFallbacks() {
+    try {
+        const home = homedir();
+        return [join(home, ".bun", "bin", "opencode"), join(home, ".opencode", "bin", "opencode"), "/opt/homebrew/bin/opencode", "/usr/local/bin/opencode"];
+    }
+    catch {
+        return ["/opt/homebrew/bin/opencode", "/usr/local/bin/opencode"];
+    }
+}
+function execOpencode(bin, args) {
+    return new Promise((resolve) => {
+        execFile(bin, args, { timeout: 4000, windowsHide: true }, (error, stdout) => {
+            const enoent = Boolean(error && error.code === "ENOENT");
+            resolve({ ok: !error, enoent, stdout: error ? "" : String(stdout).trim() });
+        });
+    });
+}
+async function run(args) {
+    const first = await execOpencode("opencode", args);
+    if (!first.enoent)
+        return first.stdout;
+    for (const candidate of opencodeFallbacks()) {
+        if (!existsSync(candidate))
+            continue;
+        const res = await execOpencode(candidate, args);
+        if (!res.enoent)
+            return res.stdout;
+    }
+    return "";
+}
+/** Loopback aliases (`localhost`, `127.0.0.1`, `[::1]`) with the same port select the trusted target, while requests still go to `trusted`. */
+export function selectsTarget(origin, trusted) {
+    if (origin === trusted)
+        return true;
+    const a = new URL(origin);
+    const b = new URL(trusted);
+    return LOOPBACK_HOSTNAMES.has(a.hostname) && LOOPBACK_HOSTNAMES.has(b.hostname) && a.port === b.port && a.protocol === b.protocol;
+}
+/** An explicit target wins. Never apply a foreground server's password to a browser-selected URL. */
+export async function discoverOpencode(target) {
+    const configured = (target ?? process.env.OPENCODE_SERVER_URL ?? "").trim();
+    let explicit;
+    if (configured) {
+        const u = new URL(configured.includes("://") ? configured : `http://${configured}`);
+        if (!/^https?:$/.test(u.protocol) || u.username || u.password || u.pathname !== "/" || u.search || u.hash) {
+            throw txError("TX021");
+        }
+        explicit = normalizeTargetUrl(u.origin) ?? undefined;
+    }
+    const service = normalizeTargetUrl(await run(["service", "status"]));
+    if (service && (!explicit || selectsTarget(explicit, service))) {
+        const password = await run(["service", "get", "password"]);
+        return { url: service, source: "service", authorization: password ? `Basic ${Buffer.from(`opencode:${password}`).toString("base64")}` : undefined };
+    }
+    if (!explicit)
+        return null;
+    const password = LOOPBACK_HOSTNAMES.has(new URL(explicit).hostname) ? process.env.OPENCODE_PASSWORD ?? process.env.OPENCODE_SERVER_PASSWORD : undefined;
+    const username = process.env.OPENCODE_PASSWORD ? "opencode" : process.env.OPENCODE_SERVER_USERNAME || "opencode";
+    return { url: explicit, source: target ? "flag" : "env", authorization: password ? `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}` : undefined };
+}
+/** A Vite/SPA fallback can return 200 HTML for *every* path. Verify the API, not just the status. */
+export async function probeOpenCode(t) {
+    const headers = new Headers({ accept: "application/json" });
+    if (t.authorization)
+        headers.set("authorization", t.authorization);
+    try {
+        for (const path of ["/api/info", "/session?limit=1"]) {
+            const res = await fetch(`${t.url}${path}`, { headers, signal: AbortSignal.timeout(5000), redirect: "manual" });
+            if (res.ok && res.headers.get("content-type")?.includes("application/json")) {
+                const data = await res.json();
+                if (path === "/api/info" ? typeof data?.version === "string" : Array.isArray(data))
+                    return res.status;
+            }
+            else {
+                await res.body?.cancel();
+                if (!res.ok && res.status !== 404 && res.status !== 405)
+                    return res.status;
+            }
+        }
+        return 415;
+    }
+    catch {
+        return 0;
+    }
+}
+function json(status, body, headers = {}) {
+    return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", "cache-control": "no-store", ...headers } });
+}
+async function readBody(request, limit = MAX_BODY_BYTES) {
+    if (!request.body)
+        return new ArrayBuffer(0);
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > limit) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(size);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+    }
+    return out.buffer;
+}
+/** The bridge as a Web `Request → Response` handler. */
+export function createBridgeHandler(options = {}) {
+    const discover = options.discover ?? (() => discoverOpencode(options.target));
+    const cacheMs = options.cacheMs ?? 30_000;
+    const extra = options.allowOrigins ?? [];
+    let cached = null;
+    const target = async (force = false) => {
+        if (!force && cached && Date.now() - cached.at < cacheMs)
+            return cached.target;
+        cached = { target: await discover(), at: Date.now() };
+        return cached.target;
+    };
+    const handler = (async (request) => {
+        const url = new URL(request.url);
+        const host = request.headers.get("host") ?? url.host;
+        if (!LOOPBACK_HOSTNAMES.has(hostnameOf(host)))
+            return json(403, { error: "Forbidden host" });
+        const origin = request.headers.get("origin");
+        if (origin !== null && !isAllowedOrigin(origin, extra))
+            return json(403, { error: "Origin not allowed" });
+        const cors = { [BRIDGE_HEADER]: "1", ...(origin !== null ? corsHeaders(origin) : {}) };
+        const method = request.method.toUpperCase();
+        if (method === "OPTIONS")
+            return new Response(null, { status: 204, headers: cors });
+        if (url.pathname === "/__bridge") {
+            const wasCached = cached !== null && Date.now() - cached.at < cacheMs;
+            let t = await target();
+            let code = t ? await probeOpenCode(t) : 0;
+            if (wasCached && t?.source === "service" && (code === 0 || code === 401)) {
+                t = await target(true);
+                code = t ? await probeOpenCode(t) : 0;
+            }
+            return json(200, { bridge: "textjs", target: t?.url ?? null, connected: code >= 200 && code < 300 }, cors);
+        }
+        if (!SAFE_METHODS.has(method) && request.headers.get(CLIENT_HEADER) !== "1")
+            return json(403, { error: `Missing ${CLIENT_HEADER} header` }, cors);
+        const wasCached = cached !== null && Date.now() - cached.at < cacheMs;
+        let t = await target();
+        if (t === null)
+            t = await target(true);
+        if (t === null)
+            return json(502, { error: "No OpenCode server found. Start `opencode` or pass --target." }, cors);
+        const buildHeaders = (auth) => {
+            const h = new Headers();
+            for (const k of FORWARD_REQUEST_HEADERS) {
+                const v = request.headers.get(k);
+                if (v)
+                    h.set(k, v);
+            }
+            if (auth)
+                h.set("authorization", auth);
+            return h;
+        };
+        let body;
+        if (method !== "GET" && method !== "HEAD") {
+            if (Number(request.headers.get("content-length") ?? 0) > MAX_BODY_BYTES)
+                return json(413, { error: "Payload Too Large" }, cors);
+            const read = await readBody(request);
+            if (read === null)
+                return json(413, { error: "Payload Too Large" }, cors);
+            body = read;
+        }
+        const canRetry = wasCached && t.source === "service" && SAFE_METHODS.has(method);
+        let upstream;
+        try {
+            upstream = await fetch(`${t.url}${url.pathname}${url.search}`, { method, headers: buildHeaders(t.authorization), body, signal: request.signal, redirect: "manual" });
+        }
+        catch (error) {
+            if (request.signal.aborted)
+                return new Response(null, { status: 499, headers: cors });
+            cached = null;
+            if (canRetry) {
+                const refreshed = await target(true);
+                if (refreshed) {
+                    try {
+                        upstream = await fetch(`${refreshed.url}${url.pathname}${url.search}`, { method, headers: buildHeaders(refreshed.authorization), body, signal: request.signal, redirect: "manual" });
+                    }
+                    catch (retryError) {
+                        if (request.signal.aborted)
+                            return new Response(null, { status: 499, headers: cors });
+                        cached = null;
+                        return json(502, { error: "OpenCode server unreachable", detail: retryError instanceof Error ? retryError.message : String(retryError) }, cors);
+                    }
+                }
+                else {
+                    return json(502, { error: "OpenCode server unreachable", detail: error instanceof Error ? error.message : String(error) }, cors);
+                }
+            }
+            else {
+                return json(502, { error: "OpenCode server unreachable", detail: error instanceof Error ? error.message : String(error) }, cors);
+            }
+        }
+        // The daemon may have restarted with a new port or password.
+        if (upstream.status === 401) {
+            cached = null;
+            if (canRetry) {
+                const refreshed = await target(true);
+                if (refreshed && (refreshed.url !== t.url || refreshed.authorization !== t.authorization)) {
+                    await upstream.body?.cancel().catch(() => undefined);
+                    try {
+                        upstream = await fetch(`${refreshed.url}${url.pathname}${url.search}`, { method, headers: buildHeaders(refreshed.authorization), body, signal: request.signal, redirect: "manual" });
+                    }
+                    catch (retryError) {
+                        if (request.signal.aborted)
+                            return new Response(null, { status: 499, headers: cors });
+                        cached = null;
+                        return json(502, { error: "OpenCode server unreachable", detail: retryError instanceof Error ? retryError.message : String(retryError) }, cors);
+                    }
+                }
+            }
+        }
+        const out = new Headers(cors);
+        for (const h of FORWARD_RESPONSE_HEADERS) {
+            const v = upstream.headers.get(h);
+            if (v)
+                out.set(h, v);
+        }
+        out.set("cache-control", "no-cache");
+        if ((upstream.headers.get("content-type") ?? "").includes("text/event-stream")) {
+            out.set("connection", "keep-alive");
+            out.set("x-accel-buffering", "no");
+        }
+        return new Response(method === "HEAD" ? null : upstream.body, { status: upstream.status, statusText: upstream.statusText, headers: out });
+    });
+    handler.target = target;
+    return handler;
+}
+async function serveNode(handler, req, res) {
+    const abort = new AbortController();
+    res.on("close", () => abort.abort());
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (typeof v === "string")
+            headers.set(k, v);
+        else if (Array.isArray(v))
+            headers.set(k, v.join(", "));
+    }
+    const method = (req.method ?? "GET").toUpperCase();
+    const hasBody = method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
+    const body = hasBody
+        ? new ReadableStream({
+            start(controller) {
+                req.on("data", (c) => controller.enqueue(new Uint8Array(c)));
+                req.on("end", () => controller.close());
+                req.on("error", (e) => controller.error(e));
+            },
+            cancel() {
+                req.destroy();
+            },
+        })
+        : undefined;
+    const request = new Request(`http://${req.headers.host ?? "127.0.0.1"}${req.url ?? "/"}`, {
+        method,
+        headers,
+        body,
+        signal: abort.signal,
+        ...(body ? { duplex: "half" } : {}),
+    });
+    const response = await handler(request);
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => res.setHeader(key, value));
+    if (!response.body) {
+        res.end();
+        return;
+    }
+    res.flushHeaders();
+    const reader = response.body.getReader();
+    const cancel = () => {
+        reader.cancel().catch(() => undefined);
+    };
+    res.on("close", cancel);
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done || res.writableEnded || res.destroyed)
+                break;
+            res.write(value);
+        }
+    }
+    catch {
+        // client disconnected mid-stream
+    }
+    finally {
+        res.off("close", cancel);
+    }
+    res.end();
+}
+/** Start the bridge on `127.0.0.1:<port>`. */
+export async function startProxy(options = {}) {
+    const handler = createBridgeHandler(options);
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? DEFAULT_PROXY_PORT;
+    const target = await handler.target();
+    if (target) {
+        const t = new URL(target.url);
+        if (LOOPBACK_HOSTNAMES.has(t.hostname) && Number(t.port) === port) {
+            throw txError("TX022", port);
+        }
+    }
+    const server = createServer((req, res) => {
+        serveNode(handler, req, res).catch((error) => {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader("content-type", "application/json");
+            }
+            res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+        });
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(port, host, () => {
+                server.off("error", reject);
+                resolve();
+            });
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (port > 0 && (err?.code === "EADDRINUSE" || /in use/i.test(msg))) {
+            const probeHost = host === "::1" ? "[::1]" : host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+            const existing = await fetch(`http://${probeHost}:${port}/__bridge`, { signal: AbortSignal.timeout(1000) })
+                .then((r) => (r.ok ? r.json() : null))
+                .catch(() => null);
+            if (existing && typeof existing === "object" && existing.bridge === "textjs") {
+                const dest = typeof existing.target === "string" ? ` → ${existing.target}` : "";
+                throw txError("TX023", `http://${probeHost}:${port}${dest}`, `http://${probeHost}:${port}`, port + 1);
+            }
+            throw txError("TX024", port, port + 1, `http://${probeHost}:${port + 1}`);
+        }
+        throw err;
+    }
+    const addr = server.address();
+    const url = `http://${host === "::1" ? "[::1]" : host}:${addr.port}`;
+    if (options.log !== false) {
+        const dest = target ? `${target.url}${target.source === "service" ? color.dim(" (opencode service)") : ""}` : color.yellow("no OpenCode server yet. Start opencode.");
+        console.log(`\n   ${color.bold("▼ Text.js OpenCode Bridge")}\n\n   ${url} ${color.dim("→")} ${dest}\n   ${color.dim("Open https://textjs.org/opencode to connect.")}\n`);
+    }
+    return {
+        server,
+        url,
+        target,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections?.();
+            server.close(() => resolve());
+        }),
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "1.0.2";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "1.0.2";

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@textjs/opencode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "A loopback bridge that connects textjs.org/opencode to the OpenCode server on your machine.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "homepage": "https://textjs.org/docs/opencode",
+  "keywords": [
+    "opencode",
+    "textjs",
+    "cors",
+    "proxy",
+    "bridge"
+  ],
+  "bin": {
+    "textjs-opencode": "bin/textjs-opencode.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/textjs-opencode.js",
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json && bun ../../scripts/esm-specifiers.ts dist",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "bun test"
+  }
+}