@vincentt-xr/cli 0.8.0 → 0.10.0

package/dist/lib/initFrom.js

@@ -0,0 +1,222 @@
+// `vincentt init <dir> --from owner/repo@tag` — the combined clone path (f6).
+//
+// One command, TWO failure domains. Everything above the seam is on disk and
+// permanent; everything below it is a network attempt. The transcript's shape is
+// what lets a creator answer "did I lose my work?" without reading the error.
+//
+// This file is an ORCHESTRATOR plus the bounded re-ask loop plus the transition
+// copy, and nothing else. `ensureLoggedIn` and `createCommand` are called
+// verbatim — a second implementation of f2's rules is a second place for them to
+// be wrong.
+import path from "node:path";
+import { SlugTakenError } from "./backend.js";
+import { slugify } from "./slug.js";
+import { formatSourceRef } from "./sourceRef.js";
+/** How many times the address prompt re-asks before falling back to the printed block. */
+export const ADDRESS_REASK_LIMIT = 3;
+const ORG_SOURCE_LABEL = {
+    active: "from your active workspace",
+    env: "from VINCENTT_ORG",
+    flag: "from --org",
+};
+/** The one sentence every registration-half failure opens with. Byte-identical across arms. */
+function reassure(print, dirLabel) {
+    print(`  Your source is fine — ${dirLabel} is on disk and it's yours.`);
+}
+/** The resume block: `cd <dir>` (when there is one) then the exact create command. */
+function resume(print, dirLabel, command, needsCd = true) {
+    if (needsCd)
+        print(`  cd ${stripLeadingDotSlash(dirLabel)}`);
+    print(`  ${command}`);
+}
+function stripLeadingDotSlash(label) {
+    return label.startsWith("./") ? label.slice(2) : label;
+}
+/**
+ * The registration half — the below-the-seam orchestrator shared by `init --from`
+ * (f6) and by `vincentt create` (create-scaffolds). One implementation, because a
+ * second implementation of f2's rules is a second place for them to be wrong.
+ *
+ * `deps.scaffolded` says whether source was written above this call, and it decides
+ * one word in every failure's last line: that word IS the on-disk state, read at a
+ * glance in scrollback by someone who wants exactly one bit of information.
+ */
+export async function registerAfterScaffold(deps, opts = {}) {
+    const defaultName = opts.name ?? path.basename(path.resolve(deps.targetDir));
+    const defaultSlug = opts.slug ?? slugify(defaultName);
+    const resumeCommand = `vincentt create --name "${defaultName}" --slug ${defaultSlug || "<address>"}`;
+    const scaffolded = deps.scaffolded ?? true;
+    const needsCd = deps.resumeNeedsCd ?? true;
+    const closing = scaffolded ? "  Nothing else was written." : "  Nothing was written.";
+    // Reached two ways — runLogin threw, and runLogin returned with still no token
+    // (the creator closed the tab). One creator-visible outcome, so one block: two
+    // copies of nine lines diverge on the first edit to either.
+    const printSignInAbandoned = () => {
+        deps.print("");
+        deps.print("✗ Sign-in was not completed.");
+        deps.print("");
+        if (scaffolded)
+            reassure(deps.print, deps.dirLabel);
+        deps.print("  The project was not registered, so no address is reserved yet.");
+        deps.print("");
+        deps.print("  Finish when you're ready:");
+        resume(deps.print, deps.dirLabel, "vincentt create", needsCd);
+        deps.print("");
+        deps.print(closing);
+    };
+    // TRAP 2 inverted deliberately: the session is checked AFTER the scaffold, and
+    // `ensureLoggedIn` is only reachable on a TTY because it opens a browser.
+    const token = await deps.currentToken();
+    if (!token) {
+        if (!deps.ask) {
+            deps.print("");
+            deps.print("✗ Not signed in, and signing in needs a browser.");
+            deps.print("");
+            if (scaffolded)
+                reassure(deps.print, deps.dirLabel);
+            deps.print("  No address is reserved yet.");
+            deps.print("");
+            deps.print("  On a machine with a browser:");
+            deps.print("  vincentt login");
+            deps.print("");
+            deps.print("  Then finish:");
+            resume(deps.print, deps.dirLabel, resumeCommand, needsCd);
+            deps.print("");
+            deps.print(closing);
+            return 1;
+        }
+        deps.print("");
+        deps.print("→ Now registering the project so it gets an address.");
+        deps.print("  You're not signed in yet — opening the browser to authorize this device…");
+        // The open path's load-bearing home, and the only new sentence in this flow.
+        // The reader is a human holding working source who is being asked for an
+        // account thirty seconds after watching an app appear on their disk — the one
+        // person for whom "you did not have to" is news, and nobody reads `--help` at
+        // the moment they are being asked to sign in. It is a statement of FACT, not
+        // an offer to abort: their source is already on disk, so the sentence has no
+        // action attached and costs the reader nothing.
+        //
+        // Only when a scaffold actually happened. In an already-scaffolded folder the
+        // creator has source `init` did not write, so the sentence would be advice to
+        // re-run a verb that has nothing left to do.
+        if (scaffolded) {
+            deps.print("  (`vincentt init` scaffolds with no account at all, if you'd rather not sign in.)");
+        }
+        try {
+            await deps.runLogin();
+        }
+        catch {
+            printSignInAbandoned();
+            return 1;
+        }
+        if (!(await deps.currentToken())) {
+            printSignInAbandoned();
+            return 1;
+        }
+    }
+    // A non-TTY caller must supply both, and the tool never invents an address.
+    if (!deps.ask && (opts.name === undefined || opts.slug === undefined)) {
+        deps.print("");
+        deps.print("✗ Can't register the project without a name and an address, and I can't ask.");
+        deps.print("");
+        if (scaffolded)
+            reassure(deps.print, deps.dirLabel);
+        deps.print("  No address is reserved yet.");
+        deps.print("");
+        deps.print("  Finish it:");
+        resume(deps.print, deps.dirLabel, resumeCommand, needsCd);
+        deps.print("");
+        deps.print(closing);
+        return 1;
+    }
+    const org = await deps.resolveOrg();
+    if (!org.ok) {
+        deps.print("");
+        deps.print(org.message);
+        deps.print("");
+        if (scaffolded)
+            reassure(deps.print, deps.dirLabel);
+        deps.print("  No address is reserved yet.");
+        deps.print("");
+        deps.print("  Check who you are:  vincentt whoami");
+        deps.print("  Then finish:");
+        resume(deps.print, deps.dirLabel, "vincentt create --org <workspace>", needsCd);
+        deps.print("");
+        deps.print(closing);
+        return 1;
+    }
+    // AF-3: name the org AND where it came from, before the address prompt. The
+    // card's command carries no --org, so a stale active workspace would otherwise
+    // claim an address in a team org silently.
+    deps.print("");
+    deps.print(`→ Registering in ${org.name} (${ORG_SOURCE_LABEL[org.source]})`);
+    let name = opts.name;
+    let slug = opts.slug;
+    if (deps.ask) {
+        if (name === undefined) {
+            const answer = await deps.ask(`? Project name: (${defaultName}) `, defaultName);
+            name = answer.trim() === "" ? defaultName : answer.trim();
+        }
+        if (slug === undefined) {
+            const fallback = slugify(name);
+            const answer = await deps.ask(`? Address: (${fallback}) `, fallback);
+            slug = answer.trim() === "" ? fallback : answer.trim();
+        }
+    }
+    let attempts = 0;
+    for (;;) {
+        try {
+            return await deps.create({ name: name, slug: slug });
+        }
+        catch (err) {
+            if (!(err instanceof SlugTakenError))
+                throw err;
+            attempts++;
+            // TRAP 3: never auto-pick suggestions[0]. On a non-TTY this refuses; on a
+            // TTY it re-asks with NO default, because there is no safe default left.
+            const canReask = Boolean(deps.ask) && attempts < ADDRESS_REASK_LIMIT;
+            if (!canReask) {
+                deps.print("");
+                deps.print("✗ That address is taken.");
+                deps.print("");
+                if (scaffolded)
+                    reassure(deps.print, deps.dirLabel);
+                deps.print("  No address is reserved yet.");
+                if (err.suggestions.length > 0) {
+                    deps.print("");
+                    deps.print("  Available alternatives:");
+                    for (const s of err.suggestions)
+                        deps.print(`    ${s}`);
+                }
+                deps.print("");
+                deps.print(deps.ask
+                    ? "  Finish with an address of your own:"
+                    : "  Finish with one of those, or your own:");
+                resume(deps.print, deps.dirLabel, `vincentt create --name "${name}" --slug <address>`, needsCd);
+                deps.print("");
+                deps.print(closing);
+                return 1;
+            }
+            // A routine, expected collision mid-flow: `!` and a re-ask, not `✗` and an
+            // exit. The command DOES proceed, so a `✗` would announce a stop that is
+            // not happening.
+            deps.print("");
+            deps.print(scaffolded
+                ? "! That address is taken. Your source is fine — pick another."
+                : "! That address is taken. Pick another.");
+            if (err.suggestions.length > 0) {
+                deps.print("");
+                deps.print("  Available alternatives:");
+                for (const s of err.suggestions)
+                    deps.print(`    ${s}`);
+            }
+            deps.print("");
+            const answer = await deps.ask("? Address: ", "");
+            slug = answer.trim();
+        }
+    }
+}
+/** The `· from owner/repo@tag` bullet in the start block. */
+export function sourceBullet(ref) {
+    return `  · from ${formatSourceRef(ref)}`;
+}

