@vincentt-xr/harness 0.2.0 → 0.3.0

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.
@@ -48,7 +48,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 +62,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 +71,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,7 +85,7 @@ 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 —
@@ -116,9 +124,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.`);
@@ -162,9 +182,14 @@ export function createHarnessMcp(opts = {}) {
             projectCwd,
             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 +198,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/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,20 @@ 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 20s). */
+    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 = 20_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

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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/harness",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Vincentt AR dev-loop harness — in-app diagnostics client + relay + agent-agnostic MCP server",
   "license": "UNLICENSED",
   "type": "module",