@rryando/arcs 3.10.0 → 4.0.0

package/dist/web-server/hook-auth.js

@@ -0,0 +1,36 @@
+/**
+ * Bearer-token gate for `/api/hook/*`.
+ *
+ * Layered on top of (never instead of) the global loopback-only
+ * `secureLocalRequest`: loopback proves the caller is on this machine, the
+ * token proves it is this project's installed hook script. Browser-facing
+ * routes stay token-free — only the hook endpoint carries a shared secret,
+ * because only it is called by something that is not the ARCS web UI.
+ */
+import { verifyHookToken } from "../utils/hook-token-store.js";
+import { fail, requireProjectDir } from "./respond.js";
+const BEARER = /^Bearer\s+(\S+)$/i;
+/** `/api/hook/:slug/...` → the slug segment, or "" when the shape is wrong. */
+function slugFromPath(url) {
+    const segments = new URL(url).pathname.split("/");
+    return segments[1] === "api" && segments[2] === "hook" ? (segments[3] ?? "") : "";
+}
+export const requireHookToken = async (c, next) => {
+    const unauthorized = () => c.json(fail("hook_unauthorized", "Missing or invalid ARCS hook token"), 401);
+    const match = BEARER.exec((c.req.header("authorization") ?? "").trim());
+    if (!match)
+        return unauthorized();
+    let projectDir;
+    try {
+        projectDir = requireProjectDir(slugFromPath(c.req.url));
+    }
+    catch {
+        // Deliberately 401, not 404: an unauthenticated caller must not be able to
+        // probe which project slugs exist on this machine.
+        return unauthorized();
+    }
+    if (!(await verifyHookToken(projectDir, match[1])))
+        return unauthorized();
+    await next();
+};
+//# sourceMappingURL=hook-auth.js.map

package/dist/web-server/hook-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-auth.js","sourceRoot":"","sources":["../../src/web-server/hook-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,MAAM,GAAG,mBAAmB,CAAC;AAEnC,+EAA+E;AAC/E,SAAS,YAAY,CAAC,GAAW;IAC/B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACpF,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAsB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;IACnE,MAAM,YAAY,GAAG,GAAG,EAAE,CACxB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,oCAAoC,CAAC,EAAE,GAAG,CAAC,CAAC;IAE/E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACxE,IAAI,CAAC,KAAK;QAAE,OAAO,YAAY,EAAE,CAAC;IAElC,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,mDAAmD;QACnD,OAAO,YAAY,EAAE,CAAC;IACxB,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,YAAY,EAAE,CAAC;IAE1E,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC"}

package/dist/web-server/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Web server entry — starts the HTTP server for the ARCS web UI.
+ */
+export interface StartWebServerOptions {
+    /** Port to listen on (defaults to `DEFAULT_WEB_PORT`). Pass 0 for an ephemeral port. */
+    port?: number;
+    /** Interface to bind (defaults to `DEFAULT_WEB_HOST`). */
+    host?: string;
+    /** Auto-open the browser (default false here; the CLI command defaults true). */
+    open?: boolean;
+    /** Override the static client root. */
+    staticRoot?: string;
+    /** Disable the data-dir watcher (tests). */
+    watch?: boolean;
+}
+export interface WebServerHandle {
+    url: string;
+    port: number;
+    host: string;
+    close: () => Promise<void>;
+}
+export declare function startWebServer(options?: StartWebServerOptions): Promise<WebServerHandle>;
+//# sourceMappingURL=index.d.ts.map

package/dist/web-server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web-server/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAeD,wBAAsB,cAAc,CAClC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,CAAC,CA8B1B"}

package/dist/web-server/index.js

