@vincentt-xr/cli 0.1.0

package/dist/relay/server.js

@@ -0,0 +1,186 @@
+// The relay: a WebSocket + HTTP server that sits beside Vite. The phone's
+// harness client pushes diag event batches over WS and POSTs annotations over the
+// tunnel; the MCP server / CLI pull diagnostics via a localhost HTTP endpoint and
+// long-poll for annotations. Deliberately tiny — buffering/query logic is in
+// store.ts, the reverse-channel store in annotations.ts. One relay per preview run.
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { WebSocketServer } from "ws";
+import { EventStore } from "./store.js";
+import { AnnotationStore, annotationsDir } from "./annotations.js";
+import { claudeCodeInjector, createDispatcher, pasteInjector, } from "./injectors.js";
+/** Cap an annotation POST body so a bad/huge upload can't exhaust memory. */
+const MAX_ANNOTATION_BYTES = 25 * 1024 * 1024;
+/** Clamp the long-poll hold so a request can't park forever. */
+const MAX_FEEDBACK_TIMEOUT_MS = 600_000;
+export function startRelay(opts = {}) {
+    const port = opts.port ?? 7331;
+    const wsPath = opts.path ?? "/__harness";
+    const store = new EventStore(opts.capacity);
+    const log = opts.onLog ?? (() => undefined);
+    const makeId = opts.makeId ?? (() => randomBytes(3).toString("hex"));
+    // Reverse channel is enabled when we know which project to bind annotations to.
+    let annotations;
+    let dispatcher;
+    if (opts.projectDir || opts.annotationStore) {
+        annotations =
+            opts.annotationStore ?? new AnnotationStore(opts.projectDir);
+        const queuePath = path.join(opts.projectDir ? annotationsDir(opts.projectDir) : ".", "queue.ndjson");
+        dispatcher =
+            opts.dispatcher ??
+                createDispatcher([
+                    claudeCodeInjector(queuePath),
+                    pasteInjector((p) => log(`annotation ready to paste:\n${p}`)),
+                ], log);
+    }
+    const http = createServer((req, res) => handleHttp(req, res, { store, annotations, dispatcher, wsPath, makeId, log }));
+    const wss = new WebSocketServer({ server: http, path: wsPath });
+    wss.on("connection", (ws) => {
+        log("client connected");
+        ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(String(data));
+                if (msg.type === "events" && Array.isArray(msg.events)) {
+                    store.ingest(msg.sessionId, msg.events);
+                }
+            }
+            catch {
+                // ignore malformed frames — a bad client must not crash the relay
+            }
+        });
+        ws.on("close", () => log("client disconnected"));
+    });
+    http.listen(port, () => log(`relay listening on :${port} (ws ${wsPath}, http /query)`));
+    return {
+        store,
+        annotations,
+        close: () => new Promise((resolve) => {
+            annotations?.close();
+            wss.close();
+            http.close(() => resolve());
+        }),
+    };
+}
+function handleHttp(req, res, ctx) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const p = url.pathname;
+    if (p === "/query") {
+        handleQuery(req, res, url, ctx);
+        return;
+    }
+    if (p === `${ctx.wsPath}/annotation`) {
+        handleAnnotationPost(req, res, ctx);
+        return;
+    }
+    if (p === `${ctx.wsPath}/feedback/next`) {
+        handleFeedbackNext(res, url, ctx);
+        return;
+    }
+    res.writeHead(404).end();
+}
+// The MCP server / CLI (same laptop) GETs/POSTs /query with a RelayQuery. Localhost
+// only; no auth in the local dev loop (the platform phase adds it).
+function handleQuery(req, res, url, ctx) {
+    readQuery(req, url)
+        .then((q) => {
+        const result = ctx.store.query(q);
+        res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(result));
+    })
+        .catch((err) => {
+        ctx.log(`query error: ${err}`);
+        res.writeHead(400).end();
+    });
+}
+// The device POSTs an annotation over the tunnel (front proxy routes wsPath/* here).
+function handleAnnotationPost(req, res, ctx) {
+    if (!ctx.annotations) {
+        res.writeHead(503).end("reverse channel not enabled");
+        return;
+    }
+    readBody(req, MAX_ANNOTATION_BYTES)
+        .then(async (body) => {
+        const input = JSON.parse(body);
+        if (!input || typeof input.message !== "string" || typeof input.screenshot !== "string") {
+            res.writeHead(400).end("annotation requires message + screenshot");
+            return;
+        }
+        const annotation = await ctx.annotations.add(input, {
+            now: Date.now(),
+            id: ctx.makeId(),
+        });
+        // Fire the injector chain best-effort — a failed dispatch must not fail the
+        // POST; the long-poll consumer still sees the persisted annotation.
+        if (ctx.dispatcher) {
+            ctx.dispatcher.dispatch(annotation).catch((err) => ctx.log(`dispatch: ${err}`));
+        }
+        res
+            .writeHead(200, { "content-type": "application/json" })
+            .end(JSON.stringify({ id: annotation.id, seq: annotation.seq }));
+    })
+        .catch((err) => {
+        ctx.log(`annotation error: ${err}`);
+        if (!res.headersSent)
+            res.writeHead(400).end();
+    });
+}
+// The agnostic consumer (`vincentt feedback --wait`) long-polls this: return the
+// next annotation after `after`, or 204 when the hold window elapses.
+function handleFeedbackNext(res, url, ctx) {
+    if (!ctx.annotations) {
+        res.writeHead(503).end("reverse channel not enabled");
+        return;
+    }
+    const after = Number(url.searchParams.get("after") ?? "0") || 0;
+    const timeoutMs = Math.min(Number(url.searchParams.get("timeout") ?? "300000") || 300_000, MAX_FEEDBACK_TIMEOUT_MS);
+    ctx.annotations
+        .nextAfter(after, timeoutMs)
+        .then((annotation) => {
+        if (!annotation) {
+            res.writeHead(204).end();
+            return;
+        }
+        res
+            .writeHead(200, { "content-type": "application/json" })
+            .end(JSON.stringify(annotation));
+    })
+        .catch((err) => {
+        ctx.log(`feedback error: ${err}`);
+        if (!res.headersSent)
+            res.writeHead(400).end();
+    });
+}
+async function readQuery(req, url) {
+    if (req.method === "POST") {
+        const body = await readBody(req);
+        return body ? JSON.parse(body) : {};
+    }
+    const q = {};
+    const p = url.searchParams;
+    if (p.get("sessionId"))
+        q.sessionId = p.get("sessionId");
+    if (p.get("kind"))
+        q.kind = p.get("kind");
+    if (p.get("since"))
+        q.since = Number(p.get("since"));
+    if (p.get("limit"))
+        q.limit = Number(p.get("limit"));
+    return q;
+}
+function readBody(req, maxBytes = Infinity) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        let bytes = 0;
+        req.on("data", (c) => {
+            bytes += c.length;
+            if (bytes > maxBytes) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            data += c;
+        });
+        req.on("end", () => resolve(data));
+        req.on("error", reject);
+    });
+}

