@vincentt-xr/harness 0.4.0 → 1.1.0

package/dist/mcp/server.js

@@ -1,239 +0,0 @@
-// The agent-agnostic MCP server. Any MCP-capable agent (Claude Code, Codex,
-// Cursor, Cline, …) points its MCP config at `harness-mcp` and gets three tools
-// to PULL diagnostics off the phone, replacing the user hand-ferrying console
-// output and DevTools traces. All formatting lives in diagnostics.ts; this file
-// is only the MCP SDK wiring.
-import path from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-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 { installDependencies, 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();
-}
-/** Resolve a call's project dir: an explicit `projectDir` arg (absolute, or
- *  relative to the server base) overrides the base; otherwise the base is used. */
-function resolveProjectDir(base, arg) {
-    return arg ? path.resolve(base, arg) : base;
-}
-const projectDirInput = {
-    projectDir: z
-        .string()
-        .optional()
-        .describe("Absolute path (or path relative to the server's working dir) of the project. Defaults to VINCENTT_PROJECT_DIR or the server's cwd. Set this when your agent spawns MCP servers outside the project directory."),
-};
-/** Wrap a lifecycle handler so a thrown error returns readable MCP error text. */
-async function guard(run) {
-    try {
-        return { content: [{ type: "text", text: await run() }] };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: msg }], isError: true };
-    }
-}
-const sharedInput = {
-    sessionId: z
-        .string()
-        .optional()
-        .describe("Filter to one preview session (phone). Omit for all."),
-    since: z
-        .number()
-        .optional()
-        .describe("Return only events with seq greater than this. Use the latestSeq from a prior call to poll for new events."),
-    limit: z
-        .number()
-        .optional()
-        .describe("Cap the number of events returned (newest kept)."),
-};
-export function createHarnessMcp(opts = {}) {
-    const defaultRelay = opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
-    // Diag tools read through this. preview_start re-points it at the live preview's
-    // relay port (OS-assigned), and preview_stop resets it to the default.
-    let relayClient = defaultRelay;
-    const now = opts.now ?? Date.now;
-    const server = new McpServer({ name: "vincentt-harness", version: "0.1.0" });
-    server.registerTool("diag_logs", {
-        description: "Read console logs the preview app produced on the device. Use `errorsOnly` to see just errors, `since` to poll for new logs. Replaces the user pasting console output.",
-        inputSchema: {
-            ...sharedInput,
-            errorsOnly: z.boolean().optional().describe("Return only error-level logs."),
-        },
-    }, async ({ sessionId, since, limit, errorsOnly }) => {
-        const q = { kind: "log", sessionId, since, limit };
-        let result = await relayClient.query(q);
-        if (errorsOnly)
-            result = filterErrors(result);
-        return { content: [{ type: "text", text: renderResult(result, "log", now()) }] };
-    });
-    server.registerTool("diag_network", {
-        description: "Read fetch/XHR requests the preview app made on the device (method, URL, status, duration). Use to find failed asset loads or slow calls without DevTools.",
-        inputSchema: sharedInput,
-    }, async ({ sessionId, since, limit }) => {
-        const result = await relayClient.query({
-            kind: "network",
-            sessionId,
-            since,
-            limit,
-        });
-        return {
-            content: [{ type: "text", text: renderResult(result, "network", now()) }],
-        };
-    });
-    server.registerTool("diag_trace", {
-        description: "Read performance samples from the device (fps, longest main-thread task, long-task count, phase marks). Replaces hand-exporting a DevTools trace to spot jank.",
-        inputSchema: sharedInput,
-    }, async ({ sessionId, since, limit }) => {
-        const result = await relayClient.query({ kind: "trace", sessionId, since, limit });
-        return { content: [{ type: "text", text: renderResult(result, "trace", now()) }] };
-    });
-    // The project directory the lifecycle verbs operate on. Do NOT assume the agent
-    // spawned the server in it — only Claude Code reliably does; Cursor/Copilot/Codex
-    // spawn MCP servers from the editor root or home. VINCENTT_PROJECT_DIR (settable
-    // in every host's MCP config `env`) is the portable knob; a per-call `projectDir`
-    // arg overrides it. See docs/harness-agent-agnostic.md.
-    const baseProjectDir = opts.cwd ?? process.env.VINCENTT_PROJECT_DIR ?? process.cwd();
-    server.registerTool("project_create", {
-        description: "Create a Vincentt project this working directory publishes to. If the directory has no app yet, it scaffolds the v2-template starter into it (like GitHub's Use-this-template); then it writes a local .vincentt/project.json binding and reserves <slug>.vincentt.app. Ask the user for a project name AND a slug before calling; pass what they give. Omit either to accept a default — name = folder name, slug = a platform-assigned catchy one. The slug is the permanent public subdomain (locked once published), so confirm it with the user. Run once per new app; publish with project_publish to go live.",
-        inputSchema: {
-            name: z
-                .string()
-                .optional()
-                .describe("Display name for the project. Defaults to the working-directory name."),
-            slug: z
-                .string()
-                .optional()
-                .describe("Desired subdomain slug (<slug>.vincentt.app), lowercase kebab-case. Omit to let the platform assign one. Permanent once published."),
-            scaffold: z
-                .boolean()
-                .optional()
-                .describe("Whether to scaffold the v2-template starter when the directory has no app. Defaults to true; set false to bind an existing/empty directory without cloning."),
-            ...projectDirInput,
-        },
-    }, async ({ name, slug, scaffold, projectDir }) => guard(async () => {
-        const projectCwd = resolveProjectDir(baseProjectDir, projectDir);
-        const existing = await loadProjectBinding(projectCwd);
-        if (existing) {
-            return `This directory is already bound to project ${existing.projectId} (slug ${existing.slug}). Delete .vincentt/project.json to rebind.`;
-        }
-        // Resolve config first so a missing PAT fails before any clone/side effect.
-        const cfg = await resolveConfig(projectCwd);
-        let scaffolded = false;
-        if (scaffold !== false && (await needsScaffold(projectCwd))) {
-            await scaffoldFromTemplate(projectCwd);
-            scaffolded = true;
-        }
-        const created = await createProject(cfg, name ?? path.basename(projectCwd), slug);
-        const bindingPath = await writeProjectBinding(projectCwd, {
-            projectId: created.projectId,
-            slug: created.slug,
-        });
-        // Install deps for a freshly scaffolded app so the first preview/build works
-        // out of the box. Best-effort — a failure just becomes a manual-install hint.
-        let scaffoldNote = "";
-        if (scaffolded) {
-            scaffoldNote = "Scaffolded the v2-template starter into this directory.\n";
-            try {
-                await installDependencies(projectCwd);
-                scaffoldNote += "Installed dependencies (npm install).\n";
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                scaffoldNote += `Note: \`npm install\` failed (${msg}) — run it manually before preview.\n`;
-            }
-        }
-        return (scaffoldNote +
-            `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.`);
-    }));
-    server.registerTool("project_publish", {
-        description: "Publish the locally-built dist so this project goes live at <slug>.vincentt.app. Build first (e.g. npm run build), then call this — the dist is uploaded as-is and the server never rebuilds. Requires a prior project_create binding.",
-        inputSchema: {
-            distDir: z
-                .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."),
-            ...projectDirInput,
-        },
-    }, async ({ distDir, note, projectDir }) => guard(async () => {
-        const projectCwd = resolveProjectDir(baseProjectDir, projectDir);
-        const binding = await loadProjectBinding(projectCwd);
-        if (!binding) {
-            return "No project is bound to this directory. Run project_create first.";
-        }
-        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,
-        });
-        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: { ...projectDirInput },
-    }, async ({ projectDir }) => 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: resolveProjectDir(baseProjectDir, projectDir),
-            onLog: (m) => console.error(`[preview] ${m}`),
-        });
-        // Point the diag tools at this preview's relay (its port is OS-assigned).
-        relayClient = httpRelayClient(`http://localhost:${activePreview.relayPort}`);
-        const readiness = activePreview.appReady
-            ? ""
-            : `\nNote: the app on :${activePreview.appPort} isn't responding yet — the URL may be blank until its build finishes. Check diag_logs.`;
-        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.${readiness}`);
-    }));
-    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();
-        // The preview's relay is gone; send diag reads back to the default.
-        relayClient = defaultRelay;
-        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/cloudflared.d.ts

@@ -1,13 +0,0 @@
-export interface EnsureCloudflaredOptions {
-    /** Progress sink for the one-time download (it is ~40MB and takes a few seconds). */
-    onLog?: (message: string) => void;
-}
-/**
- * Return a spawnable cloudflared command/path, provisioning one if the host has
- * none. Resolves to `"cloudflared"` when a system install is on PATH, else to the
- * `cloudflared` package's managed binary (already fetched by its postinstall, or
- * downloaded here on demand when install scripts were skipped). Throws only if the
- * download itself fails (offline / blocked egress) — surface that to the user
- * with the manual `brew install cloudflared` fallback.
- */
-export declare function ensureCloudflared(opts?: EnsureCloudflaredOptions): Promise<string>;

package/dist/preview/cloudflared.js

@@ -1,46 +0,0 @@
-// Resolve a runnable cloudflared binary so a preview never hard-fails on a
-// missing system install. The tunnel protocol is proprietary QUIC to Cloudflare's
-// edge — there is no pure-Node connector, so *some* cloudflared binary is
-// required. We prefer one already on PATH (respects a user's own install) and
-// otherwise fall back to the copy the `cloudflared` npm package provisions, so a
-// fresh machine that installed only the harness can still preview on a device.
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
-function isOnPath() {
-    // `which`/`where` exits 0 only when the binary resolves on PATH.
-    const probe = process.platform === "win32" ? "where" : "which";
-    return spawnSync(probe, ["cloudflared"], { stdio: "ignore" }).status === 0;
-}
-/**
- * Return a spawnable cloudflared command/path, provisioning one if the host has
- * none. Resolves to `"cloudflared"` when a system install is on PATH, else to the
- * `cloudflared` package's managed binary (already fetched by its postinstall, or
- * downloaded here on demand when install scripts were skipped). Throws only if the
- * download itself fails (offline / blocked egress) — surface that to the user
- * with the manual `brew install cloudflared` fallback.
- */
-export async function ensureCloudflared(opts = {}) {
-    if (isOnPath())
-        return "cloudflared";
-    const cloudflared = await import("cloudflared");
-    if (existsSync(cloudflared.bin))
-        return cloudflared.bin;
-    // Reached only when the package's postinstall was skipped (e.g. --ignore-scripts).
-    const log = opts.onLog ?? (() => undefined);
-    log("cloudflared not found — downloading a one-time copy…");
-    await mkdir(path.dirname(cloudflared.bin), { recursive: true });
-    // The download may print progress. On an MCP stdio server, ANY stdout write
-    // corrupts the JSON-RPC stream — redirect stdout→stderr for its duration.
-    const realWrite = process.stdout.write.bind(process.stdout);
-    process.stdout.write = process.stderr.write.bind(process.stderr);
-    try {
-        await cloudflared.install(cloudflared.bin);
-    }
-    finally {
-        process.stdout.write = realWrite;
-    }
-    log(`cloudflared ready at ${cloudflared.bin}`);
-    return cloudflared.bin;
-}

package/dist/preview/index.d.ts

@@ -1,3 +0,0 @@
-export { startSessionTunnel, type SessionTunnel } from "./tunnel.js";
-export { ensureCloudflared, type EnsureCloudflaredOptions } from "./cloudflared.js";
-export { startPreview, type StartPreviewOptions, type RunningPreview } from "./runner.js";

package/dist/preview/index.js

@@ -1,6 +0,0 @@
-// 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";
-export { startPreview } from "./runner.js";

package/dist/preview/net.d.ts

@@ -1,6 +0,0 @@
-/** Ask the OS for an unused ephemeral port. */
-export declare function getFreePort(): Promise<number>;
-/** True if something already accepts TCP connections on the port (e.g. a dev server). */
-export declare function isPortListening(port: number, host?: string): Promise<boolean>;
-/** Poll the app for any non-5xx HTTP response until it's ready or the timeout hits. */
-export declare function waitForApp(port: number, timeoutMs: number): Promise<boolean>;

package/dist/preview/net.js

@@ -1,56 +0,0 @@
-// TCP/HTTP port helpers for the preview runner: pick a free port for the internal
-// servers, detect a dev server already listening (so we reuse it instead of
-// spawning a second one), and wait for the app to actually serve before we hand
-// back a public URL.
-import { createServer, connect } from "node:net";
-import { get as httpGet } from "node:http";
-/** Ask the OS for an unused ephemeral port. */
-export function getFreePort() {
-    return new Promise((resolve, reject) => {
-        const srv = createServer();
-        srv.on("error", reject);
-        srv.listen(0, "127.0.0.1", () => {
-            const { port } = srv.address();
-            srv.close(() => resolve(port));
-        });
-    });
-}
-/** True if something already accepts TCP connections on the port (e.g. a dev server). */
-export function isPortListening(port, host = "127.0.0.1") {
-    return new Promise((resolve) => {
-        const sock = connect(port, host);
-        const done = (v) => {
-            sock.destroy();
-            resolve(v);
-        };
-        sock.setTimeout(400);
-        sock.once("connect", () => done(true));
-        sock.once("timeout", () => done(false));
-        sock.once("error", () => resolve(false));
-    });
-}
-/** Poll the app for any non-5xx HTTP response until it's ready or the timeout hits. */
-export function waitForApp(port, timeoutMs) {
-    const probe = () => new Promise((resolve) => {
-        const req = httpGet({ host: "127.0.0.1", port, path: "/", timeout: 1000 }, (res) => {
-            res.resume();
-            resolve((res.statusCode ?? 500) < 500);
-        });
-        req.on("error", () => resolve(false));
-        req.on("timeout", () => {
-            req.destroy();
-            resolve(false);
-        });
-    });
-    return new Promise((resolve) => {
-        const deadline = Date.now() + timeoutMs;
-        const tick = async () => {
-            if (await probe())
-                return resolve(true);
-            if (Date.now() >= deadline)
-                return resolve(false);
-            setTimeout(() => void tick(), 300);
-        };
-        void tick();
-    });
-}

package/dist/preview/proxy.d.ts

@@ -1,4 +0,0 @@
-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

@@ -1,49 +0,0 @@
-// 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

@@ -1,45 +0,0 @@
-import { type ChildProcess } from "node:child_process";
-export interface StartPreviewOptions {
-    /** Project directory — its .vincentt binding + dev script drive the preview. */
-    projectCwd: string;
-    /** App dev-serve port (default 5173). If a server is already listening here, it
-     *  is reused instead of spawning a second one. */
-    appPort?: number;
-    /** Relay port. Default: an OS-assigned free port (returned as relayPort). */
-    relayPort?: number;
-    /** Front-proxy port the tunnel points at. Default: an OS-assigned free port. */
-    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;
-    /** 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;
-     *  a not-yet-ready app still returns (appReady=false), it isn't an error. */
-    appReadyTimeoutMs?: 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 (may be OS-assigned). */
-    relayPort: number;
-    /** The app dev-serve port the tunnel ultimately serves. */
-    appPort: 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. */
-    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

@@ -1,110 +0,0 @@
-// 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";
-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;
-    // 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.
-    const appPort = opts.appPort ?? 5173;
-    const relayPort = opts.relayPort ?? (await getFreePort());
-    const frontPort = opts.frontPort ?? (await getFreePort());
-    // If a dev server is already up on appPort, reuse it — don't spawn a second one
-    // that would fail to bind and leave the tunnel serving a broken origin.
-    const reuseApp = await isPortListening(appPort);
-    // 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 });
-        if (reuseApp) {
-            onLog(`reusing the dev server already on :${appPort}`);
-        }
-        else {
-            app = spawn(devCommand[0], devCommand.slice(1), {
-                cwd: projectCwd,
-                env: { ...process.env, PORT: String(appPort) },
-                stdio: appStdio,
-                // Windows: npm/pnpm are .cmd shims — spawn needs a shell to resolve them.
-                shell: process.platform === "win32",
-            });
-        }
-        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);
-        // 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 };
-    }
-    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

@@ -1,14 +0,0 @@
-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

@@ -1,28 +0,0 @@
-// 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/dist/relay/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/relay/cli.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-// `harness-relay` — start the diagnostics relay beside Vite. The preview loop
-// spawns this (or you run it directly). Prints a line the tunnel step can read.
-import { startRelay } from "./server.js";
-const portArg = process.argv.indexOf("--port");
-const port = portArg !== -1 ? Number(process.argv[portArg + 1]) : 7331;
-startRelay({ port, onLog: (m) => console.log(`[harness-relay] ${m}`) });