@vincentt-xr/harness 0.2.0 → 0.4.0

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// `harness` — top-level CLI. Today it dispatches a single subcommand, `login`,
+// which obtains a Personal Access Token through the editor's /oauth flow and
+// writes it to ~/.vincentt/config.json (the MCP verbs then read it).
+import os from "node:os";
+import { runLogin } from "../login/login.js";
+const DEFAULT_EDITOR_URL = "https://editor.vincentt.studio";
+const DEFAULT_API_URL = "https://api.vincentt.studio";
+function flag(name) {
+    const i = process.argv.indexOf(name);
+    return i !== -1 ? process.argv[i + 1] : undefined;
+}
+function usage() {
+    console.log(`Usage: harness login [options]\n\n` +
+        `  Sign in and save a Vincentt access token to ~/.vincentt/config.json.\n\n` +
+        `Options:\n` +
+        `  --editor <url>  Editor base URL (default ${DEFAULT_EDITOR_URL}, or $VINCENTT_EDITOR_URL)\n` +
+        `  --api <url>     Backend API base URL (default ${DEFAULT_API_URL}, or $VINCENTT_API_URL)\n` +
+        `  --name <label>  Token label shown in the editor (default "Harness CLI (<host>)")\n`);
+}
+async function login() {
+    const editorUrl = flag("--editor") ?? process.env.VINCENTT_EDITOR_URL ?? DEFAULT_EDITOR_URL;
+    const apiUrl = flag("--api") ?? process.env.VINCENTT_API_URL ?? DEFAULT_API_URL;
+    const tokenName = flag("--name") ?? `Harness CLI (${os.hostname()})`;
+    console.log("Opening your browser to authorize this device…");
+    const { apiUrl: saved, configPath } = await runLogin({
+        editorUrl,
+        apiUrl,
+        tokenName,
+        onUrl: (url) => console.log(`\nIf your browser didn't open, visit:\n  ${url}\n`),
+    });
+    console.log(`\n✓ Signed in. Access token saved to ${configPath}`);
+    console.log(`  API: ${saved}`);
+}
+async function main() {
+    const cmd = process.argv[2];
+    switch (cmd) {
+        case "login":
+            await login();
+            break;
+        case undefined:
+        case "-h":
+        case "--help":
+            usage();
+            break;
+        default:
+            console.error(`Unknown command: ${cmd}\n`);
+            usage();
+            process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    console.error(`\n✗ ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

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.js

@@ -10,7 +10,7 @@ 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";
+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.
@@ -23,6 +23,17 @@ export async function shutdownActivePreview() {
     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 {
@@ -48,7 +59,10 @@ const sharedInput = {
         .describe("Cap the number of events returned (newest kept)."),
 };
 export function createHarnessMcp(opts = {}) {
-    const relay = opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
+    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", {
@@ -59,7 +73,7 @@ export function createHarnessMcp(opts = {}) {
         },
     }, async ({ sessionId, since, limit, errorsOnly }) => {
         const q = { kind: "log", sessionId, since, limit };
-        let result = await relay.query(q);
+        let result = await relayClient.query(q);
         if (errorsOnly)
             result = filterErrors(result);
         return { content: [{ type: "text", text: renderResult(result, "log", now()) }] };
@@ -68,7 +82,12 @@ export function createHarnessMcp(opts = {}) {
         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 });
+        const result = await relayClient.query({
+            kind: "network",
+            sessionId,
+            since,
+            limit,
+        });
         return {
             content: [{ type: "text", text: renderResult(result, "network", now()) }],
         };
@@ -77,12 +96,15 @@ export function createHarnessMcp(opts = {}) {
         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 });
+        const result = await relayClient.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();
+    // 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: {
@@ -98,8 +120,10 @@ export function createHarnessMcp(opts = {}) {
                 .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 }) => guard(async () => {
+    }, 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.`;
@@ -116,9 +140,21 @@ export function createHarnessMcp(opts = {}) {
             projectId: created.projectId,
             slug: created.slug,
         });
-        return ((scaffolded
-            ? "Scaffolded the v2-template starter into this directory.\n"
-            : "") +
+        // 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.`);
@@ -134,8 +170,10 @@ export function createHarnessMcp(opts = {}) {
                 .string()
                 .optional()
                 .describe("Optional release note recorded with the version."),
+            ...projectDirInput,
         },
-    }, async ({ distDir, note }) => guard(async () => {
+    }, 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.";
@@ -151,20 +189,25 @@ export function createHarnessMcp(opts = {}) {
     }));
     server.registerTool("preview_start", {
         description: "Start a live on-device preview: serves the app, opens a public https tunnel, and wires the diagnostics relay so diag_logs/diag_network/diag_trace read from the connected device. Returns the URL to open on a phone. Requires a project_create binding; cloudflared is auto-provisioned if missing. One preview at a time — call preview_stop before starting another. The dev server keeps running until preview_stop, so start it once and iterate.",
-        inputSchema: {},
-    }, async () => guard(async () => {
+        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,
+            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.`);
+            `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.",
@@ -173,6 +216,8 @@ export function createHarnessMcp(opts = {}) {
         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;

package/dist/preview/cloudflared.js

@@ -31,7 +31,16 @@ export async function ensureCloudflared(opts = {}) {
     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);
+    // 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/net.d.ts

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

package/dist/preview/net.js

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

package/dist/preview/runner.d.ts

@@ -2,11 +2,12 @@ import { type ChildProcess } from "node:child_process";
 export interface StartPreviewOptions {
     /** Project directory — its .vincentt binding + dev script drive the preview. */
     projectCwd: string;
-    /** Internal port for the app dev serve (default 5173). */
+    /** App dev-serve port (default 5173). If a server is already listening here, it
+     *  is reused instead of spawning a second one. */
     appPort?: number;
-    /** Relay port; must match the MCP server's relay client (default 7331). */
+    /** Relay port. Default: an OS-assigned free port (returned as relayPort). */
     relayPort?: number;
-    /** Port the tunnel points at — the front proxy origin (default 5190). */
+    /** Front-proxy port the tunnel points at. Default: an OS-assigned free port. */
     frontPort?: number;
     /** Path routed to the relay instead of the app (default /__harness). */
     harnessPath?: string;
@@ -17,14 +18,22 @@ export interface StartPreviewOptions {
     appStdio?: "ignore" | "inherit";
     /** How long to wait for cloudflared to register before giving up (default 45s). */
     registerTimeoutMs?: number;
+    /** How long to wait for the app to serve before returning anyway (default 8s).
+     *  Kept short so an MCP tool call stays within strict clients' ~30s timeout;
+     *  a not-yet-ready app still returns (appReady=false), it isn't an error. */
+    appReadyTimeoutMs?: number;
     /** Progress sink (relay/cloudflared lines). Never write app stdout to MCP stdout. */
     onLog?: (message: string) => void;
 }
 export interface RunningPreview {
     /** Public https URL to open on the device. */
     url: string;
-    /** Relay port the diag_* tools query. */
+    /** Relay port the diag_* tools query (may be OS-assigned). */
     relayPort: number;
+    /** The app dev-serve port the tunnel ultimately serves. */
+    appPort: number;
+    /** Whether the app was responding when we returned (false = URL may be blank). */
+    appReady: boolean;
     /** Tear down tunnel (+ DNS route), app dev serve, front proxy, and relay. */
     stop: () => Promise<void>;
 }

package/dist/preview/runner.js

@@ -14,8 +14,18 @@ import { startRelay } from "../relay/server.js";
 import { ensureCloudflared } from "./cloudflared.js";
 import { startSessionTunnel } from "./tunnel.js";
 import { proxyWeb, proxyWs } from "./proxy.js";
+import { getFreePort, isPortListening, waitForApp } from "./net.js";
 export async function startPreview(opts) {
-    const { projectCwd, appPort = 5173, relayPort = 7331, frontPort = 5190, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", registerTimeoutMs = 45_000, onLog = () => undefined, } = opts;
+    const { projectCwd, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", registerTimeoutMs = 45_000, appReadyTimeoutMs = 8_000, onLog = () => undefined, } = opts;
+    // Resolve ports. The app port defaults to 5173; the relay + front ports are
+    // harness-internal, so auto-pick free ones (the relay port is returned for the
+    // MCP diag_* tools to point at) instead of colliding on fixed defaults.
+    const appPort = opts.appPort ?? 5173;
+    const relayPort = opts.relayPort ?? (await getFreePort());
+    const frontPort = opts.frontPort ?? (await getFreePort());
+    // If a dev server is already up on appPort, reuse it — don't spawn a second one
+    // that would fail to bind and leave the tunnel serving a broken origin.
+    const reuseApp = await isPortListening(appPort);
     // Track every resource so any failure below can unwind exactly what started.
     let app;
     let relay;
@@ -35,11 +45,18 @@ export async function startPreview(opts) {
         // Resolve cloudflared up front so a fresh host provisions it before we mint a
         // tunnel we couldn't otherwise run.
         const cloudflaredBin = await ensureCloudflared({ onLog });
-        app = spawn(devCommand[0], devCommand.slice(1), {
-            cwd: projectCwd,
-            env: { ...process.env, PORT: String(appPort) },
-            stdio: appStdio,
-        });
+        if (reuseApp) {
+            onLog(`reusing the dev server already on :${appPort}`);
+        }
+        else {
+            app = spawn(devCommand[0], devCommand.slice(1), {
+                cwd: projectCwd,
+                env: { ...process.env, PORT: String(appPort) },
+                stdio: appStdio,
+                // Windows: npm/pnpm are .cmd shims — spawn needs a shell to resolve them.
+                shell: process.platform === "win32",
+            });
+        }
         relay = startRelay({
             port: relayPort,
             path: harnessPath,
@@ -53,7 +70,13 @@ export async function startPreview(opts) {
             stdio: ["ignore", "pipe", "pipe"],
         });
         await waitForRegister(tunnel, registerTimeoutMs);
-        return { url: session.url, relayPort, stop };
+        // Don't hand back a live URL that serves a blank page: wait for the app to
+        // actually respond. Non-fatal — a slow build still returns, flagged not-ready.
+        const appReady = reuseApp ? true : await waitForApp(appPort, appReadyTimeoutMs);
+        if (!appReady) {
+            onLog(`app on :${appPort} isn't responding yet — the URL may be blank until it builds`);
+        }
+        return { url: session.url, relayPort, appPort, appReady, stop };
     }
     catch (err) {
         await stop();

package/dist/scaffold/index.d.ts

@@ -1,4 +1,4 @@
-export declare const TEMPLATE_REPO = "git@github.com:vincentt-xr/v2-template.git";
+export declare const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
 /** Injectable git runner (real git by default; a fake in tests avoids the network). */
 export type GitRunner = (args: string[]) => Promise<void>;
 /**
@@ -17,3 +17,10 @@ export interface ScaffoldOptions {
  * fresh repo. Throws a clear error if the clone fails (e.g. no git access).
  */
 export declare function scaffoldFromTemplate(targetDir: string, opts?: ScaffoldOptions): Promise<void>;
+/**
+ * Install a freshly scaffolded project's dependencies so the first preview/build
+ * doesn't fail on a missing node_modules. Throws on failure (no network, no npm);
+ * the caller surfaces it as a "run npm install yourself" hint rather than aborting
+ * project creation.
+ */
+export declare function installDependencies(dir: string): Promise<void>;

package/dist/scaffold/index.js

@@ -9,7 +9,7 @@ import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
-export const TEMPLATE_REPO = "git@github.com:vincentt-xr/v2-template.git";
+export const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
 const realGit = async (args) => {
     await execFileAsync("git", args);
 };
@@ -70,3 +70,16 @@ async function isGitRepo(dir) {
         return false;
     }
 }
+/**
+ * Install a freshly scaffolded project's dependencies so the first preview/build
+ * doesn't fail on a missing node_modules. Throws on failure (no network, no npm);
+ * the caller surfaces it as a "run npm install yourself" hint rather than aborting
+ * project creation.
+ */
+export async function installDependencies(dir) {
+    // Windows: npm is npm.cmd — execFile needs a shell to resolve it.
+    await execFileAsync("npm", ["install"], {
+        cwd: dir,
+        shell: process.platform === "win32",
+    });
+}

package/dist/shared/config.d.ts

@@ -15,6 +15,12 @@ export interface ProjectBinding {
 export declare const MACHINE_CONFIG_PATH: string;
 export declare function projectBindingPath(cwd: string): string;
 export declare function loadMachineConfig(): Promise<Partial<MachineConfig>>;
+/**
+ * Merge a patch into ~/.vincentt/config.json (used by `harness login` to persist
+ * a freshly minted PAT). Preserves any other fields already present. The file
+ * holds a bearer credential, so the dir/file get owner-only perms.
+ */
+export declare function writeMachineConfig(patch: Partial<MachineConfig>): Promise<string>;
 export declare function loadProjectBinding(cwd: string): Promise<ProjectBinding | undefined>;
 /**
  * Write the per-tree binding and make sure `.vincentt/` is gitignored (so the

package/dist/shared/config.js

@@ -29,6 +29,20 @@ async function readJsonIfExists(p) {
 export async function loadMachineConfig() {
     return (await readJsonIfExists(MACHINE_CONFIG_PATH)) ?? {};
 }
+/**
+ * Merge a patch into ~/.vincentt/config.json (used by `harness login` to persist
+ * a freshly minted PAT). Preserves any other fields already present. The file
+ * holds a bearer credential, so the dir/file get owner-only perms.
+ */
+export async function writeMachineConfig(patch) {
+    const next = { ...(await loadMachineConfig()), ...patch };
+    await fs.mkdir(path.dirname(MACHINE_CONFIG_PATH), { recursive: true, mode: 0o700 });
+    await fs.writeFile(MACHINE_CONFIG_PATH, JSON.stringify(next, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return MACHINE_CONFIG_PATH;
+}
 export async function loadProjectBinding(cwd) {
     return readJsonIfExists(projectBindingPath(cwd));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/harness",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Vincentt AR dev-loop harness — in-app diagnostics client + relay + agent-agnostic MCP server",
   "license": "UNLICENSED",
   "type": "module",
@@ -26,6 +26,7 @@
     }
   },
   "bin": {
+    "harness": "./dist/cli/index.js",
     "harness-relay": "./dist/relay/cli.js",
     "harness-mcp": "./dist/mcp/cli.js"
   },