@vincentt-xr/cli 0.2.0 → 0.4.0

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,15 @@
  * 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
  * /tmp 66f1` reads `/tmp` as the project id — a wrong-but-plausible value, which is

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",
@@ -18,9 +28,19 @@ const BOOLEAN_FLAGS = new Set([
     "--stop",
     "--no-install",
     "--allow-custom-api",
+    "--yes",
     "--help",
     "-h",
 ]);
+/**
+ * Flags the CLI deliberately does NOT have. The checklist reports and never
+ * writes: a suggested value is one keystroke from a tool that writes it, and
+ * writing to the creator's source is a named boundary.
+ */
+const REFUSED_FLAGS = new Set(["--fix", "--write-meta"]);
+export function refusedFlag(args) {
+    return args.find((a) => REFUSED_FLAGS.has(a.split("=")[0]));
+}
 /**
  * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir
  * /tmp 66f1` reads `/tmp` as the project id — a wrong-but-plausible value, which is

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,7 +23,11 @@ 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 { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, projectPublish, } from "../lib/lifecycle.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 { 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";
 import { readLivePreview } from "../lib/relayInfo.js";
@@ -29,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 } 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";
@@ -143,7 +149,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();
@@ -186,17 +205,54 @@ async function unlink() {
         config: () => resolveConfig(cwd),
     });
 }
+/**
+ * `vincentt publish` — Flows L22-L31.
+ *
+ * The whole gate lives here: the checklist, the permanence disclosure, the
+ * confirmation, the upload and the live URL. There is no browser step in
+ * publishing, not on the first publish, not ever.
+ */
 async function publish() {
-    await requireLogin();
-    const result = await projectPublish(projectDir(), {
-        distDir: flag("--dist"),
-        note: flag("--note"),
-        allowCustomApi: has("--allow-custom-api"),
-        warn: (l) => console.log(l),
-    });
-    console.log(result.message);
-    if (result.notBound)
+    const refused = refusedFlag(argv);
+    if (refused) {
+        console.log(`✗ There's no \`${refused}\` option.`);
+        console.log("");
+        console.log("  The link-preview check reports what it found; it never edits your");
+        console.log("  source. Fix the tags in your own files, rebuild, then publish again.");
         process.exitCode = 1;
+        return;
+    }
+    const cwd = projectDir();
+    process.exitCode = await publishCommand({
+        print: (l) => console.log(l),
+        write: (s) => process.stdout.write(s),
+        confirm: stdinConfirm(),
+        cwd,
+        config: () => resolveConfig(cwd, {
+            allowCustomApi: has("--allow-custom-api"),
+            warn: (l) => console.log(l),
+        }),
+        binding: async () => {
+            const located = await locateProjectBinding(cwd);
+            return located
+                ? { projectId: located.binding.projectId, slug: located.binding.slug }
+                : undefined;
+        },
+        token: currentToken,
+        isTTY: Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        orgName: activeOrgName,
+    }, { distDir: flag("--dist"), note: flag("--note"), yes: has("--yes") });
+}
+/** Flow L30 — the six verbs that are console actions, answered rather than rejected. */
+async function consoleOnly(verb) {
+    const cwd = projectDir();
+    process.exitCode = await consoleVerbCommand({
+        print: (l) => console.log(l),
+        projectId: async () => (await locateProjectBinding(cwd))?.binding.projectId,
+        consoleUrl: flag("--console") ?? process.env.VINCENTT_CONSOLE_URL,
+    }, verb);
 }
 /**
  * `vincentt preview` — Flows L13-L21.
@@ -458,11 +514,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;
@@ -490,13 +567,14 @@ function usage() {
         `  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` +
         `  unlink             Disconnect this folder from its project\n\n` +
         `Dev loop\n` +
         `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
+        `                       [--dist <path>] [--note <s>] [--yes]\n` +
         `  preview            Serve the app at an https link a phone can open\n` +
         `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n\n` +
         `Diagnostics (need a running preview)\n` +
@@ -510,13 +588,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)) {
@@ -524,6 +608,8 @@ async function main() {
         return;
     }
     switch (cmd) {
+        case "version":
+            return version();
         case "login":
             return login();
         case "logout":
@@ -550,11 +636,14 @@ async function main() {
             return diag("trace");
         case "feedback":
             return feedback();
-        case "mcp":
-            return mcp();
         case "relay":
             return relay();
         default:
+            // Flow L30: rolling back and taking an address offline are console
+            // actions, and a bare "unknown command" here would be the product failing
+            // to answer a question it knows the answer to.
+            if (cmd !== undefined && isConsoleOnlyVerb(cmd))
+                return consoleOnly(cmd);
             console.error(`Unknown command: ${cmd}\n`);
             usage();
             process.exitCode = 1;

package/dist/lib/backend.d.ts

@@ -19,13 +19,6 @@ export interface CreatedProject {
     orgId: string;
     liveUrl: 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);
@@ -70,15 +63,6 @@ export declare function reapTunnel(cfg: ResolvedConfig, projectId: string, ref:
 }): 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 MeMembership {
     orgId: string;
     orgSlug: string;

package/dist/lib/backend.js

@@ -178,40 +178,6 @@ export async function walkDir(dir, base = dir) {
     }
     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(authFailureMessage("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) {

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/lifecycle.d.ts

@@ -59,14 +59,22 @@ export interface PublishOptions {
      * has already happened (or thrown).
      */
     warn?: (line: string) => void;
