@vincentt-xr/harness 0.4.0 → 1.0.0

package/dist/client/HarnessProvider.d.ts

@@ -17,5 +17,10 @@ export interface HarnessProviderProps {
     captureConsole?: boolean;
     captureNetwork?: boolean;
     captureTrace?: boolean;
+    /**
+     * Mount the floating "Send feedback" button (the reverse-channel capture
+     * overlay). Defaults to `enabled` — on in preview, gone in production.
+     */
+    feedback?: boolean;
 }
 export declare function HarnessProvider(props: HarnessProviderProps): ReactNode;

package/dist/client/HarnessProvider.js

@@ -52,9 +52,20 @@ export function HarnessProvider(props) {
                 captureTrace: props.captureTrace,
             });
         });
+        let unmountFeedback;
+        if (props.feedback !== false) {
+            // Separate dynamic import so the capture overlay (and its DOM code) also
+            // drops from a production bundle.
+            void import("./annotate.js").then(({ mountFeedbackButton }) => {
+                if (cancelled)
+                    return;
+                unmountFeedback = mountFeedbackButton({ sessionId: props.sessionId });
+            });
+        }
         return () => {
             cancelled = true;
             teardown?.();
+            unmountFeedback?.();
         };
         // Instrumentation is installed once for the provider's lifetime; option
         // changes mid-session are not a supported case.

package/dist/client/annotate.d.ts

@@ -0,0 +1,34 @@
+import type { AnnotationInput, AnnotationSpec } from "../shared/events.js";
+/**
+ * Capture the current frame as a PNG data URL. Prefers the largest <canvas> (the
+ * AR/three.js surface); returns an empty-ish 1x1 PNG if there is none.
+ *
+ * Caveat: reading a WebGL canvas requires it to have been created with
+ * `preserveDrawingBuffer: true`, or the read can come back blank. r3f/three set
+ * this via `gl={{ preserveDrawingBuffer: true }}`. DOM-only content isn't captured
+ * here (that needs html2canvas, deliberately not a dependency).
+ */
+export declare function captureScreenshot(): string;
+export interface SendAnnotationOptions {
+    /** Relay HTTP base (default: `<origin>/__harness`). */
+    relayHttpUrl?: string;
+}
+/** POST an annotation to the relay. Resolves with the relay-assigned id + seq. */
+export declare function sendAnnotation(input: AnnotationInput, opts?: SendAnnotationOptions): Promise<{
+    id: string;
+    seq: number;
+}>;
+export interface FeedbackButtonOptions extends SendAnnotationOptions {
+    sessionId?: string;
+    /** Collect the creator's message. Default: window.prompt. */
+    promptMessage?: () => string | null | Promise<string | null>;
+    /** Override the captured spec (strokes/pins/labels). Default: empty. */
+    spec?: AnnotationSpec;
+}
+/**
+ * Mount a minimal floating "Send feedback" button. On click it collects a message,
+ * captures the frame, and sends the annotation. Returns an unmount function. This
+ * is the smallest useful Send action; a richer draw-on-frame overlay can replace
+ * the capture/prompt without changing the wire contract.
+ */
+export declare function mountFeedbackButton(opts?: FeedbackButtonOptions): () => void;

package/dist/client/annotate.js

