@vincentt-xr/cli 0.1.4 → 0.2.0

package/dist/preview/proxy.d.ts

@@ -1,4 +1,15 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
-export declare function proxyWeb(req: IncomingMessage, res: ServerResponse, targetPort: number): void;
+/**
+ * onOriginError is where the creator's dev server being down is ACTUALLY
+ * OBSERVED.
+ *
+ * The tunnel client's own `onOriginError` fires on a socket error, and it never
+ * sees one: this proxy sits between the two and answers a refused connection
+ * with its own clean 502, so the client reads a perfectly valid HTTP response.
+ * The 502 advisory — the most common failure in the whole feature — was
+ * unreachable until the hook moved here. Found by killing a real dev server
+ * under a live preview, not by reading the code.
+ */
+export declare function proxyWeb(req: IncomingMessage, res: ServerResponse, targetPort: number, onOriginError?: () => void): void;
 export declare function proxyWs(req: IncomingMessage, socket: Duplex, head: Buffer, targetPort: number): void;

package/dist/preview/proxy.js

@@ -9,7 +9,18 @@ import { request, } from "node:http";
 function localHeaders(headers, targetPort) {
     return { ...headers, host: `localhost:${targetPort}` };
 }
-export function proxyWeb(req, res, targetPort) {
+/**
+ * onOriginError is where the creator's dev server being down is ACTUALLY
+ * OBSERVED.
+ *
+ * The tunnel client's own `onOriginError` fires on a socket error, and it never
+ * sees one: this proxy sits between the two and answers a refused connection
+ * with its own clean 502, so the client reads a perfectly valid HTTP response.
+ * The 502 advisory — the most common failure in the whole feature — was
+ * unreachable until the hook moved here. Found by killing a real dev server
+ * under a live preview, not by reading the code.
+ */
+export function proxyWeb(req, res, targetPort, onOriginError) {
     const proxyReq = request({
         host: "127.0.0.1",
         port: targetPort,
@@ -17,12 +28,10 @@ export function proxyWeb(req, res, targetPort) {
         method: req.method,
         headers: localHeaders(req.headers, targetPort),
     }, (proxyRes) => {
-        // The preview tunnel is a *proxied* Cloudflare hostname, so its CDN edge
-        // caches static extensions (.js/.css) by default whenever the origin sends
-        // no Cache-Control — and esbuild's dev serve sends none. That made a phone
-        // reload after every edit serve a stale bundle. Force no-store on every
-        // preview response so neither the CDN nor the device caches it, and drop the
-        // validators that would otherwise drive a 304 back to a cached copy.
+        // A preview response must never be cached: a capability URL in a shared
+        // or intermediary cache is a capability store, and a device that reloads
+        // after an edit must get the new bundle rather than a validated copy of
+        // the old one. The validators go with it, or a 304 defeats the point.
         const headers = { ...proxyRes.headers, "cache-control": "no-store" };
         delete headers.etag;
         delete headers["last-modified"];
@@ -30,6 +39,7 @@ export function proxyWeb(req, res, targetPort) {
         proxyRes.pipe(res);
     });
     proxyReq.on("error", () => {
+        onOriginError?.();
         if (!res.headersSent)
             res.writeHead(502);
         res.end();

package/dist/preview/qr.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Interactive-only decoration DEGRADES, it does not disappear. The QR renders
+ * on a TTY and is omitted when piped — an agent has no camera, and a thousand
+ * block characters in a tool transcript is a real cost to the creator's context
+ * window. The URL beside it is always present and is the actual payload.
+ */
+export declare function shouldRenderQr(opts: {
+    isTTY: boolean;
+    noQr: boolean;
+    columns?: number;
+}): boolean;
+/**
+ * renderModules turns a boolean module matrix into half-block rows.
+ *
+ * The convention is INVERTED from the obvious one: a set module is rendered as
+ * the BACKGROUND (a space) and an unset module as a block. Terminals are
+ * overwhelmingly light-on-dark, and a scanner needs the quiet zone and the light
+ * modules to be the brighter of the two. Getting this backwards produces a
+ * symbol that looks perfect and scans on nothing.
+ */
+export declare function renderModules(modules: boolean[][]): string[];
+/**
+ * Build the terminal QR for a preview URL.
+ *
+ * A ~62-character preview URL fits a version-3/4 symbol at error-correction
+ * level L. L rather than M because the terminal render is pixel-perfect — there
+ * is no print smudge or camera blur to recover from at the source, only at the
+ * lens — and every step up in correction level adds modules, which adds rows.
+ */
+export declare function renderTerminalQr(url: string): Promise<string[]>;

package/dist/preview/qr.js

@@ -0,0 +1,89 @@
+// The terminal QR (Flow L13 step 4) — the handoff, and the moment the feature
+// exists for. It sits above the fold with the URL.
+//
+// Half-block glyphs, so one terminal row carries TWO module rows: a 25x25
+// symbol renders in ~13 rows instead of 25, which is what keeps the QR and the
+// URL on one screen. Rendering one module per row would push the URL below the
+// fold on a standard terminal, and the URL is the payload.
+import QRCode from "qrcode";
+/**
+ * Interactive-only decoration DEGRADES, it does not disappear. The QR renders
+ * on a TTY and is omitted when piped — an agent has no camera, and a thousand
+ * block characters in a tool transcript is a real cost to the creator's context
+ * window. The URL beside it is always present and is the actual payload.
+ */
+export function shouldRenderQr(opts) {
+    if (opts.noQr)
+        return false;
+    if (!opts.isTTY)
+        return false;
+    // A symbol narrower than the terminal or it wraps, and a wrapped QR does not
+    // scan at all — which is worse than no QR, because the creator tries.
+    return (opts.columns ?? 80) >= 33;
+}
+const UPPER = "▀";
+const LOWER = "▄";
+const FULL = "█";
+const BLANK = " ";
+/**
+ * renderModules turns a boolean module matrix into half-block rows.
+ *
+ * The convention is INVERTED from the obvious one: a set module is rendered as
+ * the BACKGROUND (a space) and an unset module as a block. Terminals are
+ * overwhelmingly light-on-dark, and a scanner needs the quiet zone and the light
+ * modules to be the brighter of the two. Getting this backwards produces a
+ * symbol that looks perfect and scans on nothing.
+ */
+export function renderModules(modules) {
+    const rows = [];
+    for (let y = 0; y < modules.length; y += 2) {
+        const top = modules[y] ?? [];
+        const bottom = modules[y + 1];
+        let line = "";
+        for (let x = 0; x < top.length; x++) {
+            // `dark === true` means a set (black) module, which renders as absence.
+            const t = top[x] === true;
+            const b = bottom === undefined ? false : bottom[x] === true;
+            if (t && b)
+                line += BLANK;
+            else if (t)
+                line += LOWER;
+            else if (b)
+                line += UPPER;
+            else
+                line += FULL;
+        }
+        rows.push(line);
+    }
+    return rows;
+}
+/**
+ * Build the terminal QR for a preview URL.
+ *
+ * A ~62-character preview URL fits a version-3/4 symbol at error-correction
+ * level L. L rather than M because the terminal render is pixel-perfect — there
+ * is no print smudge or camera blur to recover from at the source, only at the
+ * lens — and every step up in correction level adds modules, which adds rows.
+ */
+export async function renderTerminalQr(url) {
+    const qr = QRCode.create(url, { errorCorrectionLevel: "L" });
+    const size = qr.modules.size;
+    const data = qr.modules.data;
+    // A two-module quiet zone on every side. The spec asks for four; two is the
+    // practical floor that still scans against a terminal background, and it
+    // costs two rows rather than four.
+    const quiet = 2;
+    const total = size + quiet * 2;
+    const grid = [];
+    for (let y = 0; y < total; y++) {
+        const row = [];
+        for (let x = 0; x < total; x++) {
+            const my = y - quiet;
+            const mx = x - quiet;
+            const inside = my >= 0 && my < size && mx >= 0 && mx < size;
+            row.push(inside ? data[my * size + mx] === 1 : false);
+        }
+        grid.push(row);
+    }
+    return renderModules(grid);
+}

package/dist/preview/runner.d.ts

@@ -1,53 +1,178 @@
-import { type ChildProcess } from "node:child_process";
+import { type ControlKind, type TunnelState, type UAClass } from "@vincentt-xr/harness/tunnel";
+import type { DiagEvent } from "@vincentt-xr/harness/events";
+import { type EventTags } from "../relay/server.js";
+import type { ResolvedConfig } from "../shared/config.js";
+/** Why a preview ended. Each maps to exactly one screen (Flow L20/L21). */
+export type PreviewEndReason = "stopped"
+/**
+ * `stopped` reported by the API, not observed locally. A separate member from
+ * `stopped` because this window was not the actor: it holds no timer and no
+ * viewer count, so it must not print the stats the local screen prints.
+ */
+ | "stopped_elsewhere"
+/**
+ * The connection closed and the session did not come back. Deliberately
+ * distinct from `grace_exhausted`, which is the CLI's own observation after
+ * it watched the link go and tried; this one is reported to a process that
+ * may never have witnessed the drop.
+ */
+ | "disconnected" | "hard_max" | "superseded" | "grace_exhausted"
+/**
+ * The drop PAST the cap — the edge refused the reconnect with a 409 because
+ * `graceUsed` is spent. Distinct from `grace_exhausted` (the grace window
+ * elapsed without the client getting back): same remedy, different diagnosis,
+ * and the copy explains the bound only at the moment it bites.
+ */
+ | "grace_cap" | "authz_revoked" | "authz_unconfirmed"
+/**
+ * The 30-minute heartbeat-silence flip. NEVER reported as `hard_max`: a
+ * session ended at minute 30 has not reached its 12-hour ceiling, and saying
+ * so is a false statement about the product's own behaviour.
+ */
+ | "abandoned" | "egress_cap";
 export interface StartPreviewOptions {
     /** Project directory — its .vincentt binding + dev script drive the preview. */
     projectCwd: string;
-    /** App dev-serve port (default 5173). If a server is already listening here, it
-     *  is reused instead of spawning a second one. */
+    /** The API host + PAT. Resolved by the caller so the runner makes no policy. */
+    config: ResolvedConfig;
+    projectId: string;
+    /** App dev-serve port (default 5173). A server already here is REUSED. */
     appPort?: number;
-    /** Relay port. Default: an OS-assigned free port (returned as relayPort). */
     relayPort?: number;
-    /** Front-proxy port the tunnel points at. Default: an OS-assigned free port. */
     frontPort?: number;
     /** Path routed to the relay instead of the app (default /__harness). */
     harnessPath?: string;
-    /** Command that starts the app dev serve on $PORT (default `npm run dev`). */
     devCommand?: string[];
-    /** stdio for the app dev serve. "ignore" (default) keeps an MCP server's stdout
-     *  clean; a CLI can pass "inherit" to surface build output. */
     appStdio?: "ignore" | "inherit";
-    /** How long to wait for cloudflared to register before giving up (default 90s).
-     *  Generous because on a network that blocks the QUIC edge, cloudflared spends
-     *  ~20-30s failing QUIC before it falls back to the http2 edge, which does work. */
-    registerTimeoutMs?: number;
-    /** How long to wait for the app to serve before returning anyway (default 8s).
-     *  Kept short so an MCP tool call stays within strict clients' ~30s timeout;
-     *  a not-yet-ready app still returns (appReady=false), it isn't an error. */
     appReadyTimeoutMs?: number;
-    /** Progress sink (relay/cloudflared lines). Never write app stdout to MCP stdout. */
+    /** Progress sink. Never write app stdout to an MCP server's stdout. */
     onLog?: (message: string) => void;
+    /**
+     * A viewer label appearing on a stream. Fires per OPEN, so the roster's
+     * per-label idempotence is what keeps one device from announcing itself once
+     * per asset.
+     *
+     * A label is per CONNECTION (the edge binds it in `ViewerForConn` and holds
+     * it for the connection's life), so a page plus nine assets is ONE label and
+     * the dedupe above is what keeps it to one line. It is NOT per device: under
+     * HTTP/1.1 a browser cannot multiplex, so one phone opens several.
+     */
+    onViewer?: (label: string, uaClass: UAClass) => void;
+    /**
+     * The other half of `onViewer`: a viewer's connection closed. Fires once,
+     * carrying the label to drop from the roster.
+     */
+    onViewerGone?: (label: string) => void;
+    /**
+     * Diagnostics landing at the relay, tagged with the connection that produced
+     * them and the tester that connection resolved to. Either tag can be absent:
+     * the tester is unknown until the app mounts and the harness introduces
+     * itself, so the first events of a load are routinely un-attributed.
+     */
+    onEvents?: (events: DiagEvent[], tags: EventTags) => void;
+    /**
+     * The tester cap was reached, once per refused session. The CLI prints one
+     * line; the connection's events are still stored, just un-attributed.
+     */
+    onCapReached?: () => void;
+    /** The tunnel's own state — what drives the L19 reconnect advisories. */
+    onTunnelState?: (state: TunnelState) => void;
+    /** The creator's dev server is not answering (L18). */
+    onOriginError?: (label: string, code: string) => void;
+    /** Their dev server answered again. Re-arms the advisory; prints NOTHING. */
+    onOriginRecovered?: () => void;
+    /** The session ended for a reason the creator did not cause. */
+    onEnded?: (reason: PreviewEndReason) => void;
+    /** The hard max is approaching. A WARNING, never an ending (L20b). */
+    onExpiring?: () => void;
+    /** Injected for tests. */
+    fetchImpl?: typeof fetch;
 }
 export interface RunningPreview {
-    /** Public https URL to open on the device. */
+    /** Public https URL to open on the device. SERVER-COMPUTED, never assembled. */
     url: string;
-    /** Relay port the diag_* tools query (may be OS-assigned). */
+    sessionId: string;
+    /** ISO8601, the hard max. Never extended by a heartbeat. */
+    expiresAt: string;
     relayPort: number;
-    /** The app dev-serve port the tunnel ultimately serves. */
     appPort: number;
-    /** The cloudflared child pid, recorded so a separate `preview --stop` can reap
-     *  an orphaned tunnel by pid. Undefined if the spawn never yielded one. */
-    tunnelPid?: number;
-    /** Whether the app was responding when we returned (false = URL may be blank). */
+    /** Whether the app was responding when we returned. */
     appReady: boolean;
-    /** Tear down tunnel (+ DNS route), app dev serve, front proxy, and relay. */
+    /** Tear down the tunnel, the app dev serve, the front proxy and the relay. */
     stop: () => Promise<void>;
 }
 export declare function startPreview(opts: StartPreviewOptions): Promise<RunningPreview>;
 /**
- * Resolve once cloudflared reports a live edge connection, reject if it exits
- * first or never registers. On failure the rejection carries cloudflared's own
- * recent output — otherwise "did not register" hides the real cause (an invalid
- * run token, or a network that blocks the QUIC edge, the two common culprits).
- * `onLine` streams each log line out live. Exported for unit testing.
+ * Two of the three CONTROL kinds are endings. `expiring` is NOT: it is the
+ * hard-max warning, and it arrives on the same channel. Mapping it to an ending
+ * would take away a link that has half an hour left, at exactly the moment the
+ * creator is being warned to plan around it — so it returns null and the caller
+ * renders the warning instead.
+ */
+export declare function controlToReason(kind: ControlKind): PreviewEndReason | null;
+/**
+ * A refused RECONNECT dial → the ending screen it means.
+ *
+ * The edge answers a reattach with three distinguishable statuses and they are
+ * deliberately not collapsed (`ingress.go:299-310`): the consume is what
+ * separates them, and collapsing would cost the CLI its ability to say "another
+ * tunnel holds this preview" versus "your preview ended" — different creator
+ * actions, and the debugging creator is the common case.
+ *
+ * A 409 is the grace cap being spent, which is the one ending that explains the
+ * bound. A 401 (the token was refused) and a 410 (the session is gone) both mean
+ * the link is not coming back, and `grace_exhausted` is that screen.
+ *
+ * Anything else — 502, 503, a transient edge fault — returns null and keeps the
+ * backoff. Ending a preview over a momentarily unavailable edge would take away
+ * a link that is about to work again.
+ */
+export declare function refusalToReason(status: number): PreviewEndReason | null;
+/**
+ * One heartbeat. A 410 is the session ending on the server's terms; a 404/403
+ * is authorization lost. They are DELIBERATELY NOT MERGED, because the remedies
+ * differ: one is "find out who you are", the other is "try again".
+ *
+ * A transport failure is neither — the API being briefly unreachable must not
+ * end a healthy preview, because the edge already fails closed on its own
+ * 60-second deadline and will drain if the outage is real.
+ *
+ * THE 410 IS NOT REPORTED AS `hard_max`. It previously was, unconditionally, and
+ * that is a FALSE STATEMENT about the product's own behaviour for every terminal
+ * cause that is not the ceiling: a session flipped `abandoned` at minute 30, or
+ * superseded, or stopped elsewhere, all answer 410, and the hard-max screen is a
+ * `✓` telling the creator the preview did exactly what it promised over 12 hours.
+ *
+ * The API's 410 body carries ONE opaque code (`preview_session_ended`) for every
+ * terminal reason — verified against the running stack: an `abandoned` row and an
+ * `expired` row return byte-identical bodies — so the CLI CANNOT tell them apart
+ * and must not guess. `session_ended` is the honest, cause-free rendering until
+ * the wire carries the discriminator. See the note on PreviewEndedError.
+ */
+export declare function runHeartbeat(config: ResolvedConfig, sessionId: string, fetchImpl: typeof fetch, onEnded?: (reason: PreviewEndReason) => void): Promise<void>;
+/**
+ * The API's `endReason` → the CLI's ending screen.
+ *
+ * `hard_max` is returned ONLY for an explicit `expired`. An UNLABELLED 410 —
+ * which is every 410 the API sends today — maps to `grace_exhausted`, the one
+ * ending whose copy states only what is actually known: the preview has ended
+ * and the link no longer works. It asserts no cause.
+ *
+ * That default is the conservative choice and it is deliberate. `hard_max` is a
+ * `✓` claiming the preview ran its full 12 hours; rendering it for a session the
+ * platform reaped at minute 30 tells the creator something untrue about their own
+ * session. `grace_exhausted` is a `✗` that says the link is gone and gives the
+ * next command, which is true of EVERY terminal cause. Under-claiming a cause
+ * costs the creator one sentence of diagnosis; over-claiming one states a fact
+ * only the product can see, and states it wrong.
+ *
+ * EVERY endReason the domain defines must have a case here. The `default` is for
+ * a reason a NEWER api invented, not for one this client forgot: a fall-through
+ * renders "your network dropped" for a cause that may be nothing of the kind.
+ * That is not hypothetical — `stopped` and `disconnected` fell through for a
+ * build, so a creator who stopped their own preview from another terminal was
+ * told their connection failed. The set is enumerated from the domain by
+ * QA-F3-C9(f), which fails when a new member is added rather than mapping it
+ * silently to a wrong screen.
  */
-export declare function waitForRegister(tunnel: ChildProcess, timeoutMs: number, onLine?: (line: string) => void): Promise<void>;
+export declare function endReasonToPreviewEnd(reason: string | undefined): PreviewEndReason;