@vincentt-xr/cli 0.1.1 → 0.1.3

package/dist/cli/index.js

@@ -14,7 +14,8 @@ import path from "node:path";
 import { runLogin } from "../login/login.js";
 import { clearMachineToken, clearProjectBinding, loadMachineConfig, } from "../shared/config.js";
 import { getMe } from "../lib/backend.js";
-import { diagQuery, diagRead, previewStart, previewStop, projectCreate, projectPublish, } from "../lib/lifecycle.js";
+import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, projectPublish, } from "../lib/lifecycle.js";
+import { writeQrPage } from "../preview/qrPage.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
 const DEFAULT_EDITOR_URL = "https://editor.vincentt.studio";
 const DEFAULT_API_URL = "https://api.vincentt.studio";
@@ -110,15 +111,33 @@ async function publish() {
         process.exitCode = 1;
 }
 async function preview() {
+    // `--stop` reaps a preview started by another process (e.g. a backgrounded run)
+    // via its pidfile — no need to hunt for the cloudflared pid by hand.
+    if (has("--stop")) {
+        const { message } = await previewStopSignal(projectDir());
+        console.log(message);
+        return;
+    }
     const { preview: p, started } = await previewStart(projectDir(), (m) => console.error(`[preview] ${m}`));
     if (!started) {
         console.log(`A preview is already running:\n${p.url}`);
         return;
     }
-    console.log(`\nLive preview — open on your device:\n  ${p.url}\n`);
-    console.log("Diagnostics: vincentt logs | network | trace");
+    console.log("\nLive preview:");
+    console.log(`  Open on your phone:  ${p.url}`);
+    // A scannable QR in the terminal is unreliable across emulators, so hand back a
+    // desktop QR page to open and scan instead. Best-effort — a preview is still
+    // usable via the URL above if writing the page fails.
+    try {
+        const qrUrl = await writeQrPage(projectDir(), p.url);
+        console.log(`  Show QR (desktop):   ${qrUrl}`);
+    }
+    catch {
+        /* non-fatal: the URL above is enough to preview */
+    }
+    console.log("\nDiagnostics: vincentt logs | network | trace");
     console.log("Feedback:    vincentt feedback --wait");
-    console.log("\nPress Ctrl-C to stop.");
+    console.log("\nStop: vincentt preview --stop (or Ctrl-C here).");
     if (!p.appReady) {
         console.log(`\nNote: the app on :${p.appPort} isn't responding yet — the URL may be blank until its build finishes.`);
     }
@@ -201,7 +220,8 @@ function usage() {
         `                       [--name <s>] [--slug <s>] [--preview] [--force]\n` +
         `  unbind             Detach this directory from its project\n` +
         `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
-        `  preview            Serve + tunnel the app for on-device preview\n\n` +
+        `  preview            Serve + tunnel the app for on-device preview\n` +
+        `                       (prints a desktop QR page to scan) [--stop]\n\n` +
         `Diagnostics (need a running preview)\n` +
         `  logs [--errors]    Console logs from the device   [--json]\n` +
         `  network            fetch/XHR requests              [--json]\n` +

package/dist/lib/lifecycle.d.ts

@@ -37,6 +37,20 @@ export interface PreviewStartResult {
 }
 export declare function previewStart(projectCwd: string, onLog: (msg: string) => void): Promise<PreviewStartResult>;
 export declare function previewStop(): Promise<boolean>;
+export interface PreviewStopOutcome {
+    stopped: boolean;
+    message: string;
+}
+/**
+ * Stop a preview started by a *different* process (the common case: `vincentt
+ * preview` runs in the background and the agent later wants it down). Reads the
+ * pidfile and signals the recorded pids rather than the in-process `activePreview`.
+ * SIGTERM to the preview process runs its graceful handler (which reaps the tunnel
+ * + backend DNS route); if that process is already gone, its cloudflared child may
+ * be orphaned to init, so kill the recorded tunnel pid directly. Either way, clear
+ * the (now stale) relay info.
+ */
+export declare function previewStopSignal(projectCwd: string): Promise<PreviewStopOutcome>;
 export interface DiagQueryOptions {
     sessionId?: string;
     since?: number;

package/dist/lib/lifecycle.js

@@ -110,7 +110,7 @@ export async function projectPublish(projectCwd, opts = {}) {
         commitSha,
     });
     return {
-        message: `Published v${result.version}. Live at ${result.liveUrl}\nThis version: ${result.url}`,
+        message: `Published v${result.version}. Live at ${result.liveUrl}`,
         notBound: false,
         version: result.version,
         liveUrl: result.liveUrl,
@@ -135,6 +135,7 @@ export async function previewStart(projectCwd, onLog) {
         relayPort: preview.relayPort,
         url: preview.url,
         pid: process.pid,
+        tunnelPid: preview.tunnelPid,
         harnessPath: "/__harness",
     });
     return { preview, started: true };
@@ -151,6 +152,55 @@ export async function previewStop() {
         await clearRelayInfo(cwd);
     return true;
 }
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0); // signal 0 = existence check, kills nothing
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Stop a preview started by a *different* process (the common case: `vincentt
+ * preview` runs in the background and the agent later wants it down). Reads the
+ * pidfile and signals the recorded pids rather than the in-process `activePreview`.
+ * SIGTERM to the preview process runs its graceful handler (which reaps the tunnel
+ * + backend DNS route); if that process is already gone, its cloudflared child may
+ * be orphaned to init, so kill the recorded tunnel pid directly. Either way, clear
+ * the (now stale) relay info.
+ */
+export async function previewStopSignal(projectCwd) {
+    const info = await readRelayInfo(projectCwd);
+    if (!info) {
+        return { stopped: false, message: "No preview is running for this directory." };
+    }
+    const previewAlive = info.pid !== undefined && isAlive(info.pid);
+    const reaped = [];
+    if (previewAlive) {
+        try {
+            process.kill(info.pid, "SIGTERM");
+            reaped.push("preview process");
+        }
+        catch {
+            /* raced with its own exit — fall through to tunnel cleanup */
+        }
+    }
+    // Only force-kill the tunnel directly when no live preview process will reap it.
+    if (!previewAlive && info.tunnelPid !== undefined && isAlive(info.tunnelPid)) {
+        try {
+            process.kill(info.tunnelPid, "SIGKILL");
+            reaped.push("orphaned tunnel");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    await clearRelayInfo(projectCwd);
+    return reaped.length > 0
+        ? { stopped: true, message: `Stopped preview (${reaped.join(", ")}).` }
+        : { stopped: false, message: "No live preview process found; cleared stale relay info." };
+}
 /** Resolve the relay client for a project's running preview, or throw a hint. */
 async function relayForProject(projectCwd, override) {
     if (override)

package/dist/lib/relayInfo.d.ts

@@ -5,6 +5,9 @@ export interface RelayInfo {
     url: string;
     /** The preview process pid, so a stale file can be detected. */
     pid: number;
+    /** The cloudflared child pid, so `preview --stop` can reap an orphaned tunnel
+     *  even after the preview process itself is gone (reparented to init). */
+    tunnelPid?: number;
     /** WS/HTTP path prefix routed to the relay (default /__harness). */
     harnessPath: string;
 }

package/dist/preview/proxy.js

@@ -17,7 +17,16 @@ export function proxyWeb(req, res, targetPort) {
         method: req.method,
         headers: localHeaders(req.headers, targetPort),
     }, (proxyRes) => {
-        res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+        // 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.
+        const headers = { ...proxyRes.headers, "cache-control": "no-store" };
+        delete headers.etag;
+        delete headers["last-modified"];
+        res.writeHead(proxyRes.statusCode ?? 502, headers);
         proxyRes.pipe(res);
     });
     proxyReq.on("error", () => {

package/dist/preview/qrPage.d.ts

@@ -0,0 +1,4 @@
+/** Full HTML for the QR page — inline SVG QR + the tappable URL, no external assets. */
+export declare function buildQrPage(url: string): Promise<string>;
+/** Write the QR page under .vincentt/ and return a file:// URL to open on the desktop. */
+export declare function writeQrPage(projectCwd: string, url: string): Promise<string>;

package/dist/preview/qrPage.js

@@ -0,0 +1,62 @@
+// A tiny self-contained QR page for the preview URL. Rendering a QR in the terminal
+// is unreliable (font/rows vary by emulator, long tunnel URLs don't scan), so instead
+// `vincentt preview` writes this page and prints a file:// link: the developer opens
+// it on their desktop and scans the big SVG QR with their phone. Written under the
+// gitignored .vincentt/ dir, so it never rides a commit.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import QRCode from "qrcode";
+const VINCENTT_DIR = ".vincentt";
+const QR_FILE = "preview-qr.html";
+/** Full HTML for the QR page — inline SVG QR + the tappable URL, no external assets. */
+export async function buildQrPage(url) {
+    // Medium ECC + a quiet margin keeps a ~50-char tunnel URL comfortably scannable.
+    const svg = await QRCode.toString(url, {
+        type: "svg",
+        margin: 2,
+        errorCorrectionLevel: "M",
+    });
+    const safe = escapeHtml(url);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Scan to preview — ${safe}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin:0; min-height:100vh; display:grid; place-items:center;
+         font:16px/1.5 system-ui, sans-serif; background:#fff; color:#111; }
+  @media (prefers-color-scheme: dark){ body{ background:#0b0b0c; color:#f4f4f5; } }
+  .card { text-align:center; padding:2rem; max-width:min(90vw,420px); }
+  .qr { width:min(72vw,320px); aspect-ratio:1; margin:0 auto 1.25rem; }
+  .qr svg { width:100%; height:100%; }
+  h1 { font-size:1.05rem; font-weight:600; margin:0 0 .35rem; }
+  p { margin:0 0 1.25rem; opacity:.7; }
+  a.url { display:inline-block; word-break:break-all; font:500 .95rem/1.4 ui-monospace,monospace;
+          color:#2563eb; text-decoration:none; }
+  @media (prefers-color-scheme: dark){ a.url{ color:#60a5fa; } }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="qr">${svg}</div>
+    <h1>Scan to open the preview</h1>
+    <p>Point your phone's camera at the code.</p>
+    <a class="url" href="${safe}">${safe}</a>
+  </div>
+</body>
+</html>
+`;
+}
+/** Write the QR page under .vincentt/ and return a file:// URL to open on the desktop. */
+export async function writeQrPage(projectCwd, url) {
+    const p = path.join(projectCwd, VINCENTT_DIR, QR_FILE);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, await buildQrPage(url), "utf8");
+    return pathToFileURL(p).href;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] ?? c);
+}

