@vincentt-xr/harness 0.1.0

package/dist/client/trace.d.ts

@@ -0,0 +1,31 @@
+import type { TraceEvent } from "../shared/events.js";
+/**
+ * Pure accumulator: feed it frame timestamps, long-task durations, and marks;
+ * ask it to summarize a window. No timers, no DOM — the sampler drives it.
+ */
+export declare class TraceAccumulator {
+    private frameTimes;
+    private longestTask;
+    private longTasks;
+    private marks;
+    private windowStart;
+    /** Record a frame boundary (a rAF callback time, ms). */
+    frame(t: number): void;
+    /** Record a completed task's duration (ms). Only long ones matter. */
+    task(durationMs: number): void;
+    /** Record a performance.mark name seen in this window. */
+    mark(name: string): void;
+    /** Whether enough has accumulated to be worth emitting. */
+    hasSamples(): boolean;
+    /**
+     * Summarize and RESET for the next window. `now` closes the window. seq/t are
+     * supplied by the caller (the buffer stamps them).
+     */
+    summarize(now: number, seq: number): TraceEvent;
+    private reset;
+}
+/**
+ * Frames-per-second from a list of frame timestamps: (frames - 1) intervals
+ * over the elapsed span. Fewer than two frames → 0 (can't measure a rate).
+ */
+export declare function computeFps(frameTimes: number[]): number;

package/dist/client/trace.js

@@ -0,0 +1,87 @@
+// The performance-tracing tier. An in-app sampler accumulates cheap perf
+// signals — frame intervals (→ fps), long tasks, and performance.mark names —
+// over a rolling window and emits one TraceEvent per window. This is the tier
+// that replaces hand-exporting a DevTools .json.gz to spot jank.
+//
+// The aggregation is a pure reducer (TraceAccumulator) so it is unit-testable;
+// the imperative sampler (rAF loop + PerformanceObserver) is a thin shell that
+// feeds it and is installed by instrument.ts.
+const LONG_TASK_MS = 50; // the standard "long task" threshold
+/**
+ * Pure accumulator: feed it frame timestamps, long-task durations, and marks;
+ * ask it to summarize a window. No timers, no DOM — the sampler drives it.
+ */
+export class TraceAccumulator {
+    frameTimes = [];
+    longestTask = 0;
+    longTasks = 0;
+    marks = [];
+    windowStart = null;
+    /** Record a frame boundary (a rAF callback time, ms). */
+    frame(t) {
+        if (this.windowStart === null)
+            this.windowStart = t;
+        this.frameTimes.push(t);
+    }
+    /** Record a completed task's duration (ms). Only long ones matter. */
+    task(durationMs) {
+        if (durationMs >= LONG_TASK_MS) {
+            this.longTasks += 1;
+            if (durationMs > this.longestTask)
+                this.longestTask = durationMs;
+        }
+    }
+    /** Record a performance.mark name seen in this window. */
+    mark(name) {
+        if (!this.marks.includes(name))
+            this.marks.push(name);
+    }
+    /** Whether enough has accumulated to be worth emitting. */
+    hasSamples() {
+        return this.frameTimes.length > 1 || this.longTasks > 0 || this.marks.length > 0;
+    }
+    /**
+     * Summarize and RESET for the next window. `now` closes the window. seq/t are
+     * supplied by the caller (the buffer stamps them).
+     */
+    summarize(now, seq) {
+        const start = this.windowStart ?? now;
+        const windowMs = Math.max(1, Math.round(now - start));
+        const fps = computeFps(this.frameTimes);
+        const event = {
+            kind: "trace",
+            windowMs,
+            fps: round1(fps),
+            longestTaskMs: Math.round(this.longestTask),
+            longTaskCount: this.longTasks,
+            marks: [...this.marks],
+            seq,
+            t: now,
+        };
+        this.reset();
+        return event;
+    }
+    reset() {
+        this.frameTimes = [];
+        this.longestTask = 0;
+        this.longTasks = 0;
+        this.marks = [];
+        this.windowStart = null;
+    }
+}
+/**
+ * Frames-per-second from a list of frame timestamps: (frames - 1) intervals
+ * over the elapsed span. Fewer than two frames → 0 (can't measure a rate).
+ */
+export function computeFps(frameTimes) {
+    if (frameTimes.length < 2)
+        return 0;
+    const span = frameTimes[frameTimes.length - 1] - frameTimes[0];
+    if (span <= 0)
+        return 0;
+    const intervals = frameTimes.length - 1;
+    return (intervals * 1000) / span;
+}
+function round1(n) {
+    return Math.round(n * 10) / 10;
+}