+    /** Skip the confirmation. REFUSED on a first publish; see publishCommand. */
+    yes?: boolean;
 }
 export interface PublishOutcome {
+    /** The full transcript, exactly as the CLI prints it. */
     message: string;
-    notBound: boolean;
-    version?: number;
-    liveUrl?: string;
-    url?: string;
+    exitCode: number;
 }
+/**
+ * The shared `publish` orchestration behind both `vincentt publish` and the MCP
+ * `project_publish` tool, so the two surfaces can never diverge.
+ *
+ * MCP has no terminal, so it is a non-TTY caller: the command refuses without
+ * `--yes` rather than assuming consent, and refuses `--yes` outright on a first
+ * publish. An agent cannot make an address permanent.
+ */
 export declare function projectPublish(projectCwd: string, opts?: PublishOptions): Promise<PublishOutcome>;
 export declare function getActivePreview(): RunningPreview | null;
 export interface PreviewStartResult {

package/dist/lib/lifecycle.js

@@ -3,9 +3,9 @@
 // lower-level pieces (backend calls, scaffold, preview, diagnostics); no CLI or
 // MCP SDK concerns leak in here. Both surfaces render the returned data their
 // own way.
-import path from "node:path";
-import { getMe, gitHeadSha, publishUpload } from "./backend.js";
+import { getMe } from "./backend.js";
 import { createCommand } from "./projects.js";
+import { publishCommand } from "../publish/command.js";
 import { activeOrgSlug, resolveActiveOrg } from "./org.js";
 import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
 import { clearRelayInfo, readLivePreview, readRelayInfo, writeRelayInfo, } from "./relayInfo.js";
@@ -68,36 +68,42 @@ export async function resolveOrgForCommand(cfg, input) {
             : "✗ No active organization.\n\n  Run `vincentt whoami` to see which organizations you belong to,\n  then re-run with `--org <slug>`.",
     };
 }
+/**
+ * The shared `publish` orchestration behind both `vincentt publish` and the MCP
+ * `project_publish` tool, so the two surfaces can never diverge.
+ *
+ * MCP has no terminal, so it is a non-TTY caller: the command refuses without
+ * `--yes` rather than assuming consent, and refuses `--yes` outright on a first
+ * publish. An agent cannot make an address permanent.
+ */
 export async function projectPublish(projectCwd, opts = {}) {
-    const cfg = await resolveConfig(projectCwd, {
-        allowCustomApi: opts.allowCustomApi,
-        warn: opts.warn,
-    });
-    const located = await locateProjectBinding(projectCwd);
-    if (!located) {
-        return {
-            message: [
-                "✗ This folder isn't linked to a project.",
-                "",
-                "  vincentt link <project-id>   (copy it from the console)",
-                "  vincentt create             Register a new project for this folder",
-            ].join("\n"),
-            notBound: true,
-        };
-    }
-    const dist = path.resolve(projectCwd, opts.distDir ?? "dist");
-    const commitSha = await gitHeadSha(projectCwd);
-    const result = await publishUpload(cfg, located.binding.projectId, dist, {
-        note: opts.note,
-        commitSha,
-    });
-    return {
-        message: `Published v${result.version}. Live at ${result.liveUrl}`,
-        notBound: false,
-        version: result.version,
-        liveUrl: result.liveUrl,
-        url: result.url,
+    const lines = [];
+    const print = (line) => {
+        lines.push(line);
     };
+    const exitCode = await publishCommand({
+        print,
+        write: () => {
+            // No redraw off a terminal; the degraded path emits whole lines.
+        },
+        confirm: async () => false,
+        cwd: projectCwd,
+        config: () => resolveConfig(projectCwd, {
+            allowCustomApi: opts.allowCustomApi,
+            warn: opts.warn ?? print,
+        }),
+        binding: async () => {
+            const located = await locateProjectBinding(projectCwd);
+            return located
+                ? { projectId: located.binding.projectId, slug: located.binding.slug }
+                : undefined;
+        },
+        token: async () => process.env.VINCENTT_PAT ?? (await loadMachineConfig()).pat,
+        isTTY: false,
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    }, { distDir: opts.distDir, note: opts.note, yes: opts.yes });
+    return { message: lines.join("\n"), exitCode };
 }
 // ---- preview (one per process) ----------------------------------------------
 let activePreview = null;

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>;