package/dist/preview/runner.d.ts

@@ -16,7 +16,9 @@ export interface StartPreviewOptions {
     /** 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 45s). */
+    /** 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;
@@ -32,6 +34,9 @@ export interface RunningPreview {
     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). */
     appReady: boolean;
     /** Tear down tunnel (+ DNS route), app dev serve, front proxy, and relay. */
@@ -40,6 +45,9 @@ export interface RunningPreview {
 export declare function startPreview(opts: StartPreviewOptions): Promise<RunningPreview>;
 /**
  * Resolve once cloudflared reports a live edge connection, reject if it exits
- * first or never registers. Exported for unit testing the log-scan/timeout logic.
+ * 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.
  */
-export declare function waitForRegister(tunnel: ChildProcess, timeoutMs: number): Promise<void>;
+export declare function waitForRegister(tunnel: ChildProcess, timeoutMs: number, onLine?: (line: string) => void): Promise<void>;

package/dist/preview/runner.js

@@ -16,7 +16,7 @@ import { startSessionTunnel } from "./tunnel.js";
 import { proxyWeb, proxyWs } from "./proxy.js";
 import { getFreePort, isPortListening, waitForApp } from "./net.js";
 export async function startPreview(opts) {
-    const { projectCwd, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", registerTimeoutMs = 45_000, appReadyTimeoutMs = 8_000, onLog = () => undefined, } = opts;
+    const { projectCwd, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", registerTimeoutMs = 90_000, appReadyTimeoutMs = 8_000, onLog = () => undefined, } = opts;
     // Resolve ports. The app port defaults to 5173; the relay + front ports are
     // harness-internal, so auto-pick free ones (the relay port is returned for the
     // MCP diag_* tools to point at) instead of colliding on fixed defaults.
@@ -70,14 +70,14 @@ export async function startPreview(opts) {
         tunnel = spawn(cloudflaredBin, ["tunnel", "run", "--token", session.runToken], {
             stdio: ["ignore", "pipe", "pipe"],
         });
-        await waitForRegister(tunnel, registerTimeoutMs);
+        await waitForRegister(tunnel, registerTimeoutMs, (line) => onLog(`[cloudflared] ${line}`));
         // Don't hand back a live URL that serves a blank page: wait for the app to
         // actually respond. Non-fatal — a slow build still returns, flagged not-ready.
         const appReady = reuseApp ? true : await waitForApp(appPort, appReadyTimeoutMs);
         if (!appReady) {
             onLog(`app on :${appPort} isn't responding yet — the URL may be blank until it builds`);
         }
-        return { url: session.url, relayPort, appPort, appReady, stop };
+        return { url: session.url, relayPort, appPort, tunnelPid: tunnel.pid, appReady, stop };
     }
     catch (err) {
         await stop();
@@ -86,11 +86,15 @@ export async function startPreview(opts) {
 }
 /**
  * Resolve once cloudflared reports a live edge connection, reject if it exits
- * first or never registers. Exported for unit testing the log-scan/timeout logic.
+ * 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.
  */
-export function waitForRegister(tunnel, timeoutMs) {
+export function waitForRegister(tunnel, timeoutMs, onLine) {
     return new Promise((resolve, reject) => {
         let settled = false;
+        const recent = [];
         const finish = (fn) => {
             if (settled)
                 return;
@@ -98,14 +102,25 @@ export function waitForRegister(tunnel, timeoutMs) {
             clearTimeout(timer);
             fn();
         };
+        const tail = () => {
+            const lines = recent.slice(-15).join("\n").trim();
+            return lines ? `\ncloudflared output:\n${lines}` : "";
+        };
         const scan = (buf) => {
-            if (/Registered tunnel connection|Connection [^ ]+ registered/.test(String(buf))) {
+            const text = String(buf);
+            for (const line of text.split(/\r?\n/)) {
+                if (!line.trim())
+                    continue;
+                recent.push(line);
+                onLine?.(line);
+            }
+            if (/Registered tunnel connection|Connection [^ ]+ registered/.test(text)) {
                 finish(resolve);
             }
         };
         tunnel.stdout?.on("data", scan);
         tunnel.stderr?.on("data", scan);
-        tunnel.on("exit", (code) => finish(() => reject(new Error(`cloudflared exited before registering (code ${code}).`))));
-        const timer = setTimeout(() => finish(() => reject(new Error(`cloudflared did not register within ${timeoutMs}ms.`))), timeoutMs);
+        tunnel.on("exit", (code) => finish(() => reject(new Error(`cloudflared exited before registering (code ${code}).${tail()}`))));
+        const timer = setTimeout(() => finish(() => reject(new Error(`cloudflared did not register within ${timeoutMs}ms.${tail()}`))), timeoutMs);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay, mcp)",
   "license": "UNLICENSED",
   "type": "module",
@@ -26,11 +26,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "cloudflared": "^0.7.1",
+    "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
     "@vincentt-xr/harness": "1.0.0"
   },
   "devDependencies": {
+    "@types/qrcode": "^1.5.5",
     "@types/ws": "^8.5.13"
   },
   "scripts": {