@@ -0,0 +1,50 @@
+/**
+ * Web server entry — starts the HTTP server for the ARCS web UI.
+ */
+import { spawn } from "node:child_process";
+import { serve } from "@hono/node-server";
+import { DEFAULT_WEB_HOST, DEFAULT_WEB_PORT } from "../utils/hook-contract.js";
+import { createApp } from "./app.js";
+import { isLoopbackHost } from "./security.js";
+function openBrowser(url) {
+    try {
+        const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+        const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // No browser available — the URL is printed either way.
+    }
+}
+export async function startWebServer(options = {}) {
+    const host = options.host ?? DEFAULT_WEB_HOST;
+    const requestedPort = options.port ?? DEFAULT_WEB_PORT;
+    if (!isLoopbackHost(host)) {
+        throw new Error(`ARCS web only binds to loopback addresses; refusing non-loopback host "${host}".`);
+    }
+    const app = createApp({ staticRoot: options.staticRoot, watch: options.watch });
+    return new Promise((resolvePromise, rejectPromise) => {
+        try {
+            const server = serve({ fetch: app.fetch, port: requestedPort, hostname: host }, (info) => {
+                const url = `http://${host}:${info.port}`;
+                if (options.open)
+                    openBrowser(url);
+                resolvePromise({
+                    url,
+                    port: info.port,
+                    host,
+                    close: () => new Promise((res) => {
+                        server.close(() => res());
+                    }),
+                });
+            });
+            server.on("error", rejectPromise);
+        }
+        catch (err) {
+            rejectPromise(err);
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/web-server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/web-server/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAsB/C,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GACP,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;QAC7F,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7E,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC5B,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAAiC,EAAE;IAEnC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAAC;IAC9C,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAAC;IACvD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,0EAA0E,IAAI,IAAI,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAEhF,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,aAAa,EAAE,EAAE;QACnD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;gBACvF,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC1C,IAAI,OAAO,CAAC,IAAI;oBAAE,WAAW,CAAC,GAAG,CAAC,CAAC;gBACnC,cAAc,CAAC;oBACb,GAAG;oBACH,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,IAAI;oBACJ,KAAK,EAAE,GAAG,EAAE,CACV,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,EAAE;wBACxB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;oBAC5B,CAAC,CAAC;iBACL,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,aAAa,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/web-server/opencode-client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * opencode session discovery bridge (Phase 1 — observability only).
+ *
+ * ARCS never spawns or manages an opencode server; it attaches to an already
+ * running `opencode serve` instance as a thin client, subscribes to the
+ * cross-instance `/global/event` SSE stream, and mirrors what it sees into the
+ * per-project session store. Everything here is best-effort: if opencode is
+ * not configured, not running, or speaks a different dialect, the ARCS web
+ * server keeps working and the sessions list is simply empty or stale.
+ *
+ * Verified against opencode 0.0.0-main-202607110203:
+ * - `opencode serve` defaults to port 0 (ephemeral), so a port/URL must be
+ *   supplied explicitly via env — there is no safe default to guess.
+ * - `OPENCODE_SERVER_PASSWORD` is enforced as HTTP Basic auth with the literal
+ *   username "opencode"; any other username is rejected with 401.
+ * - `/event` is scoped to one instance (`?directory=`); `/global/event` is the
+ *   cross-directory stream and wraps each event as `{ directory, project,
+ *   payload }`. Frames carry no `event:` field, only `data:`.
+ */
+import { type SessionStatus } from "../utils/session-store.js";
+export interface OpencodeConfig {
+    baseUrl: string;
+    password?: string;
+}
+/**
+ * Reads bridge configuration from the environment. Returns null (discovery
+ * disabled) when no opencode endpoint is configured.
+ */
+export declare function readOpencodeConfig(env?: NodeJS.ProcessEnv): OpencodeConfig | null;
+export interface OpencodeMessageTarget {
+    /** opencode-native session id ("ses_…") — never the ARCS normalized id. */
+    runtimeSessionId: string;
+    /** Worktree the session belongs to, when known — scopes opencode's lookup. */
+    directory?: string;
+}
+/**
+ * Injects a user message into a live opencode session.
+ *
+ * Unlike the rest of this module (best-effort observability) this is a user
+ * mutation, so failures throw a typed DagError the web routes can surface.
+ *
+ * Verified against opencode 1.0.0 (`GET /doc`) plus a live server:
+ * - `POST /session/:sessionID/prompt_async` acks with 204 and runs the turn in
+ *   the background. `POST /session/:sessionID/message` takes the same body but
+ *   only responds once the assistant has finished its whole turn — minutes, for
+ *   a browser request — so async delivery is the one that fits a web form.
+ * - the body requires `parts`; a text part is `{ type: "text", text }`.
+ * - `?directory=` is optional (an unscoped send still lands) but is passed when
+ *   known so the lookup is unambiguous across worktrees.
+ */
+export declare function sendOpencodeMessage(config: OpencodeConfig, target: OpencodeMessageTarget, text: string): Promise<void>;
+export interface CreateOpencodeSessionInput {
+    /** Worktree the session runs in — required, see the directory note below. */
+    directory: string;
+    title?: string;
+}
+/** Only what ARCS needs to mirror the session; the SSE stream fills in the rest. */
+export interface CreatedOpencodeSession {
+    runtimeSessionId: string;
+    title?: string;
+}
+/**
+ * Creates a live opencode session bound to a worktree.
+ *
+ * Verified against opencode 0.0.0-main-202607110203 (`GET /doc`, operationId
+ * `session.create`) plus a live server:
+ * - the route is `POST /session` — NOT `/api/session`. opencode serves its own
+ *   web UI from the same port and answers every unknown path with a 200
+ *   text/html SPA shell, so a wrong path looks like a success until the body is
+ *   read. That is why the id is checked below rather than trusting `res.ok`.
+ * - `directory` is a *query* parameter and never a body field. Omitting it does
+ *   not fail; opencode silently creates the session in its own working
+ *   directory, so the caller must always pass the worktree explicitly.
+ * - `title` is the only body field ARCS sets; the response is a full session
+ *   object (`{ id, slug, directory, title, time }`).
+ * - `DELETE /session/:sessionID` exists, so nothing created here is permanent.
+ */
+export declare function createOpencodeSession(config: OpencodeConfig, input: CreateOpencodeSessionInput): Promise<CreatedOpencodeSession>;
+interface OpencodeSessionInfo {
+    id?: string;
+    slug?: string;
+    title?: string;
+    directory?: string;
+    projectID?: string;
+    time?: {
+        created?: number;
+        updated?: number;
+    };
+    project?: {
+        worktree?: string;
+    };
+}
+interface OpencodeEvent {
+    type?: string;
+    properties?: {
+        sessionID?: string;
+        info?: OpencodeSessionInfo;
+        status?: {
+            type?: string;
+        };
+    };
+}
+/**
+ * Maps an opencode event type to the ARCS session status it implies.
+ * Returns null for events that carry no status transition (the record is
+ * refreshed but its status is left alone).
+ */
+export declare function statusForOpencodeEvent(event: OpencodeEvent): SessionStatus | null;
+export interface OpencodeDiscoveryState {
+    enabled: boolean;
+    connected: boolean;
+    baseUrl: string | null;
+}
+export declare function opencodeDiscoveryState(): OpencodeDiscoveryState;
+/**
+ * Starts the discovery loop if an opencode endpoint is configured. Idempotent;
+ * returns false when discovery is disabled (no configuration present).
+ */
+export declare function startOpencodeDiscovery(config?: OpencodeConfig | null): boolean;
+/** Stops the discovery loop (test cleanup / server shutdown). */
+export declare function stopOpencodeDiscovery(): Promise<void>;
+export {};
+//# sourceMappingURL=opencode-client.d.ts.map

package/dist/web-server/opencode-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode-client.d.ts","sourceRoot":"","sources":["../../src/web-server/opencode-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,2BAA2B,CAAC;AAanC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,cAAc,GAAG,IAAI,CAc9F;AAYD,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAiCf;AAMD,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,sBAAsB,CAAC,CAyCjC;AAeD,UAAU,mBAAmB;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE;QACX,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,mBAAmB,CAAC;QAC3B,MAAM,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5B,CAAC;CACH;AAQD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI,CAuBjF;AA2DD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,wBAAgB,sBAAsB,IAAI,sBAAsB,CAE/D;AAoQD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,wBAAuB,GAAG,OAAO,CAW7E;AAED,iEAAiE;AACjE,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAa3D"}