package/dist/relay/store.d.ts

@@ -0,0 +1,13 @@
+import type { DiagEvent, RelayQuery, RelayResult } from "@vincentt-xr/harness/events";
+export declare class EventStore {
+    private readonly capacity;
+    private readonly buf;
+    private readonly sessionsSeen;
+    private latest;
+    constructor(capacity?: number);
+    /** Ingest a batch from a client. Tracks the session and advances latestSeq. */
+    ingest(sessionId: string, events: DiagEvent[]): void;
+    /** Answer an MCP query against the buffer. Newest-biased when limited. */
+    query(q?: RelayQuery): RelayResult;
+    size(): number;
+}

package/dist/relay/store.js

@@ -0,0 +1,68 @@
+// The relay's memory: a bounded ring buffer of recent diagnostics events,
+// queryable the way the MCP server asks ("network events since seq 40", "last
+// 20 errors"). Pure and dependency-free so it is fully unit-testable; the WS
+// server in server.ts is a thin wrapper that feeds this and answers queries
+// from it.
+export class EventStore {
+    capacity;
+    buf = [];
+    sessionsSeen = new Set();
+    latest = -1;
+    constructor(capacity = 5000) {
+        this.capacity = capacity;
+    }
+    /** Ingest a batch from a client. Tracks the session and advances latestSeq. */
+    ingest(sessionId, events) {
+        this.sessionsSeen.add(sessionId);
+        for (const e of events) {
+            // Tag ownership on the stored copy so cross-session queries can filter.
+            this.buf.push(withSession(e, sessionId));
+            if (e.seq > this.latest)
+                this.latest = e.seq;
+        }
+        // Ring: drop oldest beyond capacity.
+        if (this.buf.length > this.capacity) {
+            this.buf.splice(0, this.buf.length - this.capacity);
+        }
+    }
+    /** Answer an MCP query against the buffer. Newest-biased when limited. */
+    query(q = {}) {
+        let out = this.buf.filter((e) => {
+            if (q.sessionId && sessionOf(e) !== q.sessionId)
+                return false;
+            if (q.kind && e.kind !== q.kind)
+                return false;
+            if (q.since !== undefined && e.seq <= q.since)
+                return false;
+            return true;
+        });
+        if (q.limit !== undefined && out.length > q.limit) {
+            out = out.slice(out.length - q.limit); // keep the newest `limit`
+        }
+        return {
+            events: out.map(stripSession),
+            latestSeq: this.latest,
+            sessions: [...this.sessionsSeen],
+        };
+    }
+    size() {
+        return this.buf.length;
+    }
+}
+// The store tags each event with its owning session out-of-band (a symbol key)
+// so it survives in the buffer without polluting the wire type. Queries strip
+// it before returning.
+const SESSION = Symbol("session");
+function withSession(e, sessionId) {
+    return Object.assign(Object.create(Object.getPrototypeOf(e)), e, {
+        [SESSION]: sessionId,
+    });
+}
+function sessionOf(e) {
+    return e[SESSION];
+}
+function stripSession(e) {
+    const copy = { ...e };
+    delete copy[SESSION];
+    return copy;
+}

