@vincentt-xr/harness 0.4.0 → 1.0.0

package/dist/mcp/backend.d.ts

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

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

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

package/dist/mcp/cli.js

@@ -1,10 +0,0 @@
-#!/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

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

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

@@ -1,16 +0,0 @@
-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;
-    /** 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

@@ -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>;