@vincentt-xr/harness 0.1.0 → 0.2.0

package/dist/mcp/server.d.ts

@@ -1,5 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type RelayClient } from "./diagnostics.js";
+/** Reap the running preview, if any. Called by preview_stop and on server exit. */
+export declare function shutdownActivePreview(): Promise<void>;
 export interface McpOptions {
     /** Base URL of the relay's HTTP endpoint (default matches the relay CLI). */
     relayUrl?: string;

package/dist/mcp/server.js

@@ -9,8 +9,20 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
 import { createProject, gitHeadSha, publishUpload } from "./backend.js";
-import { loadProjectBinding, resolveConfig, writeProjectBinding } from "../shared/config.js";
+import { loadProjectBinding, resolveConfig, writeProjectBinding, } from "../shared/config.js";
 import { needsScaffold, scaffoldFromTemplate } from "../scaffold/index.js";
+import { startPreview } from "../preview/index.js";
+// One preview per server process. Held at module scope so runStdio can reap it on
+// shutdown without threading the handle through createHarnessMcp's return type.
+let activePreview = null;
+/** Reap the running preview, if any. Called by preview_stop and on server exit. */
+export async function shutdownActivePreview() {
+    if (!activePreview)
+        return;
+    const preview = activePreview;
+    activePreview = null;
+    await preview.stop();
+}
 /** Wrap a lifecycle handler so a thrown error returns readable MCP error text. */
 async function guard(run) {
     try {
@@ -104,7 +116,9 @@ export function createHarnessMcp(opts = {}) {
             projectId: created.projectId,
             slug: created.slug,
         });
-        return ((scaffolded ? "Scaffolded the v2-template starter into this directory.\n" : "") +
+        return ((scaffolded
+            ? "Scaffolded the v2-template starter into this directory.\n"
+            : "") +
             `Created "${created.name}" → slug ${created.slug} (id ${created.projectId}).\n` +
             `Binding written to ${bindingPath} (gitignored).\n` +
             `Build locally, then run project_publish to go live at ${created.slug}.vincentt.app.`);
@@ -116,7 +130,10 @@ export function createHarnessMcp(opts = {}) {
                 .string()
                 .optional()
                 .describe("Path to the built dist directory, relative to the project (default: dist)."),
-            note: z.string().optional().describe("Optional release note recorded with the version."),
+            note: z
+                .string()
+                .optional()
+                .describe("Optional release note recorded with the version."),
         },
     }, async ({ distDir, note }) => guard(async () => {
         const binding = await loadProjectBinding(projectCwd);
@@ -126,15 +143,52 @@ export function createHarnessMcp(opts = {}) {
         const cfg = await resolveConfig(projectCwd);
         const dist = path.resolve(projectCwd, distDir ?? "dist");
         const commitSha = await gitHeadSha(projectCwd);
-        const result = await publishUpload(cfg, binding.projectId, dist, { note, commitSha });
+        const result = await publishUpload(cfg, binding.projectId, dist, {
+            note,
+            commitSha,
+        });
         return `Published v${result.version}. Live at ${result.liveUrl}\nThis version: ${result.url}`;
     }));
+    server.registerTool("preview_start", {
+        description: "Start a live on-device preview: serves the app, opens a public https tunnel, and wires the diagnostics relay so diag_logs/diag_network/diag_trace read from the connected device. Returns the URL to open on a phone. Requires a project_create binding; cloudflared is auto-provisioned if missing. One preview at a time — call preview_stop before starting another. The dev server keeps running until preview_stop, so start it once and iterate.",
+        inputSchema: {},
+    }, async () => guard(async () => {
+        if (activePreview) {
+            return `A preview is already running:\n${activePreview.url}\nCall preview_stop first to restart.`;
+        }
+        // App stdout would corrupt the MCP channel; keep it off stdout entirely and
+        // route harness progress to stderr.
+        activePreview = await startPreview({
+            projectCwd,
+            onLog: (m) => console.error(`[preview] ${m}`),
+        });
+        return (`Live preview running — open on your device:\n${activePreview.url}\n\n` +
+            `Diagnostics are live: diag_logs / diag_network / diag_trace now read from this device.\n` +
+            `Call preview_stop when finished.`);
+    }));
+    server.registerTool("preview_stop", {
+        description: "Stop the running preview: tears down the tunnel (and its DNS route), the app dev server, and the diagnostics relay. Safe to call when nothing is running.",
+        inputSchema: {},
+    }, async () => guard(async () => {
+        if (!activePreview)
+            return "No preview is running.";
+        await shutdownActivePreview();
+        return "Preview stopped. Tunnel and dev server torn down.";
+    }));
     return server;
 }
 export async function runStdio(opts = {}) {
     const server = createHarnessMcp(opts);
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // A running preview owns a child process + a live backend tunnel; reap both when
+    // the agent disconnects so we never leak a tunnel/DNS route past the session.
+    const shutdown = async () => {
+        await shutdownActivePreview();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
     // stdout is the MCP channel — status goes to stderr only.
     console.error("[harness-mcp] connected over stdio");
 }

package/dist/preview/index.d.ts

@@ -1,15 +1,3 @@
-import { type MintedTunnel } from "../mcp/backend.js";
+export { startSessionTunnel, type SessionTunnel } from "./tunnel.js";
 export { ensureCloudflared, type EnsureCloudflaredOptions } from "./cloudflared.js";
-export interface SessionTunnel extends MintedTunnel {
-    /** Public https URL to open on the device. */
-    url: string;
-    /** Tear the tunnel down (DNS route + tunnel). Idempotent; call on SIGINT. */
-    reap: () => Promise<void>;
-}
-/**
- * Mint a per-session dev tunnel for the project bound to `projectCwd`, routing
- * <slug>-<token>.<apex> to the local `localPort`. Returns the URL to open and a
- * `reap()` for teardown. Throws with an actionable message when the directory is
- * unbound (run project_create) or no backend/PAT is configured.
- */
-export declare function startSessionTunnel(projectCwd: string, localPort: number): Promise<SessionTunnel>;
+export { startPreview, type StartPreviewOptions, type RunningPreview } from "./runner.js";

package/dist/preview/index.js

@@ -1,30 +1,6 @@
-// Preview-script glue for the per-session dev tunnel. Resolves the project
-// binding + machine config and mints a named tunnel via the backend (which holds
-// the Cloudflare account creds). The caller (an app's preview.mjs) runs
-// `cloudflared tunnel run --token <runToken>` itself and calls reap() on exit —
-// this module stays free of any child-process / cloudflared coupling.
-import { loadProjectBinding, resolveConfig } from "../shared/config.js";
-import { mintTunnel, reapTunnel } from "../mcp/backend.js";
+// Public surface of the preview limb (`@vincentt-xr/harness/preview`): the tunnel
+// mint, the cloudflared resolver, and the full one-call preview runner. Barrel
+// only — implementations live in the sibling modules.
+export { startSessionTunnel } from "./tunnel.js";
 export { ensureCloudflared } from "./cloudflared.js";
-/**
- * Mint a per-session dev tunnel for the project bound to `projectCwd`, routing
- * <slug>-<token>.<apex> to the local `localPort`. Returns the URL to open and a
- * `reap()` for teardown. Throws with an actionable message when the directory is
- * unbound (run project_create) or no backend/PAT is configured.
- */
-export async function startSessionTunnel(projectCwd, localPort) {
-    const binding = await loadProjectBinding(projectCwd);
-    if (!binding) {
-        throw new Error("No project bound to this directory — run project_create first.");
-    }
-    const cfg = await resolveConfig(projectCwd);
-    const minted = await mintTunnel(cfg, binding.projectId, localPort);
-    return {
-        ...minted,
-        url: `https://${minted.hostname}`,
-        reap: () => reapTunnel(cfg, binding.projectId, {
-            tunnelId: minted.tunnelId,
-            dnsRecordId: minted.dnsRecordId,
-        }),
-    };
-}
+export { startPreview } from "./runner.js";

package/dist/preview/proxy.d.ts

@@ -0,0 +1,4 @@
+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;
+export declare function proxyWs(req: IncomingMessage, socket: Duplex, head: Buffer, targetPort: number): void;

package/dist/preview/proxy.js

@@ -0,0 +1,49 @@
+// A minimal same-host reverse proxy: forward HTTP requests and WebSocket upgrades
+// to a localhost target port. Enough for the preview front proxy (app + harness
+// relay behind one origin); not a general proxy. No deps.
+import { connect } from "node:net";
+import { request, } from "node:http";
+// 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}` };
+}
+export function proxyWeb(req, res, targetPort) {
+    const proxyReq = request({
+        host: "127.0.0.1",
+        port: targetPort,
+        path: req.url,
+        method: req.method,
+        headers: localHeaders(req.headers, targetPort),
+    }, (proxyRes) => {
+        res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+        proxyRes.pipe(res);
+    });
+    proxyReq.on("error", () => {
+        if (!res.headersSent)
+            res.writeHead(502);
+        res.end();
+    });
+    req.pipe(proxyReq);
+}
+export function proxyWs(req, socket, head, targetPort) {
+    // Re-issue the upgrade handshake against the target and splice the sockets.
+    const headers = localHeaders(req.headers, targetPort);
+    const upstream = connect(targetPort, "127.0.0.1", () => {
+        const headerLines = [
+            `${req.method} ${req.url} HTTP/1.1`,
+            ...Object.entries(headers).map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(", ") : v}`),
+            "",
+            "",
+        ].join("\r\n");
+        upstream.write(headerLines);
+        if (head && head.length)
+            upstream.write(head);
+        upstream.pipe(socket);
+        socket.pipe(upstream);
+    });
+    const bail = () => socket.destroy();
+    upstream.on("error", bail);
+    socket.on("error", bail);
+}

package/dist/preview/runner.d.ts

@@ -0,0 +1,36 @@
+import { type ChildProcess } from "node:child_process";
+export interface StartPreviewOptions {
+    /** Project directory — its .vincentt binding + dev script drive the preview. */
+    projectCwd: string;
+    /** Internal port for the app dev serve (default 5173). */
+    appPort?: number;
+    /** Relay port; must match the MCP server's relay client (default 7331). */
+    relayPort?: number;
+    /** Port the tunnel points at — the front proxy origin (default 5190). */
+    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 45s). */
+    registerTimeoutMs?: number;
+    /** Progress sink (relay/cloudflared lines). Never write app stdout to MCP stdout. */
+    onLog?: (message: string) => void;
+}
+export interface RunningPreview {
+    /** Public https URL to open on the device. */
+    url: string;
+    /** Relay port the diag_* tools query. */
+    relayPort: number;
+    /** Tear down tunnel (+ DNS route), app dev serve, front proxy, and 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. Exported for unit testing the log-scan/timeout logic.
+ */
+export declare function waitForRegister(tunnel: ChildProcess, timeoutMs: number): Promise<void>;

package/dist/preview/runner.js

@@ -0,0 +1,87 @@
+// The whole preview stack behind one call. Stands up, in order: the app dev serve
+// (on an internal port), the harness relay (WS event sink + localhost /query), a
+// front proxy unifying them on one origin (`/__harness` → relay, else → app), and
+// a cloudflared tunnel to that origin so a phone gets ONE https URL that serves
+// both the app (secure context → live camera) and the diagnostics socket.
+//
+// Returns the public URL plus a `stop()` that reaps everything. A failure at any
+// step tears down what was already started, so the caller never leaks a child
+// process or a live backend tunnel. Used by both the CLI (`npm run preview`) and
+// the MCP verbs (preview_start / preview_stop).
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { startRelay } from "../relay/server.js";
+import { ensureCloudflared } from "./cloudflared.js";
+import { startSessionTunnel } from "./tunnel.js";
+import { proxyWeb, proxyWs } from "./proxy.js";
+export async function startPreview(opts) {
+    const { projectCwd, appPort = 5173, relayPort = 7331, frontPort = 5190, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", registerTimeoutMs = 45_000, onLog = () => undefined, } = opts;
+    // Track every resource so any failure below can unwind exactly what started.
+    let app;
+    let relay;
+    let front;
+    let session;
+    let tunnel;
+    const stop = async () => {
+        tunnel?.kill();
+        app?.kill();
+        front?.close();
+        if (relay)
+            await relay.close();
+        if (session)
+            await session.reap();
+    };
+    try {
+        // Resolve cloudflared up front so a fresh host provisions it before we mint a
+        // tunnel we couldn't otherwise run.
+        const cloudflaredBin = await ensureCloudflared({ onLog });
+        app = spawn(devCommand[0], devCommand.slice(1), {
+            cwd: projectCwd,
+            env: { ...process.env, PORT: String(appPort) },
+            stdio: appStdio,
+        });
+        relay = startRelay({
+            port: relayPort,
+            path: harnessPath,
+            onLog: (m) => onLog(`[relay] ${m}`),
+        });
+        front = createServer((req, res) => proxyWeb(req, res, req.url?.startsWith(harnessPath) ? relayPort : appPort));
+        front.on("upgrade", (req, socket, head) => proxyWs(req, socket, head, req.url?.startsWith(harnessPath) ? relayPort : appPort));
+        await new Promise((resolve) => front.listen(frontPort, resolve));
+        session = await startSessionTunnel(projectCwd, frontPort);
+        tunnel = spawn(cloudflaredBin, ["tunnel", "run", "--token", session.runToken], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        await waitForRegister(tunnel, registerTimeoutMs);
+        return { url: session.url, relayPort, stop };
+    }
+    catch (err) {
+        await stop();
+        throw err;
+    }
+}
+/**
+ * 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.
+ */
+export function waitForRegister(tunnel, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const scan = (buf) => {
+            if (/Registered tunnel connection|Connection [^ ]+ registered/.test(String(buf))) {
+                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);
+    });
+}

package/dist/preview/tunnel.d.ts

@@ -0,0 +1,14 @@
+import { type MintedTunnel } from "../mcp/backend.js";
+export interface SessionTunnel extends MintedTunnel {
+    /** Public https URL to open on the device. */
+    url: string;
+    /** Tear the tunnel down (DNS route + tunnel). Idempotent; call on SIGINT. */
+    reap: () => Promise<void>;
+}
+/**
+ * Mint a per-session dev tunnel for the project bound to `projectCwd`, routing
+ * <slug>-<token>.<apex> to the local `localPort`. Returns the URL to open and a
+ * `reap()` for teardown. Throws with an actionable message when the directory is
+ * unbound (run project_create) or no backend/PAT is configured.
+ */
+export declare function startSessionTunnel(projectCwd: string, localPort: number): Promise<SessionTunnel>;

package/dist/preview/tunnel.js

@@ -0,0 +1,28 @@
+// Per-session dev tunnel: resolve the project binding + machine config and mint a
+// named tunnel via the backend (which holds the Cloudflare account creds). Stays
+// free of any child-process / cloudflared coupling — the caller runs cloudflared
+// with the returned run token (see runner.ts) and calls reap() on exit.
+import { loadProjectBinding, resolveConfig } from "../shared/config.js";
+import { mintTunnel, reapTunnel } from "../mcp/backend.js";
+/**
+ * Mint a per-session dev tunnel for the project bound to `projectCwd`, routing
+ * <slug>-<token>.<apex> to the local `localPort`. Returns the URL to open and a
+ * `reap()` for teardown. Throws with an actionable message when the directory is
+ * unbound (run project_create) or no backend/PAT is configured.
+ */
+export async function startSessionTunnel(projectCwd, localPort) {
+    const binding = await loadProjectBinding(projectCwd);
+    if (!binding) {
+        throw new Error("No project bound to this directory — run project_create first.");
+    }
+    const cfg = await resolveConfig(projectCwd);
+    const minted = await mintTunnel(cfg, binding.projectId, localPort);
+    return {
+        ...minted,
+        url: `https://${minted.hostname}`,
+        reap: () => reapTunnel(cfg, binding.projectId, {
+            tunnelId: minted.tunnelId,
+            dnsRecordId: minted.dnsRecordId,
+        }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/harness",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Vincentt AR dev-loop harness — in-app diagnostics client + relay + agent-agnostic MCP server",
   "license": "UNLICENSED",
   "type": "module",