@vincentt-xr/cli 0.1.0

package/dist/lib/lifecycle.d.ts

@@ -0,0 +1,45 @@
+import { type RelayClient } from "./diagnostics.js";
+import { type RunningPreview } from "../preview/index.js";
+import type { DiagEventKind, RelayResult } from "@vincentt-xr/harness/events";
+export interface CreateOptions {
+    name?: string;
+    slug?: string;
+    scaffold?: boolean;
+}
+export interface CreateResult {
+    message: string;
+    alreadyBound: boolean;
+    slug?: string;
+    projectId?: string;
+}
+export declare function projectCreate(projectCwd: string, opts?: CreateOptions): Promise<CreateResult>;
+export interface PublishOptions {
+    distDir?: string;
+    note?: string;
+}
+export interface PublishOutcome {
+    message: string;
+    notBound: boolean;
+    version?: number;
+    liveUrl?: string;
+    url?: string;
+}
+export declare function projectPublish(projectCwd: string, opts?: PublishOptions): Promise<PublishOutcome>;
+export declare function getActivePreview(): RunningPreview | null;
+export interface PreviewStartResult {
+    preview: RunningPreview;
+    /** false when a preview was already running (the existing one is returned). */
+    started: boolean;
+}
+export declare function previewStart(projectCwd: string, onLog: (msg: string) => void): Promise<PreviewStartResult>;
+export declare function previewStop(): Promise<boolean>;
+export interface DiagQueryOptions {
+    sessionId?: string;
+    since?: number;
+    limit?: number;
+    errorsOnly?: boolean;
+}
+/** Raw diagnostics query against the running relay (used by CLI --json). */
+export declare function diagQuery(projectCwd: string, kind: DiagEventKind, opts?: DiagQueryOptions, relay?: RelayClient): Promise<RelayResult>;
+/** Rendered diagnostics text (used by CLI default + MCP tools). */
+export declare function diagRead(projectCwd: string, kind: DiagEventKind, opts?: DiagQueryOptions, relay?: RelayClient, now?: () => number): Promise<string>;

package/dist/lib/lifecycle.js

