@vincentt-xr/cli 0.17.0 → 0.18.0

package/dist/preview/copy.js

@@ -16,6 +16,8 @@
 // session id, the edge hostname, or the workingTreeKey. The grant is the
 // sharpest — it transits an agent's tool-output transcript by default in this
 // product, so f1's "a token is never printed" extends to it verbatim.
+/** Flow L13 — the start block. */
+import { escapeControl } from "../lib/terminalText.js";
 export function startBlock(i) {
     const out = [
         "",
@@ -59,7 +61,7 @@ export function startBlock(i) {
  * without an account, which is false. It is offered as a CAPABILITY, not as
  * consolation — no "unfortunately", no "you can still".
  */
-export function notSignedIn() {
+export function notSignedIn(devCommand = "npm run dev", localUrl = "http://localhost:5173") {
     return [
         "",
         "✗ You're not signed in.",
@@ -68,12 +70,68 @@ export function notSignedIn() {
         "",
         "  Sign in:  vincentt login",
         "",
-        "  Your local dev loop does not need one — `npm run dev` and open",
-        "  http://localhost:5173 on this machine. The camera works there.",
+        `  Your local dev loop does not need one. Run \`${devCommand}\` and open`,
+        `  ${localUrl} on this machine. The camera works there.`,
         "  What signing in adds is the phone.",
         "",
     ];
 }
+/**
+ * Flow P1 — the two settings lines, printed right after resolution and before
+ * the sign-in check, the mint and the spawn. They are the ONLY disclosure of the
+ * dev command before it runs; no second line repeats it.
+ */
+export function settingsBanner(i) {
+    // The command is schema-checked to hold no control character; escaping here
+    // as well keeps this line honest even for a caller that skipped the check.
+    const row = (label, raw, source) => {
+        const value = escapeControl(raw);
+        return `→ ${label.padEnd(14)}${value.padEnd(Math.max(27, value.length + 2))}${source}`;
+    };
+    const out = [row("Dev command", i.devCommand, i.devCommandSource)];
+    if (i.reused) {
+        out.push(`${" ".repeat(16)}not started: something is already listening on port ${i.devPort}`);
+    }
+    out.push(row("Dev port", String(i.devPort), i.devPortSource));
+    return out;
+}
+/** Flow P3, static: `package.json` does not list the harness. Precedes the start block. */
+export function noDiagnosticsStatic() {
+    return [
+        "",
+        "! This app has no Vincentt diagnostics, so `vincentt logs`, `network` and `trace`",
+        "  will stay empty. The preview itself works.",
+        "",
+        "  To add them, install the harness and put one line at the top of your entry file:",
+        "    npm i @vincentt-xr/harness",
+        '    import "@vincentt-xr/harness/auto";',
+    ];
+}
+/** Flow P3, arrival: once per device class, only when the static line was shown. */
+export function deviceArrived(descriptor) {
+    return descriptor
+        ? `A device opened the preview · ${descriptor}`
+        : "A device opened the preview";
+}
+/**
+ * Flow P3, runtime: the harness is listed but nothing said hello. Names the
+ * device class (a tester exists only after a hello) and asserts neither cause.
+ * The window's length is deliberately not printed.
+ */
+export function noDiagnosticsRuntime(descriptor) {
+    const opened = descriptor
+        ? `A device opened the preview (${descriptor}), but no diagnostics have arrived`
+        : "A device opened the preview, but no diagnostics have arrived";
+    return [
+        `! ${opened}`,
+        "  from the app. It may not load @vincentt-xr/harness/auto, or it may have",
+        "  stopped before that line ran.",
+    ];
+}
+/** Flow P1 — the proxy refused a hidden path. Once per preview, naming the first. */
+export function hiddenPathRefused(requestPath) {
+    return `! Answered 404 for ${requestPath}. A preview never serves hidden files from your project.`;
+}
 /** Flow L16 — `--viewer`, a second terminal, not a second preview. */
 export function followingBlock(label, descriptor) {
     return [
@@ -96,12 +154,32 @@ export function followingFooter() {
  * The middle line splits the wire in two, because the creator's first instinct
  * on a 502 is to suspect us.
  */
-export function originDown(targetUrl) {
+export function originDown(targetUrl, settings) {
+    if (settings === undefined) {
+        return [
+            `! Your dev server isn't responding on ${targetUrl}.`,
+            "",
+            "  The preview is still live. The phone is reaching us; we can't reach your app.",
+            "  Start it and reload the phone:  npm run dev",
+            "",
+        ];
+    }
+    const source = settings.portSource === "vincentt.json"
+        ? " (port from vincentt.json)"
+        : settings.portSource === "flag"
+            ? " (port from --port)"
+            : "";
+    const fix = settings.portSource === "vincentt.json"
+        ? "  If it runs on another port, set dev.port in vincentt.json."
+        : settings.portSource === "flag"
+            ? "  If it runs on another port, pass that port with --port."
+            : "  If it runs on another port, pass --port or add vincentt.json.";
     return [
-        `! Your dev server isn't responding on ${targetUrl}.`,
+        `! Your dev server isn't responding on ${targetUrl}${source}.`,
         "",
-        "  The preview is still live — the phone is reaching us, we can't reach your app.",
-        "  Start it and reload the phone:  npm run dev",
+        "  The preview is still live. The phone is reaching us; we can't reach your app.",
+        `  Start it and reload the phone:  ${settings.devCommand}`,
+        fix,
         "",
     ];
 }
@@ -283,7 +361,7 @@ export function hardMaxWarning(clockTime, minutesLeft) {
         `! This preview reaches its 12-hour maximum at ${clockTime} (in ${minutesLeft}m) and will stop.`,
         "",
         "  A preview link is deliberately short-lived. To keep going, start a new one",
-        "  then — you'll get a new link, so any QR code on a desk will need re-scanning.",
+        "  then. You'll get a new link, so any QR code on a desk will need re-scanning.",
         "",
     ];
 }
@@ -310,7 +388,7 @@ export function supersededLoser() {
         "",
         "✗ This preview was replaced by a newer one for this folder.",
         "",
-        "  Its link no longer works. The new preview has a different link — whoever",
+        "  Its link no longer works. The new preview has a different link, so whoever",
         "  is holding a phone will need it again.",
         "",
     ];
@@ -363,6 +441,20 @@ export function endedUnreachable(orgName) {
         "",
     ];
 }
+/**
+ * The heartbeat's token was refused. Distinct from both causes above: the
+ * project and the access are fine, and the one thing to do is sign in again.
+ */
+export function endedAuthExpired() {
+    return [
+        "",
+        "✗ Preview ended. Your Vincentt access token is no longer valid.",
+        "",
+        "  Sign in again:  vincentt login",
+        "  Then start a new preview:  vincentt preview",
+        "",
+    ];
+}
 export function endedUnconfirmed() {
     return [
         "",
@@ -451,7 +543,7 @@ export function mintRateLimited(retryAfterSec) {
         "",
         `✗ Too many previews started recently. Try again in ${approxWait(retryAfterSec)}.`,
         "",
-        "  A running preview does not count against this — if one is already running",
+        "  A running preview does not count against this. If one is already running",
         "  for this folder, you don't need a new one.",
         "",
     ];

package/dist/preview/proxy.d.ts

@@ -12,4 +12,41 @@ import type { Duplex } from "node:stream";
  * 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;
+export interface ProxyWsOptions {
+    /**
+     * Rewrite `Origin` to the dev server's own loopback origin iff the request's
+     * Origin is BYTE-EQUAL to this value. It is the minted preview origin, fixed at
+     * mint and never read from a request. A dev server refuses a foreign Origin on
+     * its live-reload socket; equality keeps that refusal for every other page.
+     */
+    rewriteOriginFrom?: string;
+}
+export declare function proxyWs(req: IncomingMessage, socket: Duplex, head: Buffer, targetPort: number, opts?: ProxyWsOptions): void;
+/**
+ * Where the front proxy sends a request: to the relay only on the exact paths
+ * the phone-side harness uses, and nowhere at all for anything else under the
+ * harness prefix. The harness opens its WebSocket at `harnessPath` and POSTs
+ * annotations to `harnessPath/annotation`; nothing else of the relay is
+ * tunnel-facing (`/query` and `feedback/next` belong to the local CLI).
+ *
+ * Exact comparison of the raw path is what makes `/__harness/../query` and
+ * `/__harness/%2e%2e/query` land on `refuse` rather than on the relay, where
+ * URL normalisation would have turned them into `/query`.
+ */
+export declare function relayRoute(url: string, harnessPath: string, kind: "http" | "upgrade"): "relay" | "refuse" | "app";
+/**
+ * Whether the front proxy must answer 404 itself for this app-route URL, so a
+ * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`
+ * or the binding to any holder of a preview link.
+ *
+ * The path is decoded once, and an encoded `/` or `\` is refused outright (a
+ * separator the dev server would split on and this check would not). A segment
+ * still carrying an encoded dot after that one decode is judged as the dev
+ * server would read it after a second decode, so `%252eenv` cannot slip past.
+ * `.` and `..` segments are always refused, which is what makes the `/@fs/`
+ * text containment below real containment.
+ *
+ * `projectRoot` is the realpath of the binding directory, taken once at preview
+ * start; inside-ness is a segment-aligned text prefix, with no disk call.
+ */
+export declare function isHiddenAppPath(url: string, projectRoot: string): boolean;

package/dist/preview/proxy.js

@@ -3,12 +3,48 @@
 // relay behind one origin); not a general proxy. No deps.
 import { connect } from "node:net";
 import { request, } from "node:http";
+import { createGzip } from "node:zlib";
 // Rewrite Host to the loopback target. cloudflared forwards the public Host, and
 // esbuild's `serve` 403s any Host it doesn't recognize — so the phone would get a
 // 403. The origin only needs a Host it accepts; the browser never sees this value.
 function localHeaders(headers, targetPort) {
     return { ...headers, host: `localhost:${targetPort}` };
 }
+const COMPRESSIBLE_TYPE = /^(text\/(?!event-stream)|application\/(javascript|json|xml)|image\/svg\+xml)|\+json\b|\+xml\b/i;
+function acceptsGzip(header) {
+    if (header === undefined)
+        return false;
+    const value = Array.isArray(header) ? header.join(",") : header;
+    for (const part of value.split(",")) {
+        const [coding, ...params] = part.trim().split(";");
+        const name = coding?.trim().toLowerCase();
+        if (name !== "gzip" && name !== "*")
+            continue;
+        const q = params.map((p) => p.trim().toLowerCase()).find((p) => p.startsWith("q="));
+        if (q !== undefined && !(Number(q.slice(2)) > 0))
+            continue;
+        return true;
+    }
+    return false;
+}
+function shouldGzip(req, proxyRes, status) {
+    if (req.method === "HEAD" || status < 200 || status === 204 || status === 206 || status === 304)
+        return false;
+    if (proxyRes.headers["content-encoding"] !== undefined)
+        return false;
+    const cacheControl = String(proxyRes.headers["cache-control"] ?? "");
+    if (/\bno-transform\b/i.test(cacheControl))
+        return false;
+    if (!COMPRESSIBLE_TYPE.test(String(proxyRes.headers["content-type"] ?? "")))
+        return false;
+    return acceptsGzip(req.headers["accept-encoding"]);
+}
+function appendVary(existing) {
+    const current = Array.isArray(existing) ? existing.join(", ") : (existing ?? "");
+    if (/(^|,)\s*(accept-encoding|\*)\s*(,|$)/i.test(current))
+        return current;
+    return current === "" ? "Accept-Encoding" : `${current}, Accept-Encoding`;
+}
 /**
  * onOriginError is where the creator's dev server being down is ACTUALLY
  * OBSERVED.
@@ -35,7 +71,19 @@ export function proxyWeb(req, res, targetPort, onOriginError) {
         const headers = { ...proxyRes.headers, "cache-control": "no-store" };
         delete headers.etag;
         delete headers["last-modified"];
-        res.writeHead(proxyRes.statusCode ?? 502, headers);
+        const status = proxyRes.statusCode ?? 502;
+        if (shouldGzip(req, proxyRes, status)) {
+            delete headers["content-length"];
+            headers["content-encoding"] = "gzip";
+            headers.vary = appendVary(headers.vary);
+            res.writeHead(status, headers);
+            const gzip = createGzip();
+            gzip.on("error", () => res.destroy());
+            proxyRes.on("error", () => gzip.destroy());
+            proxyRes.pipe(gzip).pipe(res);
+            return;
+        }
+        res.writeHead(status, headers);
         proxyRes.pipe(res);
     });
     proxyReq.on("error", () => {
@@ -46,9 +94,12 @@ export function proxyWeb(req, res, targetPort, onOriginError) {
     });
     req.pipe(proxyReq);
 }
-export function proxyWs(req, socket, head, targetPort) {
+export function proxyWs(req, socket, head, targetPort, opts = {}) {
     // Re-issue the upgrade handshake against the target and splice the sockets.
     const headers = localHeaders(req.headers, targetPort);
+    if (opts.rewriteOriginFrom !== undefined && headers.origin === opts.rewriteOriginFrom) {
+        headers.origin = `http://localhost:${targetPort}`;
+    }
     const upstream = connect(targetPort, "127.0.0.1", () => {
         const headerLines = [
             `${req.method} ${req.url} HTTP/1.1`,
@@ -66,3 +117,101 @@ export function proxyWs(req, socket, head, targetPort) {
     upstream.on("error", bail);
     socket.on("error", bail);
 }
+/**
+ * Where the front proxy sends a request: to the relay only on the exact paths
+ * the phone-side harness uses, and nowhere at all for anything else under the
+ * harness prefix. The harness opens its WebSocket at `harnessPath` and POSTs
+ * annotations to `harnessPath/annotation`; nothing else of the relay is
+ * tunnel-facing (`/query` and `feedback/next` belong to the local CLI).
+ *
+ * Exact comparison of the raw path is what makes `/__harness/../query` and
+ * `/__harness/%2e%2e/query` land on `refuse` rather than on the relay, where
+ * URL normalisation would have turned them into `/query`.
+ */
+export function relayRoute(url, harnessPath, kind) {
+    const raw = url.split("?")[0] ?? "";
+    if (kind === "upgrade" && raw === harnessPath)
+        return "relay";
+    if (kind === "http" && raw === `${harnessPath}/annotation`)
+        return "relay";
+    return raw.startsWith(harnessPath) ? "refuse" : "app";
+}
+/**
+ * Whether the front proxy must answer 404 itself for this app-route URL, so a
+ * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`
+ * or the binding to any holder of a preview link.
+ *
+ * The path is decoded once, and an encoded `/` or `\` is refused outright (a
+ * separator the dev server would split on and this check would not). A segment
+ * still carrying an encoded dot after that one decode is judged as the dev
+ * server would read it after a second decode, so `%252eenv` cannot slip past.
+ * `.` and `..` segments are always refused, which is what makes the `/@fs/`
+ * text containment below real containment.
+ *
+ * `projectRoot` is the realpath of the binding directory, taken once at preview
+ * start; inside-ness is a segment-aligned text prefix, with no disk call.
+ */
+export function isHiddenAppPath(url, projectRoot) {
+    const raw = (url.split("#")[0] ?? "").split("?")[0] ?? "";
+    if (/%(2f|5c)/i.test(raw) || raw.includes("\\"))
+        return true;
+    let decoded;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        return true;
+    }
+    const segments = decoded.split("/").slice(1);
+    if (segments.some((s) => s === "." || s === ".."))
+        return true;
+    const checked = checkedSegmentIndexes(segments, projectRoot);
+    for (const i of checked) {
+        const seg = segments[i];
+        if (!startsWithDot(seg))
+            continue;
+        if (isAllowedDotSegment(segments, i))
+            continue;
+        return true;
+    }
+    return false;
+}
+function startsWithDot(segment) {
+    if (segment.startsWith("."))
+        return true;
+    try {
+        return decodeURIComponent(segment).startsWith(".");
+    }
+    catch {
+        return false;
+    }
+}
+function checkedSegmentIndexes(segments, projectRoot) {
+    const all = segments.map((_, i) => i);
+    if (segments[0] !== "@fs")
+        return all;
+    const disk = segments.slice(1);
+    const rootSegments = projectRoot.split("/").filter((s) => s !== "");
+    const inside = disk.length >= rootSegments.length && rootSegments.every((s, i) => disk[i] === s);
+    if (inside)
+        return all.slice(1 + rootSegments.length);
+    const lastNodeModules = disk.lastIndexOf("node_modules");
+    if (lastNodeModules !== -1)
+        return all.slice(1 + lastNodeModules + 1);
+    return all.slice(1);
+}
+/** The four anchored exceptions (D-Preview-hides-dot-paths). Case-sensitive. */
+function isAllowedDotSegment(segments, i) {
+    const seg = segments[i];
+    const prev = segments[i - 1];
+    const next = segments[i + 1];
+    if (seg === ".well-known")
+        return i === 0;
+    if (seg === ".vite" || seg === ".pnpm")
+        return prev === "node_modules";
+    if (seg === ".svelte-kit")
+        return next === "generated" && segments[i + 2] !== "server";
+    if (seg === ".yarn")
+        return next === "cache" || next === "__virtual__" || next === "unplugged";
+    return false;
+}

package/dist/preview/qrPage.js

@@ -23,7 +23,7 @@ export async function buildQrPage(url) {
 <head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>Scan to preview — ${safe}</title>
+<title>Scan to preview: ${safe}</title>
 <style>
   :root { color-scheme: light dark; }
   body { margin:0; min-height:100vh; display:grid; place-items:center;

package/dist/preview/runner.d.ts

@@ -1,7 +1,9 @@
 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";
+import { type ResolvedConfig } from "../shared/config.js";
+/** The path a 404 advisory names: the request's own path, without its query. */
+export declare function requestPathOf(url: string | undefined): string;
 /** Why a preview ended. Each maps to exactly one screen (Flow L20/L21). */
 export type PreviewEndReason = "stopped"
 /**
@@ -29,7 +31,13 @@ export type PreviewEndReason = "stopped"
  * 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";
+ | "abandoned" | "egress_cap"
+/**
+ * The heartbeat's token was refused (401). Not a network blip: every later
+ * beat is refused the same way, so the preview ends with the sign-in remedy
+ * instead of heartbeating until the edge drains it.
+ */
+ | "auth_expired";
 export interface StartPreviewOptions {
     /** Project directory — its .vincentt binding + dev script drive the preview. */
     projectCwd: string;
@@ -55,7 +63,13 @@ export interface StartPreviewOptions {
     frontPort?: number;
     /** Path routed to the relay instead of the app (default /__harness). */
     harnessPath?: string;
-    devCommand?: string[];
+    /**
+     * The dev command. A string (the resolved `dev.command`) runs through the
+     * platform shell, because creator-authored commands carry arguments and `&&`.
+     */
+    devCommand?: string[] | string;
+    /** A hidden path was refused by the front proxy (the 404 advisory). */
+    onHiddenPath?: (requestPath: string) => void;
     appStdio?: "ignore" | "inherit";
     appReadyTimeoutMs?: number;
     /** Progress sink. Never write app stdout to an MCP server's stdout. */
@@ -158,7 +172,8 @@ 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".
+ * differ: one is "find out who you are", the other is "try again". A 401 is the
+ * token itself refused, and its remedy is signing in 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
@@ -170,20 +185,17 @@ export declare function refusalToReason(status: number): PreviewEndReason | null
  * 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.
+ * The API's 410 carries the terminal reason under `detail.endReason`, and each
+ * reason maps to its own screen. A 410 with no reason gets the cause-free
+ * ending. 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.
+ * `hard_max` is returned ONLY for an explicit `expired`. An UNLABELLED 410 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