@vincentt-xr/cli 0.2.0 → 0.4.0

package/dist/scaffold/index.js

@@ -10,6 +10,18 @@ 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";
+/**
+ * The template ref a scaffold resolves by default.
+ *
+ * `latest` is a MOVING tag on v2-template, force-updated by its Release workflow
+ * only after the tagged tree passes a frozen install + build + typecheck. Cloning
+ * it rather than the default branch is what stops an unreleased commit on the
+ * template's `main` from reaching every new creator the moment it merges.
+ *
+ * A creator pins a known version with `--template 1.0.0`; version tags are
+ * immutable, which is what makes that an escape hatch rather than a coin flip.
+ */
+export const DEFAULT_TEMPLATE_REF = "latest";
 const realGit = async (args) => {
     await execFileAsync("git", args);
 };
@@ -26,6 +38,27 @@ export async function needsScaffold(dir) {
         return true;
     }
 }
+/**
+ * True when `dir` exists and holds anything at all.
+ *
+ * `needsScaffold` only answers "is there an app here", which waves through a home
+ * directory, a notes folder, or any repo that is not a Node project — and the
+ * scaffold then scatters ~30 files into it. Nothing is overwritten (the copy is
+ * `force: false`), but the files are unlisted and separating them again is manual,
+ * so the creator is asked first.
+ *
+ * Dotfiles count. A folder holding only `.git` is a repo someone cares about.
+ */
+export async function isNonEmptyDir(dir) {
+    try {
+        const entries = await fs.readdir(dir);
+        return entries.length > 0;
+    }
+    catch {
+        // Missing (the common case for `init my-app`) is not non-empty.
+        return false;
+    }
+}
 /**
  * Scaffold the template into `targetDir`. Clones to a temp dir, strips `.git`,
  * copies the files in (never overwriting anything already there), then inits a
@@ -33,14 +66,23 @@ export async function needsScaffold(dir) {
  */
 export async function scaffoldFromTemplate(targetDir, opts = {}) {
     const repo = opts.repo ?? TEMPLATE_REPO;
+    const ref = opts.ref ?? DEFAULT_TEMPLATE_REF;
     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]);
+            await runGit(["clone", "--depth", "1", "--branch", ref, repo, tmp]);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
+            // A missing ref and a missing network both surface as a failed clone, and
+            // the remedies are opposite ("check your access" is useless advice when the
+            // real cause is a typo'd version). git names the ref in this specific case,
+            // so split on that rather than reporting one cause for both.
+            if (/(remote branch|Remote branch).*not found|couldn't find remote ref/i.test(msg)) {
+                throw new Error(`The template has no version "${ref}". ` +
+                    `Check the tag exists, or omit --template to use the latest release.`);
+            }
             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 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.2.0",
-  "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay, mcp)",
+  "version": "0.4.0",
+  "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
   "files": [
@@ -21,7 +21,6 @@
     "vincentt": "./dist/cli/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",

package/dist/mcp/server.d.ts

@@ -1,16 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type RelayClient } from "../lib/diagnostics.js";
-export interface McpOptions {
-    /** Base URL of the relay's HTTP endpoint (default matches the relay CLI). */
-    relayUrl?: string;
-    /** Injected for tests; defaults to an HTTP client against relayUrl. */
-    relay?: RelayClient;
-    /** Injected clock for deterministic relative-time rendering in tests. */
-    now?: () => number;
-    /** Project directory for the lifecycle verbs' binding. Defaults to process.cwd(). */
-    cwd?: string;
-}
-/** Reap the running preview, if any. Called by preview_stop and on server exit. */
-export declare function shutdownActivePreview(): Promise<void>;
-export declare function createHarnessMcp(opts?: McpOptions): McpServer;
-export declare function runStdio(opts?: McpOptions): Promise<void>;

package/dist/mcp/server.js