@@ -0,0 +1,140 @@
+// The dev-loop implementation, shared by the `vincentt` CLI verbs and the MCP
+// adapter so the two surfaces can never diverge. Pure orchestration over the
+// lower-level pieces (backend calls, scaffold, preview, diagnostics); no CLI or
+// MCP SDK concerns leak in here. Both surfaces render the returned data their
+// own way.
+import path from "node:path";
+import { createProject, gitHeadSha, publishUpload } from "./backend.js";
+import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
+import { clearRelayInfo, readRelayInfo, writeRelayInfo } from "./relayInfo.js";
+import { loadProjectBinding, resolveConfig, writeProjectBinding, } from "../shared/config.js";
+import { installDependencies, needsScaffold, scaffoldFromTemplate, } from "../scaffold/index.js";
+import { startPreview } from "../preview/index.js";
+export async function projectCreate(projectCwd, opts = {}) {
+    const existing = await loadProjectBinding(projectCwd);
+    if (existing) {
+        return {
+            message: `This directory is already bound to project ${existing.projectId} (slug ${existing.slug}). Delete .vincentt/project.json to rebind.`,
+            alreadyBound: true,
+            slug: existing.slug,
+            projectId: existing.projectId,
+        };
+    }
+    // Resolve config first so a missing PAT fails before any clone/side effect.
+    const cfg = await resolveConfig(projectCwd);
+    let scaffolded = false;
+    if (opts.scaffold !== false && (await needsScaffold(projectCwd))) {
+        await scaffoldFromTemplate(projectCwd);
+        scaffolded = true;
+    }
+    const created = await createProject(cfg, opts.name ?? path.basename(projectCwd), opts.slug);
+    const bindingPath = await writeProjectBinding(projectCwd, {
+        projectId: created.projectId,
+        slug: created.slug,
+    });
+    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 {
+        message: scaffoldNote +
+            `Created "${created.name}" → slug ${created.slug} (id ${created.projectId}).\n` +
+            `Binding written to ${bindingPath} (gitignored).\n` +
+            `Build locally, then publish to go live at ${created.slug}.vincentt.app.`,
+        alreadyBound: false,
+        slug: created.slug,
+        projectId: created.projectId,
+    };
+}
+export async function projectPublish(projectCwd, opts = {}) {
+    const binding = await loadProjectBinding(projectCwd);
+    if (!binding) {
+        return {
+            message: "No project is bound to this directory. Run `vincentt create` first.",
+            notBound: true,
+        };
+    }
+    const cfg = await resolveConfig(projectCwd);
+    const dist = path.resolve(projectCwd, opts.distDir ?? "dist");
+    const commitSha = await gitHeadSha(projectCwd);
+    const result = await publishUpload(cfg, binding.projectId, dist, {
+        note: opts.note,
+        commitSha,
+    });
+    return {
+        message: `Published v${result.version}. Live at ${result.liveUrl}\nThis version: ${result.url}`,
+        notBound: false,
+        version: result.version,
+        liveUrl: result.liveUrl,
+        url: result.url,
+    };
+}
+// ---- preview (one per process) ----------------------------------------------
+let activePreview = null;
+let activeProjectCwd = null;
+export function getActivePreview() {
+    return activePreview;
+}
+export async function previewStart(projectCwd, onLog) {
+    if (activePreview)
+        return { preview: activePreview, started: false };
+    const preview = await startPreview({ projectCwd, onLog });
+    activePreview = preview;
+    activeProjectCwd = projectCwd;
+    // Record the OS-assigned relay port so a separate `vincentt logs`/`feedback`
+    // invocation can find this preview's relay.
+    await writeRelayInfo(projectCwd, {
+        relayPort: preview.relayPort,
+        url: preview.url,
+        pid: process.pid,
+        harnessPath: "/__harness",
+    });
+    return { preview, started: true };
+}
+export async function previewStop() {
+    if (!activePreview)
+        return false;
+    const preview = activePreview;
+    const cwd = activeProjectCwd;
+    activePreview = null;
+    activeProjectCwd = null;
+    await preview.stop();
+    if (cwd)
+        await clearRelayInfo(cwd);
+    return true;
+}
+/** Resolve the relay client for a project's running preview, or throw a hint. */
+async function relayForProject(projectCwd, override) {
+    if (override)
+        return override;
+    const info = await readRelayInfo(projectCwd);
+    if (!info) {
+        throw new Error("No running preview for this project — run `vincentt preview` first.");
+    }
+    return httpRelayClient(`http://localhost:${info.relayPort}`);
+}
+/** Raw diagnostics query against the running relay (used by CLI --json). */
+export async function diagQuery(projectCwd, kind, opts = {}, relay) {
+    const client = await relayForProject(projectCwd, relay);
+    const q = {
+        kind,
+        sessionId: opts.sessionId,
+        since: opts.since,
+        limit: opts.limit,
+    };
+    const result = await client.query(q);
+    return kind === "log" && opts.errorsOnly ? filterErrors(result) : result;
+}
+/** Rendered diagnostics text (used by CLI default + MCP tools). */
+export async function diagRead(projectCwd, kind, opts = {}, relay, now = Date.now) {
+    const result = await diagQuery(projectCwd, kind, opts, relay);
+    return renderResult(result, kind, now());
+}

package/dist/lib/relayInfo.d.ts

@@ -0,0 +1,14 @@
+export interface RelayInfo {
+    /** The relay's localhost HTTP/WS port (OS-assigned per preview run). */
+    relayPort: number;
+    /** The public preview URL, for display. */
+    url: string;
+    /** The preview process pid, so a stale file can be detected. */
+    pid: number;
+    /** WS/HTTP path prefix routed to the relay (default /__harness). */
+    harnessPath: string;
+}
+export declare function relayInfoPath(cwd: string): string;
+export declare function writeRelayInfo(cwd: string, info: RelayInfo): Promise<string>;
+export declare function readRelayInfo(cwd: string): Promise<RelayInfo | undefined>;
+export declare function clearRelayInfo(cwd: string): Promise<void>;

