@vincentt-xr/harness 0.3.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

@@ -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 {
@@ -88,9 +99,12 @@ export function createHarnessMcp(opts = {}) {
         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: {
@@ -106,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.`;
@@ -154,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.";
@@ -171,15 +189,15 @@ 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).

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/runner.d.ts

@@ -18,7 +18,9 @@ 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). */
+    /** 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;

package/dist/preview/runner.js

@@ -16,7 +16,7 @@ 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, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", registerTimeoutMs = 45_000, appReadyTimeoutMs = 20_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.

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>;
 /**

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);
 };

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.3.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"
   },