@vincentt-xr/cli 0.1.2 → 0.1.4

package/dist/cli/index.js

@@ -12,9 +12,11 @@
 import os from "node:os";
 import path from "node:path";
 import { runLogin } from "../login/login.js";
+import { ensureLoggedIn } from "../login/ensure.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";
@@ -50,6 +52,18 @@ async function login() {
     console.log(`\n✓ Signed in. Access token saved to ${configPath}`);
     console.log(`  API: ${saved}`);
 }
+/** The token that would authenticate a machine call, if any (env wins over file). */
+async function currentToken() {
+    return process.env.VINCENTT_PAT ?? (await loadMachineConfig()).pat;
+}
+/** Guard an auth-requiring verb: log in inline on first run instead of erroring. */
+async function requireLogin() {
+    await ensureLoggedIn({
+        currentToken,
+        runLogin: login,
+        notify: (m) => console.error(m),
+    });
+}
 async function logout() {
     const { path: p, hadToken } = await clearMachineToken();
     console.log(hadToken ? `✓ Signed out. Token removed from ${p}` : "Already signed out.");
@@ -78,6 +92,7 @@ async function whoami() {
 }
 // ---- dev loop ---------------------------------------------------------------
 async function create() {
+    await requireLogin();
     const result = await projectCreate(projectDir(), {
         name: flag("--name"),
         slug: flag("--slug"),
@@ -101,6 +116,7 @@ async function unbind() {
     console.log(hadBinding ? `✓ Unbound. Removed ${p}` : "This directory has no project binding.");
 }
 async function publish() {
+    await requireLogin();
     const result = await projectPublish(projectDir(), {
         distDir: flag("--dist"),
         note: flag("--note"),
@@ -110,15 +126,34 @@ 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;
+    }
+    await requireLogin();
     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 +236,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/login/ensure.d.ts

@@ -0,0 +1,10 @@
+export interface EnsureLoginDeps {
+    /** Resolve the current token (env override or machine config), or undefined. */
+    currentToken: () => Promise<string | undefined>;
+    /** Run the interactive login flow (loopback OAuth), persisting a token. */
+    runLogin: () => Promise<void>;
+    /** Surface a line to the user (stderr, so it never pollutes machine-readable stdout). */
+    notify: (message: string) => void;
+}
+/** No-op when a token is already present; otherwise log-and-login before returning. */
+export declare function ensureLoggedIn(deps: EnsureLoginDeps): Promise<void>;

package/dist/login/ensure.js

@@ -0,0 +1,13 @@
+// First-run login guard. An auth-requiring verb (create / preview / publish) calls
+// this before doing any work: if there's no token yet, it runs the login flow inline
+// and continues, instead of failing with "not signed in". Login stays a human browser
+// approval — this only removes the separate `vincentt login` step a user had to know
+// to run first. Deps are injected so the branch is unit-testable without a real
+// browser round-trip or a real config file.
+/** No-op when a token is already present; otherwise log-and-login before returning. */
+export async function ensureLoggedIn(deps) {
+    if (await deps.currentToken())
+        return;
+    deps.notify("You're not signed in yet — opening the browser to authorize this device…");
+    await deps.runLogin();
+}

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

@@ -34,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. */

package/dist/preview/runner.js

@@ -77,7 +77,7 @@ export async function startPreview(opts) {
         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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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": {