package/dist/lib/relayInfo.js

@@ -0,0 +1,35 @@
+// A running preview writes its OS-assigned relay port to <project>/.vincentt/relay.json
+// so a SEPARATE CLI invocation (`vincentt logs`, `vincentt feedback --wait`) can
+// find the relay to talk to. Written on preview start, cleared on stop. Lives under
+// the gitignored .vincentt/ dir, so it never rides a commit.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const RELAY_INFO_FILE = "relay.json";
+const VINCENTT_DIR = ".vincentt";
+export function relayInfoPath(cwd) {
+    return path.join(cwd, VINCENTT_DIR, RELAY_INFO_FILE);
+}
+export async function writeRelayInfo(cwd, info) {
+    const p = relayInfoPath(cwd);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, JSON.stringify(info, null, 2) + "\n", "utf8");
+    return p;
+}
+export async function readRelayInfo(cwd) {
+    try {
+        return JSON.parse(await fs.readFile(relayInfoPath(cwd), "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+export async function clearRelayInfo(cwd) {
+    try {
+        await fs.unlink(relayInfoPath(cwd));
+    }
+    catch {
+        // Already gone — clearing a non-existent info file is a no-op.
+    }
+}

package/dist/login/login.d.ts

@@ -0,0 +1,34 @@
+export interface LoginOptions {
+    /** Editor base URL that serves the /oauth consent page. */
+    editorUrl: string;
+    /** Backend API base URL the minted PAT authenticates against (paired with editorUrl). */
+    apiUrl: string;
+    /** Human label stored with the token (shown in the editor's token list). */
+    tokenName: string;
+    /** Abort if the browser round-trip doesn't complete in time. Default 5 min. */
+    timeoutMs?: number;
+    /** Set false to skip launching a browser (tests / headless). Default true. */
+    openInBrowser?: boolean;
+    /** Called with the authorize URL once the listener is up (for a printable fallback). */
+    onUrl?: (url: string) => void;
+}
+/** Prefix a scheme when the user passed a bare host; localhost defaults to http. */
+export declare function normalizeBaseUrl(u: string): string;
+export declare function buildAuthorizeUrl(editorBase: string, redirectUri: string, state: string, tokenName: string): string;
+export type CallbackResult = {
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** Interpret the editor's loopback redirect. State is verified first, always. */
+export declare function parseCallback(params: URLSearchParams, expectedState: string): CallbackResult;
+/**
+ * Run the loopback OAuth round-trip and persist the resulting PAT. Resolves with
+ * the apiUrl written to config; rejects on cancel, state mismatch, or timeout.
+ */
+export declare function runLogin(opts: LoginOptions): Promise<{
+    apiUrl: string;
+    configPath: string;
+}>;

package/dist/login/login.js

@@ -0,0 +1,148 @@
+// `harness login` — obtain a Personal Access Token via the editor's /oauth flow.
+//
+// The CLI can't mint a PAT directly (POST /access-tokens is Cognito-only, so a
+// machine token can never mint another). Instead it delegates to the editor:
+//   1. Start a loopback HTTP listener on 127.0.0.1:<ephemeral port>.
+//   2. Open the browser to <editor>/oauth?redirect_uri=…&state=…&name=… — the
+//      editor reuses its own passwordless login + a consent screen and mints the
+//      PAT on the user's behalf.
+//   3. The editor redirects ?token=<vpat_…>&state=… back to the loopback.
+//   4. Verify state, write the PAT to ~/.vincentt/config.json.
+// The PAT crosses only over loopback on the user's own machine.
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { getFreePort } from "../preview/net.js";
+import { writeMachineConfig } from "../shared/config.js";
+/** Prefix a scheme when the user passed a bare host; localhost defaults to http. */
+export function normalizeBaseUrl(u) {
+    if (/^https?:\/\//i.test(u))
+        return u;
+    const local = /^(localhost|127\.0\.0\.1)(:|\/|$)/i.test(u);
+    return `${local ? "http" : "https"}://${u}`;
+}
+export function buildAuthorizeUrl(editorBase, redirectUri, state, tokenName) {
+    const u = new URL("/oauth", normalizeBaseUrl(editorBase));
+    u.searchParams.set("redirect_uri", redirectUri);
+    u.searchParams.set("state", state);
+    u.searchParams.set("name", tokenName);
+    return u.toString();
+}
+/** Interpret the editor's loopback redirect. State is verified first, always. */
+export function parseCallback(params, expectedState) {
+    if (params.get("state") !== expectedState) {
+        return { ok: false, message: "State mismatch — ignoring an unexpected callback." };
+    }
+    const error = params.get("error");
+    if (error) {
+        return {
+            ok: false,
+            message: error === "access_denied" ? "Authorization was cancelled." : `Authorization failed: ${error}`,
+        };
+    }
+    const token = params.get("token");
+    if (!token)
+        return { ok: false, message: "No token in the authorization response." };
+    return { ok: true, token };
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+// Standalone success/failure page shown in the browser tab after the loopback
+// round-trip. Fully self-contained (inline CSS, no assets) since it's served off
+// the CLI's own listener; theme-aware to match the editor's sand/ink palette.
+function browserPage(ok, heading, body) {
+    const accent = ok ? "#16a34a" : "#dc2626";
+    const glyph = ok ? "&check;" : "&times;";
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>Vincentt XR</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body { margin:0; min-height:100vh; display:flex; align-items:center; justify-content:center;
+    font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
+    background:#f4efe6; color:#1c1917; }
+  .card { width:min(92vw,380px); background:#fff; border:1px solid #e7e0d3; border-radius:16px;
+    padding:40px 36px; text-align:center; box-shadow:0 10px 40px rgba(0,0,0,.08); }
+  .brand { display:flex; align-items:center; justify-content:center; gap:8px; margin-bottom:26px;
+    font-weight:700; font-size:15px; letter-spacing:-.01em; }
+  .dot { width:26px; height:26px; border-radius:8px; background:linear-gradient(135deg,#7c3aed,#2563eb); }
+  .glyph { width:48px; height:48px; margin:0 auto 16px; border-radius:50%; color:#fff;
+    display:flex; align-items:center; justify-content:center; font-size:26px; line-height:1; background:${accent}; }
+  h1 { font-size:19px; margin:0 0 6px; }
+  p { font-size:13px; opacity:.7; margin:0; line-height:1.5; }
+  @media (prefers-color-scheme: dark) {
+    body { background:#1c1917; color:#f4efe6; }
+    .card { background:#292524; border-color:#3f3a36; }
+  }
+</style></head>
+<body><div class="card">
+  <div class="brand"><span class="dot"></span>Vincentt XR</div>
+  <div class="glyph">${glyph}</div>
+  <h1>${escapeHtml(heading)}</h1>
+  <p>${escapeHtml(body)}</p>
+</div></body></html>`;
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // Falls back to the printed URL (onUrl) — never fatal.
+    }
+}
+/**
+ * Run the loopback OAuth round-trip and persist the resulting PAT. Resolves with
+ * the apiUrl written to config; rejects on cancel, state mismatch, or timeout.
+ */
+export async function runLogin(opts) {
+    const state = randomBytes(16).toString("hex");
+    const port = await getFreePort();
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const authorizeUrl = buildAuthorizeUrl(opts.editorUrl, redirectUri, state, opts.tokenName);
+    const token = await new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("Not found");
+                return;
+            }
+            const result = parseCallback(url.searchParams, state);
+            res.writeHead(result.ok ? 200 : 400, { "content-type": "text/html; charset=utf-8" });
+            res.end(result.ok
+                ? browserPage(true, "You're signed in", "You can close this tab and return to your terminal.")
+                : browserPage(false, "Sign-in failed", result.message));
+            // A state-mismatch response is answered but must NOT settle the flow — a
+            // stray/forged request shouldn't tear down the listener the real callback
+            // still needs.
+            if (result.ok) {
+                server.close();
+                resolve(result.token);
+            }
+            else if (url.searchParams.get("state") === state) {
+                server.close();
+                reject(new Error(result.message));
+            }
+        });
+        server.on("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            opts.onUrl?.(authorizeUrl);
+            if (opts.openInBrowser !== false)
+                openBrowser(authorizeUrl);
+        });
+        const timer = setTimeout(() => {
+            server.close();
+            reject(new Error("Timed out waiting for browser authorization."));
+        }, opts.timeoutMs ?? 5 * 60_000);
+        timer.unref();
+    });
+    const apiUrl = opts.apiUrl.replace(/\/$/, "");
+    const configPath = await writeMachineConfig({ apiUrl, pat: token });
+    return { apiUrl, configPath };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,16 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type RelayClient } from "../lib/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;
+}
+/** Reap the running preview, if any. Called by preview_stop and on server exit. */
+export declare function shutdownActivePreview(): Promise<void>;
+export declare function createHarnessMcp(opts?: McpOptions): McpServer;
+export declare function runStdio(opts?: McpOptions): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,188 @@
+// The agent-agnostic MCP server: a THIN adapter over the shared dev-loop lib
+// (../lib/lifecycle). Any MCP-capable agent (Claude Code, Codex, Cursor, Cline,
+// …) points its MCP config at `vincentt mcp` and gets the same verbs the CLI
+// exposes — diagnostics PULL tools plus the create/publish/preview lifecycle.
+// This file is only SDK wiring + argument shapes; all behavior lives in the lib,
+// so the CLI and MCP surfaces can never diverge.
+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 { httpRelayClient } from "../lib/diagnostics.js";
+import { diagRead, getActivePreview, previewStart, previewStop, projectCreate, projectPublish, } from "../lib/lifecycle.js";
+/** 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 };
+    }
+}
+/** Reap the running preview, if any. Called by preview_stop and on server exit. */
+export async function shutdownActivePreview() {
+    await previewStop();
+}
+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 = {}) {
+    // Diag tools read through this explicit client so the MCP server stays
+    // self-contained (works against a standalone relay without a relay.json file).
+    // preview_start re-points it at the live preview's relay port (OS-assigned).
+    let relayClient = opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
+    const now = opts.now ?? Date.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.
+    const baseProjectDir = opts.cwd ?? process.env.VINCENTT_PROJECT_DIR ?? process.cwd();
+    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 }) => ({
+        content: [
+            {
+                type: "text",
+                text: await diagRead(baseProjectDir, "log", { sessionId, since, limit, errorsOnly }, relayClient, 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 }) => ({
+        content: [
+            {
+                type: "text",
+                text: await diagRead(baseProjectDir, "network", { sessionId, since, limit }, relayClient, 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 }) => ({
+        content: [
+            {
+                type: "text",
+                text: await diagRead(baseProjectDir, "trace", { sessionId, since, limit }, relayClient, now),
+            },
+        ],
+    }));
+    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 result = await projectCreate(resolveProjectDir(baseProjectDir, projectDir), {
+            name,
+            slug,
+            scaffold,
+        });
+        return result.message;
+    }));
+    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 result = await projectPublish(resolveProjectDir(baseProjectDir, projectDir), {
+            distDir,
+            note,
+        });
+        return result.message;
+    }));
+    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 (getActivePreview()) {
+            return `A preview is already running:\n${getActivePreview().url}\nCall preview_stop first to restart.`;
+        }
+        // App stdout would corrupt the MCP channel; route harness progress to stderr.
+        const { preview } = await previewStart(resolveProjectDir(baseProjectDir, projectDir), (m) => console.error(`[preview] ${m}`));
+        // Point the diag tools at this preview's relay (its port is OS-assigned).
+        relayClient = httpRelayClient(`http://localhost:${preview.relayPort}`);
+        const readiness = preview.appReady
+            ? ""
+            : `\nNote: the app on :${preview.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${preview.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 () => {
+        const stopped = await previewStop();
+        if (!stopped)
+            return "No preview is running.";
+        // The preview's relay is gone; send diag reads back to the default.
+        relayClient = opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
+        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("[vincentt 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>;