@vincentt-xr/cli 0.7.0 → 0.9.0

package/dist/cli/args.d.ts

@@ -13,8 +13,25 @@ export declare function isHelpInvocation(args: string[]): boolean;
  * skip a publish the creator asked for. Anywhere else it stays an unknown flag.
  */
 export declare function isVersionInvocation(args: string[]): boolean;
-/** Flags that stand alone; every other `--flag` consumes the next argument. */
+/**
+ * Flags that stand alone; every other `--flag` consumes the next argument.
+ *
+ * A boolean flag missing from this set silently eats the argument after it. For
+ * `vincentt assets add --download lib_7f3a…` that would swallow the asset id and
+ * leave the command with nothing to resolve, so every new boolean belongs here at
+ * the moment it is introduced.
+ */
 export declare const BOOLEAN_FLAGS: Set<string>;
+export interface ArgConflict {
+    /** The two flags that cannot appear together, in the order the copy names them. */
+    flags: [string, string];
+    kind: "source" | "install";
+}
+/**
+ * The `--from` exclusivity rules, checked during argument parsing before any
+ * work begins. Returns the conflict to report, or undefined.
+ */
+export declare function fromFlagConflict(args: string[]): ArgConflict | undefined;
 export declare function refusedFlag(args: string[]): string | undefined;
 /**
  * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir

package/dist/cli/args.js

@@ -17,7 +17,14 @@ export function isHelpInvocation(args) {
 export function isVersionInvocation(args) {
     return args[0] === "--version" || args[0] === "-v";
 }
-/** Flags that stand alone; every other `--flag` consumes the next argument. */
+/**
+ * Flags that stand alone; every other `--flag` consumes the next argument.
+ *
+ * A boolean flag missing from this set silently eats the argument after it. For
+ * `vincentt assets add --download lib_7f3a…` that would swallow the asset id and
+ * leave the command with nothing to resolve, so every new boolean belongs here at
+ * the moment it is introduced.
+ */
 export const BOOLEAN_FLAGS = new Set([
     "--force",
     "--preview",
@@ -33,9 +40,41 @@ export const BOOLEAN_FLAGS = new Set([
     "--no-install",
     "--allow-custom-api",
     "--yes",
+    "--download",
     "--help",
     "-h",
 ]);
+/**
+ * Flags that would turn the dependency install back ON. `--from` is mutually
+ * exclusive with every one of them, and the refusal lives HERE rather than in a
+ * code path (Q-1).
+ *
+ * Install is opt-out (`if (!opts.skipInstall)`), so the natural implementation of
+ * `--from` INHERITS the install — a developer has to actively write code to
+ * prevent it, which is the wrong direction for a security control. Making the
+ * refusal structural means the rule cannot be lost by forgetting something, only
+ * by deleting an explicit refusal, which is a reviewable act. S-2's accepted
+ * moved-tag risk is conditional on S-1 holding, so a single flag must not be able
+ * to defeat it.
+ */
+const INSTALL_ENABLING_FLAGS = new Set(["--install", "--with-install", "--deps"]);
+/**
+ * The `--from` exclusivity rules, checked during argument parsing before any
+ * work begins. Returns the conflict to report, or undefined.
+ */
+export function fromFlagConflict(args) {
+    const names = new Set(args.filter((a) => a.startsWith("-")).map((a) => a.split("=")[0]));
+    if (!names.has("--from"))
+        return undefined;
+    // Both choose which source to scaffold from; honoring both is undefined.
+    if (names.has("--template"))
+        return { flags: ["--from", "--template"], kind: "source" };
+    for (const f of names) {
+        if (INSTALL_ENABLING_FLAGS.has(f))
+            return { flags: ["--from", f], kind: "install" };
+    }
+    return undefined;
+}
 /**
  * Flags the CLI deliberately does NOT have. The checklist reports and never
  * writes: a suggested value is one keystroke from a tool that writes it, and

package/dist/cli/index.js

@@ -18,7 +18,7 @@ import { runPkceLogin } from "../login/pkceLogin.js";
 import { httpAuthBackend } from "../login/authBackend.js";
 import { loginCommand } from "../login/loginCommand.js";
 import { ensureLoggedIn } from "../login/ensure.js";
-import { clearMachineToken, loadMachineConfig, locateProjectBinding, resolveConfig, MACHINE_CONFIG_PATH, } from "../shared/config.js";
+import { clearMachineToken, loadMachineConfig, locateProjectBinding, resolveConfig, writeDxEnablement, MACHINE_CONFIG_PATH, } from "../shared/config.js";
 import { getMe, ProjectUnreachableError } from "../lib/backend.js";
 import { initCommand } from "../lib/initCommand.js";
 import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
@@ -36,12 +36,18 @@ import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
 import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
 import { record as recordInvocation } from "../dx/journal.js";
-import { dxSendCommand, parseDxOptions, runDx } from "../dx/command.js";
+import { dxDisableCommand, dxEnableCommand, dxSendCommand, parseDxOptions, runDx, } from "../dx/command.js";
+import { DX_UNATTENDED_SUNSET, loadEnablement } from "../dx/enablement.js";
 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 { isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
+import { fromFlagConflict, isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
+import { parseSourceRef } from "../lib/sourceRef.js";
+import { printFlagConflict, printSourceRefFailure } from "../lib/sourceRefCopy.js";
+import { registerAfterScaffold } from "../lib/initFrom.js";
+import { createCommand } from "../lib/projects.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.
 // This is the prod console; vincentt.app is the published-PROJECT apex, not the console, so a
@@ -163,17 +169,75 @@ async function init() {
     // ABSENCE as "may not ask" — so a piped or CI invocation refuses rather than
     // blocking forever on a question nobody can see.
     const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    const print = (l) => console.log(l);
+    const dir = positional(1);
+    const dirLabel = dir ?? "<dir>";
+    // Refused during ARGUMENT PARSING, before anything is written (Q-1).
+    const conflict = fromFlagConflict(argv);
+    if (conflict) {
+        printFlagConflict(print, conflict, { dir: dirLabel });
+        process.exitCode = 1;
+        return;
+    }
+    const rawFrom = flag("--from");
+    let from;
+    if (rawFrom !== undefined) {
+        const parsed = parseSourceRef(rawFrom);
+        if (!parsed.ok) {
+            printSourceRefFailure(print, parsed.failure, { dir: dirLabel });
+            process.exitCode = 1;
+            return;
+        }
+        from = parsed.ref;
+    }
     process.exitCode = await initCommand({
-        print: (l) => console.log(l),
+        print,
         cwd: process.cwd(),
         ask: interactive ? stdinAsk() : undefined,
         confirm: interactive ? stdinConfirm() : undefined,
+        register: from
+            ? (rd, o) => registerAfterScaffold({
+                ...rd,
+                currentToken,
+                runLogin: async () => {
+                    await login();
+                },
+                resolveOrg: async () => {
+                    const cfg = await resolveConfig(rd.targetDir, { warn: print });
+                    const resolved = await resolveOrgForCommand(cfg, { flag: flag("--org") });
+                    if (!resolved.ok)
+                        return resolved;
+                    return {
+                        ok: true,
+                        name: resolved.org.name,
+                        source: orgSource(),
+                    };
+                },
+                create: async ({ name, slug }) => createCommand({
+                    print,
+                    cwd: rd.targetDir,
+                    config: () => resolveConfig(rd.targetDir, { warn: print }),
+                    org: async () => resolveOrgForCommand(await resolveConfig(rd.targetDir, { warn: print }), { flag: flag("--org") }),
+                }, { name, slug }),
+            }, o)
+            : undefined,
     }, {
-        dir: positional(1),
+        dir,
         skipInstall: has("--no-install"),
         template: flag("--template"),
+        from,
+        name: flag("--name"),
+        slug: flag("--slug"),
     });
 }
+/** Where the resolved org came from, so a surprising value is diagnosable (AF-3). */
+function orgSource() {
+    if (flag("--org"))
+        return "flag";
+    if (process.env.VINCENTT_ORG)
+        return "env";
+    return "active";
+}
 async function create() {
     await requireLogin();
     const result = await projectCreate(projectDir(), {
@@ -253,6 +317,8 @@ async function publish() {
         now: () => Date.now(),
         sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
         orgName: activeOrgName,
+        orgSlug: async () => (await activeOrgName()) || undefined,
+        consoleUrl: flag("--console") ?? process.env.VINCENTT_CONSOLE_URL,
     }, { distDir: flag("--dist"), note: flag("--note"), yes: has("--yes") });
 }
 /** Flow L30 — the six verbs that are console actions, answered rather than rejected. */
@@ -583,8 +649,35 @@ async function version() {
 // ---- dx ---------------------------------------------------------------------
 async function dx() {
     const options = parseDxOptions(argv);
+    const now = Date.now();
+    // Both descriptors, matching publish and init. stdin alone let
+    // `vincentt dx --send --yes > out.txt` through — a redirected stdout is
+    // precisely the case where nobody reads what was disclosed.
+    const interactive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (options.enable || options.disable) {
+        const deps = {
+            print: (l) => console.log(l),
+            now: () => now,
+            interactive,
+            confirm: (q) => stdinConfirm()(`  ${q} [y/N] `, false),
+            // `enable` does NOT require being signed in. --send refuses without a PAT
+            // regardless, so a config holding only enablement keys is inert; and
+            // ordering the two verbs ("you must log in before you may state a
+            // preference") would be a rule with no safety behind it.
+            save: async (next) => {
+                await writeDxEnablement(next);
+            },
+        };
+        process.exitCode = options.enable
+            ? await dxEnableCommand(deps, DX_UNATTENDED_SUNSET)
+            : await dxDisableCommand(deps);
+        return;
+    }
+    // Read strictly and independently of auth: a truncated config must disable the
+    // relaxation, not throw through it.
+    const enablement = await loadEnablement(now);
     if (!options.send) {
-        process.exitCode = runDx(argv, (l) => console.log(l));
+        process.exitCode = runDx(argv, (l) => console.log(l), () => enablement);
         return;
     }
     // `--send` is the one path out of this machine, so it resolves auth the way
@@ -592,7 +685,7 @@ async function dx() {
     process.exitCode = await dxSendCommand({
         entries: readJournal,
         print: (l) => console.log(l),
-        now: () => Date.now(),
+        now: () => now,
         enabled: () => journalEnabled(),
         path: journalPath,
         cliVersion,
@@ -613,9 +706,91 @@ async function dx() {
         },
         post: (apiUrl, pat, report) => postReport(apiUrl, pat, report),
         confirm: (q) => stdinConfirm()(`${q} [y/N] `, false),
-        interactive: () => Boolean(process.stdin.isTTY),
+        interactive,
+        enablement: () => enablement,
     }, options);
 }
+// ---- assets (f5) ------------------------------------------------------------
+/**
+ * `vincentt assets <search|show|add>` — the CLI's FIRST nested subcommand group,
+ * so this is one `case` with an inner switch rather than a new flat verb.
+ *
+ * The whole group is gated on being signed in, and every screen it prints goes to
+ * STDERR: under `--json` stdout must carry only the JSON document, so an agent
+ * piping stdout into a parser never gets a mixed stream.
+ */
+async function assets() {
+    const sub = positional(1);
+    if (sub === undefined) {
+        console.error("Usage: vincentt assets <search|show|add> [options]");
+        process.exitCode = 1;
+        return;
+    }
+    if (sub !== "search" && sub !== "show" && sub !== "add") {
+        console.error(`Unknown assets command: ${sub}`);
+        console.error("Usage: vincentt assets <search|show|add> [options]");
+        process.exitCode = 1;
+        return;
+    }
+    const { httpLibraryClient } = await import("../library/client.js");
+    const { assetsAdd, assetsSearch, assetsShow } = await import("../library/assetsCommand.js");
+    const cwd = projectDir();
+    let cfg;
+    try {
+        cfg = await resolveConfig(cwd, {
+            allowCustomApi: has("--allow-custom-api"),
+            warn: (l) => console.error(l),
+        });
+    }
+    catch {
+        // 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>\"")) {
+            console.error(l);
+        }
+        process.exitCode = 4;
+        return;
+    }
+    const deps = {
+        out: (l) => console.log(l),
+        err: (l) => console.error(l),
+        client: httpLibraryClient(cfg),
+        cwd,
+    };
+    const json = has("--json");
+    if (sub === "search") {
+        // The query is the bare argument after `search`; the remaining positionals are
+        // ignored rather than concatenated, so a quoting mistake fails loudly.
+        const query = positional(2);
+        if (query === undefined) {
+            console.error('Usage: vincentt assets search "<query>" [--kind prop|frame] [--limit N]');
+            process.exitCode = 1;
+            return;
+        }
+        process.exitCode = await assetsSearch(deps, {
+            query,
+            kind: flag("--kind"),
+            render: flag("--render"),
+            palette: flag("--palette"),
+            limit: flag("--limit"),
+            json,
+        });
+        return;
+    }
+    const ids = positionalArgs(argv).slice(2);
+    if (sub === "show") {
+        process.exitCode = await assetsShow(deps, { ids, json });
+        return;
+    }
+    process.exitCode = await assetsAdd(deps, {
+        ids,
+        json,
+        download: has("--download"),
+        force: has("--force"),
+        dir: flag("--dir"),
+    });
+}
 // ---- servers ----------------------------------------------------------------
 async function relay() {
     const { startRelay } = await import("../relay/server.js");
@@ -646,6 +821,8 @@ function usage() {
         `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` +
@@ -663,6 +840,15 @@ function usage() {
         `                       --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` +
@@ -673,7 +859,12 @@ function usage() {
         `  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\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`);
 }
@@ -721,6 +912,8 @@ async function main() {
             return feedback();
         case "relay":
             return relay();
+        case "assets":
+            return assets();
         case "dx":
             return dx();
         default:
@@ -756,8 +949,13 @@ function journal(exitCode, error) {
     if (verbOf(argv) === "dx")
         return;
     try {
+        // STDERR, not stdout. This is human narration appended after EVERY verb, so on
+        // any `--json` invocation it would land inside the document an agent is piping
+        // into a parser and corrupt it. Whether that happened was down to the nudge's
+        // own timing heuristic, which makes it the worst kind of intermittent: green in
+        // a test run, broken on a creator's machine a week later.
         for (const l of nudgeFor(readJournal(), Date.now()))
-            console.log(l);
+            console.error(l);
     }
     catch {
         // A hint that can break a publish is not worth having.

package/dist/dx/command.d.ts

@@ -1,3 +1,4 @@
+import type { Enablement } from "./enablement.js";
 import type { JournalEntry } from "./journal.js";
 import type { WireReport } from "./send.js";
 export interface DxDeps {
@@ -6,6 +7,11 @@ export interface DxDeps {
     now: () => number;
     enabled: () => boolean;
     path: () => string;
+    /**
+     * Durable unattended-send state. Optional so the many callers that only read
+     * the journal need not resolve it; absent reads as not enabled.
+     */
+    enablement?: () => Enablement;
 }
 export interface DxOptions {
     /** Only consider runs from the last N days. */
@@ -17,11 +23,55 @@ export interface DxOptions {
     yes: boolean;
     /** The creator's own words about the friction, carried with the report. */
     note?: string;
+    /** `vincentt dx enable` — a positional subcommand, not a flag. */
+    enable: boolean;
+    /** `vincentt dx disable` — a positional subcommand, not a flag. */
+    disable: boolean;
 }
 export declare function parseDxOptions(args: string[]): DxOptions;
 export declare function dxCommand(deps: DxDeps, options: DxOptions): number;
 /** Wire the command to the real journal. */
-export declare function runDx(args: string[], print: (line: string) => void): number;
+export declare function runDx(args: string[], print: (line: string) => void, enablement?: () => Enablement): number;
+export interface DxEnableDeps {
+    print: (line: string) => void;
+    now: () => number;
+    /** stdin.isTTY && stdout.isTTY. Evidence of an interactive session, not proof of a human. */
+    interactive: () => boolean;
+    /** Ask once. Returns false to abort. */
+    confirm: (question: string) => Promise<boolean>;
+    /**
+     * Persist the grant, or clear it when given undefined. NEVER called on a
+     * refusal path — `enable` that refuses must not touch the file at all.
+     */
+    save: (next: {
+        at: string;
+    } | undefined) => Promise<void>;
+}
+/**
+ * `vincentt dx enable` — grant this machine durable permission to send DX reports
+ * without asking first.
+ *
+ * The TTY requirement is a SPEED BUMP, NOT A BOUNDARY, and is written down as
+ * such so a later reader does not build on a guarantee that is not there. It
+ * stops the reflex — an agent that meets a prompt, infers there must be a way
+ * past it, and tries the obvious thing. It does not stop a caller that allocates
+ * a PTY or writes config.json directly.
+ *
+ * The refusal path writes NOTHING. Not "writes the same bytes back" — nothing at
+ * all: this file holds the PAT, and a refusal that round-trips the config through
+ * a write can lose the credential if it dies mid-write.
+ */
+export declare function dxEnableCommand(deps: DxEnableDeps, sunset: number): Promise<number>;
+/**
+ * `vincentt dx disable` — the obvious opposite command.
+ *
+ * Clears BOTH keys. Leaving the timestamp behind would make a later re-enable
+ * report its age from the first grant, which is the kind of thing that ships
+ * wrong and is never noticed. Needs no terminal and no confirmation: turning a
+ * capability OFF is always safe to do, and requiring a TTY here would strand a
+ * creator who wanted to revoke from a script.
+ */
+export declare function dxDisableCommand(deps: DxEnableDeps): Promise<number>;
 export interface DxSendDeps extends DxDeps {
     /** Resolved API host + PAT. Absent when the creator is not signed in. */
     auth: () => Promise<{
@@ -36,8 +86,15 @@ export interface DxSendDeps extends DxDeps {
     /** Ask before sending. Returns false to abort. */
     confirm: (question: string) => Promise<boolean>;
     cliVersion: () => string;
-    /** True when stdin is a terminal — i.e. a human is here to answer. */
+    /**
+     * stdin.isTTY && stdout.isTTY. Evidence of an INTERACTIVE SESSION, not proof of
+     * a human: an agent harness that allocates a PTY passes this with nobody
+     * present. The enabled path below is the honest one; this arm gates
+     * convenience, not authorization.
+     */
     interactive: () => boolean;
+    /** Durable unattended-send state, read strictly. Absent reads as not enabled. */
+    enablement?: () => Enablement;
 }
 /**
  * `vincentt dx --send`.