viewable-one 0.0.0-stage → 0.12.1

package/lib/sharedPreview.mjs

@@ -0,0 +1,292 @@
+// Provider-neutral lifecycle for sharing a worktree dev server, over rows
+// (brief 30 Move 2b, 2026-09-11). The app asks with a `run_ops` row of
+// `kind:"preview"` now (`heartbeat`'s `ops`, `opTake` claims it once,
+// `opResult` is UPDATABLE - unlike merge/delete/relaunch, a preview's result
+// ticks through starting/ready/offline/error on the SAME op row rather than
+// one receipt per state). This module proves that the named loopback port is
+// a verified server belonging to the named board run before a tunnel
+// provider ever sees it - the proof is read from the CLAIMED run row (via
+// `runnerApi.runs`) and from `get_node` over `hosted.callTool`, NEVER from
+// `canvas/`: there is no local mirror requirement any more, so a preview
+// works whether or not a browser has this folder linked at all.
+//
+// WHAT REPLACED WHAT. The file version polled a directory of `*.json`
+// requests every tick and noticed a deleted file as "stop it, the request
+// was removed"; there is no such signal over rows (a taken `run_ops` row
+// carries no "cancel" op in the Move 2 contract - `run_op_cancel` only
+// reaches an UNTAKEN one, server-side, before this module ever sees it). So
+// every preview this module tracks ends the same way now: the next proof
+// check fails - the owning run stopped, the browser node was deleted or its
+// URL changed, the recorded server can no longer be verified - and that
+// failure IS the removal signal, exactly as it already was for "the request
+// changed under me" in the file version. `close()` still stops every
+// tracked tunnel on its own shutdown.
+//
+// THE PROOF ITSELF is the same three checks the file version made, sourced
+// differently: which run this preview belongs to (`runnerApi.runs`, matched
+// by `runKey === run.id`, its OWN `from_id` naming the prompt directly -
+// simpler than the old graph search for "a prompt whose `run.key` equals
+// this one", because the row already knows), the browser node's kind, url
+// and incoming edge from that prompt (`get_node`, parsed off its own text
+// reply - the endpoint's only shape), and the recorded dev server itself
+// (`run.server`, mirrored onto the row by `runnerCompletion.mjs` when the
+// child exits, or the worktree's own live `.glytch-server.json` while the
+// run is still going - `verifyPreviewServer`, unchanged).
+
+import { readWorktreeRecord, verifyPreviewServer } from "./devserver.mjs";
+import { callTool as hostedCallToolDefault } from "./hosted.mjs";
+import { fromIdOf } from "./boardside.mjs";
+import * as runnerApiModule from "./runnerApi.mjs";
+
+export const PREVIEW_VERSION = 1;
+export const MAX_RESTARTS = 5;
+export const STABLE_RESET_MS = 60_000;
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const SAFE_ID = /^[A-Za-z0-9_-]+$/;
+// Match the grant issuer's namespaced cloud-board contract. Values outside
+// this shape can never receive a member grant, so reject them before startup.
+const SAFE_CLOUD_BOARD_ID = /^[^\s:]+:[^\s:]+$/;
+const OPAQUE_PREVIEW_ID = /^[A-Za-z0-9_-]{16,128}$/;
+
+function localOrigin(value) {
+  let url;
+  try { url = new URL(value); } catch { return null; }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  if (!["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) return null;
+  if (url.username || url.password) return null;
+  const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? { url, port, origin: url.origin } : null;
+}
+
+/** Validate a `run_ops` row's own `payload` for `kind:"preview"` - the same
+ *  fields the file request used to carry (Move 2 contract: `{nodeId, runKey,
+ *  localUrl, boardId, workspaceId, cloudBoardId}`), unchanged in shape. */
+function parsePayload(payload) {
+  const value = isObject(payload) ? payload : {};
+  if (value.version !== undefined && value.version !== PREVIEW_VERSION) {
+    throw new Error("Preview request needs version 1.");
+  }
+  for (const field of ["boardId", "workspaceId", "cloudBoardId", "nodeId", "runKey", "localUrl"]) {
+    if (typeof value[field] !== "string" || value[field].trim() === "") throw new Error(`Preview request needs ${field}.`);
+  }
+  for (const field of ["boardId", "workspaceId", "nodeId", "runKey"]) {
+    if (!SAFE_ID.test(value[field])) throw new Error(`Preview request ${field} contains unsafe characters.`);
+  }
+  if (!SAFE_CLOUD_BOARD_ID.test(value.cloudBoardId)) throw new Error("Preview request cloudBoardId contains unsafe characters.");
+  const origin = localOrigin(value.localUrl);
+  if (!origin) throw new Error("localUrl must be a credential-free loopback HTTP(S) URL.");
+  return { ...value, origin: origin.origin, port: origin.port };
+}
+
+/** Parse `get_node`'s own text reply (supabase/functions/board-mcp/tools.mjs)
+ *  back into `{node, incoming, outgoing}`. It is a text protocol for a
+ *  model, not a second JSON API - one line is the node's own JSON (an image
+ *  value redacted, harmless here), then "Incoming edges from: a, b" and
+ *  "Outgoing edges to: c, d" when either exists. */
+export function parseNodeText(text) {
+  let node = null;
+  for (const line of String(text ?? "").split("\n")) {
+    if (!line.startsWith("{")) continue;
+    try { node = JSON.parse(line); break; } catch { /* not this line */ }
+  }
+  const split = (label) => {
+    const m = new RegExp(`^${label}: (.*)$`, "m").exec(text ?? "");
+    return m ? m[1].split(",").map((s) => s.trim()).filter(Boolean) : [];
+  };
+  return { node, incoming: split("Incoming edges from"), outgoing: split("Outgoing edges to") };
+}
+
+/** The proof, over rows. Throws with a human-readable reason on any failure
+ *  - the caller turns that into an `error` opResult, unchanged in spirit
+ *  from the file version. */
+async function rowServerProof(request, projectId, deps) {
+  const listed = await deps.runs({ projectIds: [projectId] }, deps.rowsOpts);
+  if (!listed.ok) throw new Error(`Could not list this project's runs: ${listed.error}`);
+  const run = (listed.runs ?? []).find((r) => r.id === request.runKey);
+  if (!run || run.approved !== true) throw new Error(`No matching approved run for ${request.runKey}.`);
+
+  const promptId = fromIdOf(run.request);
+  if (!promptId) throw new Error(`Run ${request.runKey} has no idea to attach a preview to.`);
+
+  const nodeOut = await deps.callTool("get_node", { id: request.nodeId }, { ...deps.toolOpts, boardId: request.cloudBoardId });
+  if (nodeOut.isError) throw new Error(`Could not read node ${request.nodeId}: ${nodeOut.text}`);
+  const browser = parseNodeText(nodeOut.text);
+  if (browser.node?.data?.kind !== "browser") throw new Error(`Node ${request.nodeId} is not a browser on board ${request.boardId}.`);
+  if (browser.node?.data?.url !== request.localUrl) throw new Error("Browser node local URL does not match the preview request.");
+  if (!browser.incoming.includes(promptId)) throw new Error("Browser node is not linked from the idea that owns this run.");
+
+  // THE RECORDED DEV SERVER: the worktree's own live file while the run is
+  // still going (a session that just started its server, before the runner
+  // has mirrored anything onto the row), else the row's own `server` column,
+  // mirrored by `runnerCompletion.mjs` once the child exits.
+  let record = null;
+  if (typeof run.sidecar?.worktreePath === "string" && run.sidecar.worktreePath !== "") {
+    record = await deps.readLiveRecord(run.sidecar.worktreePath);
+    if (record) record = { ...record, worktreePath: run.sidecar.worktreePath };
+  }
+  if (!record && run.server) record = run.server;
+  if (!record) throw new Error("This run has no recorded dev server.");
+  if (Number(record.port) !== request.port) throw new Error("Preview URL port does not match the recorded dev server.");
+  const verified = await deps.verify(record);
+  if (!verified?.ours) throw new Error(`Recorded dev server could not be verified: ${verified?.reason ?? "unknown"}.`);
+  return { record, promptId, run };
+}
+
+/** A rows-driven preview tunnel service. `onOps(ops, projectId)` is fed
+ *  `heartbeat`'s untaken ops list each beat (like `serviceRowOps`'s
+ *  merge/delete handling) and claims (`opTake`) every `kind:"preview"` one
+ *  it finds, once; `tick()` re-verifies and advances every op it is
+ *  tracking, writing `opResult` on each lifecycle change; `close()` tears
+ *  every tracked tunnel down. `projectId` is threaded through per call
+ *  rather than fixed at construction, because `watch()` only learns its
+ *  project id after the FIRST successful `register` - the service itself is
+ *  made once, before that. */
+export function createSharedPreviewService({ runnerApi = runnerApiModule, hostedCallTool = hostedCallToolDefault, env, fetchImpl, deps: overrides = {}, startTunnel }) {
+  if (typeof startTunnel !== "function") throw new TypeError("startTunnel is required");
+  const rowsOpts = { env, fetchImpl };
+  const toolOpts = { env, fetchImpl };
+  const deps = {
+    now: () => Date.now(),
+    runs: runnerApi.runs,
+    opResult: runnerApi.opResult,
+    callTool: hostedCallTool,
+    readLiveRecord: readWorktreeRecord,
+    verify: verifyPreviewServer,
+    rowsOpts,
+    toolOpts,
+    ...overrides,
+  };
+  const active = new Map(); // opId -> {request, stamp, handle, restarts, nextAttemptAt, readySince}
+  const lifetime = new AbortController();
+  let closed = false;
+
+  const writeResult = (opId, status, extra = {}) =>
+    deps.opResult({ opId, result: { status, ...extra, updatedAt: deps.now() } }, rowsOpts);
+
+  const stop = async (opId, state, detail) => {
+    active.delete(opId);
+    try { await state.handle?.stop?.(); } catch { /* best effort; the result still tells */ }
+    await writeResult(opId, "offline", { detail });
+  };
+
+  /** Claim every untaken preview op this beat's heartbeat surfaced. Bad
+   *  payloads are refused at once, same as a malformed file used to be. */
+  async function onOps(ops, projectId) {
+    for (const op of ops ?? []) {
+      if (closed) return;
+      if (op.kind !== "preview" || active.has(op.id)) continue;
+      const taken = await runnerApi.opTake({ opId: op.id }, rowsOpts);
+      if (!taken.ok || !taken.op) continue; // already taken, gone, or not ours
+      if (closed) {
+        await writeResult(op.id, "offline", { detail: "Preview service stopped." });
+        return;
+      }
+      let request;
+      try {
+        request = parsePayload(taken.op.payload);
+      } catch (error) {
+        await writeResult(op.id, "error", { detail: error instanceof Error ? error.message : String(error) });
+        continue;
+      }
+      active.set(op.id, { request, projectId, handle: null, restarts: 0, nextAttemptAt: 0 });
+    }
+  }
+
+  let ticking = null;
+
+  /** Re-verify and advance every tracked preview. Called every beat.
+   *  Single-flight: two concurrent calls share one pass rather than racing
+   *  each other into starting the same tunnel twice. */
+  function tick() {
+    if (ticking) return ticking;
+    ticking = runTick().finally(() => { ticking = null; });
+    return ticking;
+  }
+
+  async function runTick() {
+    if (closed) return;
+    for (const [opId, state] of [...active]) {
+      if (closed) return;
+      const { request, projectId } = state;
+      if (state.handle) {
+        try {
+          await rowServerProof(request, projectId, deps);
+        } catch (error) {
+          await stop(opId, state, error instanceof Error ? error.message : String(error));
+          continue;
+        }
+        let alive = true;
+        try { alive = state.handle.alive ? await state.handle.alive() : true; } catch { alive = false; }
+        if (alive) {
+          if (deps.now() - state.readySince >= STABLE_RESET_MS) state.restarts = 0;
+          await writeResult(opId, "ready", { previewId: state.previewId, url: new URL(state.handle.url).toString() });
+          continue;
+        }
+        try { await state.handle.stop?.(); } catch { /* already gone */ }
+        state.handle = null;
+        state.nextAttemptAt = deps.now() + Math.min(30_000, 1000 * 2 ** state.restarts);
+        state.restarts += 1;
+        await writeResult(opId, "offline", { detail: "Tunnel stopped; restart is scheduled." });
+        continue;
+      }
+      if (state.restarts >= MAX_RESTARTS || deps.now() < state.nextAttemptAt) continue;
+      let provisional = null;
+      try {
+        const proof = await rowServerProof(request, projectId, deps);
+        if (closed) return;
+        await writeResult(opId, "starting");
+        const handle = await startTunnel(request.origin, {
+          ...request, fullLocalUrl: request.localUrl, record: proof.record, promptId: proof.promptId,
+          signal: lifetime.signal,
+          authorizeTarget: async () => {
+            if (closed) return false;
+            try { await rowServerProof(request, projectId, deps); return !closed; }
+            catch { return false; }
+          },
+        });
+        if (isObject(handle) && typeof handle.stop === "function") provisional = handle;
+        if (!isObject(handle) || typeof handle.url !== "string" || typeof handle.stop !== "function") {
+          throw new Error("Tunnel provider returned no preview id/URL/stop handle.");
+        }
+        if (typeof handle.previewId !== "string" || !OPAQUE_PREVIEW_ID.test(handle.previewId)) {
+          throw new Error("Tunnel provider returned no opaque preview id.");
+        }
+        const publicUrl = new URL(handle.url);
+        if (publicUrl.protocol !== "https:" || publicUrl.username || publicUrl.password ||
+          ["localhost", "127.0.0.1", "[::1]"].includes(publicUrl.hostname)) {
+          throw new Error("Tunnel provider URL must be a credential-free, non-loopback HTTPS URL.");
+        }
+        if (closed) throw new Error("Preview service stopped during tunnel startup.");
+        await rowServerProof(request, projectId, deps);
+        if (closed) throw new Error("Preview service stopped during tunnel startup.");
+        state.handle = handle;
+        state.previewId = handle.previewId;
+        state.readySince = deps.now();
+        provisional = null;
+        await writeResult(opId, "ready", { previewId: handle.previewId, url: publicUrl.toString() });
+      } catch (error) {
+        try { await provisional?.stop?.(); } catch { /* provider cleanup is best effort */ }
+        state.restarts += 1;
+        state.nextAttemptAt = deps.now() + Math.min(30_000, 1000 * 2 ** (state.restarts - 1));
+        await writeResult(opId, "error", { detail: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+
+  const close = async () => {
+    closed = true;
+    lifetime.abort();
+    // A provider start already in flight must finish (or abort, on the
+    // signal just fired) before we enumerate the handles to stop, otherwise
+    // shutdown can leave a late handle exposed.
+    let failure;
+    try { if (ticking) await ticking; } catch (error) { failure = error; }
+    for (const [opId, state] of [...active]) {
+      try { await stop(opId, state, "Preview service stopped."); }
+      catch (error) { failure ??= error; }
+    }
+    if (failure) throw failure;
+  };
+  return { onOps, tick, close };
+}

package/lib/signIn.mjs

@@ -0,0 +1,47 @@
+// SIGN IN TO CODEX FROM THE BOARD (#482, ruling #470: "the Codex sign-in
+// page opened for you"). The app files a run row whose request is
+// `{kind: "sign-in", agent: "codex"}`; the runner answers it here by
+// starting `codex login` on this computer. Codex opens the ChatGPT sign-in
+// page in this computer's browser and exits once the sign-in lands, so no
+// one types in a terminal. The runner then probes the agents again, and the
+// app's box goes once the probe says Codex is signed in.
+//
+// Nothing is billed: `codex login` starts no model turn.
+import { spawn } from "node:child_process";
+import { runnableCommand } from "./windows-command.mjs";
+
+/** How long a person has to finish signing in on the page that opened. */
+export const SIGN_IN_WAIT_MS = 10 * 60_000;
+
+/** The engines a sign-in request may name. Claude Code signs in from its
+ *  own first run; opencode's sign-in cannot be checked (detect.mjs). */
+export const SIGN_IN_AGENTS = ["codex"];
+
+/** Start `codex login` and wait for it to end. Resolves `{ok, detail}`,
+ *  never throws: a missing binary or a sign-in left open is an answer. */
+export function codexLogin({ env = process.env, timeoutMs = SIGN_IN_WAIT_MS, platform = process.platform } = {}) {
+  const bin = env.PM_CODEX_BIN?.trim() || "codex";
+  const command = runnableCommand(bin, ["login"], { platform, env });
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command.file, command.args, { env, shell: command.shell, windowsHide: true, stdio: "ignore" });
+    } catch (error) {
+      resolve({ ok: false, detail: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    const timer = setTimeout(() => {
+      child.kill();
+      resolve({ ok: false, detail: "The sign-in page was left open for 10 minutes." });
+    }, timeoutMs);
+    timer.unref?.();
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ ok: false, detail: error.code === "ENOENT" ? "Codex is not installed on this computer." : error.message });
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      resolve(code === 0 ? { ok: true, detail: "Codex is signed in." } : { ok: false, detail: `codex login ended with code ${code}.` });
+    });
+  });
+}