@vincentt-xr/cli 0.18.3 → 0.19.0

package/dist/preview/runner.js

@@ -16,7 +16,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { realpath } from "node:fs/promises";
 import { createServer } from "node:http";
-import { TunnelClient, resolveForwardTarget, } from "@vincentt-xr/harness/tunnel";
+import { TunnelClient, resolveForwardTarget, } from "../tunnel/index.js";
 import { startRelay } from "../relay/server.js";
 import { mintRelayToken } from "../relay/guard.js";
 import { isHiddenAppPath, proxyWeb, proxyWs, relayRoute } from "./proxy.js";
@@ -26,20 +26,35 @@ import { withoutCliCredentials } from "../shared/config.js";
 import { ProjectUnreachableError } from "../lib/backend.js";
 import { AuthExpiredError } from "../shared/authError.js";
 import { apiFetch } from "../shared/http.js";
+import { terminalSafe } from "../lib/terminalText.js";
 /** The path a 404 advisory names: the request's own path, without its query. */
 export function requestPathOf(url) {
-    const raw = (url ?? "/").split("?")[0] ?? "/";
-    // Control characters never reach the terminal from a request line.
-    return raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+    const raw = ((url ?? "/").split("#")[0] ?? "/").split("?")[0] ?? "/";
+    let decoded = raw;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        /* an undecodable path is printed as sent */
+    }
+    return terminalSafe(decoded);
+}
+/**
+ * The project root as the `/@fs/` check compares it: Vite writes `/@fs/C:/...`
+ * with forward slashes, so a Windows root holding backslashes would never match
+ * as inside, and a project under a dotted parent folder would get false 404s.
+ */
+export function hiddenPathRoot(realRoot) {
+    return realRoot.replaceAll("\\", "/");
 }
 export async function startPreview(opts) {
     const { projectCwd, projectRoot = projectCwd, config, projectId, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", appReadyTimeoutMs = 8_000, onLog = () => undefined, fetchImpl = apiFetch, } = opts;
     const appPort = opts.appPort ?? 5173;
     const relayPort = opts.relayPort ?? (await getFreePort());
     const frontPort = opts.frontPort ?? (await getFreePort());
-    const reuseApp = await isPortListening(appPort);
+    const reuseApp = opts.appPortFresh ? false : await isPortListening(appPort);
     const relayToken = mintRelayToken();
-    const hiddenRoot = await realpath(projectRoot).catch(() => projectRoot);
+    const hiddenRoot = hiddenPathRoot(await realpath(projectRoot).catch(() => projectRoot));
     let app;
     let killApp;
     let relay;

package/dist/preview/stream.d.ts

@@ -1,5 +1,5 @@
 import type { DiagEvent, LogEvent, NetworkEvent, TraceEvent } from "@vincentt-xr/harness/events";
-import type { UAClass } from "@vincentt-xr/harness/tunnel";
+import type { UAClass } from "../tunnel/index.js";
 /** One line per viewer per 5s on the terminal. The agent's pull is unthrottled. */
 export declare const PERF_THROTTLE_MS = 5000;
 export declare function uaLabel(c: UAClass): string;

package/dist/preview/viewers.d.ts

@@ -1,4 +1,4 @@
-import type { UAClass } from "@vincentt-xr/harness/tunnel";
+import type { UAClass } from "../tunnel/index.js";
 /** The roster block prints once, on the FOURTH TESTER's arrival, and never again. */
 export declare const ROSTER_AT = 4;
 /**

package/dist/relay/server.js

@@ -10,7 +10,7 @@ import { EventStore } from "./store.js";
 import { TesterRegistry, isTesterId } from "./testers.js";
 import { AnnotationStore } from "./annotations.js";
 import { RELAY_TOKEN_HEADER, hasRelayToken, isAllowedHost, isAllowedOrigin, isJsonContentType, } from "./guard.js";
-import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "@vincentt-xr/harness/tunnel";
+import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "../tunnel/index.js";
 /** Cap an annotation POST body so a bad/huge upload can't exhaust memory. */
 const MAX_ANNOTATION_BYTES = 25 * 1024 * 1024;
 /** Clamp the long-poll hold so a request can't park forever. */

package/dist/tunnel/cbor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The CBOR SUBSET, Node half. It mirrors `api/internal/edge/cbor.go` decision
+ * for decision, because two implementations of one wire format that were
+ * written independently are two implementations that drift.
+ *
+ * It decodes CONTROL payloads only — OPEN and HEAD. It NEVER touches a DATA
+ * payload.
+ *
+ * It is hand-written rather than a library for the same reason the Go one is: a
+ * general CBOR library's allocation behavior on hostile input would be someone
+ * else's decision, and the limits below are the whole point.
+ *
+ * Everything indefinite-length, every tag, every float, every byte string and
+ * every negative integer is REFUSED — not because they are dangerous in
+ * themselves, but because the encoder we own never emits them, so accepting
+ * them would only widen the input this parser has to be correct about.
+ */
+/**
+ * VIEWER_LABEL_RE is the SAME regex the edge assigns against, and this client
+ * RE-VALIDATES rather than trusting the edge. That is closure (c) of the three
+ * that keep viewer-supplied bytes out of the creator's agent's context: the
+ * label flows viewerLabel -> the relay ring-buffer key -> CLI terminal output
+ * and MCP tool output, which is a terminal/log-injection path INTO the agent,
+ * and a Go-only check would pass on a client that trusted the edge.
+ */
+export declare const VIEWER_LABEL_RE: RegExp;
+export declare function parseViewerLabel(s: string): string | null;
+/**
+ * UA_CLASSES is the CLOSED ENUM OF SIX, mirroring the Go edge. `unknown` is the
+ * TOTAL fallback. This client validates the class it receives against this set
+ * before stamping the relay handshake, so an unmatched or forged class becomes
+ * `unknown` rather than an echo.
+ */
+export declare const UA_CLASSES: readonly ["ios_safari", "android_chrome", "desktop_chrome", "desktop_safari", "desktop_firefox", "unknown"];
+export type UAClass = (typeof UA_CLASSES)[number];
+export declare function parseUAClass(s: string): UAClass;
+export interface OpenPayload {
+    viewerLabel: string;
+    method: string;
+    path: string;
+    headers: [string, string][];
+    upgrade?: string;
+}
+export interface HeadPayload {
+    status: number;
+    headers: [string, string][];
+}
+/**
+ * `viewer_gone` is the ONE non-terminal kind: the other three mean the session
+ * is ending, this one means a viewer's connection closed while the session
+ * continues. It is also the only kind carrying a second key.
+ */
+export type ControlKind = "revoke" | "expiring" | "superseded" | "viewer_gone";
+/** A decoded CONTROL payload. `viewerLabel` is present only on `viewer_gone`. */
+export interface ControlPayload {
+    kind: ControlKind;
+    viewerLabel?: string;
+}
+export declare function decodeOpen(b: Uint8Array): OpenPayload;
+export declare function decodeHead(b: Uint8Array): HeadPayload;
+/**
+ * The map arity is asserted AGAINST THE KIND, so a payload claiming `revoke`
+ * with a trailing label is refused as malformed rather than quietly accepted
+ * with the extra key ignored.
+ */
+export declare function decodeControl(b: Uint8Array): ControlPayload;
+/** Canonical key order: viewerLabel, method, path, headers, [upgrade]. */
+export declare function encodeOpen(p: OpenPayload): Uint8Array;
+/** Canonical key order: status, headers. */
+export declare function encodeHead(p: HeadPayload): Uint8Array;
+export declare function encodeControl(kind: ControlKind, viewerLabel?: string): Uint8Array;

package/dist/tunnel/cbor.js

@@ -0,0 +1,403 @@
+/**
+ * The CBOR SUBSET, Node half. It mirrors `api/internal/edge/cbor.go` decision
+ * for decision, because two implementations of one wire format that were
+ * written independently are two implementations that drift.
+ *
+ * It decodes CONTROL payloads only — OPEN and HEAD. It NEVER touches a DATA
+ * payload.
+ *
+ * It is hand-written rather than a library for the same reason the Go one is: a
+ * general CBOR library's allocation behavior on hostile input would be someone
+ * else's decision, and the limits below are the whole point.
+ *
+ * Everything indefinite-length, every tag, every float, every byte string and
+ * every negative integer is REFUSED — not because they are dangerous in
+ * themselves, but because the encoder we own never emits them, so accepting
+ * them would only widen the input this parser has to be correct about.
+ */
+import { MAX_CBOR_DEPTH, MAX_HEADERS, MAX_HEADER_BYTES, MAX_OPEN_PAYLOAD, MAX_PATH_LEN, ProtocolError, } from "./frame.js";
+const MAX_METHOD_LEN = 16;
+const MAX_VIEWER_LABEL_LEN = 11;
+/** Every CBOR error is STREAM-level: the stream dies, the tunnel SURVIVES. */
+function fail(code) {
+    throw new ProtocolError(code, false);
+}
+/**
+ * VIEWER_LABEL_RE is the SAME regex the edge assigns against, and this client
+ * RE-VALIDATES rather than trusting the edge. That is closure (c) of the three
+ * that keep viewer-supplied bytes out of the creator's agent's context: the
+ * label flows viewerLabel -> the relay ring-buffer key -> CLI terminal output
+ * and MCP tool output, which is a terminal/log-injection path INTO the agent,
+ * and a Go-only check would pass on a client that trusted the edge.
+ */
+export const VIEWER_LABEL_RE = /^viewer-[0-9]{1,4}$/;
+export function parseViewerLabel(s) {
+    return VIEWER_LABEL_RE.test(s) ? s : null;
+}
+/**
+ * UA_CLASSES is the CLOSED ENUM OF SIX, mirroring the Go edge. `unknown` is the
+ * TOTAL fallback. This client validates the class it receives against this set
+ * before stamping the relay handshake, so an unmatched or forged class becomes
+ * `unknown` rather than an echo.
+ */
+export const UA_CLASSES = [
+    "ios_safari",
+    "android_chrome",
+    "desktop_chrome",
+    "desktop_safari",
+    "desktop_firefox",
+    "unknown",
+];
+export function parseUAClass(s) {
+    return UA_CLASSES.includes(s) ? s : "unknown";
+}
+/**
+ * CONTROL_ARITY is the EXACT map length per kind, mirroring controlArity in the
+ * Go edge. The grammar stays closed per-kind rather than becoming "one or two
+ * keys, whatever arrives": a decoder that accepts a viewerLabel on `revoke`, or
+ * omits it on `viewer_gone`, is a decoder with a shape the encoder never emits.
+ */
+const CONTROL_ARITY = new Map([
+    ["revoke", 1],
+    ["expiring", 1],
+    ["superseded", 1],
+    ["viewer_gone", 2],
+]);
+// ---- decoding ---------------------------------------------------------------
+class Reader {
+    b;
+    i = 0;
+    depth = 1;
+    constructor(b) {
+        this.b = b;
+    }
+    /**
+     * head reads a CBOR initial byte and its argument. Indefinite-length
+     * (ai === 31) is REFUSED outright: it is the one CBOR shape whose length is
+     * not knowable before reading, which is the property every limit depends on.
+     */
+    head() {
+        if (this.i >= this.b.length)
+            fail("cbor_malformed");
+        const c = this.b[this.i++];
+        const major = c >> 5;
+        const ai = c & 0x1f;
+        if (ai < 24)
+            return { major, arg: ai };
+        if (ai === 24) {
+            if (this.i >= this.b.length)
+                fail("cbor_malformed");
+            return { major, arg: this.b[this.i++] };
+        }
+        if (ai === 25) {
+            if (this.i + 2 > this.b.length)
+                fail("cbor_malformed");
+            const v = (this.b[this.i] << 8) + this.b[this.i + 1];
+            this.i += 2;
+            return { major, arg: v };
+        }
+        if (ai === 26) {
+            if (this.i + 4 > this.b.length)
+                fail("cbor_malformed");
+            const v = this.b[this.i] * 0x1000000 +
+                (this.b[this.i + 1] << 16) +
+                (this.b[this.i + 2] << 8) +
+                this.b[this.i + 3];
+            this.i += 4;
+            return { major, arg: v };
+        }
+        if (ai === 27) {
+            if (this.i + 8 > this.b.length)
+                fail("cbor_malformed");
+            let v = 0;
+            for (let k = 0; k < 8; k++)
+                v = v * 256 + this.b[this.i + k];
+            this.i += 8;
+            return { major, arg: v };
+        }
+        // 28..30 reserved; 31 indefinite-length. Both refused.
+        return fail("cbor_malformed");
+    }
+    /**
+     * text reads a definite-length UTF-8 string, bounded by `max` BEFORE the
+     * slice is taken — so a declared 4 GiB string costs a comparison, not a copy.
+     */
+    text(max) {
+        const { major, arg } = this.head();
+        if (major !== 3)
+            fail("cbor_malformed");
+        if (arg > max)
+            fail("cbor_malformed");
+        if (this.i + arg > this.b.length)
+            fail("cbor_malformed");
+        const s = new TextDecoder("utf-8", { fatal: false }).decode(this.b.subarray(this.i, this.i + arg));
+        this.i += arg;
+        return s;
+    }
+    uint(max) {
+        const { major, arg } = this.head();
+        if (major !== 0 || arg > max)
+            fail("cbor_malformed");
+        return arg;
+    }
+    /**
+     * headerPairs reads a map of text->text, enforcing MAX_HEADERS and
+     * MAX_HEADER_BYTES as it goes. The COUNT bound is checked against the
+     * DECLARED map size before a single pair is read, so a payload claiming 2^32
+     * headers allocates nothing.
+     */
+    headerPairs() {
+        this.depth++;
+        if (this.depth > MAX_CBOR_DEPTH)
+            fail("cbor_depth");
+        try {
+            const { major, arg } = this.head();
+            if (major !== 5)
+                fail("cbor_malformed");
+            if (arg > MAX_HEADERS)
+                fail("cbor_headers");
+            const out = [];
+            let total = 0;
+            for (let k = 0; k < arg; k++) {
+                const name = this.text(MAX_HEADER_BYTES);
+                const val = this.text(MAX_HEADER_BYTES);
+                total += name.length + val.length;
+                if (total > MAX_HEADER_BYTES)
+                    fail("cbor_header_bytes");
+                out.push([name, val]);
+            }
+            return out;
+        }
+        finally {
+            this.depth--;
+        }
+    }
+}
+export function decodeOpen(b) {
+    if (b.length > MAX_OPEN_PAYLOAD)
+        fail("open_payload_too_large");
+    const r = new Reader(b);
+    const { major, arg } = r.head();
+    if (major !== 5 || arg > 8)
+        fail("cbor_malformed");
+    let viewerLabel;
+    let method;
+    let path;
+    let headers = [];
+    let upgrade;
+    for (let k = 0; k < arg; k++) {
+        const key = r.text(32);
+        switch (key) {
+            case "viewerLabel": {
+                const raw = r.text(MAX_VIEWER_LABEL_LEN);
+                // RE-VALIDATED here, not merely trusted because the edge assigned it.
+                const parsed = parseViewerLabel(raw);
+                if (parsed === null)
+                    fail("cbor_viewer");
+                viewerLabel = parsed;
+                break;
+            }
+            case "method":
+                method = r.text(MAX_METHOD_LEN);
+                break;
+            case "path": {
+                const p = r.text(MAX_PATH_LEN + 1);
+                if (p.length > MAX_PATH_LEN)
+                    fail("cbor_path_len");
+                path = p;
+                break;
+            }
+            case "headers":
+                headers = r.headerPairs();
+                break;
+            case "upgrade":
+                upgrade = r.text(32);
+                break;
+            default:
+                // An unknown key is a MALFORMED payload, not a skipped field. Skipping
+                // would mean accepting bytes we do not understand on the one payload
+                // this client parses.
+                fail("cbor_malformed");
+        }
+    }
+    if (viewerLabel === undefined || method === undefined || path === undefined) {
+        fail("cbor_malformed");
+    }
+    // Trailing bytes after a complete payload are a second message hiding in one
+    // frame.
+    if (r.i !== b.length)
+        fail("cbor_malformed");
+    const out = { viewerLabel, method, path, headers };
+    if (upgrade !== undefined)
+        out.upgrade = upgrade;
+    return out;
+}
+export function decodeHead(b) {
+    if (b.length > MAX_OPEN_PAYLOAD)
+        fail("open_payload_too_large");
+    const r = new Reader(b);
+    const { major, arg } = r.head();
+    if (major !== 5 || arg > 4)
+        fail("cbor_malformed");
+    let status;
+    let headers = [];
+    for (let k = 0; k < arg; k++) {
+        const key = r.text(32);
+        switch (key) {
+            case "status": {
+                const v = r.uint(0xffff);
+                // A status outside 100..599 is a protocol violation and never a
+                // relayed status.
+                if (v < 100 || v > 599)
+                    fail("cbor_status");
+                status = v;
+                break;
+            }
+            case "headers":
+                headers = r.headerPairs();
+                break;
+            default:
+                fail("cbor_malformed");
+        }
+    }
+    if (status === undefined)
+        fail("cbor_malformed");
+    if (r.i !== b.length)
+        fail("cbor_malformed");
+    return { status, headers };
+}
+/**
+ * The map arity is asserted AGAINST THE KIND, so a payload claiming `revoke`
+ * with a trailing label is refused as malformed rather than quietly accepted
+ * with the extra key ignored.
+ */
+export function decodeControl(b) {
+    if (b.length > MAX_OPEN_PAYLOAD)
+        fail("open_payload_too_large");
+    const r = new Reader(b);
+    const { major, arg } = r.head();
+    if (major !== 5)
+        fail("cbor_malformed");
+    if (r.text(32) !== "kind")
+        fail("cbor_malformed");
+    const v = r.text(32);
+    const want = CONTROL_ARITY.get(v);
+    if (want === undefined || arg !== want)
+        fail("cbor_malformed");
+    const kind = v;
+    let viewerLabel;
+    if (kind === "viewer_gone") {
+        if (r.text(32) !== "viewerLabel")
+            fail("cbor_malformed");
+        // Parsed, not copied: the label reaches the creator's terminal.
+        const raw = r.text(MAX_VIEWER_LABEL_LEN);
+        if (parseViewerLabel(raw) === null)
+            fail("cbor_viewer");
+        viewerLabel = raw;
+    }
+    if (r.i !== b.length)
+        fail("cbor_malformed");
+    return viewerLabel === undefined ? { kind } : { kind, viewerLabel };
+}
+// ---- encoding ---------------------------------------------------------------
+/**
+ * The encoder emits CANONICAL CBOR for the subset: definite lengths, shortest
+ * integer encoding, and map keys in a fixed order, with header pairs SORTED.
+ *
+ * Canonicality is what makes the checked-in golden fixture comparable
+ * byte-for-byte against BOTH implementations' output. A non-deterministic
+ * encoder would make the fixture assertable in one direction only.
+ */
+function head(major, arg) {
+    const m = major << 5;
+    if (arg < 24)
+        return [m | arg];
+    if (arg <= 0xff)
+        return [m | 24, arg];
+    if (arg <= 0xffff)
+        return [m | 25, (arg >>> 8) & 0xff, arg & 0xff];
+    if (arg <= 0xffffffff) {
+        return [
+            m | 26,
+            (arg >>> 24) & 0xff,
+            (arg >>> 16) & 0xff,
+            (arg >>> 8) & 0xff,
+            arg & 0xff,
+        ];
+    }
+    const out = [m | 27];
+    let v = arg;
+    const bytes = [];
+    for (let k = 0; k < 8; k++) {
+        bytes.unshift(v % 256);
+        v = Math.floor(v / 256);
+    }
+    return out.concat(bytes);
+}
+function text(s) {
+    const b = Array.from(new TextEncoder().encode(s));
+    return head(3, b.length).concat(b);
+}
+function headerMap(h) {
+    // Sorted by name then value, so two encoders handed the same headers in a
+    // different order still produce the same bytes.
+    const sorted = [...h].sort((a, b) => a[0] === b[0] ? (a[1] < b[1] ? -1 : 1) : a[0] < b[0] ? -1 : 1);
+    let out = head(5, sorted.length);
+    for (const [k, v] of sorted)
+        out = out.concat(text(k), text(v));
+    return out;
+}
+/** Canonical key order: viewerLabel, method, path, headers, [upgrade]. */
+export function encodeOpen(p) {
+    if (parseViewerLabel(p.viewerLabel) === null)
+        fail("cbor_viewer");
+    if (p.path.length > MAX_PATH_LEN)
+        fail("cbor_path_len");
+    if (p.headers.length > MAX_HEADERS)
+        fail("cbor_headers");
+    const n = p.upgrade ? 5 : 4;
+    let out = head(5, n);
+    out = out.concat(text("viewerLabel"), text(p.viewerLabel));
+    out = out.concat(text("method"), text(p.method));
+    out = out.concat(text("path"), text(p.path));
+    out = out.concat(text("headers"), headerMap(p.headers));
+    if (p.upgrade)
+        out = out.concat(text("upgrade"), text(p.upgrade));
+    const b = new Uint8Array(out);
+    if (b.length > MAX_OPEN_PAYLOAD)
+        fail("open_payload_too_large");
+    return b;
+}
+/** Canonical key order: status, headers. */
+export function encodeHead(p) {
+    if (p.status < 100 || p.status > 599)
+        fail("cbor_status");
+    if (p.headers.length > MAX_HEADERS)
+        fail("cbor_headers");
+    let out = head(5, 2);
+    out = out.concat(text("status"), head(0, p.status));
+    out = out.concat(text("headers"), headerMap(p.headers));
+    const b = new Uint8Array(out);
+    if (b.length > MAX_OPEN_PAYLOAD)
+        fail("open_payload_too_large");
+    return b;
+}
+export function encodeControl(kind, viewerLabel) {
+    const arity = CONTROL_ARITY.get(kind);
+    if (arity === undefined)
+        fail("cbor_malformed");
+    if (kind === "viewer_gone") {
+        if (viewerLabel === undefined || parseViewerLabel(viewerLabel) === null) {
+            fail("cbor_viewer");
+        }
+    }
+    else if (viewerLabel !== undefined) {
+        // A label on a terminal kind is a caller bug, refused rather than dropped.
+        fail("cbor_malformed");
+    }
+    const out = head(5, arity).concat(text("kind"), text(kind));
+    if (kind === "viewer_gone") {
+        out.push(...text("viewerLabel"), ...text(viewerLabel));
+    }
+    return new Uint8Array(out);
+}