@@ -0,0 +1,104 @@
+// The in-app capture overlay's Send action — the client half of the reverse
+// channel. It captures the current frame, packages the creator's message + spec,
+// and POSTs it to the relay over the same tunnel the app is served on. The relay
+// (see the CLI's relay/annotations) stamps + persists it and unblocks a waiting
+// `vincentt feedback --wait`.
+//
+// Loaded via dynamic import from HarnessProvider (like the instrumentation), so a
+// production build never ships it. DOM-only, no React.
+/** Default relay HTTP base: the same origin the app is served on + the harness path. */
+function defaultRelayHttpUrl() {
+    return `${window.location.origin}/__harness`;
+}
+/**
+ * Capture the current frame as a PNG data URL. Prefers the largest <canvas> (the
+ * AR/three.js surface); returns an empty-ish 1x1 PNG if there is none.
+ *
+ * Caveat: reading a WebGL canvas requires it to have been created with
+ * `preserveDrawingBuffer: true`, or the read can come back blank. r3f/three set
+ * this via `gl={{ preserveDrawingBuffer: true }}`. DOM-only content isn't captured
+ * here (that needs html2canvas, deliberately not a dependency).
+ */
+export function captureScreenshot() {
+    const canvases = Array.from(document.querySelectorAll("canvas"));
+    const biggest = canvases.sort((a, b) => b.width * b.height - a.width * a.height)[0];
+    if (biggest) {
+        try {
+            return biggest.toDataURL("image/png");
+        }
+        catch {
+            // Tainted canvas (cross-origin texture without CORS) — fall through.
+        }
+    }
+    const fallback = document.createElement("canvas");
+    fallback.width = fallback.height = 1;
+    return fallback.toDataURL("image/png");
+}
+/** POST an annotation to the relay. Resolves with the relay-assigned id + seq. */
+export async function sendAnnotation(input, opts = {}) {
+    const base = opts.relayHttpUrl ?? defaultRelayHttpUrl();
+    const res = await fetch(`${base}/annotation`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input),
+    });
+    if (!res.ok)
+        throw new Error(`annotation POST failed: ${res.status}`);
+    return (await res.json());
+}
+/**
+ * Mount a minimal floating "Send feedback" button. On click it collects a message,
+ * captures the frame, and sends the annotation. Returns an unmount function. This
+ * is the smallest useful Send action; a richer draw-on-frame overlay can replace
+ * the capture/prompt without changing the wire contract.
+ */
+export function mountFeedbackButton(opts = {}) {
+    if (typeof document === "undefined")
+        return () => undefined;
+    const btn = document.createElement("button");
+    btn.textContent = "Send feedback";
+    Object.assign(btn.style, {
+        position: "fixed",
+        right: "12px",
+        bottom: "12px",
+        zIndex: "2147483647",
+        padding: "10px 14px",
+        borderRadius: "10px",
+        border: "none",
+        background: "linear-gradient(135deg,#7c3aed,#2563eb)",
+        color: "#fff",
+        font: "600 13px/1 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif",
+        boxShadow: "0 4px 16px rgba(0,0,0,.25)",
+        cursor: "pointer",
+    });
+    const setBusy = (busy, label) => {
+        btn.disabled = busy;
+        btn.textContent = label ?? "Send feedback";
+        btn.style.opacity = busy ? "0.6" : "1";
+    };
+    btn.addEventListener("click", async () => {
+        const getMsg = opts.promptMessage ?? (() => window.prompt("Feedback for the agent:"));
+        const message = await getMsg();
+        if (message == null || message.trim() === "")
+            return;
+        setBusy(true, "Sending…");
+        try {
+            const screenshot = captureScreenshot();
+            const input = {
+                message: message.trim(),
+                screenshot,
+                spec: opts.spec ?? {},
+                sessionId: opts.sessionId,
+            };
+            await sendAnnotation(input, { relayHttpUrl: opts.relayHttpUrl });
+            setBusy(false, "Sent ✓");
+            window.setTimeout(() => setBusy(false), 1500);
+        }
+        catch (err) {
+            setBusy(false, "Failed — retry");
+            console.error("[harness] annotation send failed:", err);
+        }
+    });
+    document.body.appendChild(btn);
+    return () => btn.remove();
+}

package/dist/client/index.d.ts

@@ -1,3 +1,5 @@
 export { HarnessProvider } from "./HarnessProvider.js";
 export type { HarnessProviderProps } from "./HarnessProvider.js";
+export { sendAnnotation, captureScreenshot, mountFeedbackButton, type SendAnnotationOptions, type FeedbackButtonOptions, } from "./annotate.js";
 export type { DiagEvent, LogEvent, NetworkEvent, TraceEvent } from "../shared/events.js";
