@vincentt-xr/cli 0.9.0 → 0.10.0

package/dist/cli/index.js

@@ -19,7 +19,8 @@ import { httpAuthBackend } from "../login/authBackend.js";
 import { loginCommand } from "../login/loginCommand.js";
 import { ensureLoggedIn } from "../login/ensure.js";
 import { clearMachineToken, loadMachineConfig, locateProjectBinding, resolveConfig, writeDxEnablement, MACHINE_CONFIG_PATH, } from "../shared/config.js";
-import { getMe, ProjectUnreachableError } from "../lib/backend.js";
+import { getMe, listProjects, ProjectUnreachableError } from "../lib/backend.js";
+import { listProjectsCommand } from "../lib/listProjects.js";
 import { initCommand } from "../lib/initCommand.js";
 import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
 import { whoamiCommand } from "../lib/whoami.js";
@@ -28,13 +29,16 @@ import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, proj
 import { publishCommand } from "../publish/command.js";
 import { stdinAsk, stdinConfirm } from "../publish/prompt.js";
 import { consoleVerbCommand, isConsoleOnlyVerb } from "../publish/consoleVerbs.js";
+import { resolveVerb } from "./verb-surface.js";
+import { USAGE_TEXT } from "./usage-text.js";
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
-import { readLivePreview } from "../lib/relayInfo.js";
+import { readLivePreview, relayInfoDir } from "../lib/relayInfo.js";
 import { attachedToRunning, mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
 import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
+import * as feedbackCopy from "../lib/feedbackCopy.js";
 import { record as recordInvocation } from "../dx/journal.js";
 import { dxDisableCommand, dxEnableCommand, dxSendCommand, parseDxOptions, runDx, } from "../dx/command.js";
 import { DX_UNATTENDED_SUNSET, loadEnablement } from "../dx/enablement.js";
@@ -42,11 +46,12 @@ import { journalEnabled, journalPath, readJournal } from "../dx/journal.js";
 import { postReport } from "../dx/send.js";
 import { nudgeFor } from "../dx/nudge.js";
 import { verbOf } from "../dx/skeleton.js";
-import { fromFlagConflict, isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
+import { createSourceFlagRefusal, fromFlagConflict, isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
 import { parseSourceRef } from "../lib/sourceRef.js";
-import { printFlagConflict, printSourceRefFailure } from "../lib/sourceRefCopy.js";
+import { printCreateSourceFlagRefusal, printFlagConflict, printSourceRefFailure, } from "../lib/sourceRefCopy.js";
 import { registerAfterScaffold } from "../lib/initFrom.js";
-import { createCommand } from "../lib/projects.js";
+import { registerProject } from "../lib/projects.js";
+import { sanitizeAppName } from "../lib/initCommand.js";
 import { resolveOrgForCommand } from "../lib/lifecycle.js";
 // The console origin serves /cli-auth (the browser target for `vincentt login`). VINCENTT_
 // CONSOLE_URL overrides for dev/dogfood; VINCENTT_EDITOR_URL is honored as a legacy alias.
@@ -75,6 +80,15 @@ function projectDir() {
 function positional(n) {
     return positionalArgs(argv)[n];
 }
+/**
+ * The value of a `--flag=value` spelling, which `flag()` cannot see at all (it is
+ * a bare `argv.indexOf`). Only used to echo the creator's own argument back into a
+ * refusal's remedy, so both spellings produce a copy-pasteable line.
+ */
+function valueOfEqualsFlag(args, name) {
+    const hit = args.find((a) => a.startsWith(`${name}=`));
+    return hit?.slice(name.length + 1) || undefined;
+}
 // ---- auth -------------------------------------------------------------------
 async function resolveAuthUrls() {
     const machine = await loadMachineConfig();
@@ -204,7 +218,9 @@ async function init() {
                 },
                 resolveOrg: async () => {
                     const cfg = await resolveConfig(rd.targetDir, { warn: print });
-                    const resolved = await resolveOrgForCommand(cfg, { flag: flag("--org") });
+                    const resolved = await resolveOrgForCommand(cfg, {
+                        flag: flag("--org"),
+                    });
                     if (!resolved.ok)
                         return resolved;
                     return {
@@ -213,7 +229,10 @@ async function init() {
                         source: orgSource(),
                     };
                 },
-                create: async ({ name, slug }) => createCommand({
+                // registerProject, NOT createCommand: createCommand is now the
+                // whole two-half verb, so calling it here would classify and
+                // scaffold a second time inside the half that already cloned.
+                create: async ({ name, slug }) => registerProject({
                     print,
                     cwd: rd.targetDir,
                     config: () => resolveConfig(rd.targetDir, { warn: print }),
@@ -239,13 +258,54 @@ function orgSource() {
     return "active";
 }
 async function create() {
-    await requireLogin();
+    // NO requireLogin() here, deliberately. The scaffold half must not depend on a
+    // session: `create` in an empty folder writes the open template, and a gate at
+    // the top of the verb would put it behind the auth gate. The session is
+    // consulted BELOW the seam, inside the verb. `link()` three lines down still
+    // calls requireLogin, correctly — do not copy it up here.
+    const print = (l) => console.log(l);
+    const dirLabel = positional(1) ?? ".";
+    // The parser refusal runs FIRST, before anything is read or written. `flag()` is
+    // a global argv scan with no per-verb gate, so a single natural copy of
+    // `template: flag("--template")` into this function would make `create` an
+    // unauthenticated arbitrary-ref clone-and-execute, and nothing would go red.
+    const refusedSource = createSourceFlagRefusal(argv);
+    if (refusedSource) {
+        printCreateSourceFlagRefusal(print, refusedSource, {
+            dir: dirLabel,
+            value: flag(refusedSource) ?? valueOfEqualsFlag(argv, refusedSource),
+        });
+        process.exitCode = 1;
+        return;
+    }
+    const raw = positional(1);
+    let dir;
+    if (raw !== undefined) {
+        const safe = sanitizeAppName(raw);
+        if (safe === null) {
+            print(`✗ "${raw.trim()}" is not a folder name.`);
+            print("");
+            print("  Use a plain name (my-ar-app), or `vincentt create` for this folder.");
+            process.exitCode = 1;
+            return;
+        }
+        dir = safe;
+    }
+    const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
     const result = await projectCreate(projectDir(), {
         name: flag("--name"),
         slug: flag("--slug"),
         org: flag("--org"),
         force: has("--force"),
         allowCustomApi: has("--allow-custom-api"),
+        dir,
+        skipInstall: has("--no-install"),
+        ask: interactive ? stdinAsk() : undefined,
+        currentToken,
+        runLogin: async () => {
+            await login();
+        },
+        orgSource,
         onLine: (l) => console.log(l),
     });
     if (result.exitCode !== 0) {
@@ -279,6 +339,34 @@ async function unlink() {
         config: () => resolveConfig(cwd),
     });
 }
+/**
+ * `vincentt projects` — which projects does this workspace have?
+ *
+ * Reads the MACHINE config and the org precedence chain, never the folder's
+ * binding, for the same reason `whoami` does: it answers a question about the
+ * workspace. A folder-derived default would make the one verb a creator runs
+ * BECAUSE they are in an unbound folder depend on that folder having a binding.
+ */
+async function projects() {
+    await requireLogin();
+    const machine = await loadMachineConfig();
+    const config = async () => {
+        const apiUrl = process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
+        const pat = process.env.VINCENTT_PAT ?? machine.pat;
+        return pat ? { apiUrl: apiUrl.replace(/\/$/, ""), pat } : undefined;
+    };
+    process.exitCode = await listProjectsCommand({
+        print: (l) => console.log(l),
+        config,
+        org: async () => {
+            const cfg = await config();
+            if (!cfg)
+                return { ok: false, message: "Not signed in. Run `vincentt login`." };
+            return resolveOrgForCommand(cfg, { flag: flag("--org") });
+        },
+        list: listProjects,
+    }, { json: has("--json") });
+}
 /**
  * `vincentt publish` — Flows L22-L31.
  *
@@ -417,6 +505,7 @@ async function preview() {
                 }
             },
             onCapReached: () => ui.capReached(),
+            onAnnotation: (tags) => ui.annotation(tags),
             onTunnelState: (state) => ui.tunnel(state),
             onOriginError: () => ui.originError(),
             onOriginRecovered: () => ui.originRecovered(),
@@ -451,6 +540,7 @@ async function preview() {
         orgName: await activeOrgName(),
         targetUrl: `http://localhost:${running.appPort}`,
         url: running.url,
+        consoleUrl: await projectConsoleUrl(cwd),
         qr,
         expiresInHours: 12,
     })) {
@@ -560,6 +650,22 @@ async function projectDisplayName(cwd) {
     const located = await locateProjectBinding(cwd);
     return located?.binding.slug ?? path.basename(cwd);
 }
+/**
+ * The project's page in the console, or undefined for an unlinked folder.
+ *
+ * The path is the BARE-ID route (`/projects/<id>`), the same shape
+ * `consoleVerbCommand` deep-links to. The console redirects it to the org-scoped
+ * address, so the CLI does not need the org slug and cannot print a stale one — a
+ * folder can outlive the org binding the machine config happens to hold.
+ */
+async function projectConsoleUrl(cwd) {
+    const located = await locateProjectBinding(cwd);
+    if (!located)
+        return undefined;
+    const cfg = await loadMachineConfig();
+    const base = (cfg.consoleUrl ?? DEFAULT_CONSOLE_URL).replace(/\/$/, "");
+    return `${base}/projects/${located.binding.projectId}`;
+}
 /**
  * Map a mint failure to its screen. Each cause has a DISTINCT first line so the
  * creator never has to read a second, and none of them names the edge, the API
@@ -598,28 +704,179 @@ async function diag(kind) {
     }
 }
 // ---- reverse channel --------------------------------------------------------
+/**
+ * `vincentt feedback` — the reverse channel's consumer, and the one verb whose
+ * EXIT CODE is the contract.
+ *
+ * | exit | meaning                                  | stdout    | cursor    |
+ * |------|------------------------------------------|-----------|-----------|
+ * | 0    | one or more annotations handed over      | NDJSON    | advanced  |
+ * | 64   | the bounded window elapsed, nothing new  | *(empty)* | untouched |
+ * | 65   | the preview session has ended            | *(empty)* | untouched |
+ * | 1    | usage error, or an unexpected fault      | *(empty)* | untouched |
+ *
+ * A caller never parses stdout to decide whether to re-park: empty stdout is
+ * never ambiguous, because 64 and 65 differ. 64 and 65 are NOT errors — a
+ * recipe must be able to loop on 64 without also swallowing real failures.
+ *
+ * 64/65 sit above the band generic tooling overloads, below the shell-reserved
+ * 126, and deliberately avoid 124: GNU `timeout` emits 124, and a recipe that
+ * wraps this command in `timeout` would otherwise be unable to tell its own
+ * timeout from ours.
+ *
+ * The contract is APPEND-ONLY, permanently: a code may be added, an existing
+ * code's meaning never changes, a flag once accepted stays accepted, and
+ * stdout's one-JSON-per-line grammar never changes shape.
+ */
 async function feedback() {
     const cwd = projectDir();
     const timeoutMs = (numFlag("--timeout") ?? 300) * 1000;
+    const verbose = has("--verbose");
     const watch = has("--watch");
     if (!watch && !has("--wait")) {
-        console.error("Usage: vincentt feedback --wait | --watch [--timeout <seconds>]");
+        console.error(feedbackCopy.USAGE);
         process.exitCode = 1;
         return;
     }
-    do {
-        const after = await readCursor(cwd);
-        const annotation = await fetchNext(cwd, { after, timeoutMs });
-        if (!annotation) {
-            // 204 re-arm signal: --wait exits empty, --watch loops.
-            if (!watch)
-                return;
+    // process.exit() would truncate a pending pipe write, so every path here
+    // assigns exitCode and RETURNS — the loop drains on its own.
+    process.exitCode = watch
+        ? await feedbackWatch(cwd, timeoutMs, verbose)
+        : await feedbackWait(cwd, timeoutMs, verbose);
+}
+/**
+ * The drain. `--wait` hands over EVERY pending annotation and then exits, not
+ * exactly one: a creator who walked the room and sent three is one hand-off, and
+ * three round trips would be three wakes for one thought.
+ *
+ * The first park uses the full window; every subsequent probe asks "is there
+ * another RIGHT NOW" with `timeoutMs: 0` and must not block, or the batch
+ * silently costs one window per annotation.
+ */
+async function feedbackWait(cwd, timeoutMs, verbose) {
+    for (const l of feedbackCopy.waiting())
+        console.error(l);
+    let after = await readCursor(cwd);
+    let handed = 0;
+    for (;;) {
+        const result = await fetchNext(cwd, {
+            after,
+            timeoutMs: handed === 0 ? timeoutMs : 0,
+        });
+        if (result.kind === "empty") {
+            if (handed > 0)
+                break;
+            for (const l of feedbackCopy.windowElapsed(timeoutMs))
+                console.error(l);
+            return 64;
+        }
+        if (result.kind === "closed") {
+            if (handed > 0)
+                break;
+            for (const l of feedbackCopy.sessionEnded(handed))
+                console.error(l);
+            if (verbose) {
+                for (const l of feedbackCopy.sessionEndedDetail(result.reason, await relayInfoDir(cwd), after)) {
+                    console.error(l);
+                }
+            }
+            return 65;
+        }
+        await handOver(cwd, result.annotation);
+        after = result.annotation.seq;
+        handed += 1;
+    }
+    // A session that ended MID-BATCH is still a successful hand-off: exiting 65
+    // here would tell a polling host to stop after it had just been given work.
+    // The un-drained tail is not skipped — the cursor names only what was printed.
+    for (const l of feedbackCopy.handedOver(handed))
+        console.error(l);
+    return 0;
+}
+/**
+ * `--watch` streams for a human and does not return on an elapsed window — it
+ * re-arms. It DOES return 65 when the session ends, rather than looping forever
+ * against a channel that can never speak again.
+ *
+ * `--timeout` is accepted here (a flag once accepted is accepted forever) and
+ * names the internal re-arm interval rather than a bounded window.
+ */
+async function feedbackWatch(cwd, timeoutMs, verbose) {
+    for (const l of feedbackCopy.watching())
+        console.error(l);
+    // A human stopping a watch is not a failure, so it ends 0 — and the ending
+    // says the PREVIEW is still live, because what stopped is this command.
+    //
+    // An interrupt between a completed write and its cursor advance leaves the
+    // cursor behind, which re-delivers that annotation on the next run. That is
+    // at-least-once working as designed, and the safe direction.
+    process.on("SIGINT", () => {
+        for (const l of feedbackCopy.stoppedWatching())
+            console.error(l);
+        process.exit(0);
+    });
+    let after = await readCursor(cwd);
+    let handed = 0;
+    // A `--timeout 0` here would make the re-arm a busy loop against the relay
+    // rather than a parked request. The flag stays ACCEPTED (it always has been)
+    // and the floor is applied silently: a watch's window is an implementation
+    // detail of its re-arm, not a contract the caller reads back.
+    const armMs = Math.max(timeoutMs, 1_000);
+    for (;;) {
+        const result = await fetchNext(cwd, { after, timeoutMs: armMs });
+        if (result.kind === "empty")
             continue;
+        if (result.kind === "closed") {
+            // `{N}` is what THIS invocation handed over, which for a watch that ran
+            // for an hour is not 0. The ending is C4's, exit code included: a watch
+            // against a dead channel would otherwise loop forever.
+            for (const l of feedbackCopy.sessionEnded(handed))
+                console.error(l);
+            if (verbose) {
+                for (const l of feedbackCopy.sessionEndedDetail(result.reason, await relayInfoDir(cwd), after)) {
+                    console.error(l);
+                }
+            }
+            return 65;
         }
-        // Print BEFORE advancing the cursor → at-least-once (a crash re-delivers).
-        console.log(JSON.stringify(annotation));
-        await writeCursor(cwd, annotation.seq);
-    } while (watch);
+        const a = result.annotation;
+        await handOver(cwd, a);
+        // The human's copy, on stderr, in the second fidelity. stdout stays the
+        // exact NDJSON, so `feedback --watch > out.ndjson` is still clean.
+        console.error("");
+        for (const l of feedbackCopy.watchEntry({
+            createdAt: a.createdAt,
+            tester: a.sessionId,
+            message: a.message,
+            screenshotPath: a.screenshotPath,
+        }, process.stderr.columns)) {
+            console.error(l);
+        }
+        after = a.seq;
+        handed += 1;
+    }
+}
+/**
+ * THE ORDERING THAT MAKES DELIVERY AT-LEAST-ONCE.
+ *
+ * The cursor advances only inside write's completion callback, having fired
+ * without error. On a PIPE — the consumer case this channel exists for —
+ * `write()` is ASYNCHRONOUS and returns before the bytes reach the OS.
+ * Advancing on return and then being killed loses the annotation with the
+ * cursor already past it: at-most-once, silently, with no way for the creator to
+ * learn their words were gone.
+ *
+ * `console.log` is barred from this path for the same reason — it offers no
+ * completion callback, so there is no point at which the cursor may legally
+ * advance. There is no `stdout.flush()`; Node streams have no such method, and
+ * the callback is the only correct signal.
+ */
+async function handOver(cwd, a) {
+    const line = JSON.stringify(a) + "\n";
+    await new Promise((resolve, reject) => {
+        process.stdout.write(line, (err) => (err ? reject(err) : resolve()));
+    });
+    await writeCursor(cwd, a.seq);
 }
 // ---- meta -------------------------------------------------------------------
 /**
@@ -746,7 +1003,7 @@ async function assets() {
         // Not signed in — the exit-4 screen, because we did not answer. The library is
         // a platform call, and the creator's PROJECT is unaffected either way.
         const { unreachableLines } = await import("../library/render.js");
-        for (const l of unreachableLines("auth", "vincentt assets search \"<what you want>\"")) {
+        for (const l of unreachableLines("auth", 'vincentt assets search "<what you want>"')) {
             console.error(l);
         }
         process.exitCode = 4;
@@ -803,70 +1060,9 @@ async function relay() {
     });
 }
 // ---- dispatch ---------------------------------------------------------------
-function usage() {
-    console.log(`Vincentt CLI — local-first AR dev loop\n\n` +
-        `Usage: vincentt <command> [options]\n\n` +
-        `Getting started (building a new app with a coding agent)\n` +
-        `  1. Confirm a project name with the developer first.\n` +
-        `  2. Scaffold:  vincentt init <dir>     (no account needed)\n` +
-        `  3. Register:  vincentt create --name "<name>"\n` +
-        `  4. Read AGENTS.md, confirm it is ready, and stop — do NOT invent an app.\n` +
-        `     Wait for the developer to describe what to build.\n` +
-        `  Full guide: npm view @vincentt-xr/cli readme\n\n` +
-        `Auth\n` +
-        `  login              Sign in; save an access token to ~/.vincentt/config.json\n` +
-        `                       [--api <url>] [--console <url>] to target a non-prod env\n` +
-        `  logout             Remove the saved access token\n` +
-        `  whoami             Show the signed-in account\n\n` +
-        `Project\n` +
-        `  init [dir]         Scaffold a Vincentt XR app — no account needed\n` +
-        `                       [--no-install] [--template <version>]\n` +
-        `                       [--from <owner>/<repo>@<tag>] Clone a gallery template\n` +
-        `                       and register it   [--name <s>] [--slug <s>]\n` +
-        `  create             Register a project and reserve its address\n` +
-        `                       [--name <s>] [--slug <s>] [--org <s>] [--preview] [--force]\n` +
-        `  link <project-id>  Link this folder to an existing project\n` +
-        `  unlink             Disconnect this folder from its project\n\n` +
-        `Dev loop\n` +
-        `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
-        `                       [--dist <path>] [--note <s>] [--yes]\n` +
-        `  preview            Serve the app at an https link a phone can open\n` +
-        `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n` +
-        `                       Re-running prints the live link; --restart mints a new one.\n\n` +
-        `Diagnostics (need a running preview)\n` +
-        `  logs [--errors]    Console logs from the device    [--json] [--tester <id>]\n` +
-        `  network            fetch/XHR requests              [--json] [--tester <id>]\n` +
-        `  trace              Performance samples             [--json] [--tester <id>]\n` +
-        `                       --tester t1 filters to one tester (one tab, across\n` +
-        `                       its refreshes). --viewer <label> filters to a single\n` +
-        `                       connection; one tab opens several.\n\n` +
-        `Asset library\n` +
-        `  assets search "<query>"   Find curated assets   [--kind prop|frame]\n` +
-        `                              [--render 3d-clay] [--palette sage] [--limit 20] [--json]\n` +
-        `  assets show <id> [<id>…]  Everything known about an asset            [--json]\n` +
-        `  assets add <id> [<id>…]   Print the URLs to reference from your source\n` +
-        `                              Writes nothing. [--download [--dir <path>] [--force]]\n` +
-        `                              [--json]\n` +
-        `                              Ids look like lib_7f3a2c67d4e5b6a7; search returns\n` +
-        `                              them. Reference only ids the tool returned.\n\n` +
-        `Reverse channel\n` +
-        `  feedback --wait    Block for the next phone annotation, print it, exit\n` +
-        `  feedback --watch   Stream annotations as they arrive\n\n` +
-        `Servers\n` +
-        `  relay              Run the diagnostics/annotation relay\n\n` +
-        `Meta\n` +
-        `  version            CLI version, and the API this machine resolves to\n` +
-        `  dx                 Where this dev loop fought you  [--days <n>] [--json]\n` +
-        `                       Reads a local journal of your own runs. Local by default.\n` +
-        `                       --send reports the findings to the Vincentt team; it\n` +
-        `                       shows the exact payload and asks first. [--note <text>]\n` +
-        `  dx enable          Allow reports to be sent from this machine without asking.\n` +
-        `                       Asks you to confirm in your terminal. Stays on until you\n` +
-        `                       disable it, and is shown on \`vincentt dx\` and\n` +
-        `                       \`vincentt version\` while on.\n` +
-        `  dx disable         Turn that off again.\n\n` +
-        `Common options: --dir <path> (project dir, default cwd)\n` +
-        `                --allow-custom-api  honor a binding's apiUrl override\n`);
+export function usage() {
+    console.log(USAGE_TEXT);
+    return USAGE_TEXT;
 }
 async function main() {
     const cmd = argv[0];
@@ -881,7 +1077,19 @@ async function main() {
         usage();
         return;
     }
-    switch (cmd) {
+    const verb = resolveVerb(cmd);
+    if (verb === undefined) {
+        // Flow L30: rolling back and taking an address offline are console
+        // actions, and a bare "unknown command" here would be the product failing
+        // to answer a question it knows the answer to.
+        if (cmd !== undefined && isConsoleOnlyVerb(cmd))
+            return consoleOnly(cmd);
+        console.error(`Unknown command: ${cmd}\n`);
+        usage();
+        process.exitCode = 1;
+        return;
+    }
+    switch (verb) {
         case "version":
             return version();
         case "login":
@@ -898,6 +1106,8 @@ async function main() {
             return link();
         case "unlink":
             return unlink();
+        case "projects":
+            return projects();
         case "publish":
             return publish();
         case "preview":
@@ -916,15 +1126,6 @@ async function main() {
             return assets();
         case "dx":
             return dx();
-        default:
-            // Flow L30: rolling back and taking an address offline are console
-            // actions, and a bare "unknown command" here would be the product failing
-            // to answer a question it knows the answer to.
-            if (cmd !== undefined && isConsoleOnlyVerb(cmd))
-                return consoleOnly(cmd);
-            console.error(`Unknown command: ${cmd}\n`);
-            usage();
-            process.exitCode = 1;
     }
 }
 // Every invocation is journaled here, at the one site that sees all of them —

package/dist/cli/usage-text.d.ts

@@ -0,0 +1 @@
+export declare const USAGE_TEXT: string;

package/dist/cli/usage-text.js

@@ -0,0 +1,97 @@
+// The help text, in its own module so it can be rendered without importing the
+// CLI entrypoint — `cli/index.ts` calls `main()` at module scope, so importing it
+// runs the CLI, writes the dx journal and sets process.exitCode.
+export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
+    `Usage: vincentt <command> [options]\n\n` +
+    `Getting started (building a new app with a coding agent)\n` +
+    `  1. Confirm a project name with the developer first.\n` +
+    `  2. Create:  vincentt create <name>     (scaffolds if the folder is empty)\n` +
+    `  3. The scaffold writes the agent contract into the project root. Read it,\n` +
+    `     confirm the project is ready, and stop — do NOT invent an app.\n` +
+    `     Wait for the developer to describe what to build.\n` +
+    `  Full guide: npm view @vincentt-xr/cli readme\n\n` +
+    `Auth\n` +
+    `  login              Sign in; save an access token to ~/.vincentt/config.json\n` +
+    `                       [--api <url>] [--console <url>] to target a non-prod env\n` +
+    `  logout             Remove the saved access token\n` +
+    `  whoami             Show the signed-in account\n\n` +
+    `Project\n` +
+    `  init [dir]         Scaffold a Vincentt XR app — no account needed, ever\n` +
+    `                       [--no-install] [--template <version>]\n` +
+    `                       [--from <owner>/<repo>@<tag>] Clone a gallery template\n` +
+    `                       and register it   [--name <s>] [--slug <s>]\n` +
+    `  create [name]      Register a project and reserve its address; scaffolds first\n` +
+    `                       if the folder is empty   [--name <s>] [--slug <s>]\n` +
+    `                       [--org <s>] [--preview] [--force] [--no-install]\n` +
+    `  link <project-id>  Link this folder to an existing project\n` +
+    `  unlink             Disconnect this folder from its project\n` +
+    `  projects           List the workspace's projects and their ids  [--json]\n` +
+    `                       [--org <s>] to list a workspace other than the active one\n\n` +
+    `Dev loop\n` +
+    `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
+    `                       [--dist <path>] [--note <s>] [--yes]\n` +
+    `  preview            Serve the app at an https link a phone can open\n` +
+    `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n` +
+    `                       Re-running prints the live link; --restart mints a new one.\n\n` +
+    `Diagnostics (need a running preview)\n` +
+    `  logs [--errors]    Console logs from the device    [--json] [--tester <id>]\n` +
+    `  network            fetch/XHR requests              [--json] [--tester <id>]\n` +
+    `  trace              Performance samples             [--json] [--tester <id>]\n` +
+    `                       --tester t1 filters to one tester (one tab, across\n` +
+    `                       its refreshes). --viewer <label> filters to a single\n` +
+    `                       connection; one tab opens several.\n\n` +
+    `Asset library\n` +
+    `  assets search "<query>"   Find curated assets   [--kind prop|frame]\n` +
+    `                              [--render 3d-clay] [--palette sage] [--limit 20] [--json]\n` +
+    `  assets show <id> [<id>…]  Everything known about an asset            [--json]\n` +
+    `  assets add <id> [<id>…]   Print the URLs to reference from your source\n` +
+    `                              Writes nothing. [--download [--dir <path>] [--force]]\n` +
+    `                              [--json]\n` +
+    `                              Ids look like lib_7f3a2c67d4e5b6a7; search returns\n` +
+    `                              them. Reference only ids the tool returned.\n\n` +
+    // Help text is SOLICITED output, so an instruction would be permitted here —
+    // and it is still written as facts, because these exact words get quoted into
+    // a creator's own agent instructions, where they are unbidden by the time
+    // anything acts on them.
+    //
+    // Every line below is load-bearing. The exit codes are named HERE because a
+    // reader who has to look them up elsewhere guesses instead. "Blocking costs
+    // nothing while it waits" is the sentence that kills the poll-on-a-timer
+    // pattern — that pattern exists because a blocked command is assumed
+    // expensive and polling cheap, which is exactly backwards. "the same command
+    // may be run again immediately" teaches the re-park loop without naming a
+    // host, a shell, or any background mechanism, and "nothing is missed and
+    // nothing is re-read" forecloses an invented seen-set or a `--since` flag
+    // that does not exist.
+    //
+    // DELIBERATELY ABSENT: any product name; any shell idiom; any mention of a
+    // scheduled task EVEN TO FORBID ONE (naming a bad pattern is how a reader
+    // learns it exists); any "recommended for AI" framing.
+    `Reverse channel — feedback sent from the phone\n` +
+    `  feedback --wait     Block until feedback arrives, print every annotation\n` +
+    `                        waiting as one JSON object per line, then exit.\n` +
+    `                        [--timeout <seconds>, default 300]\n` +
+    `                        Exit 0  one or more annotations printed\n` +
+    `                        Exit 64 the window passed with nothing waiting\n` +
+    `                        Exit 65 the preview ended; nothing more can arrive\n` +
+    `                        Blocking costs nothing while it waits. On 64 the same\n` +
+    `                        command may be run again immediately; nothing is\n` +
+    `                        missed and nothing is re-read. On 65 a preview has to\n` +
+    `                        be running before there is anything to wait on.\n` +
+    `  feedback --watch    The same stream, printed as it arrives, without exiting.\n` +
+    `                        For a person watching a terminal.\n\n` +
+    `Servers\n` +
+    `  relay              Run the diagnostics/annotation relay\n\n` +
+    `Meta\n` +
+    `  version            CLI version, and the API this machine resolves to\n` +
+    `  dx                 Where this dev loop fought you  [--days <n>] [--json]\n` +
+    `                       Reads a local journal of your own runs. Local by default.\n` +
+    `                       --send reports the findings to the Vincentt team; it\n` +
+    `                       shows the exact payload and asks first. [--note <text>]\n` +
+    `  dx enable          Allow reports to be sent from this machine without asking.\n` +
+    `                       Asks you to confirm in your terminal. Stays on until you\n` +
+    `                       disable it, and is shown on \`vincentt dx\` and\n` +
+    `                       \`vincentt version\` while on.\n` +
+    `  dx disable         Turn that off again.\n\n` +
+    `Common options: --dir <path> (project dir, default cwd)\n` +
+    `                --allow-custom-api  honor a binding's apiUrl override\n`;

package/dist/cli/verb-surface.d.ts

@@ -0,0 +1,24 @@
+export declare const PINNED_VERBS: readonly ["version", "login", "logout", "whoami", "init", "create", "link", "unlink", "publish", "preview", "logs", "network", "trace", "feedback", "relay", "assets", "dx", "projects"];
+export type PinnedVerb = (typeof PINNED_VERBS)[number];
+export declare const VERB_HANDLERS: {
+    readonly version: true;
+    readonly login: true;
+    readonly logout: true;
+    readonly whoami: true;
+    readonly init: true;
+    readonly create: true;
+    readonly link: true;
+    readonly unlink: true;
+    readonly publish: true;
+    readonly preview: true;
+    readonly logs: true;
+    readonly network: true;
+    readonly trace: true;
+    readonly feedback: true;
+    readonly relay: true;
+    readonly assets: true;
+    readonly dx: true;
+    readonly projects: true;
+};
+export type DispatchVerb = keyof typeof VERB_HANDLERS;
+export declare function resolveVerb(cmd: string | undefined): DispatchVerb | undefined;