package/dist/lib/lifecycle.d.ts

@@ -1,3 +1,5 @@
+import type { OrgSource } from "./initFrom.js";
+import type { Ask } from "../publish/prompt.js";
 import { type ResolvedOrg } from "./org.js";
 import { type RelayClient } from "./diagnostics.js";
 import { type ResolvedConfig } from "../shared/config.js";
@@ -12,6 +14,18 @@ export interface CreateOptions {
     org?: string;
     /** Honor a binding's apiUrl override (--allow-custom-api). */
     allowCustomApi?: boolean;
+    /** The positional, already through `sanitizeAppName`. Resolves against the cwd. */
+    dir?: string;
+    /** `--no-install`, the same meaning it has on `init`. */
+    skipInstall?: boolean;
+    /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
+    ask?: Ask;
+    /** The PAT that would authenticate a call, if any. Never triggers a login. */
+    currentToken?: () => Promise<string | undefined>;
+    /** The interactive browser login. Only ever reached on a TTY. */
+    runLogin?: () => Promise<void>;
+    /** Where the resolved org came from, so a surprising value is diagnosable. */
+    orgSource?: () => OrgSource;
     /**
      * Stream the transcript as it happens. The CLI passes console.log so a slow
      * create shows progress and the apiUrl advisory lands before the request; MCP
@@ -30,8 +44,9 @@ export interface CreateResult {
  * `project_create` tool, so the two surfaces can never diverge in behavior OR in
  * what they tell the caller.
  *
- * It does NOT scaffold — that is `vincentt init`, which needs no account. See
- * `initCommand`.
+ * A two-half verb: it scaffolds an EMPTY folder from the standard starter, only
+ * registers a folder that is already a Vincentt app, and refuses anything else.
+ * See `createCommand`.
  */
 export declare function projectCreate(projectCwd: string, opts?: CreateOptions): Promise<CreateResult>;
 /**
@@ -95,6 +110,16 @@ export interface PreviewStopOutcome {
     stopped: boolean;
     message: string;
 }
+export interface PreviewStopDeps {
+    /**
+     * The relay to ask for presence. Injected for tests; in production it is built
+     * from the marker's port. A client that throws, hangs, or answers a body of
+     * the wrong shape yields NO count, which yields no line.
+     */
+    relay?: RelayClient;
+    /** Injected so the SIGTERM is observable without signalling a real process. */
+    kill?: (pid: number, signal: NodeJS.Signals) => void;
+}
 /**
  * Stop a preview started by a *different* process (the common case: `vincentt
  * preview` runs in the background and the agent later wants it down). Reads the
@@ -107,7 +132,7 @@ export interface PreviewStopOutcome {
  * closes, the edge sees the tunnel go, and the session drains on its own — so
  * SIGTERM plus clearing the stale relay info is the whole of the cleanup.
  */
