@vincentt-xr/cli 0.1.0

package/dist/cli/deprecated/harness-mcp.d.ts

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

package/dist/cli/deprecated/harness-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Deprecated alias for `vincentt mcp`. Rewrites argv to the `mcp` subcommand
+// (preserving flags like --relay-url) and dispatches to the unified CLI.
+console.error("Note: `harness-mcp` is deprecated in favor of `vincentt mcp`.");
+process.argv = [process.argv[0], process.argv[1], "mcp", ...process.argv.slice(2)];
+await import("../index.js");
+export {};

package/dist/cli/deprecated/harness-relay.d.ts

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

package/dist/cli/deprecated/harness-relay.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Deprecated alias for `vincentt relay`. Rewrites argv to the `relay` subcommand
+// (preserving flags like --port) and dispatches to the unified CLI.
+console.error("Note: `harness-relay` is deprecated in favor of `vincentt relay`.");
+process.argv = [process.argv[0], process.argv[1], "relay", ...process.argv.slice(2)];
+await import("../index.js");
+export {};

package/dist/cli/deprecated/harness.d.ts

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

package/dist/cli/deprecated/harness.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Deprecated alias for `vincentt`. Kept for one release so the live dogfood setup
+// and any early installs keep working. Prints a notice, then dispatches to the
+// same CLI (`harness login` → `vincentt login`).
+console.error("Note: `harness` is deprecated in favor of `vincentt` (e.g. `vincentt login`).");
+await import("../index.js");
+export {};

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// `vincentt` — the unified CLI for the local-first dev loop. A human and a
+// bash-capable coding agent drive the same verbs. No MCP registration is required
+// for the default path; `vincentt mcp` exists only for hosts without a shell.
+//
+// Verb groups:
+//   auth        login · logout · whoami
+//   dev loop    create · publish · preview
+//   diagnostics logs · network · trace
+//   reverse     feedback (--wait | --watch)
+//   servers     relay · mcp
+import os from "node:os";
+import path from "node:path";
+import { runLogin } from "../login/login.js";
+import { clearMachineToken, loadMachineConfig, } from "../shared/config.js";
+import { getMe } from "../lib/backend.js";
+import { diagQuery, diagRead, previewStart, previewStop, projectCreate, projectPublish, } from "../lib/lifecycle.js";
+import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
+const DEFAULT_EDITOR_URL = "https://editor.vincentt.studio";
+const DEFAULT_API_URL = "https://api.vincentt.studio";
+// ---- arg helpers ------------------------------------------------------------
+const argv = process.argv.slice(2);
+function flag(name) {
+    const i = argv.indexOf(name);
+    return i !== -1 ? argv[i + 1] : undefined;
+}
+function has(name) {
+    return argv.includes(name);
+}
+function numFlag(name) {
+    const v = flag(name);
+    return v !== undefined ? Number(v) : undefined;
+}
+function projectDir() {
+    const dir = flag("--dir");
+    return dir ? path.resolve(dir) : process.cwd();
+}
+// ---- auth -------------------------------------------------------------------
+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") ?? `Vincentt 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 logout() {
+    const { path: p, hadToken } = await clearMachineToken();
+    console.log(hadToken ? `✓ Signed out. Token removed from ${p}` : "Already signed out.");
+}
+async function whoami() {
+    const machine = await loadMachineConfig();
+    const apiUrl = process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
+    const pat = process.env.VINCENTT_PAT ?? machine.pat;
+    if (!pat) {
+        console.log("Not signed in. Run `vincentt login`.");
+        process.exitCode = 1;
+        return;
+    }
+    const cfg = { apiUrl: apiUrl.replace(/\/$/, ""), pat };
+    try {
+        const me = await getMe(cfg);
+        const who = me.email ?? me.name ?? me.id ?? "(unknown account)";
+        console.log(`Signed in as ${who}`);
+        console.log(`  API: ${cfg.apiUrl}`);
+    }
+    catch (err) {
+        // Degrade: offline or a backend without /me still confirms a token is present.
+        console.log(`API: ${cfg.apiUrl}`);
+        console.log(`Token present but unverified (${err instanceof Error ? err.message : String(err)}).`);
+    }
+}
+// ---- dev loop ---------------------------------------------------------------
+async function create() {
+    const result = await projectCreate(projectDir(), {
+        name: flag("--name"),
+        slug: flag("--slug"),
+        scaffold: has("--no-scaffold") ? false : undefined,
+    });
+    console.log(result.message);
+    if (result.alreadyBound)
+        process.exitCode = 1;
+}
+async function publish() {
+    const result = await projectPublish(projectDir(), {
+        distDir: flag("--dist"),
+        note: flag("--note"),
+    });
+    console.log(result.message);
+    if (result.notBound)
+        process.exitCode = 1;
+}
+async function preview() {
+    const { preview: p, started } = await previewStart(projectDir(), (m) => console.error(`[preview] ${m}`));
+    if (!started) {
+        console.log(`A preview is already running:\n${p.url}`);
+        return;
+    }
+    console.log(`\nLive preview — open on your device:\n  ${p.url}\n`);
+    console.log("Diagnostics: vincentt logs | network | trace");
+    console.log("Feedback:    vincentt feedback --wait");
+    console.log("\nPress Ctrl-C to stop.");
+    if (!p.appReady) {
+        console.log(`\nNote: the app on :${p.appPort} isn't responding yet — the URL may be blank until its build finishes.`);
+    }
+    // Keep the process alive until interrupted; reap the tunnel/dev-server on exit.
+    await new Promise((resolve) => {
+        const stop = async () => {
+            console.error("\nStopping preview…");
+            await previewStop();
+            resolve();
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+    });
+}
+// ---- diagnostics ------------------------------------------------------------
+async function diag(kind) {
+    const cwd = projectDir();
+    const opts = {
+        sessionId: flag("--session"),
+        since: numFlag("--since"),
+        limit: numFlag("--limit"),
+        errorsOnly: has("--errors"),
+    };
+    if (has("--json")) {
+        console.log(JSON.stringify(await diagQuery(cwd, kind, opts), null, 2));
+    }
+    else {
+        console.log(await diagRead(cwd, kind, opts));
+    }
+}
+// ---- reverse channel --------------------------------------------------------
+async function feedback() {
+    const cwd = projectDir();
+    const timeoutMs = (numFlag("--timeout") ?? 300) * 1000;
+    const watch = has("--watch");
+    if (!watch && !has("--wait")) {
+        console.error("Usage: vincentt feedback --wait | --watch [--timeout <seconds>]");
+        process.exitCode = 1;
+        return;
+    }
+    do {
+        const after = await readCursor(cwd);
+        const annotation = await fetchNext(cwd, { after, timeoutMs });
+        if (!annotation) {
+            // 204 re-arm signal: --wait exits empty, --watch loops.
+            if (!watch)
+                return;
+            continue;
+        }
+        // Print BEFORE advancing the cursor → at-least-once (a crash re-delivers).
+        console.log(JSON.stringify(annotation));
+        await writeCursor(cwd, annotation.seq);
+    } while (watch);
+}
+// ---- servers ----------------------------------------------------------------
+async function mcp() {
+    const { runStdio } = await import("../mcp/server.js");
+    await runStdio({ relayUrl: flag("--relay-url") });
+}
+async function relay() {
+    const { startRelay } = await import("../relay/server.js");
+    const port = numFlag("--port") ?? 7331;
+    const dir = flag("--dir");
+    startRelay({
+        port,
+        projectDir: dir ? path.resolve(dir) : undefined,
+        onLog: (m) => console.log(`[relay] ${m}`),
+    });
+}
+// ---- dispatch ---------------------------------------------------------------
+function usage() {
+    console.log(`Vincentt CLI — local-first AR dev loop\n\n` +
+        `Usage: vincentt <command> [options]\n\n` +
+        `Auth\n` +
+        `  login              Sign in; save an access token to ~/.vincentt/config.json\n` +
+        `  logout             Remove the saved access token\n` +
+        `  whoami             Show the signed-in account (via GET /me)\n\n` +
+        `Dev loop\n` +
+        `  create             Create/bind a project (scaffolds the starter if empty)\n` +
+        `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
+        `  preview            Serve + tunnel the app for on-device preview\n\n` +
+        `Diagnostics (need a running preview)\n` +
+        `  logs [--errors]    Console logs from the device   [--json]\n` +
+        `  network            fetch/XHR requests              [--json]\n` +
+        `  trace              Performance samples             [--json]\n\n` +
+        `Reverse channel\n` +
+        `  feedback --wait    Block for the next phone annotation, print it, exit\n` +
+        `  feedback --watch   Stream annotations as they arrive\n\n` +
+        `Servers\n` +
+        `  relay              Run the diagnostics/annotation relay\n` +
+        `  mcp                Run the MCP adapter (for hosts without a shell)\n\n` +
+        `Common options: --dir <path> (project dir, default cwd)\n`);
+}
+async function main() {
+    const cmd = argv[0];
+    switch (cmd) {
+        case "login":
+            return login();
+        case "logout":
+            return logout();
+        case "whoami":
+            return whoami();
+        case "create":
+            return create();
+        case "publish":
+            return publish();
+        case "preview":
+            return preview();
+        case "logs":
+            return diag("log");
+        case "network":
+            return diag("network");
+        case "trace":
+            return diag("trace");
+        case "feedback":
+            return feedback();
+        case "mcp":
+            return mcp();
+        case "relay":
+            return relay();
+        case undefined:
+        case "-h":
+        case "--help":
+            usage();
+            return;
+        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/lib/backend.d.ts

@@ -0,0 +1,61 @@
+import type { ResolvedConfig } from "../shared/config.js";
+export interface CreatedProject {
+    projectId: string;
+    slug: string;
+    name: string;
+}
+export interface PublishResult {
+    version: number;
+    /** Immutable versioned URL (<slug>.<apex>/v<n>/). */
+    url: string;
+    /** Stable live alias (<slug>.<apex>/). */
+    liveUrl: string;
+}
+export declare class BackendError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * Create a backend project (reuses POST /projects). A `slug` pins the permanent
+ * <slug>.vincentt.app host; omit it and the platform assigns a catchy one. A
+ * taken slug comes back 409, surfaced so the caller can re-ask.
+ */
+export declare function createProject(cfg: ResolvedConfig, name: string, slug?: string): Promise<CreatedProject>;
+export interface MintedTunnel {
+    tunnelId: string;
+    /** The public host the phone opens: <slug>-<token>.<previewApex>. */
+    hostname: string;
+    /** cloudflared run token — `cloudflared tunnel run --token <this>`. */
+    runToken: string;
+    /** DNS record id, passed back on reap. */
+    dnsRecordId: string;
+}
+/** Mint a per-session dev tunnel for `localPort` (the backend holds CF creds). */
+export declare function mintTunnel(cfg: ResolvedConfig, projectId: string, localPort: number): Promise<MintedTunnel>;
+/** Tear down a session tunnel (DNS route + tunnel). Best-effort; never throws. */
+export declare function reapTunnel(cfg: ResolvedConfig, projectId: string, ref: {
+    tunnelId: string;
+    dnsRecordId?: string;
+}): Promise<void>;
+/** Recursively list files under `dir`, returning dir-relative POSIX paths. */
+export declare function walkDir(dir: string, base?: string): Promise<string[]>;
+/**
+ * Upload a locally-built dist and make it live. Each file rides as a multipart
+ * part whose filename is its dist-relative path (the backend reconstructs the
+ * tree). Requires an index.html at the dist root.
+ */
+export declare function publishUpload(cfg: ResolvedConfig, projectId: string, distDir: string, opts?: {
+    note?: string;
+    commitSha?: string;
+}): Promise<PublishResult>;
+export interface Me {
+    id?: string;
+    email?: string;
+    name?: string;
+    networkId?: string;
+}
+/** Resolve the signed-in identity for `vincentt whoami`. Throws on any non-2xx so
+ *  the caller can degrade to "token present, unverified". */
+export declare function getMe(cfg: ResolvedConfig): Promise<Me>;
+/** The working tree's current commit, for publish provenance. Undefined if not a repo. */
+export declare function gitHeadSha(cwd: string): Promise<string | undefined>;

package/dist/lib/backend.js

@@ -0,0 +1,155 @@
+// The lifecycle verbs' backend calls, isolated from the MCP SDK wiring (server.ts)
+// so they're unit-testable and the transport can change without touching them.
+// Every call is PAT-authed (Bearer). The publish path uploads an already-built
+// dist as-is — the backend never rebuilds (Principle 0).
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export class BackendError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "BackendError";
+    }
+}
+async function authFetch(cfg, pathname, init = {}) {
+    return fetch(`${cfg.apiUrl}${pathname}`, {
+        ...init,
+        headers: { ...(init.headers ?? {}), authorization: `Bearer ${cfg.pat}` },
+    });
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Create a backend project (reuses POST /projects). A `slug` pins the permanent
+ * <slug>.vincentt.app host; omit it and the platform assigns a catchy one. A
+ * taken slug comes back 409, surfaced so the caller can re-ask.
+ */
+export async function createProject(cfg, name, slug) {
+    const res = await authFetch(cfg, "/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ name, ...(slug ? { slug } : {}) }),
+    });
+    if (res.status === 409) {
+        throw new BackendError(`slug "${slug}" is already in use — pick another.`, 409);
+    }
+    if (!res.ok) {
+        throw new BackendError(`create project failed (${res.status}): ${await safeText(res)}`, res.status);
+    }
+    const p = (await res.json());
+    const projectId = p._id ?? p.id;
+    if (!projectId || !p.slug) {
+        throw new BackendError("create project: response missing id/slug");
+    }
+    return { projectId, slug: p.slug, name: p.name ?? name };
+}
+/** Mint a per-session dev tunnel for `localPort` (the backend holds CF creds). */
+export async function mintTunnel(cfg, projectId, localPort) {
+    const res = await authFetch(cfg, `/projects/${projectId}/tunnel`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ port: localPort }),
+    });
+    if (!res.ok) {
+        throw new BackendError(`tunnel mint failed (${res.status}): ${await safeText(res)}`, res.status);
+    }
+    return (await res.json());
+}
+/** Tear down a session tunnel (DNS route + tunnel). Best-effort; never throws. */
+export async function reapTunnel(cfg, projectId, ref) {
+    try {
+        await authFetch(cfg, `/projects/${projectId}/tunnel/reap`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(ref),
+        });
+    }
+    catch {
+        // Reap is a cleanup courtesy — a failure must never crash the preview teardown.
+    }
+}
+/** Recursively list files under `dir`, returning dir-relative POSIX paths. */
+export async function walkDir(dir, base = dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new BackendError(`dist directory not found: ${dir}`);
+        }
+        throw err;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walkDir(full, base)));
+        else if (entry.isFile())
+            out.push(path.relative(base, full).split(path.sep).join("/"));
+    }
+    return out;
+}
+/**
+ * Upload a locally-built dist and make it live. Each file rides as a multipart
+ * part whose filename is its dist-relative path (the backend reconstructs the
+ * tree). Requires an index.html at the dist root.
+ */
+export async function publishUpload(cfg, projectId, distDir, opts = {}) {
+    const files = await walkDir(distDir);
+    if (!files.includes("index.html")) {
+        throw new BackendError(`dist at ${distDir} has no index.html at its root — did the build run?`);
+    }
+    const form = new FormData();
+    // The real dist-relative paths ride as an ordered manifest — a multipart filename
+    // can't carry a directory (FormData strips it to a basename), so the backend maps
+    // paths[i] → files[i] to rebuild the tree.
+    form.append("paths", JSON.stringify(files));
+    for (const rel of files) {
+        const bytes = await fs.readFile(path.join(distDir, rel));
+        // Uint8Array (Buffer) is a valid BlobPart; the filename is cosmetic (the backend
+        // uses the manifest), but pass the basename so server logs read sensibly.
+        form.append("files", new Blob([bytes]), path.basename(rel));
+    }
+    if (opts.note)
+        form.append("note", opts.note);
+    if (opts.commitSha)
+        form.append("commitSha", opts.commitSha);
+    const res = await authFetch(cfg, `/projects/${projectId}/publish/upload`, {
+        method: "POST",
+        body: form,
+    });
+    if (!res.ok) {
+        throw new BackendError(`publish failed (${res.status}): ${await safeText(res)}`, res.status);
+    }
+    return (await res.json());
+}
+/** Resolve the signed-in identity for `vincentt whoami`. Throws on any non-2xx so
+ *  the caller can degrade to "token present, unverified". */
+export async function getMe(cfg) {
+    const res = await authFetch(cfg, "/me");
+    if (!res.ok) {
+        throw new BackendError(`/me failed (${res.status}): ${await safeText(res)}`, res.status);
+    }
+    return (await res.json());
+}
+/** The working tree's current commit, for publish provenance. Undefined if not a repo. */
+export async function gitHeadSha(cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", cwd, "rev-parse", "HEAD"]);
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/diagnostics.d.ts

@@ -0,0 +1,13 @@
+import type { DiagEvent, LogEvent, NetworkEvent, RelayQuery, RelayResult, TraceEvent } from "@vincentt-xr/harness/events";
+export interface RelayClient {
+    query(q: RelayQuery): Promise<RelayResult>;
+}
+/** A RelayClient backed by the relay's HTTP /query endpoint. */
+export declare function httpRelayClient(baseUrl: string): RelayClient;
+export declare function formatLog(e: LogEvent, now: number): string;
+export declare function formatNetwork(e: NetworkEvent, now: number): string;
+export declare function formatTrace(e: TraceEvent, now: number): string;
+/** Render a RelayResult for one kind into the text block a tool returns. */
+export declare function renderResult(result: RelayResult, kind: DiagEvent["kind"], now: number): string;
+/** Only-errors convenience filter applied on top of a log query result. */
+export declare function filterErrors(result: RelayResult): RelayResult;

package/dist/lib/diagnostics.js

@@ -0,0 +1,61 @@
+// The MCP server's logic, independent of the MCP SDK surface: fetch events from
+// the relay and format them into the compact text an agent reads. Kept separate
+// from the SDK wiring (server.ts) so the formatting is unit-testable and the SDK
+// version can churn without touching this.
+/** A RelayClient backed by the relay's HTTP /query endpoint. */
+export function httpRelayClient(baseUrl) {
+    return {
+        async query(q) {
+            const res = await fetch(`${baseUrl}/query`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(q),
+            });
+            if (!res.ok)
+                throw new Error(`relay /query returned ${res.status}`);
+            return (await res.json());
+        },
+    };
+}
+/** Human-time from the client timestamp, relative to now, for the agent's read. */
+function ago(t, now) {
+    const s = Math.max(0, Math.round((now - t) / 1000));
+    return s < 60 ? `${s}s ago` : `${Math.round(s / 60)}m ago`;
+}
+export function formatLog(e, now) {
+    const level = e.level.toUpperCase().padEnd(5);
+    const origin = e.origin ? `  (${e.origin})` : "";
+    return `[${level}] ${e.message}${origin}  · ${ago(e.t, now)} #${e.seq}`;
+}
+export function formatNetwork(e, now) {
+    const status = e.error ? `ERR ${e.error}` : String(e.status);
+    return `${e.method} ${e.url} → ${status} (${e.durationMs}ms)  · ${ago(e.t, now)} #${e.seq}`;
+}
+export function formatTrace(e, now) {
+    const marks = e.marks.length ? `  marks: ${e.marks.join(", ")}` : "";
+    return (`${e.fps.toFixed(0)}fps over ${e.windowMs}ms · longest task ${e.longestTaskMs}ms · ` +
+        `${e.longTaskCount} long task(s)${marks}  · ${ago(e.t, now)} #${e.seq}`);
+}
+/** Render a RelayResult for one kind into the text block a tool returns. */
+export function renderResult(result, kind, now) {
+    const lines = result.events.map((e) => {
+        if (e.kind === "log")
+            return formatLog(e, now);
+        if (e.kind === "network")
+            return formatNetwork(e, now);
+        return formatTrace(e, now);
+    });
+    const header = result.sessions.length > 1 ? `sessions: ${result.sessions.join(", ")}\n` : "";
+    const cursor = `\n\n(latestSeq ${result.latestSeq} — pass since=${result.latestSeq} to get only newer ${kind} events)`;
+    if (lines.length === 0) {
+        return `${header}No ${kind} events${result.latestSeq >= 0 ? " matched" : " yet — is the preview app open on the device?"}.${result.latestSeq >= 0 ? cursor : ""}`;
+    }
+    return `${header}${lines.join("\n")}${cursor}`;
+}
+/** Only-errors convenience filter applied on top of a log query result. */
+export function filterErrors(result) {
+    return {
+        ...result,
+        events: result.events.filter((e) => e.kind === "log" && e.level === "error"),
+    };
+}

package/dist/lib/feedback.d.ts

@@ -0,0 +1,15 @@
+import type { Annotation } from "@vincentt-xr/harness/events";
+export declare function cursorPath(cwd: string): string;
+/** Last-consumed annotation seq for this project (0 if none consumed yet). */
+export declare function readCursor(cwd: string): Promise<number>;
+/** Advance the cursor. Called ONLY after the annotation was handed off. */
+export declare function writeCursor(cwd: string, seq: number): Promise<void>;
+/**
+ * Long-poll the relay for the next annotation after `after`. Resolves the
+ * annotation, or null when the poll window elapsed with nothing new. Throws a
+ * clear hint when no preview relay is running for this project.
+ */
+export declare function fetchNext(cwd: string, opts: {
+    after: number;
+    timeoutMs: number;
+}): Promise<Annotation | null>;

package/dist/lib/feedback.js

@@ -0,0 +1,58 @@
+// The agent-agnostic reverse-channel consumer behind `vincentt feedback --wait`.
+// Long-polls the running preview's relay for the next annotation after a locally
+// persisted cursor. Delivery is at-least-once: the caller advances the cursor only
+// after it has successfully handed the annotation off (printed it), so a crash
+// before that re-delivers on the next call.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readRelayInfo } from "./relayInfo.js";
+const CURSOR_FILE = ".vincentt/annotations/offset";
+export function cursorPath(cwd) {
+    return path.join(cwd, CURSOR_FILE);
+}
+/** Last-consumed annotation seq for this project (0 if none consumed yet). */
+export async function readCursor(cwd) {
+    try {
+        const raw = await fs.readFile(cursorPath(cwd), "utf8");
+        return Number(raw.trim()) || 0;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+}
+/** Advance the cursor. Called ONLY after the annotation was handed off. */
+export async function writeCursor(cwd, seq) {
+    const p = cursorPath(cwd);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, `${seq}\n`, "utf8");
+}
+/**
+ * Long-poll the relay for the next annotation after `after`. Resolves the
+ * annotation, or null when the poll window elapsed with nothing new. Throws a
+ * clear hint when no preview relay is running for this project.
+ */
+export async function fetchNext(cwd, opts) {
+    const info = await readRelayInfo(cwd);
+    if (!info) {
+        throw new Error("No running preview for this project — run `vincentt preview` first.");
+    }
+    const base = `http://localhost:${info.relayPort}`;
+    const u = new URL(`${info.harnessPath}/feedback/next`, base);
+    u.searchParams.set("project", cwd);
+    u.searchParams.set("after", String(opts.after));
+    u.searchParams.set("timeout", String(opts.timeoutMs));
+    let res;
+    try {
+        res = await fetch(u);
+    }
+    catch (err) {
+        throw new Error(`Could not reach the preview relay on :${info.relayPort} (${err.message}). Is the preview still running?`);
+    }
+    if (res.status === 204)
+        return null;
+    if (!res.ok)
+        throw new Error(`relay feedback/next returned ${res.status}`);
+    return (await res.json());
+}