+export type { Annotation, AnnotationInput, AnnotationSpec, AnnotationStroke, AnnotationPin, } from "../shared/events.js";

package/dist/client/index.js

@@ -3,3 +3,4 @@
 // tree-shakes it). The relay and MCP server are NOT exported here; they are
 // run-from-bin, not imported.
 export { HarnessProvider } from "./HarnessProvider.js";
+export { sendAnnotation, captureScreenshot, mountFeedbackButton, } from "./annotate.js";

package/dist/shared/events.d.ts

@@ -75,4 +75,54 @@ export interface RelayResult {
     /** Sessions the relay has seen events for (so the agent can disambiguate). */
     sessions: string[];
 }
+/** A freehand stroke over the frame, in normalized [0,1] frame coordinates. */
+export interface AnnotationStroke {
+    points: {
+        x: number;
+        y: number;
+    }[];
+    color?: string;
+}
+/** A point marker on the frame, in normalized [0,1] frame coordinates. */
+export interface AnnotationPin {
+    x: number;
+    y: number;
+    label?: string;
+}
+/** The drawn overlay accompanying an annotation. All fields optional — a bare
+ *  message with a screenshot is a valid annotation. */
+export interface AnnotationSpec {
+    strokes?: AnnotationStroke[];
+    pins?: AnnotationPin[];
+    labels?: string[];
+    note?: string;
+}
+/** Client → relay POST body (`POST /__harness/annotation`). The relay stamps the
+ *  id, receipt time, project binding, and on-disk screenshot path. */
+export interface AnnotationInput {
+    /** The creator's message to the agent. */
+    message: string;
+    /** Annotated frame as a data URL (image/png). */
+    screenshot: string;
+    spec?: AnnotationSpec;
+    /** Optional preview session id, to correlate with diag events. */
+    sessionId?: string;
+}
+/** A persisted annotation the agent consumes (via `vincentt feedback --wait`). */
+export interface Annotation {
+    /** Short relay-assigned id (e.g. "a7f3"). */
+    id: string;
+    /** Monotonic per-project cursor; a consumer polls "after this seq". */
+    seq: number;
+    /** Receipt time, stamped by the relay (not the browser). */
+    createdAt: Timestamp;
+    /** The bound project directory this annotation belongs to. */
+    projectDir: string;
+    /** The creator's message to the agent. */
+    message: string;
+    /** Absolute path to the full-res annotated screenshot on disk. */
+    screenshotPath: string;
+    spec: AnnotationSpec;
+    sessionId?: string;
+}
 export {};

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@vincentt-xr/harness",
-  "version": "0.4.0",
-  "description": "Vincentt AR dev-loop harness — in-app diagnostics client + relay + agent-agnostic MCP server",
+  "version": "1.0.0",
+  "description": "Vincentt AR dev-loop harness — in-app diagnostics provider + wire contract",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,
   "files": [
-    "/dist"
+    "dist"
   ],
   "main": "./dist/client/index.js",
   "module": "./dist/client/index.js",
@@ -16,46 +16,20 @@
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js"
     },
-    "./relay": {
-      "types": "./dist/relay/server.d.ts",
-      "import": "./dist/relay/server.js"
-    },
-    "./preview": {
-      "types": "./dist/preview/index.d.ts",
-      "import": "./dist/preview/index.js"
+    "./events": {
+      "types": "./dist/shared/events.d.ts",
+      "import": "./dist/shared/events.js"
     }
   },
-  "bin": {
-    "harness": "./dist/cli/index.js",
-    "harness-relay": "./dist/relay/cli.js",
-    "harness-mcp": "./dist/mcp/cli.js"
-  },
   "peerDependencies": {
     "react": "^18.2.0"
   },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "cloudflared": "^0.7.1",
