@vincentt-xr/cli 0.8.0 → 0.10.0

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

@@ -0,0 +1,46 @@
+export interface SourceRef {
+    owner: string;
+    repo: string;
+    tag: string;
+}
+export type ParseFailure = {
+    kind: "missing_tag";
+    value: string;
+} | {
+    kind: "missing_repo";
+    value: string;
+} | {
+    kind: "bad_owner";
+    value: string;
+} | {
+    kind: "bad_repo";
+    value: string;
+} | {
+    kind: "bad_tag";
+    value: string;
+} | {
+    kind: "looks_like_url";
+    value: string;
+    converted?: SourceRef;
+};
+export type ParseResult = {
+    ok: true;
+    ref: SourceRef;
+} | {
+    ok: false;
+    failure: ParseFailure;
+};
+/**
+ * Parse `owner/repo@tag`. Pure: no filesystem, no network, no process.
+ *
+ * A bare `owner/repo` is REFUSED, never defaulted to a branch — a default would
+ * point the command at a moving target (S-2).
+ */
+export declare function parseSourceRef(input: string): ParseResult;
+/**
+ * The clone URL's ONLY composition point. The host is a compile-time constant —
+ * never configuration, never derived from stored data (S-6).
+ */
+export declare function templateCloneURL(owner: string, repo: string): string;
+/** `owner/repo@tag`, the form the creator typed and the card shows. */
+export declare function formatSourceRef(ref: SourceRef): string;

package/dist/lib/sourceRef.js

@@ -0,0 +1,107 @@
+// `--from owner/repo@tag` — the CLI's only writer of the values handed to git.
+//
+// THE PATTERN IS THE SPECIFICATION. Where a comment here and a pattern below
+// disagree, the pattern is the design (f6 S-5).
+//
+// Three parsers accept this grammar (the Go write-boundary validator, this one,
+// and the console's paste parser, which deliberately accepts MORE). The shared
+// row list is `features/f6-gallery/fixtures/source-refs.json`, and every row
+// names the parsers it applies to.
+const OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const REPO = /^(?!\.)(?!.*\.\.)[A-Za-z0-9._-]{1,100}$/;
+const TAG = /^(?!.*\.\.)(?!.*\/\/)[A-Za-z0-9._][A-Za-z0-9._/-]{0,127}$/;
+/** A trailing `.git` is refused outright rather than stripped (S-5 fixture row). */
+function validRepo(repo) {
+    return REPO.test(repo) && !repo.endsWith(".git");
+}
+/** git's own check-ref-format rules, on top of the character grammar. */
+function validTag(tag) {
+    return TAG.test(tag) && !tag.endsWith("/") && !tag.endsWith(".lock");
+}
+const URL_LIKE = /^(https?:\/\/|git@|ssh:\/\/|github\.com[/:])/i;
+/**
+ * Best-effort conversion of a pasted GitHub URL to the shorthand, used ONLY to
+ * show the creator the form they should have typed. It never feeds git — a URL
+ * is always a refusal, and this is the remedy line.
+ */
+function convertUrl(input) {
+    const withoutScheme = input.replace(/^(https?:\/\/|ssh:\/\/|git@)/i, "").replace(/^git@/i, "");
+    const path = withoutScheme.replace(/^github\.com[/:]/i, "");
+    if (path === withoutScheme && !/^github\.com/i.test(withoutScheme))
+        return undefined;
+    const parts = path.split("/").filter((p) => p !== "");
+    if (parts.length < 2)
+        return undefined;
+    const owner = parts[0];
+    const repo = parts[1].replace(/\.git$/i, "");
+    // /releases/tag/<tag> and /tree/<tag> are the two forms a creator copies from
+    // a repo page; the tag may itself contain slashes, so take everything after.
+    let tag;
+    if (parts[2] === "releases" && parts[3] === "tag" && parts.length > 4) {
+        tag = parts.slice(4).join("/");
+    }
+    else if (parts[2] === "tree" && parts.length > 3) {
+        tag = parts.slice(3).join("/");
+    }
+    else if (parts.length === 2 && repo.includes("@")) {
+        const [r, t] = repo.split("@");
+        return OWNER.test(owner) && validRepo(r) && validTag(t)
+            ? { owner, repo: r, tag: t }
+            : undefined;
+    }
+    if (tag === undefined)
+        return undefined;
+    if (!OWNER.test(owner) || !validRepo(repo) || !validTag(tag))
+        return undefined;
+    return { owner, repo, tag };
+}
+/**
+ * Parse `owner/repo@tag`. Pure: no filesystem, no network, no process.
+ *
+ * A bare `owner/repo` is REFUSED, never defaulted to a branch — a default would
+ * point the command at a moving target (S-2).
+ */
+export function parseSourceRef(input) {
+    const s = input.trim();
+    if (URL_LIKE.test(s)) {
+        return { ok: false, failure: { kind: "looks_like_url", value: s, converted: convertUrl(s) } };
+    }
+    const at = s.indexOf("@");
+    const slash = s.indexOf("/");
+    if (at === -1) {
+        return {
+            ok: false,
+            failure: slash === -1 ? { kind: "missing_repo", value: s } : { kind: "missing_tag", value: s },
+        };
+    }
+    const left = s.slice(0, at);
+    const tag = s.slice(at + 1);
+    if (!left.includes("/"))
+        return { ok: false, failure: { kind: "missing_repo", value: s } };
+    const firstSlash = left.indexOf("/");
+    const owner = left.slice(0, firstSlash);
+    const repo = left.slice(firstSlash + 1);
+    if (!OWNER.test(owner))
+        return { ok: false, failure: { kind: "bad_owner", value: owner } };
+    if (!validRepo(repo))
+        return { ok: false, failure: { kind: "bad_repo", value: repo } };
+    if (!validTag(tag))
+        return { ok: false, failure: { kind: "bad_tag", value: tag } };
+    return { ok: true, ref: { owner, repo, tag } };
+}
+/**
+ * The clone URL's ONLY composition point. The host is a compile-time constant —
+ * never configuration, never derived from stored data (S-6).
+ */
+export function templateCloneURL(owner, repo) {
+    const url = `https://github.com/${owner}/${repo}.git`;
+    const parsed = new URL(url);
+    if (parsed.host !== "github.com" || parsed.protocol !== "https:") {
+        throw new Error(`Refusing to clone from ${parsed.host}`);
+    }
+    return url;
+}
+/** `owner/repo@tag`, the form the creator typed and the card shows. */
+export function formatSourceRef(ref) {
+    return `${ref.owner}/${ref.repo}@${ref.tag}`;
+}

package/dist/lib/sourceRefCopy.d.ts

@@ -0,0 +1,30 @@
+import { type ParseFailure } from "./sourceRef.js";
+export interface FromFailureContext {
+    /** The target directory as typed, for the runnable remedy line. */
+    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];
+    kind: "source" | "install";
+}, ctx: FromFailureContext): void;