@@ -1,215 +0,0 @@
-// The agent-agnostic MCP server: a THIN adapter over the shared dev-loop lib
-// (../lib/lifecycle). Any MCP-capable agent (Claude Code, Codex, Cursor, Cline,
-// …) points its MCP config at `vincentt mcp` and gets the same verbs the CLI
-// exposes — diagnostics PULL tools plus the create/publish/preview lifecycle.
-// This file is only SDK wiring + argument shapes; all behavior lives in the lib,
-// so the CLI and MCP surfaces can never diverge.
-import path from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { httpRelayClient } from "../lib/diagnostics.js";
-import { diagRead, getActivePreview, previewStart, previewStop, projectCreate, projectPublish, } from "../lib/lifecycle.js";
-/** 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 {
-        return { content: [{ type: "text", text: await run() }] };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: msg }], isError: true };
-    }
-}
-/** Reap the running preview, if any. Called by preview_stop and on server exit. */
-export async function shutdownActivePreview() {
-    await previewStop();
-}
-// An MCP tool description is NOT documentation — it is the routing logic the
-// agent executes. The shipped `viewer` text sent an agent asked about "this
-// tester's phone" to the coordinate that churns, and the word doing the damage
-// was "device". It stays out of both descriptions below.
-//
-// There is no `sessionId` parameter. It took the raw client-supplied key, which
-// made a free-form string an agent could be talked into echoing the same leak
-// from the other direction.
-const sharedInput = {
-    tester: z
-        .string()
-        .optional()
-        .describe("Filter to ONE tester, e.g. `t1`. THIS IS THE FILTER YOU WANT for 'it breaks on their phone but not mine': a tester is one browser tab, recognised across refreshes, so it still resolves after the tester reloads — which they will have done before reporting the bug. Several testers normally share one preview and a merged stream is not debuggable. The ids currently connected are listed at the top of any unfiltered result."),
-    viewer: z
-        .string()
-        .optional()
-        .describe("Filter to ONE connection, e.g. `viewer-2`. This is the SUB-COORDINATE below `tester` and is rarely what you want: a single tab opens several connections, so this shows a fraction of one tester's traffic. A label identifies a CONNECTION, not a person; one that reconnects gets a new label and the old one is never reused. Use `tester` unless you are debugging a specific connection."),
-    since: z
-        .number()
-        .optional()
-        .describe("Return only events with seq greater than this. Use the latestSeq from a prior call to poll for new events."),
-    limit: z
-        .number()
-        .optional()
-        .describe("Cap the number of events returned (newest kept)."),
-};
-export function createHarnessMcp(opts = {}) {
-    // Diag tools read through this explicit client so the MCP server stays
-    // self-contained (works against a standalone relay without a relay.json file).
-    // preview_start re-points it at the live preview's relay port (OS-assigned).
-    let relayClient = opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
-    const now = opts.now ?? Date.now;
-    // 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.
-    const baseProjectDir = opts.cwd ?? process.env.VINCENTT_PROJECT_DIR ?? process.cwd();
-    const server = new McpServer({ name: "vincentt-harness", version: "0.1.0" });
-    server.registerTool("diag_logs", {
-        description: "Read console logs the preview app produced on the device. Use `errorsOnly` to see just errors, `since` to poll for new logs. Replaces the user pasting console output.",
-        inputSchema: {
-            ...sharedInput,
-            errorsOnly: z.boolean().optional().describe("Return only error-level logs."),
-        },
-    }, async ({ tester, viewer, since, limit, errorsOnly }) => ({
-        content: [
-            {
-                type: "text",
-                text: await diagRead(baseProjectDir, "log", { tester, viewer, since, limit, errorsOnly }, relayClient, now),
-            },
-        ],
-    }));
-    server.registerTool("diag_network", {
-        description: "Read fetch/XHR requests the preview app made on the device (method, URL, status, duration). Use to find failed asset loads or slow calls without DevTools.",
-        inputSchema: sharedInput,
-    }, async ({ tester, viewer, since, limit }) => ({
-        content: [
-            {
-                type: "text",
-                text: await diagRead(baseProjectDir, "network", { tester, viewer, since, limit }, relayClient, now),
-            },
-        ],
-    }));
-    server.registerTool("diag_trace", {
-        description: "Read performance samples from the device (fps, longest main-thread task, long-task count, phase marks). Replaces hand-exporting a DevTools trace to spot jank.",
-        inputSchema: sharedInput,
-    }, async ({ tester, viewer, since, limit }) => ({
-        content: [
-            {
-                type: "text",
-                text: await diagRead(baseProjectDir, "trace", { tester, viewer, since, limit }, relayClient, now),
-            },
-        ],
-    }));
-    server.registerTool("project_create", {
-        description: "Register a Vincentt project for this working directory and reserve its <slug>.vincentt.app address, then write the local .vincentt/project.json binding. This does NOT scaffold an app — run `vincentt init` first for that (it needs no account). Ask the user for a project name AND an address before calling; pass what they give. The address is never auto-assigned: if it is taken, this returns suggestions and creates nothing, so re-ask the user rather than picking one. The address is permanent once published. Run once per new app; publish with project_publish to go live.",
-        inputSchema: {
-            name: z
-                .string()
-                .optional()
-                .describe("Display name for the project. Defaults to the working-directory name."),
-            slug: z
-                .string()
-                .optional()
-                .describe("Desired address (<slug>.vincentt.app), lowercase kebab-case. Defaults to one derived from the name. Never auto-assigned on a collision. Permanent once published."),
-            org: z
-                .string()
-                .optional()
-                .describe("Slug of the organization to create the project in. Defaults to the user's active org."),
-            force: z
-                .boolean()
-                .optional()
-                .describe("Replace a binding this folder already has."),
-            ...projectDirInput,
-        },
-    }, async ({ name, slug, org, force, projectDir }) => guard(async () => {
-        const result = await projectCreate(resolveProjectDir(baseProjectDir, projectDir), {
-            name,
-            slug,
-            org,
-            force,
-        });
-        return result.message;
-    }));
-    server.registerTool("project_publish", {
-        description: "Publish the locally-built dist so this project goes live at <slug>.vincentt.app. Build first (e.g. npm run build), then call this — the dist is uploaded as-is and the server never rebuilds. Requires a prior project_create binding.",
-        inputSchema: {
-            distDir: z
-                .string()
-                .optional()
-                .describe("Path to the built dist directory, relative to the project (default: dist)."),
-            note: z
-                .string()
-                .optional()
-                .describe("Optional release note recorded with the version."),
-            ...projectDirInput,
-        },
-    }, async ({ distDir, note, projectDir }) => guard(async () => {
-        const result = await projectPublish(resolveProjectDir(baseProjectDir, projectDir), {
-            distDir,
-            note,
-        });
-        return result.message;
-    }));
-    server.registerTool("preview_start", {
-        description: "Start a live on-device preview: serves the app at an https link a phone can open, and wires the diagnostics relay so diag_logs/diag_network/diag_trace read from the connected devices. Returns the URL to open on a phone — no sign-in is needed on the phone, and several devices can open the same link at once. Requires a project_create binding and a signed-in account. The link is temporary: it stops working when the preview stops, and at a 12-hour maximum. One preview at a time per folder — call preview_stop before starting another. The dev server keeps running until preview_stop, so start it once and iterate.",
-        inputSchema: { ...projectDirInput },
-    }, async ({ projectDir }) => guard(async () => {
-        if (getActivePreview()) {
-            return `A preview is already running:\n${getActivePreview().url}\nCall preview_stop first to restart.`;
-        }
-        // App stdout would corrupt the MCP channel; route harness progress to stderr.
-        const { preview } = await previewStart(resolveProjectDir(baseProjectDir, projectDir), (m) => console.error(`[preview] ${m}`));
-        // Point the diag tools at this preview's relay (its port is OS-assigned).
-        relayClient = httpRelayClient(`http://localhost:${preview.relayPort}`);
-        const readiness = preview.appReady
-            ? ""
-            : `\nNote: the app on :${preview.appPort} isn't responding yet — the URL may be blank until its build finishes. Check diag_logs.`;
-        return (`Preview is live — open this on a device:\n${preview.url}\n\n` +
-            `No sign-in is needed on the phone, and several devices can open it at once.\n` +
-            `Diagnostics are live: diag_logs / diag_network / diag_trace read from the\n` +
-            `connected devices; pass \`tester\` to filter to one tester's stream.\n` +
-            // The GRANT, the session id and the edge hostname are absent, and stay
-            // absent. This text lands verbatim in an agent's transcript, which is
-            // exactly why f1's "a token is never printed" extends to grants.
-            `The link is temporary and stops working at ${preview.expiresAt}.\n` +
-            `Call preview_stop when finished.${readiness}`);
-    }));
-    server.registerTool("preview_stop", {
-        description: "Stop the running preview: ends the session, closes the tunnel, and tears down the app dev server and the diagnostics relay. The link stops working immediately. Safe to call when nothing is running.",
-        inputSchema: {},
-    }, async () => guard(async () => {
-        const stopped = await previewStop();
-        if (!stopped)
-            return "No preview is running.";
-        // The preview's relay is gone; send diag reads back to the default.
-        relayClient =
-            opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
-        return "Preview stopped. Tunnel and dev server torn down.";
-    }));
-    return server;
-}
-export async function runStdio(opts = {}) {
-    const server = createHarnessMcp(opts);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    // A running preview owns a child process + a live backend tunnel; reap both when
-    // the agent disconnects so we never leak a tunnel/DNS route past the session.
-    const shutdown = async () => {
-        await shutdownActivePreview();
-        process.exit(0);
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-    // stdout is the MCP channel — status goes to stderr only.
-    console.error("[vincentt mcp] connected over stdio");
-}