@vincentt-xr/cli 0.8.0 → 0.10.0

package/dist/lib/feedbackCopy.d.ts

@@ -0,0 +1,70 @@
+/** Flow C1 — the two lines before the park. */
+export declare function waiting(): string[];
+/** Flow C6 — the opening line of a watch. */
+export declare function watching(): string[];
+/**
+ * Flow C2 — the ending of a drain. A count and nothing else: a fact about what
+ * this process did, naming no next step.
+ *
+ * It exists because a human running this in their own terminal otherwise reads
+ * three dense JSON lines and cannot tell whether the command is finished. It is
+ * deliberately NOT one line per annotation, which would duplicate the preview
+ * stream's arrival line in a second place and triple the stderr noise of the
+ * exact case this feature exists for.
+ */
+export declare function handedOver(n: number): string[];
+/**
+ * Flow C3 — the bounded window elapsed. One line, one integer, no glyph.
+ *
+ * `The preview is still live` is the load-bearing half: it is the fact that
+ * makes exit 64 actionable without an instruction. The window is named with its
+ * number because an unexplained stop is worse than the calibration.
+ */
+export declare function windowElapsed(timeoutMs: number): string[];
+/**
+ * Flow C4 — the session ended. `✗`, because this one stops: 65 is not a fault,
+ * but it is the end of a channel, and the glyph separates it from 64 at a glance
+ * in scrollback.
+ *
+ * The last line answers the creator's actual fear ("did my annotations die with
+ * the preview?") before they can ask it. It does NOT say to start a preview —
+ * that precondition is stated in `--help`, which is where a recipe reads it.
+ *
+ * `0 already handed over` reads slightly oddly and is the price of one sentence
+ * covering both counts; suppressing the line at zero would make the ending's
+ * shape depend on the count and give a reader two endings to learn.
+ */
+export declare function sessionEnded(handed: number): string[];
+/**
+ * The triage detail behind a 65, one flag away.
+ *
+ * The two paths print IDENTICALLY by default: a polling host reaches 65 on every
+ * re-park once a preview has ended, and a creator cannot act on the difference
+ * between a graceful teardown and a killed process. The distinction belongs to
+ * whoever is diagnosing, not to the hot path.
+ */
+export declare function sessionEndedDetail(reason: "signalled" | "unreachable", tree: string, cursor: number): string[];
+/** Flow C6 — a human stopped a watch. The preview is not what ended. */
+export declare function stoppedWatching(): string[];
+/** Flow C5 — the usage error. */
+export declare const USAGE = "Usage: vincentt feedback --wait | --watch [--timeout <seconds>]";
+/**
+ * Flow C6's human render, on stderr, while stdout keeps the exact NDJSON. One
+ * observation, two fidelities — the rule that already governs the perf stream.
+ *
+ * Columns are the preview stream's columns (time, then the tester, then the
+ * content), so a creator who has read a preview stream reads this with nothing
+ * new to learn. The screenshot path is its own line, unadorned, so it is
+ * copy-clean. NOT rendered: id, seq, projectDir — a human can act on none of
+ * them.
+ */
+export interface WatchEntry {
+    createdAt: number;
+    tester?: string;
+    message: string;
+    screenshotPath: string;
+}
+export declare function watchEntry(e: WatchEntry, columns: number | undefined): string[];
+export declare function stripControl(s: string): string;
+/** Hard wrap at `width`, breaking on spaces where one is available. */
+export declare function wrap(s: string, width: number): string[];

package/dist/lib/feedbackCopy.js