-    "ws": "^8.18.0",
-    "zod": "^3.23.8"
-  },
   "devDependencies": {
-    "@types/node": "^22.9.0",
-    "@types/react": "^18.3.12",
-    "@types/ws": "^8.5.13",
-    "prettier": "3.3.3",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.5"
+    "@types/react": "^18.3.12"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "relay": "node --loader ts-node/esm src/relay/cli.ts",
-    "mcp": "node --loader ts-node/esm src/mcp/cli.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "format:check": "prettier --check .",
-    "format": "prettier --write ."
+    "test": "vitest run"
   }
 }

package/README.md

@@ -1,87 +0,0 @@
-# @vincentt-xr/harness
-
-The Vincentt AR dev-loop harness. It is **one always-on diagnostics channel**
-between the AR app running on a phone and the coding agent running on a laptop,
-so the agent can see what the phone sees — console logs, network requests,
-performance — without the developer hand-ferrying DevTools traces or pasting
-console output.
-
-Agent-agnostic: the agent side is a plain **MCP server**, so any MCP-capable
-agent (Claude Code, Codex, Cursor, Cline, …) uses it the same way.
-
-## The three parts
-
-```
-  PHONE (preview app)          RELAY (laptop)         AGENT (laptop)
-  ┌──────────────────┐    ┌────────────────┐    ┌────────────────────┐
-  │ HarnessProvider  │    │  harness-relay │    │  harness-mcp       │
-  │ • patch console  │─ws→│  ring buffer   │←──→│  diag_logs         │
-  │ • wrap fetch/XHR │    │  per session   │http│  diag_network      │
-  │ • sample perf    │    │                │    │  diag_trace        │
-  └──────────────────┘    └────────────────┘    └────────────────────┘
-   src/client (npm pkg)      src/relay (bin)        src/mcp (bin)
-```
-
-- **`src/client`** — the in-app half; the published npm package. `HarnessProvider`
-  patches `console.*`, wraps `fetch`/`XHR`, and samples `performance`, shipping
-  events to the relay over a WebSocket. Auto-on in a dev build, no-op (and
-  tree-shaken) in production.
-- **`src/relay`** — a small WebSocket + HTTP server beside Vite. Holds a bounded
-  ring buffer of recent events per session. The phone pushes; the agent pulls.
-- **`src/mcp`** — the agent-agnostic MCP server. Exposes `diag_logs`,
-  `diag_network`, `diag_trace` that pull from the relay.
-
-- **`src/shared/events.ts`** — the wire contract all three import, so they can't
-  drift on the event shape.
-
-## Use it
-
-**In the app (once):**
-
-```tsx
-import { HarnessProvider } from "@vincentt-xr/harness";
-
-<HarnessProvider>
-  <App />
-</HarnessProvider>;
-```
-
-That's the whole author-facing surface. It self-activates in dev and disappears
-in the production build.
-
-**Run the relay** beside your dev server (the preview tunnel carries its socket
-to the phone):
-
-```
-npx harness-relay          # listens on :7331, ws path /__harness
-```
-
-**Point your agent at the MCP server.** In the agent's MCP config:
-
-```json
-{
-  "mcpServers": {
-    "vincentt-harness": { "command": "npx", "args": ["harness-mcp"] }
-  }
-}
-```
-
-Then, while the app is open on the phone, the agent calls `diag_logs`,
-`diag_network`, `diag_trace` to read what the device is doing — no DevTools, no
-copy-paste.
-
-## Develop
-
-```
-pnpm install
-pnpm test         # unit tests (pure event-shaping, buffer, ring store, formatting, fps)
-pnpm typecheck
-pnpm build        # emits dist/ (client = npm surface; relay/mcp = bins)
-```
-
-## Status
-
-Local-first. The diagnostics limb is built and proven end-to-end
-(phone → relay → agent). The platform lifecycle (per-project server-minted
-tunnels, `createProject`/`publish`, auth) is a separate later phase; the same
-client + relay also feed the production client-review service.

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

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

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

@@ -1,148 +0,0 @@
-// `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 };
-}