package/dist/mcp/backend.d.ts

@@ -0,0 +1,52 @@
+import type { ResolvedConfig } from "../shared/config.js";
+export interface CreatedProject {
+    projectId: string;
+    slug: string;
+    name: string;
+}
+export interface PublishResult {
+    version: number;
+    /** Immutable versioned URL (<slug>.<apex>/v<n>/). */
+    url: string;
+    /** Stable live alias (<slug>.<apex>/). */
+    liveUrl: string;
+}
+export declare class BackendError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * Create a backend project (reuses POST /projects). A `slug` pins the permanent
+ * <slug>.vincentt.app host; omit it and the platform assigns a catchy one. A
+ * taken slug comes back 409, surfaced so the caller can re-ask.
+ */
+export declare function createProject(cfg: ResolvedConfig, name: string, slug?: string): Promise<CreatedProject>;
+export interface MintedTunnel {
+    tunnelId: string;
+    /** The public host the phone opens: <slug>-<token>.<previewApex>. */
+    hostname: string;
+    /** cloudflared run token — `cloudflared tunnel run --token <this>`. */
+    runToken: string;
+    /** DNS record id, passed back on reap. */
+    dnsRecordId: string;
+}
+/** Mint a per-session dev tunnel for `localPort` (the backend holds CF creds). */
+export declare function mintTunnel(cfg: ResolvedConfig, projectId: string, localPort: number): Promise<MintedTunnel>;
+/** Tear down a session tunnel (DNS route + tunnel). Best-effort; never throws. */
+export declare function reapTunnel(cfg: ResolvedConfig, projectId: string, ref: {
+    tunnelId: string;
+    dnsRecordId?: string;
+}): Promise<void>;
+/** Recursively list files under `dir`, returning dir-relative POSIX paths. */
+export declare function walkDir(dir: string, base?: string): Promise<string[]>;
+/**
+ * Upload a locally-built dist and make it live. Each file rides as a multipart
+ * part whose filename is its dist-relative path (the backend reconstructs the
+ * tree). Requires an index.html at the dist root.
+ */
+export declare function publishUpload(cfg: ResolvedConfig, projectId: string, distDir: string, opts?: {
+    note?: string;
+    commitSha?: string;
+}): Promise<PublishResult>;
+/** The working tree's current commit, for publish provenance. Undefined if not a repo. */
+export declare function gitHeadSha(cwd: string): Promise<string | undefined>;

package/dist/mcp/backend.js

