@vincentt-xr/cli 0.3.0 → 0.4.1

package/README.md

@@ -68,7 +68,9 @@ Reverse channel
 
 Servers
   relay              Run the diagnostics/annotation relay
-  mcp                Run the MCP adapter (for hosts without a shell)
+
+Meta
+  version            CLI version, and the API this machine resolves to
 
 Common options: --dir <path> (project dir, default cwd)
 ```

package/dist/cli/args.d.ts

@@ -5,6 +5,14 @@
  * usage instead of running the (side-effectful) verb.
  */
 export declare function isHelpInvocation(args: string[]): boolean;
+/**
+ * True for `vincentt --version` / `-v` — the flag form, as the FIRST argument
+ * only. Unlike `--help`, this is deliberately not honored anywhere in the args:
+ * `--help` is safe to obey late because it cancels the action, whereas treating
+ * a trailing `-v` on `vincentt publish -v` as "print the version" would silently
+ * skip a publish the creator asked for. Anywhere else it stays an unknown flag.
+ */
+export declare function isVersionInvocation(args: string[]): boolean;
 export declare function refusedFlag(args: string[]): string | undefined;
 /**
  * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir

package/dist/cli/args.js

@@ -7,6 +7,16 @@
 export function isHelpInvocation(args) {
     return args[0] === undefined || args.includes("--help") || args.includes("-h");
 }
+/**
+ * True for `vincentt --version` / `-v` — the flag form, as the FIRST argument
+ * only. Unlike `--help`, this is deliberately not honored anywhere in the args:
+ * `--help` is safe to obey late because it cancels the action, whereas treating
+ * a trailing `-v` on `vincentt publish -v` as "print the version" would silently
+ * skip a publish the creator asked for. Anywhere else it stays an unknown flag.
+ */
+export function isVersionInvocation(args) {
+    return args[0] === "--version" || args[0] === "-v";
+}
 /** Flags that stand alone; every other `--flag` consumes the next argument. */
 const BOOLEAN_FLAGS = new Set([
     "--force",

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/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.
+// `vincentt` — the CLI for the local-first dev loop, and the only surface. A human
+// and a bash-capable coding agent drive the same verbs, so there is nothing to
+// register: an agent that can run a shell command already has the whole product.
 //
 // Verb groups:
 //   auth        login · logout · whoami
@@ -9,7 +9,9 @@
 //   dev loop    publish · preview
 //   diagnostics logs · network · trace
 //   reverse     feedback (--wait | --watch)
-//   servers     relay · mcp
+//   servers     relay
+//   meta        version
+import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { runPkceLogin } from "../login/pkceLogin.js";
@@ -21,9 +23,10 @@ import { getMe, ProjectUnreachableError } from "../lib/backend.js";
 import { initCommand } from "../lib/initCommand.js";
 import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
 import { whoamiCommand } from "../lib/whoami.js";
+import { renderVersion, versionReport } from "../lib/version.js";
 import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, } from "../lib/lifecycle.js";
 import { publishCommand } from "../publish/command.js";
-import { stdinConfirm } from "../publish/prompt.js";
+import { stdinAsk, stdinConfirm } from "../publish/prompt.js";
 import { consoleVerbCommand, isConsoleOnlyVerb } from "../publish/consoleVerbs.js";
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
@@ -32,7 +35,7 @@ import { mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../p
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
 import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
-import { isHelpInvocation, positionalArgs, refusedFlag } from "./args.js";
+import { isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag } from "./args.js";
 // The console origin serves /cli-auth (the browser target for `vincentt login`). VINCENTT_
 // CONSOLE_URL overrides for dev/dogfood; VINCENTT_EDITOR_URL is honored as a legacy alias.
 const DEFAULT_CONSOLE_URL = "https://vincentt.app";
@@ -59,18 +62,20 @@ function positional(n) {
     return positionalArgs(argv)[n];
 }
 // ---- auth -------------------------------------------------------------------
-function resolveAuthUrls() {
+async function resolveAuthUrls() {
+    const machine = await loadMachineConfig();
     const consoleUrl = flag("--console") ??
         flag("--editor") ??
         process.env.VINCENTT_CONSOLE_URL ??
         process.env.VINCENTT_EDITOR_URL ??
+        machine.consoleUrl ??
         DEFAULT_CONSOLE_URL;
-    const apiUrl = flag("--api") ?? process.env.VINCENTT_API_URL ?? DEFAULT_API_URL;
+    const apiUrl = flag("--api") ?? process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
     return { consoleUrl, apiUrl };
 }
 /** The PKCE loopback + code-exchange login (f1). The raw PAT never rides a redirect query. */
 async function runLoginFlow() {
-    const { consoleUrl, apiUrl } = resolveAuthUrls();
+    const { consoleUrl, apiUrl } = await resolveAuthUrls();
     return runPkceLogin({
         consoleUrl,
         apiUrl,
@@ -79,7 +84,7 @@ async function runLoginFlow() {
 }
 /** `vincentt login` [--force] — the L1/L2/L4 transcripts. */
 async function login() {
-    const { apiUrl } = resolveAuthUrls();
+    const { apiUrl } = await resolveAuthUrls();
     const code = await loginCommand({
         print: (line) => console.log(line),
         currentToken,
@@ -146,7 +151,20 @@ async function whoami() {
 }
 // ---- project ----------------------------------------------------------------
 async function init() {
-    process.exitCode = await initCommand({ print: (l) => console.log(l), cwd: process.cwd() }, { dir: positional(1), skipInstall: has("--no-install") });
+    // Both prompts are omitted when stdin is not a TTY, and initCommand reads their
+    // ABSENCE as "may not ask" — so a piped or CI invocation refuses rather than
+    // blocking forever on a question nobody can see.
+    const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    process.exitCode = await initCommand({
+        print: (l) => console.log(l),
+        cwd: process.cwd(),
+        ask: interactive ? stdinAsk() : undefined,
+        confirm: interactive ? stdinConfirm() : undefined,
+    }, {
+        dir: positional(1),
+        skipInstall: has("--no-install"),
+        template: flag("--template"),
+    });
 }
 async function create() {
     await requireLogin();
@@ -498,11 +516,32 @@ async function feedback() {
         await writeCursor(cwd, annotation.seq);
     } while (watch);
 }
-// ---- servers ----------------------------------------------------------------
-async function mcp() {
-    const { runStdio } = await import("../mcp/server.js");
-    await runStdio({ relayUrl: flag("--relay-url") });
+// ---- meta -------------------------------------------------------------------
+/**
+ * The running package's version, read from the manifest rather than baked in by
+ * the build — a hardcoded string is one forgotten edit away from a CLI that
+ * misreports itself, which is worse than not having the command at all.
+ * `src/cli/` and the emitted `dist/cli/` sit at the same depth, so one relative
+ * path serves both.
+ */
+function cliVersion() {
+    try {
+        const manifest = createRequire(import.meta.url)("../../package.json");
+        return manifest.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function version() {
+    const report = await versionReport(projectDir(), {
+        cliVersion: cliVersion(),
+        allowCustomApi: has("--allow-custom-api"),
+    });
+    for (const line of renderVersion(report))
+        console.log(line);
 }
+// ---- servers ----------------------------------------------------------------
 async function relay() {
     const { startRelay } = await import("../relay/server.js");
     const port = numFlag("--port") ?? 7331;
@@ -526,11 +565,12 @@ function usage() {
         `  Full guide: npm view @vincentt-xr/cli readme\n\n` +
         `Auth\n` +
         `  login              Sign in; save an access token to ~/.vincentt/config.json\n` +
+        `                       [--api <url>] [--console <url>] to target a non-prod env\n` +
         `  logout             Remove the saved access token\n` +
         `  whoami             Show the signed-in account\n\n` +
         `Project\n` +
         `  init [dir]         Scaffold a Vincentt XR app — no account needed\n` +
-        `                       [--no-install]\n` +
+        `                       [--no-install] [--template <version>]\n` +
         `  create             Register a project and reserve its address\n` +
         `                       [--name <s>] [--slug <s>] [--org <s>] [--preview] [--force]\n` +
         `  link <project-id>  Link this folder to an existing project\n` +
@@ -551,13 +591,19 @@ function usage() {
         `  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` +
+        `  relay              Run the diagnostics/annotation relay\n\n` +
+        `Meta\n` +
+        `  version            CLI version, and the API this machine resolves to\n\n` +
         `Common options: --dir <path> (project dir, default cwd)\n` +
         `                --allow-custom-api  honor a binding's apiUrl override\n`);
 }
 async function main() {
     const cmd = argv[0];
+    // Checked BEFORE the help gate: `--version` is a lone flag with no verb, which
+    // the help gate would otherwise answer with usage — the one response that does
+    // not contain the version.
+    if (isVersionInvocation(argv))
+        return version();
     // `--help`/`-h` anywhere means "explain, don't act" — never let it fall through to
     // a verb. Otherwise `login --help` runs login, `create --help` scaffolds, etc.
     if (isHelpInvocation(argv)) {
@@ -565,6 +611,8 @@ async function main() {
         return;
     }
     switch (cmd) {
+        case "version":
+            return version();
         case "login":
             return login();
         case "logout":
@@ -591,8 +639,6 @@ async function main() {
             return diag("trace");
         case "feedback":
             return feedback();
-        case "mcp":
-            return mcp();
         case "relay":
             return relay();
         default:

package/dist/lib/initCommand.d.ts

@@ -1,14 +1,31 @@
+import type { Ask, Confirm } from "../publish/prompt.js";
 export interface InitDeps {
     print: (line: string) => void;
     cwd: string;
-    scaffold?: (targetDir: string) => Promise<void>;
+    scaffold?: (targetDir: string, ref?: string) => Promise<void>;
     install?: (targetDir: string) => Promise<string>;
     isEmpty?: (targetDir: string) => Promise<boolean>;
+    /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
+    ask?: Ask;
+    /** y/N prompt. Absent → not a TTY. */
+    confirm?: Confirm;
+    /** Non-empty check for the resolved target; injected in tests. */
+    isNonEmpty?: (targetDir: string) => Promise<boolean>;
 }
+/** The folder name offered when `init` is run bare and the creator just hits Enter. */
+export declare const DEFAULT_APP_NAME = "my-ar-app";
+/**
+ * A folder name safe to create from a typed answer. Keeps this from becoming a
+ * path-traversal seam: the answer names a child of the cwd, never `../` upward and
+ * never an absolute path.
+ */
+export declare function sanitizeAppName(answer: string): string | null;
 export interface InitOptions {
     /** Positional target directory; defaults to the cwd. */
     dir?: string;
     /** Skip the dependency install (CI, or a creator who wants to pick a manager). */
     skipInstall?: boolean;
+    /** Template version to scaffold from; defaults to the latest release. */
+    template?: string;
 }
 export declare function initCommand(deps: InitDeps, opts?: InitOptions): Promise<number>;

package/dist/lib/initCommand.js

@@ -6,10 +6,49 @@
 // does need an account) is offered at the end as the next thing AVAILABLE, never as
 // a requirement.
 import path from "node:path";
-import { detectPackageManager, installDependencies, needsScaffold, scaffoldFromTemplate, } from "../scaffold/index.js";
+import { detectPackageManager, installDependencies, isNonEmptyDir, needsScaffold, scaffoldFromTemplate, } from "../scaffold/index.js";
+/** The folder name offered when `init` is run bare and the creator just hits Enter. */
+export const DEFAULT_APP_NAME = "my-ar-app";
+/**
+ * A folder name safe to create from a typed answer. Keeps this from becoming a
+ * path-traversal seam: the answer names a child of the cwd, never `../` upward and
+ * never an absolute path.
+ */
+export function sanitizeAppName(answer) {
+    const trimmed = answer.trim();
+    if (trimmed === "" || trimmed === "." || trimmed === "..")
+        return null;
+    if (trimmed.includes("/") || trimmed.includes("\\"))
+        return null;
+    if (trimmed.startsWith("-"))
+        return null;
+    return trimmed;
+}
 export async function initCommand(deps, opts = {}) {
-    const target = path.resolve(deps.cwd, opts.dir ?? ".");
-    const label = opts.dir ? `./${opts.dir}` : ".";
+    // Resolve WHERE before checking what is there. Bare `init` used to mean "here",
+    // which is the surprising reading — a creator typing it in their home directory
+    // meant "make me an app", not "fill this folder with one".
+    let dir = opts.dir;
+    if (dir === undefined) {
+        if (!deps.ask) {
+            deps.print("✗ init needs a target directory when it can't ask.");
+            deps.print("");
+            deps.print("  vincentt init <dir>   Scaffold into a new folder");
+            deps.print("  vincentt init .       Scaffold into the current folder");
+            return 1;
+        }
+        const answer = await deps.ask(`Project name: (${DEFAULT_APP_NAME}) `, DEFAULT_APP_NAME);
+        const name = sanitizeAppName(answer);
+        if (name === null) {
+            deps.print(`✗ "${answer.trim()}" is not a folder name.`);
+            deps.print("");
+            deps.print("  Use a plain name (my-ar-app), or `vincentt init .` for this folder.");
+            return 1;
+        }
+        dir = name;
+    }
+    const target = path.resolve(deps.cwd, dir);
+    const label = dir === "." ? "." : `./${dir}`;
     const isEmpty = deps.isEmpty ?? needsScaffold;
     if (!(await isEmpty(target))) {
         deps.print(`✗ ${label} already contains an app (package.json).`);
@@ -18,11 +57,34 @@ export async function initCommand(deps, opts = {}) {
         deps.print("  vincentt create           Register THIS folder as a project");
         return 1;
     }
+    // No package.json, but not empty either — the case the old guard waved through.
+    const isNonEmpty = deps.isNonEmpty ?? isNonEmptyDir;
+    if (await isNonEmpty(target)) {
+        if (!deps.confirm) {
+            deps.print(`✗ ${label} is not empty, and I can't ask whether to add to it.`);
+            deps.print("");
+            deps.print("  vincentt init <dir>   Scaffold into a new folder instead");
+            return 1;
+        }
+        deps.print(`! ${label} is not empty. Scaffolding adds the template's files alongside what's there.`);
+        deps.print("  Existing files are never overwritten.");
+        if (!(await deps.confirm("? Continue? (y/N) ", false))) {
+            deps.print("");
+            deps.print("  Nothing was written.");
+            return 1;
+        }
+    }
     deps.print(`→ Scaffolding a Vincentt XR app in ${label}…`);
     deps.print("  · React + react-three-fiber + @vincentt-xr/sdk");
-    const scaffold = deps.scaffold ?? ((dir) => scaffoldFromTemplate(dir));
+    // Only announce the version when it was asked for. On the default path the ref
+    // is an implementation detail, and naming it would invite creators to pin a
+    // version they have no reason to care about.
+    if (opts.template)
+        deps.print(`  · template ${opts.template}`);
+    const scaffold = deps.scaffold ??
+        ((dir, ref) => scaffoldFromTemplate(dir, { ref }));
     try {
-        await scaffold(target);
+        await scaffold(target, opts.template);
     }
     catch (err) {
         deps.print("");
@@ -50,8 +112,9 @@ export async function initCommand(deps, opts = {}) {
     deps.print(`✓ Created ${label}`);
     deps.print("");
     const steps = [];
-    if (opts.dir)
-        steps.push([`cd ${opts.dir}`, ""]);
+    // Keyed off the RESOLVED dir, not the flag — a prompted name needs the cd too.
+    if (dir !== ".")
+        steps.push([`cd ${dir}`, ""]);
     if (!installed || opts.skipInstall) {
         steps.push([`${pm} install`, "Install dependencies"]);
     }

package/dist/lib/version.d.ts

@@ -0,0 +1,34 @@
+export interface VersionReport {
+    cliVersion: string;
+    nodeVersion: string;
+    apiUrl: string;
+    /** Where apiUrl came from, in creator-facing words. */
+    apiSource: string;
+    /** Set when a binding names a different API that was NOT used. */
+    ignoredBindingApiUrl?: string;
+    /** True when the resolved host is the built-in fallback (nothing configured). */
+    isDefault: boolean;
+}
+export interface VersionEnv {
+    envApiUrl?: string;
+    machineApiUrl?: string;
+    bindingApiUrl?: string;
+    allowCustomApi?: boolean;
+    nodeVersion: string;
+    cliVersion: string;
+}
+/**
+ * Decide what to report. Pure, so the transcript is testable without a home
+ * directory, an env var, or a built package.
+ */
+export declare function buildVersionReport(env: VersionEnv): VersionReport;
+/**
+ * The transcript. Two aligned columns so the host and its provenance read as one
+ * fact, not two.
+ */
+export declare function renderVersion(r: VersionReport): string[];
+/** Read the machine's real state and produce the report. */
+export declare function versionReport(cwd: string, opts: {
+    cliVersion: string;
+    allowCustomApi?: boolean;
+}): Promise<VersionReport>;

package/dist/lib/version.js

@@ -0,0 +1,82 @@
+// `vincentt version` — which CLI is running, and which backend it will actually
+// talk to.
+//
+// The second half is the point. A creator can have the right CLI pointed at the
+// wrong API (a leftover VINCENTT_API_URL, a machine config written months ago,
+// or the localhost default on a fresh install), and every failure that follows
+// reads like a server outage rather than a misconfiguration. So this reports the
+// resolved host AND its provenance, using the same decideApiUrl the real verbs
+// use — a version command that re-derived the URL could disagree with them.
+import { decideApiUrl, loadMachineConfig, locateProjectBinding, } from "../shared/config.js";
+/**
+ * Decide what to report. Pure, so the transcript is testable without a home
+ * directory, an env var, or a built package.
+ */
+export function buildVersionReport(env) {
+    const decided = decideApiUrl({
+        bindingApiUrl: env.bindingApiUrl,
+        envApiUrl: env.envApiUrl,
+        machineApiUrl: env.machineApiUrl,
+        allowCustomApi: env.allowCustomApi,
+    });
+    let apiSource;
+    let isDefault = false;
+    if (decided.usedBindingApiUrl) {
+        apiSource = "this folder's binding (--allow-custom-api)";
+    }
+    else if (env.envApiUrl) {
+        apiSource = "VINCENTT_API_URL";
+    }
+    else if (env.machineApiUrl) {
+        apiSource = "~/.vincentt/config.json";
+    }
+    else {
+        apiSource = "built-in default";
+        isDefault = true;
+    }
+    return {
+        cliVersion: env.cliVersion,
+        nodeVersion: env.nodeVersion,
+        apiUrl: decided.apiUrl,
+        apiSource,
+        ignoredBindingApiUrl: decided.ignoredBindingApiUrl,
+        isDefault,
+    };
+}
+/**
+ * The transcript. Two aligned columns so the host and its provenance read as one
+ * fact, not two.
+ */
+export function renderVersion(r) {
+    const out = [
+        "",
+        `vincentt ${r.cliVersion}`,
+        "",
+        `  api     ${r.apiUrl}`,
+        `          from ${r.apiSource}`,
+    ];
+    // A localhost default on a machine that never configured anything is the
+    // single most confusing state to be in: every verb fails with a connection
+    // error that looks like the platform is down.
+    if (r.isDefault && /localhost|127\.0\.0\.1/.test(r.apiUrl)) {
+        out.push("", "  !  Nothing is configured, so this points at a local backend.", "     Set VINCENTT_API_URL, or run `vincentt login` to save one.");
+    }
+    if (r.ignoredBindingApiUrl) {
+        out.push("", `  !  This folder's binding names a different API (${r.ignoredBindingApiUrl})`, "     and was ignored. Re-run with --allow-custom-api to use it.");
+    }
+    out.push("", `  node    ${r.nodeVersion}`, "");
+    return out;
+}
+/** Read the machine's real state and produce the report. */
+export async function versionReport(cwd, opts) {
+    const machine = await loadMachineConfig();
+    const located = await locateProjectBinding(cwd);
+    return buildVersionReport({
+        envApiUrl: process.env.VINCENTT_API_URL,
+        machineApiUrl: machine.apiUrl,
+        bindingApiUrl: located?.binding.apiUrl,
+        allowCustomApi: opts.allowCustomApi,
+        nodeVersion: process.version,
+        cliVersion: opts.cliVersion,
+    });
+}

package/dist/publish/prompt.d.ts

@@ -1,4 +1,7 @@
 export type Confirm = (prompt: string, defaultYes: boolean) => Promise<boolean>;
 /** Reads one line from stdin. Anything that is not an explicit answer takes the default. */
 export declare function stdinConfirm(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Confirm;
+/** Reads one free-text line. An empty answer takes the offered default. */
+export type Ask = (prompt: string, fallback: string) => Promise<string>;
+export declare function stdinAsk(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Ask;
 export declare function interpretAnswer(answer: string, defaultYes: boolean): boolean;

package/dist/publish/prompt.js

@@ -17,6 +17,18 @@ export function stdinConfirm(input = process.stdin, output = process.stdout) {
         }
     };
 }
+export function stdinAsk(input = process.stdin, output = process.stdout) {
+    return async (prompt, fallback) => {
+        const rl = readline.createInterface({ input, output });
+        try {
+            const answer = await new Promise((resolve) => rl.question(prompt, resolve));
+            return answer.trim() === "" ? fallback : answer.trim();
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
 export function interpretAnswer(answer, defaultYes) {
     const normalized = answer.trim().toLowerCase();
     if (normalized === "")

package/dist/scaffold/index.d.ts

@@ -1,4 +1,16 @@
 export declare 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 declare const DEFAULT_TEMPLATE_REF = "latest";
 /** Injectable git runner (real git by default; a fake in tests avoids the network). */
 export type GitRunner = (args: string[]) => Promise<void>;
 /**
@@ -6,8 +18,22 @@ export type GitRunner = (args: string[]) => Promise<void>;
  * A directory that already holds an app is left untouched (project_create just binds).
  */
 export declare function needsScaffold(dir: string): Promise<boolean>;
+/**
+ * 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 declare function isNonEmptyDir(dir: string): Promise<boolean>;
 export interface ScaffoldOptions {
     repo?: string;
+    /** Template ref (tag) to scaffold from. Defaults to `DEFAULT_TEMPLATE_REF`. */
+    ref?: string;
     /** Test seam — defaults to spawning real git. */
     runGit?: GitRunner;
 }

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/dist/shared/config.d.ts

@@ -1,6 +1,8 @@
 export interface MachineConfig {
     /** Base URL of the Vincentt backend API (e.g. https://api.vincentt.studio). */
     apiUrl: string;
+    /** Console origin that serves /cli-auth (e.g. https://vincentt.app); used by `login`. */
+    consoleUrl: string;
     /** Personal access token (bearer) for machine auth. */
     pat: string;
     /** Org slug commands act in when no --org flag or VINCENTT_ORG env is given. */

package/dist/shared/config.js

@@ -1,7 +1,7 @@
 // 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).
+//   • ~/.vincentt/config.json — machine-global { apiUrl, consoleUrl, 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.3.0",
-  "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay, mcp)",
+  "version": "0.4.1",
+  "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. A project's FIRST publish cannot be automated: it makes the address permanent, so the user must run `vincentt publish` in their own terminal once. Every publish after that works from here.",
-        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 () => {
-        // `yes` is the only value an MCP caller can pass: there is no terminal to
-        // prompt at. On a FIRST publish the command refuses it outright, which is
-        // what keeps an irreversible act off an agent's tool surface.
-        const result = await projectPublish(resolveProjectDir(baseProjectDir, projectDir), { distDir, note, yes: true });
-        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");
-}