package/dist/scaffold/index.d.ts

@@ -0,0 +1,26 @@
+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>;
+/**
+ * True when `dir` has no app yet (no package.json) → safe to scaffold into.
+ * A directory that already holds an app is left untouched (project_create just binds).
+ */
+export declare function needsScaffold(dir: string): Promise<boolean>;
+export interface ScaffoldOptions {
+    repo?: string;
+    /** Test seam — defaults to spawning real git. */
+    runGit?: GitRunner;
+}
+/**
+ * Scaffold the template into `targetDir`. Clones to a temp dir, strips `.git`,
+ * copies the files in (never overwriting anything already there), then inits a
+ * 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

@@ -0,0 +1,85 @@
+// Scaffold a new app from the v2-template GitHub template as part of
+// project_create. Shallow-clones the template, drops its git history, copies the
+// files into the target, and inits a fresh repo the creator owns — the local-first
+// equivalent of GitHub's "Use this template". Node-only (spawns git); not imported
+// by browser consumers.
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
+const realGit = async (args) => {
+    await execFileAsync("git", args);
+};
+/**
+ * True when `dir` has no app yet (no package.json) → safe to scaffold into.
+ * A directory that already holds an app is left untouched (project_create just binds).
+ */
+export async function needsScaffold(dir) {
+    try {
+        await fs.access(path.join(dir, "package.json"));
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Scaffold the template into `targetDir`. Clones to a temp dir, strips `.git`,
+ * copies the files in (never overwriting anything already there), then inits a
+ * fresh repo. Throws a clear error if the clone fails (e.g. no git access).
+ */
+export async function scaffoldFromTemplate(targetDir, opts = {}) {
+    const repo = opts.repo ?? TEMPLATE_REPO;
+    const runGit = opts.runGit ?? realGit;
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "vincentt-tmpl-"));
+    try {
+        try {
+            await runGit(["clone", "--depth", "1", repo, tmp]);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Could not clone the ${repo} template (check your git access): ${msg}`);
+        }
+        await fs.rm(path.join(tmp, ".git"), { recursive: true, force: true });
+        // Copy template contents in without clobbering anything already in the target.
+        for (const entry of await fs.readdir(tmp)) {
+            await fs.cp(path.join(tmp, entry), path.join(targetDir, entry), {
+                recursive: true,
+                force: false,
+                errorOnExist: false,
+            });
+        }
+        // Fresh history the creator owns (skip if the target is already a repo).
+        if (!(await isGitRepo(targetDir))) {
+            await runGit(["-C", targetDir, "init"]);
+        }
+    }
+    finally {
+        await fs.rm(tmp, { recursive: true, force: true });
+    }
+}
+async function isGitRepo(dir) {
+    try {
+        await execFileAsync("git", ["-C", dir, "rev-parse", "--git-dir"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install a freshly scaffolded project's dependencies so the first preview/build
+ * doesn't fail on a missing node_modules. Throws on failure (no network, no npm);
+ * the caller surfaces it as a "run npm install yourself" hint rather than aborting
+ * project creation.
+ */
+export async function installDependencies(dir) {
+    // Windows: npm is npm.cmd — execFile needs a shell to resolve it.
+    await execFileAsync("npm", ["install"], {
+        cwd: dir,
+        shell: process.platform === "win32",
+    });
+}

package/dist/shared/config.d.ts

@@ -0,0 +1,47 @@
+export interface MachineConfig {
+    /** Base URL of the Vincentt backend API (e.g. https://api.vincentt.studio). */
+    apiUrl: string;
+    /** Personal access token (bearer) for machine auth. */
+    pat: string;
+}
+export interface ProjectBinding {
+    /** The backend Project id this working tree publishes to. */
+    projectId: string;
+    /** The project's slug — its <slug>.<apex> host. Informational (server-authoritative). */
+    slug: string;
+    /** Optional per-project API override; else the machine config's apiUrl. */
+    apiUrl?: string;
+}
+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>;
+/**
+ * Remove the stored PAT from ~/.vincentt/config.json (used by `vincentt logout`),
+ * preserving apiUrl and any other fields. Returns whether a token was present.
+ */
+export declare function clearMachineToken(): Promise<{
+    path: string;
+    hadToken: boolean;
+}>;
+export declare function loadProjectBinding(cwd: string): Promise<ProjectBinding | undefined>;
+/**
+ * Write the per-tree binding and make sure `.vincentt/` is gitignored (so the
+ * secret-free-but-tenant-scoped binding never rides a commit or `git archive`).
+ */
+export declare function writeProjectBinding(cwd: string, binding: ProjectBinding): Promise<string>;
+export interface ResolvedConfig {
+    apiUrl: string;
+    pat: string;
+}
+/**
+ * Resolve the API URL + PAT for a machine call. Precedence: a project binding's
+ * apiUrl wins for the URL; env vars override the machine-config file; the file is
+ * the base. Throws a clear, actionable error when no PAT is configured.
+ */
+export declare function resolveConfig(cwd: string): Promise<ResolvedConfig>;

package/dist/shared/config.js

@@ -0,0 +1,105 @@
+// Config the lifecycle MCP verbs (project_create / project_publish) read to reach
+// a creator's Vincentt backend. Two homes, by sensitivity:
+//   • ~/.vincentt/config.json — machine-global { apiUrl, pat }. The PAT is a
+//     bearer credential, so it lives OUTSIDE any repo (never committed).
+//   • <project>/.vincentt/project.json — the per-tree binding { projectId, slug }.
+//     Gitignored: `git archive HEAD` (the remix path) must NOT carry it, or a
+//     remixer would inherit — and publish over — the original's project.
+// Env vars (VINCENTT_API_URL / VINCENTT_PAT) override the file for local/dogfood
+// runs so a creator can point at a dev backend without editing the machine config.
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const MACHINE_CONFIG_PATH = path.join(os.homedir(), ".vincentt", "config.json");
+const BINDING_DIR = ".vincentt";
+const BINDING_FILE = "project.json";
+export function projectBindingPath(cwd) {
+    return path.join(cwd, BINDING_DIR, BINDING_FILE);
+}
+async function readJsonIfExists(p) {
+    try {
+        return JSON.parse(await fs.readFile(p, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+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;
+}
+/**
+ * Remove the stored PAT from ~/.vincentt/config.json (used by `vincentt logout`),
+ * preserving apiUrl and any other fields. Returns whether a token was present.
+ */
+export async function clearMachineToken() {
+    const current = await loadMachineConfig();
+    const hadToken = Boolean(current.pat);
+    delete current.pat;
+    await fs.mkdir(path.dirname(MACHINE_CONFIG_PATH), { recursive: true, mode: 0o700 });
+    await fs.writeFile(MACHINE_CONFIG_PATH, JSON.stringify(current, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return { path: MACHINE_CONFIG_PATH, hadToken };
+}
+export async function loadProjectBinding(cwd) {
+    return readJsonIfExists(projectBindingPath(cwd));
+}
+/**
+ * Write the per-tree binding and make sure `.vincentt/` is gitignored (so the
+ * secret-free-but-tenant-scoped binding never rides a commit or `git archive`).
+ */
+export async function writeProjectBinding(cwd, binding) {
+    await fs.mkdir(path.join(cwd, BINDING_DIR), { recursive: true });
+    const p = projectBindingPath(cwd);
+    await fs.writeFile(p, JSON.stringify(binding, null, 2) + "\n", "utf8");
+    await ensureGitignored(cwd, `${BINDING_DIR}/`);
+    return p;
+}
+/** Append a pattern to the repo's .gitignore if not already present (best-effort). */
+async function ensureGitignored(cwd, pattern) {
+    const gitignore = path.join(cwd, ".gitignore");
+    try {
+        const current = await fs.readFile(gitignore, "utf8").catch(() => "");
+        const has = current.split(/\r?\n/).some((l) => l.trim() === pattern.trim());
+        if (has)
+            return;
+        const next = current && !current.endsWith("\n") ? `${current}\n${pattern}\n` : `${current}${pattern}\n`;
+        await fs.writeFile(gitignore, next, "utf8");
+    }
+    catch {
+        // A missing/unwritable .gitignore must not fail project creation.
+    }
+}
+/**
+ * Resolve the API URL + PAT for a machine call. Precedence: a project binding's
+ * apiUrl wins for the URL; env vars override the machine-config file; the file is
+ * the base. Throws a clear, actionable error when no PAT is configured.
+ */
+export async function resolveConfig(cwd) {
+    const machine = await loadMachineConfig();
+    const binding = await loadProjectBinding(cwd);
+    const apiUrl = binding?.apiUrl ?? process.env.VINCENTT_API_URL ?? machine.apiUrl ?? "http://localhost:5051";
+    const pat = process.env.VINCENTT_PAT ?? machine.pat;
+    if (!pat) {
+        throw new Error(`No Vincentt access token found. Add {"apiUrl":"…","pat":"…"} to ${MACHINE_CONFIG_PATH}, ` +
+            `or set the VINCENTT_PAT env var.`);
+    }
+    return { apiUrl: apiUrl.replace(/\/$/, ""), pat };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vincentt-xr/cli",
+  "version": "0.1.0",
+  "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay, mcp)",
+  "license": "UNLICENSED",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./preview": {
+      "types": "./dist/preview/index.d.ts",
+      "import": "./dist/preview/index.js"
+    },
+    "./relay": {
+      "types": "./dist/relay/server.d.ts",
+      "import": "./dist/relay/server.js"
+    }
+  },
+  "bin": {
+    "vincentt": "./dist/cli/index.js",
+    "harness": "./dist/cli/deprecated/harness.js",
+    "harness-mcp": "./dist/cli/deprecated/harness-mcp.js",
+    "harness-relay": "./dist/cli/deprecated/harness-relay.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cloudflared": "^0.7.1",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8",
+    "@vincentt-xr/harness": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}