@@ -0,0 +1,146 @@
+// The lifecycle verbs' backend calls, isolated from the MCP SDK wiring (server.ts)
+// so they're unit-testable and the transport can change without touching them.
+// Every call is PAT-authed (Bearer). The publish path uploads an already-built
+// dist as-is — the backend never rebuilds (Principle 0).
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export class BackendError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "BackendError";
+    }
+}
+async function authFetch(cfg, pathname, init = {}) {
+    return fetch(`${cfg.apiUrl}${pathname}`, {
+        ...init,
+        headers: { ...(init.headers ?? {}), authorization: `Bearer ${cfg.pat}` },
+    });
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Create a backend project (reuses POST /projects). A `slug` pins the permanent
+ * <slug>.vincentt.app host; omit it and the platform assigns a catchy one. A
+ * taken slug comes back 409, surfaced so the caller can re-ask.
+ */
+export async function createProject(cfg, name, slug) {
+    const res = await authFetch(cfg, "/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ name, ...(slug ? { slug } : {}) }),
+    });
+    if (res.status === 409) {
+        throw new BackendError(`slug "${slug}" is already in use — pick another.`, 409);
+    }
+    if (!res.ok) {
+        throw new BackendError(`create project failed (${res.status}): ${await safeText(res)}`, res.status);
+    }
+    const p = (await res.json());
+    const projectId = p._id ?? p.id;
+    if (!projectId || !p.slug) {
+        throw new BackendError("create project: response missing id/slug");
+    }
+    return { projectId, slug: p.slug, name: p.name ?? name };
+}
+/** Mint a per-session dev tunnel for `localPort` (the backend holds CF creds). */
+export async function mintTunnel(cfg, projectId, localPort) {
+    const res = await authFetch(cfg, `/projects/${projectId}/tunnel`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ port: localPort }),
+    });
+    if (!res.ok) {
+        throw new BackendError(`tunnel mint failed (${res.status}): ${await safeText(res)}`, res.status);
+    }
+    return (await res.json());
+}
+/** Tear down a session tunnel (DNS route + tunnel). Best-effort; never throws. */
+export async function reapTunnel(cfg, projectId, ref) {
+    try {
+        await authFetch(cfg, `/projects/${projectId}/tunnel/reap`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(ref),
+        });
+    }
+    catch {
+        // Reap is a cleanup courtesy — a failure must never crash the preview teardown.
+    }
+}
+/** Recursively list files under `dir`, returning dir-relative POSIX paths. */
+export async function walkDir(dir, base = dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new BackendError(`dist directory not found: ${dir}`);
+        }
+        throw err;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walkDir(full, base)));
+        else if (entry.isFile())
+            out.push(path.relative(base, full).split(path.sep).join("/"));
+    }
+    return out;
+}
+/**
+ * Upload a locally-built dist and make it live. Each file rides as a multipart
+ * part whose filename is its dist-relative path (the backend reconstructs the
+ * tree). Requires an index.html at the dist root.
+ */
+export async function publishUpload(cfg, projectId, distDir, opts = {}) {
+    const files = await walkDir(distDir);
+    if (!files.includes("index.html")) {
+        throw new BackendError(`dist at ${distDir} has no index.html at its root — did the build run?`);
+    }
+    const form = new FormData();
+    // The real dist-relative paths ride as an ordered manifest — a multipart filename
+    // can't carry a directory (FormData strips it to a basename), so the backend maps
+    // paths[i] → files[i] to rebuild the tree.
+    form.append("paths", JSON.stringify(files));
+    for (const rel of files) {
+        const bytes = await fs.readFile(path.join(distDir, rel));
+        // Uint8Array (Buffer) is a valid BlobPart; the filename is cosmetic (the backend
+        // uses the manifest), but pass the basename so server logs read sensibly.
+        form.append("files", new Blob([bytes]), path.basename(rel));
+    }
+    if (opts.note)
+        form.append("note", opts.note);
+    if (opts.commitSha)
+        form.append("commitSha", opts.commitSha);
+    const res = await authFetch(cfg, `/projects/${projectId}/publish/upload`, {
+        method: "POST",
+        body: form,
+    });
+    if (!res.ok) {
+        throw new BackendError(`publish failed (${res.status}): ${await safeText(res)}`, res.status);
+    }
+    return (await res.json());
+}
+/** The working tree's current commit, for publish provenance. Undefined if not a repo. */
+export async function gitHeadSha(cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", cwd, "rev-parse", "HEAD"]);
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/mcp/cli.d.ts

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

package/dist/mcp/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// `harness-mcp` — the agent-side MCP server. An MCP agent spawns this over
+// stdio. Point it at a non-default relay with --relay-url.
+import { runStdio } from "./server.js";
+const urlArg = process.argv.indexOf("--relay-url");
+const relayUrl = urlArg !== -1 ? process.argv[urlArg + 1] : undefined;
+runStdio({ relayUrl }).catch((err) => {
+    console.error("[harness-mcp] fatal:", err);
+    process.exit(1);
+});

package/dist/mcp/diagnostics.d.ts

@@ -0,0 +1,13 @@
+import type { DiagEvent, LogEvent, NetworkEvent, RelayQuery, RelayResult, TraceEvent } from "../shared/events.js";
+export interface RelayClient {
+    query(q: RelayQuery): Promise<RelayResult>;
+}
+/** A RelayClient backed by the relay's HTTP /query endpoint. */
+export declare function httpRelayClient(baseUrl: string): RelayClient;
+export declare function formatLog(e: LogEvent, now: number): string;
+export declare function formatNetwork(e: NetworkEvent, now: number): string;
+export declare function formatTrace(e: TraceEvent, now: number): string;
+/** Render a RelayResult for one kind into the text block a tool returns. */
+export declare function renderResult(result: RelayResult, kind: DiagEvent["kind"], now: number): string;
+/** Only-errors convenience filter applied on top of a log query result. */
+export declare function filterErrors(result: RelayResult): RelayResult;

package/dist/mcp/diagnostics.js

@@ -0,0 +1,61 @@
+// The MCP server's logic, independent of the MCP SDK surface: fetch events from
+// the relay and format them into the compact text an agent reads. Kept separate
+// from the SDK wiring (server.ts) so the formatting is unit-testable and the SDK
+// version can churn without touching this.
+/** A RelayClient backed by the relay's HTTP /query endpoint. */
+export function httpRelayClient(baseUrl) {
+    return {
+        async query(q) {
+            const res = await fetch(`${baseUrl}/query`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(q),
+            });
+            if (!res.ok)
+                throw new Error(`relay /query returned ${res.status}`);
+            return (await res.json());
+        },
+    };
+}
+/** Human-time from the client timestamp, relative to now, for the agent's read. */
+function ago(t, now) {
+    const s = Math.max(0, Math.round((now - t) / 1000));
+    return s < 60 ? `${s}s ago` : `${Math.round(s / 60)}m ago`;
+}
+export function formatLog(e, now) {
+    const level = e.level.toUpperCase().padEnd(5);
+    const origin = e.origin ? `  (${e.origin})` : "";
+    return `[${level}] ${e.message}${origin}  · ${ago(e.t, now)} #${e.seq}`;
+}
+export function formatNetwork(e, now) {
+    const status = e.error ? `ERR ${e.error}` : String(e.status);
+    return `${e.method} ${e.url} → ${status} (${e.durationMs}ms)  · ${ago(e.t, now)} #${e.seq}`;
+}
+export function formatTrace(e, now) {
+    const marks = e.marks.length ? `  marks: ${e.marks.join(", ")}` : "";
+    return (`${e.fps.toFixed(0)}fps over ${e.windowMs}ms · longest task ${e.longestTaskMs}ms · ` +
+        `${e.longTaskCount} long task(s)${marks}  · ${ago(e.t, now)} #${e.seq}`);
+}
+/** Render a RelayResult for one kind into the text block a tool returns. */
+export function renderResult(result, kind, now) {
+    const lines = result.events.map((e) => {
+        if (e.kind === "log")
+            return formatLog(e, now);
+        if (e.kind === "network")
+            return formatNetwork(e, now);
+        return formatTrace(e, now);
+    });
+    const header = result.sessions.length > 1 ? `sessions: ${result.sessions.join(", ")}\n` : "";
+    const cursor = `\n\n(latestSeq ${result.latestSeq} — pass since=${result.latestSeq} to get only newer ${kind} events)`;
+    if (lines.length === 0) {
+        return `${header}No ${kind} events${result.latestSeq >= 0 ? " matched" : " yet — is the preview app open on the device?"}.${result.latestSeq >= 0 ? cursor : ""}`;
+    }
+    return `${header}${lines.join("\n")}${cursor}`;
+}
+/** Only-errors convenience filter applied on top of a log query result. */
+export function filterErrors(result) {
+    return {
+        ...result,
+        events: result.events.filter((e) => e.kind === "log" && e.level === "error"),
+    };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type RelayClient } from "./diagnostics.js";
+export interface McpOptions {
+    /** Base URL of the relay's HTTP endpoint (default matches the relay CLI). */
+    relayUrl?: string;
+    /** Injected for tests; defaults to an HTTP client against relayUrl. */
+    relay?: RelayClient;
+    /** Injected clock for deterministic relative-time rendering in tests. */
+    now?: () => number;
+    /** Project directory for the lifecycle verbs' binding. Defaults to process.cwd(). */
+    cwd?: string;
+}
+export declare function createHarnessMcp(opts?: McpOptions): McpServer;
+export declare function runStdio(opts?: McpOptions): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,140 @@
+// 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 { needsScaffold, scaffoldFromTemplate } from "../scaffold/index.js";
+/** 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 relay = opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
+    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 relay.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 relay.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 relay.query({ kind: "trace", sessionId, since, limit });
+        return { content: [{ type: "text", text: renderResult(result, "trace", now()) }] };
+    });
+    // The cwd the agent spawned this server in IS the creator's project directory —
+    // where the .vincentt/project.json binding is read and written.
+    const projectCwd = opts.cwd ?? 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."),
+        },
+    }, async ({ name, slug, scaffold }) => guard(async () => {
+        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,
+        });
+        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.`);
+    }));
+    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."),
+        },
+    }, async ({ distDir, note }) => guard(async () => {
+        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}`;
+    }));
+    return server;
+}
+export async function runStdio(opts = {}) {
+    const server = createHarnessMcp(opts);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the MCP channel — status goes to stderr only.
+    console.error("[harness-mcp] connected over stdio");
+}

package/dist/preview/cloudflared.d.ts

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

@@ -0,0 +1,37 @@
+// 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 });
+    await cloudflared.install(cloudflared.bin);
+    log(`cloudflared ready at ${cloudflared.bin}`);
+    return cloudflared.bin;
+}

package/dist/preview/index.d.ts

@@ -0,0 +1,15 @@
+import { type MintedTunnel } from "../mcp/backend.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>;

package/dist/preview/index.js

@@ -0,0 +1,30 @@
+// 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";
+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,
+        }),
+    };
+}