@vincentt-xr/cli 0.9.0 → 0.10.0

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. */

package/dist/lib/projects.js

@@ -7,18 +7,51 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { BackendError, SlugTakenError, createProject, getProject, } from "./backend.js";
+import { classifyTarget } from "./classifyTarget.js";
+import { registerAfterScaffold } from "./initFrom.js";
 import { slugify } from "./slug.js";
+import { detectPackageManager, installDependencies, scaffoldFromTemplate, } from "../scaffold/index.js";
 import { clearProjectBinding, loadProjectBinding, locateProjectBinding, writeProjectBinding, } from "../shared/config.js";
 /**
- * `vincentt create` — register a project and link this folder to it.
+ * `vincentt create` — a TWO-HALF verb with one seam.
  *
- * 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.
+ * 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.
+ *
+ * `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 async function createCommand(deps, opts = {}) {
-    const existing = await loadProjectBinding(deps.cwd);
+    // ONE target, resolved as the first statement. `deps.cwd` is never read again
+    // and never passed onward: once a positional exists it is the PARENT, and a
+    // guard asking its question about the parent lets `--force` overwrite a
+    // different project's binding while registering a project for the child.
+    //
+    // The PARENT is canonicalized here, before anything is classified, so that the
+    // writer's realpath re-check below compares like with like. Without this the
+    // guard fires on every ordinary run whose path merely passes through a symlink:
+    // on macOS `/tmp` is a symlink to `/private/tmp`, so `path.resolve` and
+    // `realpath` disagree about a perfectly innocent target and the verb refuses.
+    // Found by driving the built CLI, not by a unit test — the unit injected a
+    // realpath that was the identity function, which is exactly the shape of a
+    // check that passes while the artifact is wrong.
+    const realpath = deps.realpath ?? ((dir) => fs.realpath(dir));
+    const rawParent = path.resolve(deps.cwd);
+    const parent = await realpath(rawParent).catch(() => rawParent);
+    const target = opts.dir ? path.join(parent, opts.dir) : parent;
+    const dirLabel = opts.dir ? `./${opts.dir}` : ".";
+    const existing = await loadProjectBinding(target);
     if (existing && !opts.force) {
         deps.print(`✗ This folder is already linked to a project (${existing.slug}).`);
         deps.print("");
@@ -27,13 +60,259 @@ export async function createCommand(deps, opts = {}) {
         deps.print("  Replace it:   vincentt create --force");
         return 1;
     }
-    if (!(await looksLikeVincenttApp(deps.cwd))) {
-        deps.print("!  This folder doesn't look like a Vincentt app (no package.json with @vincentt-xr/sdk).");
-        deps.print("   `vincentt create` registers a project — it doesn't scaffold one.");
-        deps.print("   To start from the template:  npx @vincentt-xr/cli init");
+    const classify = deps.classify ?? classifyTarget;
+    const folderCase = await classify(target);
+    if (folderCase === "occupied") {
+        // Every case-3 cause prints this exact screen — occupied, unreadable, a
+        // symlink to anything, a dangling symlink, a regular file, ENOTDIR, ELOOP, an
+        // unforeseen errno. The CLI could not establish that the target is safe to
+        // write into; that is one fact with one remedy pair. A per-cause message
+        // would advertise which filenames the predicate has opinions about, which is
+        // the allowlist this design refuses to open.
+        deps.print("✗ This folder isn't a Vincentt app, and it isn't empty.");
+        deps.print("");
+        deps.print("  `vincentt create` scaffolds an empty folder and registers an existing app.");
+        deps.print("  This folder is neither, and adding the template's files here would mix them");
+        deps.print("  into what's already present.");
+        deps.print("");
+        deps.print("  vincentt create <name>   Scaffold and register in a new folder");
+        deps.print("  vincentt init .          Scaffold into THIS folder anyway (asks first)");
+        deps.print("");
+        deps.print("  Nothing was written.");
+        return 1;
+    }
+    let scaffolded = false;
+    let installed = true;
+    let pm = "npm";
+    let actedOn = dirLabel;
+    if (folderCase === "empty") {
+        const wrote = await scaffoldInto(deps, target, dirLabel, opts);
+        if (!wrote.ok)
+            return 1;
+        scaffolded = true;
+        installed = wrote.installed;
+        pm = wrote.pm;
+    }
+    else {
+        // Case 2 writes too — a binding and a .gitignore line — so it runs the same
+        // re-check the case-1 writer does. It never calls scaffoldInto, so without
+        // this the guard is asymmetric: a symlink whose target holds an
+        // @vincentt-xr package.json classifies as `vincentt-app` (looksLikeApp runs
+        // first and follows the link), and the binding lands in the link target.
+        const resolved = await realpath(target).catch(() => target);
+        // Two different collisions land here, and they need different copy. A
+        // DIFFERENT PARENT means a symlink pointing out of the folder the creator
+        // named — refuse, because the binding would land somewhere they cannot see.
+        // The SAME parent with a different basename is the case-insensitive twin
+        // (`create myapp` beside `MyApp/` on the default macOS volume): the folder
+        // is right there and visible, so it is FORK-C4(ii)'s transparency case, not
+        // a refusal — name what it resolved to and carry on.
+        if (path.dirname(resolved) !== path.dirname(target)) {
+            deps.print("✗ That folder resolves somewhere else.");
+            deps.print("");
+            deps.print(`  ${dirLabel} is a link, and registering would write into its target`);
+            deps.print("  rather than into the folder you named.");
+            deps.print("");
+            deps.print("  Run the command from the real folder instead.");
+            deps.print("");
+            deps.print("  Nothing was written.");
+            return 1;
+        }
+        const onDisk = path.basename(resolved);
+        if (opts.dir && onDisk !== opts.dir)
+            actedOn = `./${onDisk}`;
+    }
+    let cachedOrg;
+    const org = async () => (cachedOrg ??= await deps.org());
+    const sharedDeps = { ...deps, org };
+    // Only when the folder on disk is spelled differently from what was typed.
+    // Printing it every time would be noise; printing it here is the one signal
+    // that `create myapp` is about to register `MyApp/`.
+    if (actedOn !== dirLabel) {
+        deps.print(`! Registering ${actedOn}, which is what ${dirLabel} resolves to.`);
+    }
+    const code = await registerAfterScaffold({
+        print: deps.print,
+        targetDir: target,
+        dirLabel,
+        ask: deps.ask,
+        scaffolded,
+        // Bare `create` acts in the cwd, so a `cd .` in the resume block is noise.
+        resumeNeedsCd: Boolean(opts.dir),
+        currentToken: deps.currentToken ?? (async () => undefined),
+        runLogin: deps.runLogin ?? (async () => undefined),
+        resolveOrg: async () => {
+            const resolved = await org();
+            if (!resolved.ok)
+                return resolved;
+            return {
+                ok: true,
+                name: resolved.org.name,
+                source: deps.orgSource?.() ?? "active",
+            };
+        },
+        create: async ({ name, slug }) => registerProject(sharedDeps, {
+            ...opts,
+            dir: opts.dir,
+            name,
+            slug,
+            rethrowSlugTaken: true,
+        }),
+    }, 
+    // Case 2 keeps the shipped basename default: a creator made that folder and
+    // put an app in it. Case 1's folder was created by the CLI from a token an
+    // agent passed, so defaulting an address off it would be the CLI claiming a
+    // globally-unique public address from a name it generated the path for.
+    scaffolded
+        ? { name: opts.name, slug: opts.slug }
+        : {
+            name: opts.name ?? path.basename(target),
+            slug: opts.slug ?? slugify(opts.name ?? path.basename(target)),
+        });
+    if (code !== 0)
+        return code;
+    if (scaffolded) {
+        // This reader has never run the dev server, so the block that fits is the one
+        // `init` already ships for exactly this reader — two aligned columns off the
+        // DETECTED package manager, never a hardcoded one (the template ships a pnpm
+        // lockfile and a hoisted node-linker).
+        const steps = [];
+        if (opts.dir)
+            steps.push([`cd ${opts.dir}`, ""]);
+        if (!installed || opts.skipInstall)
+            steps.push([`${pm} install`, "Install dependencies"]);
+        steps.push([`${pm} run dev`, "Start the local dev server"]);
+        steps.push(["vincentt preview", "Try it on your phone"]);
         deps.print("");
+        for (const line of alignedSteps(steps))
+            deps.print(line);
+    }
+    return 0;
+}
+/** Two columns, aligned on the widest command, so the block reads as a table. */
+function alignedSteps(steps) {
+    const width = Math.max(...steps.map(([cmd]) => cmd.length));
+    return steps.map(([cmd, note]) => note ? `  ${cmd.padEnd(width)}   ${note}` : `  ${cmd}`);
+}
+/**
+ * The scaffold half — everything above the seam, and the only place this verb
+ * writes before a 201.
+ *
+ * TWO GUARDS LIVE HERE RATHER THAN IN THE CLASSIFIER, because the classifier
+ * answers a question at a moment and both of these failures happen after it:
+ *
+ *  1. `mkdir` with `{recursive: false}`. Measured: `mkdir(p, {recursive: true})`
+ *     on a path that is an EXISTING SYMLINK TO A DIRECTORY succeeds silently, and
+ *     the scaffold then writes through the link, outside the parent the creator
+ *     named. The same call non-recursively throws EEXIST. Without this the
+ *     classifier's lstat check is defeated by anything that plants a symlink
+ *     between the classify and the write.
+ *  2. `realpath(target)` is compared against the path that was classified, and a
+ *     mismatch refuses WITHOUT writing. This closes the general
+ *     classify-then-write window rather than one instance of it.
+ *
+ * Both also close a collision that needs no attacker at all: `sanitizeAppName`
+ * accepts `MyApp` and `myapp` as distinct tokens and the default macOS volume is
+ * case-INsensitive, so `create myapp` beside an existing `MyApp/` resolves to one
+ * directory and would otherwise bind a project to somebody else's folder while
+ * reporting success.
+ */
+async function scaffoldInto(deps, target, dirLabel, opts) {
+    deps.print(`→ Scaffolding a Vincentt XR app in ${dirLabel}…`);
+    deps.print("  · React + react-three-fiber + @vincentt-xr/sdk");
+    if (!opts.skipInstall)
+        deps.print("  · installing dependencies");
+    const mkdir = deps.mkdir ??
+        (async (dir) => {
+            await fs.mkdir(path.dirname(dir), { recursive: true });
+            await fs.mkdir(dir, { recursive: false });
+        });
+    const realpath = deps.realpath ?? ((dir) => fs.realpath(dir));
+    try {
+        await mkdir(target);
+    }
+    catch (err) {
+        // EEXIST here is guard 1 firing: something occupies the path that the
+        // classifier said was absent or empty. It is a refusal, not a retry.
+        const code = err?.code;
+        if (code !== "EEXIST") {
+            deps.print("");
+            // The errno and the label the creator typed, never err.message — that
+            // carries the resolved absolute path, and transcripts get pasted into
+            // bug reports and agent context.
+            deps.print(`✗ Could not create ${dirLabel}${code ? ` (${code})` : ""}.`);
+            deps.print("");
+            deps.print("  Run `vincentt create` again once that is resolved.");
+            return { ok: false };
+        }
     }
-    const name = opts.name ?? path.basename(path.resolve(deps.cwd));
+    let resolved;
+    try {
+        resolved = await realpath(target);
+    }
+    catch {
+        resolved = "";
+    }
+    if (resolved !== target) {
+        deps.print("");
+        deps.print("✗ This folder isn't a Vincentt app, and it isn't empty.");
+        deps.print("");
+        deps.print("  `vincentt create` scaffolds an empty folder and registers an existing app.");
+        deps.print("  This folder is neither, and adding the template's files here would mix them");
+        deps.print("  into what's already present.");
+        deps.print("");
+        deps.print("  vincentt create <name>   Scaffold and register in a new folder");
+        deps.print("  vincentt init .          Scaffold into THIS folder anyway (asks first)");
+        deps.print("");
+        deps.print("  Nothing was written.");
+        return { ok: false };
+    }
+    // A CONSTANT call: no `repo`, no `ref`, so scaffoldFromTemplate resolves
+    // TEMPLATE_REPO at DEFAULT_TEMPLATE_REF. ScaffoldCall's two fields exist for
+    // `init --from`; `create` never populates either, and there is no code path by
+    // which it could — which is exactly what `--template`/`--from` being refused at
+    // the parser makes structurally true, and what the install below rests on.
+    const scaffold = deps.scaffold ?? ((dir, o) => scaffoldFromTemplate(dir, o));
+    try {
+        await scaffold(target, {});
+    }
+    catch (err) {
+        // No `✓ Created`, so no registration is attempted, and this arm carries
+        // NEITHER closing string: a partial directory may exist, so "Nothing was
+        // written." would be a lie.
+        deps.print("");
+        deps.print(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        deps.print("");
+        deps.print("  Run `vincentt create` again once that is resolved.");
+        return { ok: false };
+    }
+    let installed = true;
+    if (!opts.skipInstall) {
+        const install = deps.install ?? ((dir) => installDependencies(dir));
+        try {
+            await install(target);
+        }
+        catch {
+            installed = false;
+        }
+    }
+    const detect = deps.detectPm ?? ((dir) => detectPackageManager(dir));
+    const pm = await detect(target).catch(() => "npm");
+    deps.print("");
+    deps.print(`✓ Created ${dirLabel}`);
+    return { ok: true, installed, pm };
+}
+/**
+ * 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 async function registerProject(deps, opts = {}) {
+    const target = opts.dir ? path.resolve(deps.cwd, opts.dir) : path.resolve(deps.cwd);
+    const name = opts.name ?? path.basename(target);
     const slug = opts.slug ?? slugify(name);
     if (!slug) {
         deps.print("✗ Could not derive an address from that name.");
@@ -56,13 +335,17 @@ export async function createCommand(deps, opts = {}) {
         created = await createProject(cfg, org.org.slug, name, slug);
     }
     catch (err) {
-        if (err instanceof SlugTakenError) {
+        // `registerAfterScaffold` owns the taken-address copy on its own path (it has
+        // the bounded re-ask and the reassure block, neither of which exists here), so
+        // when it is the caller the error is its to handle. Printing here as well
+        // would emit two refusals for one condition AND kill the re-ask loop.
+        if (err instanceof SlugTakenError && !opts.rethrowSlugTaken) {
             printSlugTaken(deps.print, err.suggestions, name);
             return 1;
         }
         throw err;
     }
-    await writeProjectBinding(deps.cwd, {
+    await writeProjectBinding(target, {
         projectId: created.projectId,
         slug: created.slug,
     });
@@ -77,9 +360,17 @@ export async function createCommand(deps, opts = {}) {
 /**
  * Four words, byte-identical to the console's — it must read the same whether the
  * holder is your own org, a stranger, a tombstone, a burn, or a reserved hostname.
- * Suggestions are LISTED, never applied: the remedy restates the whole command so
- * it is copy-pasteable, and the closing clause offers the creator's own choice as
- * an equal option, so an agent reading this cannot conclude auto-picking is sanctioned.
+ *
+ * Suggestions are LISTED, never applied, and the remedy carries the `<address>`
+ * PLACEHOLDER on both arms. It is the only command in the verb an agent cannot run
+ * verbatim, and that is the tool refusing to choose a globally-unique public
+ * address on the creator's behalf: a creator who pastes a filled-in command has
+ * accepted an address the tool picked. Substituting `suggestions[0]` would make
+ * auto-picking look sanctioned, and an agent reading this transcript would learn to
+ * do it every time. One verb, one answer — the sibling copy in
+ * `registerAfterScaffold` reads the same, and two answers to one condition,
+ * reproducible only by standing in the right folder, is the shape of a bug report
+ * nobody can reproduce.
  */
 function printSlugTaken(print, suggestions, name) {
     print("✗ That address is taken.");
@@ -89,12 +380,9 @@ function printSlugTaken(print, suggestions, name) {
         for (const s of suggestions)
             print(`    ${s}`);
         print("");
-        print(`  Run \`vincentt create --name "${name}" --slug ${suggestions[0]}\` to use one,`);
-        print("  or pick your own with any --slug.");
-    }
-    else {
-        print(`  Run \`vincentt create --name "${name}" --slug <address>\` with another address.`);
+        print("  Finish with one of those, or your own:");
     }
+    print(`  Run \`vincentt create --name "${name}" --slug <address>\` with another address.`);
 }
 // ---- link -------------------------------------------------------------------
 /**
@@ -188,9 +476,13 @@ export async function unlinkCommand(deps) {
 }
 // ---- shared -----------------------------------------------------------------
 /**
- * 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 async function looksLikeVincenttApp(cwd) {
     try {

package/dist/lib/sourceRefCopy.d.ts

@@ -4,6 +4,25 @@ export interface FromFailureContext {
     dir: string;
 }
 export declare function printSourceRefFailure(print: (line: string) => void, failure: ParseFailure, ctx: FromFailureContext): void;
+/**
+ * `--template` / `--from` on `create` — the parser refusal, and it is a security
+ * control rather than a scope note. The basis for installing dependencies on the
+ * unauthenticated scaffold path is that `create` can only ever clone our own
+ * hardcoded template at a release-gated ref; this screen is what makes that
+ * structurally true rather than conventional.
+ *
+ * "on `create`" is REQUIRED on line 1 and is not required by the shipped
+ * `printFlagConflict` precedent: `--template` really does exist, on `init`, and the
+ * remedy three lines below depends on that being true. An unqualified claim is one
+ * a creator disproves in one command.
+ *
+ * The creator's own typed arguments are carried through verbatim, so all three
+ * remedy lines are copy-pasteable with no placeholder to guess.
+ */
+export declare function printCreateSourceFlagRefusal(print: (line: string) => void, flagName: string, ctx: {
+    dir: string;
+    value?: string;
+}): void;
 /** `--from` with `--template`, or with an install-enabling flag. */
 export declare function printFlagConflict(print: (line: string) => void, conflict: {
     flags: [string, string];