-export declare function previewStopSignal(projectCwd: string): Promise<PreviewStopOutcome>;
+export declare function previewStopSignal(projectCwd: string, deps?: PreviewStopDeps): Promise<PreviewStopOutcome>;
 export interface DiagQueryOptions {
     since?: number;
     limit?: number;

package/dist/lib/lifecycle.js

@@ -3,6 +3,7 @@
 // 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 } from "./backend.js";
 import { createCommand } from "./projects.js";
 import { publishCommand } from "../publish/command.js";
@@ -11,13 +12,18 @@ import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
 import { clearRelayInfo, readLivePreview, readRelayInfo, writeRelayInfo, } from "./relayInfo.js";
 import { loadMachineConfig, locateProjectBinding, resolveConfig, } from "../shared/config.js";
 import { startPreview, } from "../preview/index.js";
+// The SHIPPED stopping line, reused rather than reworded: the interrupt path and
+// this path are one sentence about one event, and it says CONNECTIONS because one
+// tab opens several under HTTP/1.1 (preview/copy.ts).
+import * as previewCopy from "../preview/copy.js";
 /**
  * The shared `create` orchestration behind both `vincentt create` and the MCP
  * `project_create` tool, so the two surfaces can never diverge in behavior OR in
  * what they tell the caller.
  *
- * It does NOT scaffold — that is `vincentt init`, which needs no account. See
- * `initCommand`.
+ * A two-half verb: it scaffolds an EMPTY folder from the standard starter, only
+ * registers a folder that is already a Vincentt app, and refuses anything else.
+ * See `createCommand`.
  */
 export async function projectCreate(projectCwd, opts = {}) {
     const lines = [];
@@ -25,11 +31,16 @@ export async function projectCreate(projectCwd, opts = {}) {
         lines.push(line);
         opts.onLine?.(line);
     };
+    // ONE target: the positional names a child of `projectCwd`, and the config must
+    // be read from the folder the verb ACTS on, not from its parent — a parent's
+    // binding carrying an apiUrl override would otherwise decide where the child's
+    // project is registered.
+    const target = opts.dir ? path.resolve(projectCwd, opts.dir) : path.resolve(projectCwd);
     // Resolved once, lazily: a create refused by a local guard must not require a
     // PAT and must not reach the network at all.
     let cached;
     const config = async () => {
-        cached ??= await resolveConfig(projectCwd, {
+        cached ??= await resolveConfig(target, {
             allowCustomApi: opts.allowCustomApi,
             warn: print,
         });
@@ -40,7 +51,17 @@ export async function projectCreate(projectCwd, opts = {}) {
         cwd: projectCwd,
         config,
         org: async () => resolveOrgForCommand(await config(), { flag: opts.org }),
-    }, { name: opts.name, slug: opts.slug, force: opts.force });
+        ask: opts.ask,
+        currentToken: opts.currentToken,
+        runLogin: opts.runLogin,
+        orgSource: opts.orgSource,
+    }, {
+        name: opts.name,
+        slug: opts.slug,
+        force: opts.force,
+        dir: opts.dir,
+        skipInstall: opts.skipInstall,
+    });
     return { message: lines.join("\n"), exitCode };
 }
 /**
@@ -171,6 +192,51 @@ function isAlive(pid) {
         return false;
     }
 }
+/** The bound the caller is held to: one query, no retry, isRelayResponding's window. */
+const PRESENCE_TIMEOUT_MS = 700;
+/**
+ * How many connections are attached, or UNDEFINED when that cannot be
+ * established — and undefined is a first-class answer here, not an error.
+ *
+ * ⚠ THE WRONG SOURCE IS IN THE SAME RESPONSE OBJECT. A `RelayResult` carries
+ * `viewers[]` and `testers[]`, and when `liveConnections` is absent those arrays
+ * are frequently NON-EMPTY, because they are ever-seen sets the store never
+ * prunes (relay/store.ts:14-31). `result.viewers.length` therefore returns a
+ * plausible number at exactly the moment the real count is unknown, and printing
+ * it claims a phone that closed its tab twenty minutes ago is still watching.
+ * There is NO FALLBACK here on purpose: no `?? 0`, no `viewers.length`. Absent
+ * means unknown, and unknown prints nothing.
+ */
+async function readLiveConnections(relay) {
+    // BOUNDED, not rate-limited: one query, the same window isRelayResponding
+    // uses, no retry. The relay has no limiter and this branch reads two in-memory
+    // integers; the discipline belongs on the caller.
+    const timeout = new Promise((resolve) => setTimeout(() => resolve(undefined), PRESENCE_TIMEOUT_MS).unref?.());
+    let result;
+    try {
+        result = await Promise.race([relay.query({ presence: true, limit: 0 }), timeout]);
+    }
+    catch {
+        // Refused, non-JSON, a non-2xx — every one of them is "no count".
+        return undefined;
+    }
+    if (result === undefined)
+        return undefined;
+    // The SHAPE is the identity proof, the same one isRelayResponding applies: a
+    // stranger on a reused port does not answer a RelayResult. Only after the
+    // envelope is recognised is the count itself read, and it must be a real
+    // non-negative integer — a relay that predates the field sends none.
+    if (typeof result !== "object" ||
+        result === null ||
+        !Array.isArray(result.events) ||
+        typeof result.latestSeq !== "number") {
+        return undefined;
+    }
+    const n = result.liveConnections;
+    if (typeof n !== "number" || !Number.isInteger(n) || n < 0)
+        return undefined;
+    return n;
+}
 /**
  * Stop a preview started by a *different* process (the common case: `vincentt
  * preview` runs in the background and the agent later wants it down). Reads the
@@ -183,17 +249,43 @@ function isAlive(pid) {
  * closes, the edge sees the tunnel go, and the session drains on its own — so
  * SIGTERM plus clearing the stale relay info is the whole of the cleanup.
  */
-export async function previewStopSignal(projectCwd) {
+export async function previewStopSignal(projectCwd, deps = {}) {
     const info = await readRelayInfo(projectCwd);
     if (!info) {
         return { stopped: false, message: "No preview is running for this directory." };
     }
     const previewAlive = info.pid !== undefined && isAlive(info.pid);
     if (previewAlive) {
+        // PRESENCE IS READ BEFORE THE SIGNAL, and the order is the feature. The
+        // creator is about to blank someone's screen, so the count has to describe
+        // the moment before that happens; asking after the SIGTERM would race the
+        // relay's own teardown and print a number that was true of a preview which
+        // no longer exists. A dead pid is never queried at all — the marker is stale
+        // and there is nothing on that port to ask.
+        const relay = deps.relay ?? httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
+        const connected = await readLiveConnections(relay);
         try {
-            process.kill(info.pid, "SIGTERM");
+            (deps.kill ?? ((pid, sig) => process.kill(pid, sig)))(info.pid, "SIGTERM");
             await clearRelayInfo(projectCwd);
-            return { stopped: true, message: "✓ Preview stopped. The link no longer works." };
+            // A TRUE ZERO AND AN UNAVAILABLE COUNT PRODUCE THE IDENTICAL BYTES, and
+            // that is the decision rather than an accident. `stopping(0)` is the bare
+            // `→ Stopping…`, which carries no count — so emitting it on a confirmed
+            // zero while omitting it on an unknown would make the two distinguishable
+            // by a line that says nothing either way, and a creator could read the
+            // difference as meaning something. The line is emitted only when there is
+            // a count to state; both silent states collapse.
+            //
+            // "0 connections open" is the other tempting answer and it is refused for
+            // the same reason `stopping()` already refuses it: it would be a claim,
+            // and in the unavailable case a false one. Silence claims nothing.
+            const line = connected === undefined || connected === 0
+                ? undefined
+                : previewCopy.stopping(connected);
+            const lines = [
+                ...(line === undefined ? [] : [line]),
+                "✓ Preview stopped. The link no longer works.",
+            ];
+            return { stopped: true, message: lines.join("\n") };
         }
         catch {
             // Raced with its own exit; the socket is gone either way.

package/dist/lib/listProjects.d.ts

@@ -0,0 +1,41 @@
+import type { ProjectView } from "./backend.js";
+import type { ResolvedConfig } from "../shared/config.js";
+export interface ListProjectsDeps {
+    print: (line: string) => void;
+    /** The machine's API host + PAT, or undefined when nothing is signed in. */
+    config: () => Promise<ResolvedConfig | undefined>;
+    /** The workspace to list. Resolved by the caller's own precedence chain. */
+    org: () => Promise<{
+        ok: true;
+        org: {
+            slug: string;
+            name: string;
+        };
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    list: (cfg: ResolvedConfig, orgSlug: string) => Promise<ProjectView[]>;
+}
+export interface ListProjectsOptions {
+    json?: boolean;
+}
+/**
+ * The columns are `id`, `slug`, `name` and where it stands.
+ *
+ * THE ID IS FIRST AND IS NEVER ELIDED. It is the whole reason the verb exists:
+ * the next command a reader runs is `vincentt link <project-id>`, and a listing
+ * that truncated the id would send them to the console for the one value the
+ * command needs — which is the gap this closes.
+ */
+export declare function listProjectsCommand(deps: ListProjectsDeps, opts?: ListProjectsOptions): Promise<number>;
+/**
+ * Aligned on the widest id and slug so the block reads as a table in a terminal
+ * and stays greppable in an agent's transcript.
+ *
+ * The state column reads from `publishState` and NEVER computes a URL from the
+ * slug: `liveUrl` is server-computed because the apex differs per environment,
+ * so a client that assembled `<slug>.vincentt.app` itself would print the wrong
+ * address on staging and dev.
+ */
+export declare function projectRows(projects: ProjectView[]): string[];

package/dist/lib/listProjects.js

@@ -0,0 +1,77 @@
+// `vincentt projects` — which projects does this workspace have?
+//
+// A READ-ONLY verb, and an APPEND to the verb surface (B-F3-8 permits additions;
+// nothing is renamed or removed). It is NEUTRAL in the sense the feature
+// requires: a human typing it gets exactly what an agent running it gets, and
+// nothing about it exists for a plugin.
+//
+// It answers the one question the neutral surface could not. An agent asked to
+// resume a project in an UNBOUND folder previously had three options and all
+// were bad: guess an id, tell the creator to open the console and copy one, or
+// fail. `link` needs an id, and until now nothing printed one.
+//
+// The IO boundary (print, backend, org) is injected, so every branch is testable
+// with no API, no HOME, and no network.
+/**
+ * The columns are `id`, `slug`, `name` and where it stands.
+ *
+ * THE ID IS FIRST AND IS NEVER ELIDED. It is the whole reason the verb exists:
+ * the next command a reader runs is `vincentt link <project-id>`, and a listing
+ * that truncated the id would send them to the console for the one value the
+ * command needs — which is the gap this closes.
+ */
+export async function listProjectsCommand(deps, opts = {}) {
+    const cfg = await deps.config();
+    if (!cfg) {
+        deps.print("Not signed in. Run `vincentt login`.");
+        return 1;
+    }
+    const org = await deps.org();
+    if (!org.ok) {
+        deps.print(org.message);
+        return 1;
+    }
+    const projects = await deps.list(cfg, org.org.slug);
+    if (opts.json) {
+        // `{projects: [...]}` — the server's own envelope, holding the SAME
+        // `ProjectView` every other verb in this CLI parses a project into. It is a
+        // projection of the wire row (the API also sends version/timestamp fields),
+        // and it is deliberately the shared one rather than a listing-specific
+        // shape: a second projection here would be a second thing that can drift.
+        deps.print(JSON.stringify({ projects }, null, 2));
+        return 0;
+    }
+    if (projects.length === 0) {
+        // Not a failure, so no ✗ glyph: an empty workspace is a fact. The remedy is
+        // named because a reader who ran this verb was looking for something to act
+        // on and found nothing.
+        deps.print(`No projects in ${org.org.name}.`);
+        deps.print("");
+        deps.print("  vincentt create <name>   Register one for a new folder");
+        return 0;
+    }
+    deps.print(`${projects.length} project${projects.length === 1 ? "" : "s"} in ${org.org.name}`);
+    deps.print("");
+    for (const line of projectRows(projects))
+        deps.print(line);
+    deps.print("");
+    deps.print("  Link a folder to one:  vincentt link <project-id>");
+    return 0;
+}
+/**
+ * Aligned on the widest id and slug so the block reads as a table in a terminal
+ * and stays greppable in an agent's transcript.
+ *
+ * The state column reads from `publishState` and NEVER computes a URL from the
+ * slug: `liveUrl` is server-computed because the apex differs per environment,
+ * so a client that assembled `<slug>.vincentt.app` itself would print the wrong
+ * address on staging and dev.
+ */
+export function projectRows(projects) {
+    const idWidth = Math.max(...projects.map((p) => p.id.length));
+    const slugWidth = Math.max(...projects.map((p) => p.slug.length));
+    return projects.map((p) => {
+        const state = p.publishState === "live" && p.liveUrl ? p.liveUrl : p.publishState;
+        return `  ${p.id.padEnd(idWidth)}   ${p.slug.padEnd(slugWidth)}   ${p.name}   ${state}`;
+    });
+}

package/dist/lib/projects.d.ts

@@ -1,3 +1,7 @@
+import { type FolderCase } from "./classifyTarget.js";
+import { type OrgSource } from "./initFrom.js";
+import type { ScaffoldCall } from "./initCommand.js";
+import type { Ask } from "../publish/prompt.js";
 import { type ResolvedConfig } from "../shared/config.js";
 export interface ProjectCommandDeps {
     /** Print a transcript line. */
@@ -23,22 +27,70 @@ export interface CreateCommandDeps extends ProjectCommandDeps {
         ok: false;
         message: string;
     }>;
+    /** Which of the three folder cases the target is in. Defaults to `classifyTarget`. */
+    classify?: (dir: string) => Promise<FolderCase>;
+    /** Create the target directory. See the writer's guards below. */
+    mkdir?: (dir: string) => Promise<void>;
+    /** Resolve a path through its symlinks, for the classify→write re-check. */
+    realpath?: (dir: string) => Promise<string>;
+    scaffold?: (dir: string, opts: ScaffoldCall) => Promise<void>;
+    install?: (dir: string) => Promise<string>;
+    detectPm?: (dir: string) => Promise<string>;
+    /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
+    ask?: Ask;
+    /** The PAT that would authenticate a call, if any. Never triggers a login itself. */
+    currentToken?: () => Promise<string | undefined>;
+    /** The interactive browser login. Only ever reached on a TTY. */
+    runLogin?: () => Promise<void>;
+    /** Where the resolved org came from, so a surprising value is diagnosable (AF-3). */
+    orgSource?: () => OrgSource;
 }
 export interface CreateCommandOptions {
     name?: string;
     slug?: string;
     /** Replace a binding this folder already has. */
     force?: boolean;
+    /** The positional, already through `sanitizeAppName`. Resolves against `cwd`. */
+    dir?: string;
+    /** `--no-install`, the same meaning it has on `init`. */
+    skipInstall?: boolean;
+    /**
+     * Let a `409 slug_taken` propagate instead of printing here. Set by the callers
+     * that own their own taken-address copy (`registerAfterScaffold`, which has the
+     * bounded re-ask). See the throw site.
+     */
+    rethrowSlugTaken?: boolean;
 }
 /**
- * `vincentt create` — register a project and link this folder to it.
+ * `vincentt create` — a TWO-HALF verb with one seam.
+ *
+ * Above the seam is local and permanent (a directory, source on disk); below it is
+ * a network attempt (a session, an org, a slug claim, a binding). Which half
+ * failed is readable from the transcript's shape, which is what lets a creator
+ * answer "did I lose my work?" without reading the error twice.
+ *
+ * In an EMPTY folder it scaffolds the standard starter, installs, and then
+ * registers. In a folder that is already a Vincentt app it only registers. In any
+ * other non-empty folder it REFUSES and names `vincentt init .`, which is the
+ * escape hatch with its own confirm.
  *
- * It does NOT scaffold. An unscaffolded folder gets a `!` advisory and the command
- * PROCEEDS: the server accepts a create from any folder or none, and blocking here
- * would put the open template behind the auth gate, which is the one thing the
- * init/create split exists to prevent.
+ * `requireLogin()` is deliberately NOT called above this: the scaffold half must
+ * never depend on a session or on our availability, and a session check at the top
+ * of the verb would put the open template behind the auth gate. A "cleanup" that
+ * restores it silently reverts the whole design — `link()` three lines below in
+ * cli/index.ts does exactly that, which is what a dev writes by copying a
+ * neighbour.
  */
 export declare function createCommand(deps: CreateCommandDeps, opts?: CreateCommandOptions): Promise<number>;
+/**
+ * The registration half — the binding guard's remainder, the slug derivation, the
+ * round trip, and the binding write. Extracted from `createCommand` so
+ * `registerAfterScaffold` can call it without a cycle (that orchestrator IS the
+ * below-the-seam half of `create`, and it calls this as its `create` dep).
+ *
+ * Pure refactor of what shipped: no behavior change on f6's path.
+ */
+export declare function registerProject(deps: CreateCommandDeps, opts?: CreateCommandOptions): Promise<number>;
 /**
  * `vincentt link <project-id>` — one verb for four situations (console-first
  * birth, a fresh clone, a folder that lost its binding, a re-link after
@@ -70,9 +122,13 @@ export declare function printUnreachable(print: (line: string) => void, message:
  */
 export declare function unlinkCommand(deps: ProjectCommandDeps): Promise<number>;
 /**
- * The advisory's trigger: a package.json that depends on @vincentt-xr/sdk. It is a
- * HINT only — create proceeds either way — so a false negative costs one extra
- * line of output, never a refused command.
+ * A package.json that depends on `@vincentt-xr/*`.
+ *
+ * This is a GATE, not a hint. It is `classifyTarget`'s first and unconditional
+ * question, and it decides whether `create` registers only (true) or goes on to ask
+ * whether the folder is empty (false). A false negative therefore costs a refused
+ * command on a non-empty folder and a SCAFFOLD on an empty one — never one extra
+ * line of output, which is what this used to say and is no longer true.
  */
 export declare function looksLikeVincenttApp(cwd: string): Promise<boolean>;
 /** Resolve the bound project for a project-scoped verb, or explain why not. */