@@ -0,0 +1,163 @@
+// Every line `vincentt feedback` writes to STDERR (Flows C1-C6). Pure functions
+// returning string arrays, so the transcripts are assertable without a terminal.
+//
+// The verb has two readers on two streams and they are different audiences:
+// stdout is a MACHINE (one JSON annotation per line, nothing else, ever) and
+// stderr is a HUMAN. Nothing in this file may ever be written to stdout.
+//
+// Two rules govern all of it:
+//   - UNBIDDEN OUTPUT STATES A FACT, NEVER A COMMAND. `--wait` prints on its own
+//     initiative into what is often an agent's input, so no line here names
+//     something to run. Every ending states what is true about the world
+//     ("The preview is still live", "The preview ended") where the CLI's older
+//     verbs would have ended with an instruction.
+//   - An exit code that means "retry is correct" carries NO GLYPH. 64 is neither
+//     a failure nor a success: `✗` would teach a polling host's reader that the
+//     normal case looks broken, and `✓` would claim something happened.
+//
+// The annotation's own content is never echoed here on the `--wait` path. It is
+// viewer-authored and hostile, and the reader is a parked consumer that is about
+// to receive the whole record on stdout anyway.
+/** Flow C1 — the two lines before the park. */
+export function waiting() {
+    return [
+        "  Waiting for feedback from the preview in this folder.",
+        // The verb is ambiguous on first contact — `feedback` could plausibly mean
+        // "send feedback to Vincentt", which is `vincentt dx`. This disambiguates by
+        // naming DIRECTION rather than by issuing an instruction.
+        "  Nothing is sent from here; this only reads what your phone sends.",
+    ];
+}
+/** Flow C6 — the opening line of a watch. */
+export function watching() {
+    return ["  Watching for feedback from the preview in this folder. Ctrl-C to stop."];
+}
+/**
+ * Flow C2 — the ending of a drain. A count and nothing else: a fact about what
+ * this process did, naming no next step.
+ *
+ * It exists because a human running this in their own terminal otherwise reads
+ * three dense JSON lines and cannot tell whether the command is finished. It is
+ * deliberately NOT one line per annotation, which would duplicate the preview
+ * stream's arrival line in a second place and triple the stderr noise of the
+ * exact case this feature exists for.
+ */
+export function handedOver(n) {
+    return ["", `  ${n} handed over.`, ""];
+}
+/**
+ * Flow C3 — the bounded window elapsed. One line, one integer, no glyph.
+ *
+ * `The preview is still live` is the load-bearing half: it is the fact that
+ * makes exit 64 actionable without an instruction. The window is named with its
+ * number because an unexplained stop is worse than the calibration.
+ */
+export function windowElapsed(timeoutMs) {
+    return [
+        "",
+        `  No feedback in the last ${windowLabel(timeoutMs)}. The preview is still live.`,
+        "",
+    ];
+}
+/** Whole minutes read as minutes; anything else reads as seconds. */
+function windowLabel(timeoutMs) {
+    const seconds = Math.max(Math.round(timeoutMs / 1000), 0);
+    if (seconds >= 60 && seconds % 60 === 0) {
+        const minutes = seconds / 60;
+        return `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+    }
+    return `${seconds} ${seconds === 1 ? "second" : "seconds"}`;
+}
+/**
+ * Flow C4 — the session ended. `✗`, because this one stops: 65 is not a fault,
+ * but it is the end of a channel, and the glyph separates it from 64 at a glance
+ * in scrollback.
+ *
+ * The last line answers the creator's actual fear ("did my annotations die with
+ * the preview?") before they can ask it. It does NOT say to start a preview —
+ * that precondition is stated in `--help`, which is where a recipe reads it.
+ *
+ * `0 already handed over` reads slightly oddly and is the price of one sentence
+ * covering both counts; suppressing the line at zero would make the ending's
+ * shape depend on the count and give a reader two endings to learn.
+ */
+export function sessionEnded(handed) {
+    return [
+        "",
+        "✗ The preview ended. Nothing more can arrive on it.",
+        "",
+        `  Nothing was missed — the ${handed} already handed over stay handed over.`,
+        "",
+    ];
+}
+/**
+ * The triage detail behind a 65, one flag away.
+ *
+ * The two paths print IDENTICALLY by default: a polling host reaches 65 on every
+ * re-park once a preview has ended, and a creator cannot act on the difference
+ * between a graceful teardown and a killed process. The distinction belongs to
+ * whoever is diagnosing, not to the hot path.
+ */
+export function sessionEndedDetail(reason, tree, cursor) {
+    const which = reason === "signalled"
+        ? "The preview signalled it was ending"
+        : "The relay stopped answering (no teardown signal)";
+    return [`  ${which} · ${tree}`, `  Cursor unchanged at ${cursor}.`, ""];
+}
+/** Flow C6 — a human stopped a watch. The preview is not what ended. */
+export function stoppedWatching() {
+    return ["", "  Stopped watching. The preview is still live.", ""];
+}
+/** Flow C5 — the usage error. */
+export const USAGE = "Usage: vincentt feedback --wait | --watch [--timeout <seconds>]";
+/** Content indent + the time column + its gutter — where the tester starts. */
+const TESTER_COL = 9;
+export function watchEntry(e, columns) {
+    const time = clockLabel(e.createdAt);
+    const tester = e.tester ?? "";
+    const head = `  ${time}  ${tester}`;
+    const gutter = " ".repeat(TESTER_COL);
+    // The message is viewer-authored and hostile. A raw `\n` or an ANSI escape in
+    // it must not forge a second entry or repaint the screen, so control
+    // characters are STRIPPED (not escaped — this stream is for reading) before
+    // the text is wrapped. stdout's equivalent protection is JSON.stringify.
+    const width = wrapWidth(columns);
+    const indent = " ".repeat(head.length + 2);
+    const body = wrap(stripControl(e.message), Math.max(width - indent.length, 20));
+    const out = [`${head}  ${body[0] ?? ""}`];
+    for (const line of body.slice(1))
+        out.push(`${indent}${line}`);
+    out.push(`${gutter}${stripControl(e.screenshotPath)}`);
+    return out;
+}
+function clockLabel(createdAt) {
+    const d = new Date(createdAt);
+    if (Number.isNaN(d.getTime()))
+        return "--:--";
+    return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+function wrapWidth(columns) {
+    return columns !== undefined && columns >= 40 ? columns : 80;
+}
+/**
+ * C0 and C1 controls out, including ESC, CR, LF, NUL and the DEL range. A
+ * replacement character would still occupy a cell for something the tester did
+ * not type, so they are removed rather than substituted.
+ */
+const CONTROL_RE = /[\u0000-\u001f\u007f-\u009f]/gu;
+export function stripControl(s) {
+    return s.replace(CONTROL_RE, "");
+}
+/** Hard wrap at `width`, breaking on spaces where one is available. */
+export function wrap(s, width) {
+    const out = [];
+    let rest = s;
+    while (rest.length > width) {
+        const cut = rest.lastIndexOf(" ", width);
+        const at = cut > 0 ? cut : width;
+        out.push(rest.slice(0, at));
+        rest = rest.slice(cut > 0 ? at + 1 : at);
+    }
+    out.push(rest);
+    return out;
+}

package/dist/lib/initCommand.d.ts

@@ -1,8 +1,10 @@
+import type { RegisterDeps } from "./initFrom.js";
+import { type SourceRef } from "./sourceRef.js";
 import type { Ask, Confirm } from "../publish/prompt.js";
 export interface InitDeps {
     print: (line: string) => void;
     cwd: string;
-    scaffold?: (targetDir: string, ref?: string) => Promise<void>;
+    scaffold?: (targetDir: string, opts: ScaffoldCall) => Promise<void>;
     install?: (targetDir: string) => Promise<string>;
     isEmpty?: (targetDir: string) => Promise<boolean>;
     /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
@@ -11,6 +13,23 @@ export interface InitDeps {
     confirm?: Confirm;
     /** Non-empty check for the resolved target; injected in tests. */
     isNonEmpty?: (targetDir: string) => Promise<boolean>;
+    /**
+     * The registration half of `--from`. Injected whole so the combined path is
+     * drivable without a real API, a real browser, or a real HOME.
+     */
+    register?: (deps: Pick<RegisterDeps, "print" | "targetDir" | "dirLabel" | "ask">, opts: {
+        name?: string;
+        slug?: string;
+    }) => Promise<number>;
+}
+/**
+ * What `InitDeps.scaffold` is called with. An OBJECT rather than a positional
+ * ref: `--from` needs to name a repo too, and a positional-to-object change
+ * compiles silently in a fake that ignores its second argument.
+ */
+export interface ScaffoldCall {
+    repo?: string;
+    ref?: string;
 }
 /** The folder name offered when `init` is run bare and the creator just hits Enter. */
 export declare const DEFAULT_APP_NAME = "my-ar-app";
@@ -27,5 +46,13 @@ export interface InitOptions {
     skipInstall?: boolean;
     /** Template version to scaffold from; defaults to the latest release. */
     template?: string;
+    /**
+     * A gallery source, already parsed. The combined path (f6): clone this repo at
+     * this tag, then register the project. NEVER installs dependencies (S-1).
+     */
+    from?: SourceRef;
+    /** `--name` / `--slug`, accepted on `init` only when `--from` is present. */
+    name?: string;
+    slug?: string;
 }
 export declare function initCommand(deps: InitDeps, opts?: InitOptions): Promise<number>;

package/dist/lib/initCommand.js

@@ -1,12 +1,19 @@
-// `vincentt init [dir]` — scaffold a Vincentt XR app. NO account, NO network call
-// to the API, NO binding written.
+// `vincentt init [dir]` — scaffold a Vincentt XR app. On the BARE path: NO
+// account, NO network call to the API, NO binding written.
 //
 // This is the acquisition wedge: local-first is a smaller room, not a wall, so the
 // template must be reachable without ever touching the auth gate. `create` (which
 // does need an account) is offered at the end as the next thing AVAILABLE, never as
 // a requirement.
+//
+// `--from owner/repo@tag` (f6) adds a SECOND path that clones a gallery template
+// and then registers the project, so it does call the API — for its second half,
+// after the source is on disk. The claim above is scoped to the bare path and
+// stays true of it: no flag added to `init` may make the bare path touch the
+// network (A-5.3).
 import path from "node:path";
-import { detectPackageManager, installDependencies, isNonEmptyDir, needsScaffold, scaffoldFromTemplate, } from "../scaffold/index.js";
+import { ScaffoldRefError, detectPackageManager, installDependencies, isNonEmptyDir, needsScaffold, scaffoldFromTemplate, } from "../scaffold/index.js";
+import { formatSourceRef, templateCloneURL } from "./sourceRef.js";
 /** The folder name offered when `init` is run bare and the creator just hits Enter. */
 export const DEFAULT_APP_NAME = "my-ar-app";
 /**
@@ -81,20 +88,36 @@ export async function initCommand(deps, opts = {}) {
     // version they have no reason to care about.
     if (opts.template)
         deps.print(`  · template ${opts.template}`);
+    if (opts.from)
+        deps.print(`  · from ${formatSourceRef(opts.from)}`);
     const scaffold = deps.scaffold ??
-        ((dir, ref) => scaffoldFromTemplate(dir, { ref }));
+        ((dir, o) => scaffoldFromTemplate(dir, o));
     try {
-        await scaffold(target, opts.template);
+        await scaffold(target, opts.from
+            ? { repo: templateCloneURL(opts.from.owner, opts.from.repo), ref: opts.from.tag }
+            : { ref: opts.template });
     }
     catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
         deps.print("");
-        deps.print(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        if (opts.from) {
+            printFromScaffoldFailure(deps.print, opts.from, isRefFailure(err, msg));
+            return 1;
+        }
+        deps.print(`✗ ${msg}`);
         deps.print("");
         deps.print("  Run `vincentt init` again once that is resolved.");
         return 1;
     }
+    // S-1: the combined path CLONES AND STOPS. No package manager is spawned, and
+    // the refusal is structural — `--from` is rejected in the argument parser
+    // alongside any install-enabling flag, so this branch cannot be re-enabled by
+    // a caller.
     let installed = true;
-    if (!opts.skipInstall) {
+    if (opts.from) {
+        installed = false;
+    }
+    else if (!opts.skipInstall) {
         deps.print("  · installing dependencies");
         const install = deps.install ?? ((dir) => installDependencies(dir));
         try {
@@ -110,7 +133,6 @@ export async function initCommand(deps, opts = {}) {
     const pm = await detectPackageManager(target).catch(() => "npm");
     deps.print("");
     deps.print(`✓ Created ${label}`);
-    deps.print("");
     const steps = [];
     // Keyed off the RESOLVED dir, not the flag — a prompted name needs the cd too.
     if (dir !== ".")
@@ -119,18 +141,71 @@ export async function initCommand(deps, opts = {}) {
         steps.push([`${pm} install`, "Install dependencies"]);
     }
     steps.push([`${pm} run dev`, "Start the local dev server"]);
-    for (const line of alignedSteps(steps))
-        deps.print(line);
+    if (!opts.from) {
+        deps.print("");
+        for (const line of alignedSteps(steps))
+            deps.print(line);
+        deps.print("");
+        deps.print("  No account needed. When you're ready to put it online:");
+        for (const line of alignedSteps([
+            ["vincentt login", "Connect this machine to Vincentt"],
+            ["vincentt create", "Register the project and reserve its address"],
+        ])) {
+            deps.print(line);
+        }
+        return 0;
+    }
+    // S-1's whole UX: two sentences, no apology and no threat model. The install
+    // appears below as an ordinary step, never as a remedy — a creator should
+    // never learn that it is unusual.
+    deps.print("  The source is yours. Dependencies are not installed yet.");
+    // TRAP 4: the scaffold's success is already in the output, and the exit code
+    // still reports the registration half. The `✗` is the last glyph, always.
+    const register = deps.register;
+    if (!register)
+        return 0;
+    const code = await register({ print: deps.print, targetDir: target, dirLabel: label, ask: deps.ask }, { name: opts.name, slug: opts.slug });
+    if (code !== 0)
+        return code;
     deps.print("");
-    deps.print("  No account needed. When you're ready to put it online:");
-    for (const line of alignedSteps([
-        ["vincentt login", "Connect this machine to Vincentt"],
-        ["vincentt create", "Register the project and reserve its address"],
-    ])) {
+    deps.print("  Next:");
+    for (const line of alignedSteps(steps))
         deps.print(line);
-    }
     return 0;
 }
+/**
+ * The scaffold half's failure copy for `--from`, which branches on WHICH repo
+ * was cloned. The shipped "omit --template to use the latest release" advice is
+ * right for the built-in template and meaningless for a gallery source.
+ *
+ * Nothing was written — no `else` — because there is no second half above this.
+ */
+function isRefFailure(err, message) {
+    return (err instanceof ScaffoldRefError ||
+        /has no version|remote branch|couldn't find remote ref/i.test(message));
+}
+function printFromScaffoldFailure(print, from, refMissing) {
+    const named = `${from.owner}/${from.repo}`;
+    if (refMissing) {
+        print(`✗ The repository ${named} has no tag "${from.tag}"`);
+        print("");
+        print("  The gallery card always shows the current reference. If you pasted this command");
+        print("  from somewhere else, it may be out of date.");
+        print("");
+        print("  Nothing was written.");
+        print("");
+        print("  Copy the command again from the gallery and run it.");
+        return;
+    }
+    print(`✗ Could not reach github.com/${named}`);
+    print("");
+    print("  The repository may have been renamed or made private, or your network may be");
+    print("  blocking github.com.");
+    print("");
+    print("  Nothing was written.");
+    print("");
+    print("  Check the command on the gallery card and run it again.");
+}
 /** 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));

package/dist/lib/initFrom.d.ts

@@ -0,0 +1,70 @@
+import { type SourceRef } from "./sourceRef.js";
+/** How many times the address prompt re-asks before falling back to the printed block. */
+export declare const ADDRESS_REASK_LIMIT = 3;
+export interface RegisterDeps {
+    print: (line: string) => void;
+    /** The scaffolded directory — the cwd the registration acts in. */
+    targetDir: string;
+    /** Label for the resume command (`cd <label>`). */
+    dirLabel: string;
+    /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
+    ask?: (prompt: string, fallback: string) => Promise<string>;
+    /** Resolve the current PAT, or undefined. Never triggers a login by itself. */
+    currentToken: () => Promise<string | undefined>;
+    /** Run the interactive browser login. Only ever called on a TTY. */
+    runLogin: () => Promise<void>;
+    /** Resolve which org to register in, and where that choice came from. */
+    resolveOrg: () => Promise<{
+        ok: true;
+        name: string;
+        source: OrgSource;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /**
+     * f2's shipped registration half, injected. Returns the exit code; it owns the
+     * binding write, which happens ONLY after the 201.
+     */
+    create: (opts: {
+        name: string;
+        slug: string;
+    }) => Promise<number>;
+    /**
+     * Whether a scaffold ran above this call. It changes exactly one word, and that
+     * word is the on-disk state: "Nothing else was written." (source exists) versus
+     * "Nothing was written." (it does not).
+     *
+     * `create` in an ALREADY-scaffolded folder (case 2) reaches this orchestrator
+     * without having written anything, so the shipped default — true, f6's combined
+     * path, where a clone always precedes it — would tell that creator their source
+     * was written by this command.
+     */
+    scaffolded?: boolean;
+    /**
+     * Whether the resume block carries a `cd <dir>`. `create` run in the cwd has
+     * nowhere to cd to, so the line would be `cd .`.
+     *
+     * Defaults to true: f6's path always scaffolds INTO a named directory.
+     */
+    resumeNeedsCd?: boolean;
+}
+export type OrgSource = "active" | "env" | "flag";
+export interface RegisterOptions {
+    /** `--name`, read before prompting. */
+    name?: string;
+    /** `--slug`, read before prompting. */
+    slug?: string;
+}
+/**
+ * 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 declare function registerAfterScaffold(deps: RegisterDeps, opts?: RegisterOptions): Promise<number>;
+/** The `· from owner/repo@tag` bullet in the start block. */
+export declare function sourceBullet(ref: SourceRef): string;