@vincentt-xr/cli 0.7.0 → 0.8.0

package/dist/dx/enablement.js

@@ -0,0 +1,97 @@
+/**
+ * Durable authorization for unattended `vincentt dx --send`.
+ *
+ * `--send` transmits only when the session is interactive OR this machine has
+ * been explicitly enabled by a person, at a terminal, via `vincentt dx enable`.
+ * The state is two fields in ~/.vincentt/config.json, set by `enable`, cleared by
+ * `disable` and by `logout`, and it has NO expiry — it stays on until the creator
+ * turns it off.
+ *
+ * Because there is no expiry, VISIBILITY is the entire mitigation, and the AGE is
+ * the load-bearing half of it: `ENABLED` alone reads as configuration, while
+ * `(145 days)` reads as drift and is the number that makes someone ask whether
+ * they still want it. That is why an unparseable timestamp fails CLOSED rather
+ * than printing `since Invalid Date (NaN days)` — a degraded mitigation is worse
+ * than a visible absence.
+ */
+import { loadMachineConfig } from "../shared/config.js";
+/**
+ * The product-lifetime bound on an explicitly internal-beta capability. Past this
+ * date `enable` refuses AND an existing flag stops being honored, so FORGETTING
+ * THIS TURNS THE FEATURE OFF — the safe direction.
+ *
+ * This is deliberately a constant in shipped code rather than a CI test with a
+ * hard-coded date: such a test fires in an uninvolved engineer's lap at a moment
+ * with no context, and the cheapest green is bumping the constant. Reaching this
+ * date is a decision to make (extend, or remove the feature), not a number to
+ * raise.
+ */
+export const DX_UNATTENDED_SUNSET = Date.parse("2027-02-24T00:00:00.000Z");
+const DISABLED = { enabled: false };
+/**
+ * Decide enablement from an already-parsed config object. Pure, and STRICT:
+ * identity against `true`, never truthiness.
+ *
+ * Truthiness fails OPEN on `"false"`, `"0"`, `{}`, `[]`, `1`, and `"garbage"` —
+ * every one of those is truthy in JavaScript. The worst is `"false"`, which is
+ * what a person hand-editing this file writes when they are trying to turn the
+ * feature OFF; `{}` is what a refactor grouping the two fields produces. A gate
+ * that reads a creator's "off" as "on" is inverted, not merely loose.
+ */
+export function readEnablement(cfg, now) {
+    if (typeof cfg !== "object" || cfg === null)
+        return DISABLED;
+    const { dxSendEnabled, dxSendEnabledAt } = cfg;
+    if (dxSendEnabled !== true)
+        return DISABLED;
+    if (typeof dxSendEnabledAt !== "string")
+        return DISABLED;
+    if (!Number.isFinite(Date.parse(dxSendEnabledAt)))
+        return DISABLED;
+    if (now >= DX_UNATTENDED_SUNSET)
+        return DISABLED;
+    return { enabled: true, at: dxSendEnabledAt };
+}
+/**
+ * Read enablement from the real machine config.
+ *
+ * Wrapped in its OWN try/catch, independent of the auth read, because
+ * `readJsonIfExists` rethrows everything that is not ENOENT: a truncated
+ * config.json must DISABLE the relaxation, not throw through it and take an
+ * unrelated verb down with it.
+ */
+export async function loadEnablement(now) {
+    try {
+        return readEnablement(await loadMachineConfig(), now);
+    }
+    catch {
+        return DISABLED;
+    }
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Whole days elapsed, floored, never negative — a clock skew must not print `(-2 days)`. */
+export function ageInDays(at, now) {
+    const t = Date.parse(at);
+    if (!Number.isFinite(t))
+        return 0;
+    return Math.max(0, Math.floor((now - t) / DAY_MS));
+}
+/** The calendar day of the grant, in UTC. The time of day is noise at this age scale. */
+export function grantedOn(at) {
+    return new Date(Date.parse(at)).toISOString().slice(0, 10);
+}
+/**
+ * The one visibility line, in the single pinned shape every human surface uses:
+ *
+ *   Unattended send: ENABLED since 2026-04-01 (145 days)
+ *
+ * Returns undefined when not enabled. Nothing is printed in that case, on
+ * purpose: a line that prints unconditionally is a line readers learn to skip,
+ * which would cost exactly the attention the enabled line needs.
+ */
+export function enablementLine(e, now) {
+    if (!e.enabled || e.at === undefined)
+        return undefined;
+    const days = ageInDays(e.at, now);
+    return `Unattended send: ENABLED since ${grantedOn(e.at)} (${days} ${days === 1 ? "day" : "days"})`;
+}

package/dist/dx/qa.f7.fixtures.d.ts

@@ -0,0 +1,73 @@
+/**
+ * QA fixtures for the dx-agent-consent delta (f7).
+ *
+ * Declared in the change's qa.md `## Fixtures` section. All three are
+ * machine-config state, which f7 has never had a fixture for — its existing
+ * fixtures (F7_JOURNAL_FRICTION, F7_REPORT_EXPIRED, …) are journal-side or
+ * server-side.
+ *
+ * F7_CONFIG_SIGNED_IN is written by driving the REAL writeMachineConfig(), never
+ * by hand-writing JSON. A hand-written config asserts against a shape the CLI
+ * never produces — the f1 orgs/memberships failure at file scope, where a mock
+ * of state the API could actually produce drifted from the API and stayed green.
+ *
+ * These are QA-owned (qa.* prefix) and deliberately separate from dev's test
+ * files in the same package.
+ */
+import type { JournalEntry } from "./journal.js";
+/** The honest baseline config, as the CLI itself writes it. */
+export declare const F7_CONFIG_SIGNED_IN: {
+    readonly apiUrl: "https://api.test";
+    readonly consoleUrl: "https://console.test";
+    readonly pat: "vct_alice";
+    readonly activeOrg: "alice";
+};
+/**
+ * The instant every fixture is dated against. 145 days after the grant in
+ * F7_CONFIG_ENABLED, and before DX_UNATTENDED_SUNSET.
+ */
+export declare const F7_NOW: number;
+/** 145 days before F7_NOW. The AGE is the point — see qa.md on F7_CONFIG_ENABLED. */
+export declare const F7_ENABLED_AT = "2026-04-01T00:00:00.000Z";
+/**
+ * The single pinned human-facing shape. Every human surface must render this
+ * byte-for-byte; the age is the load-bearing half, so it is pinned as a literal
+ * rather than computed (a computed expectation would follow a broken
+ * implementation wherever it went).
+ */
+export declare const F7_PINNED_ENABLEMENT_LINE = "Unattended send: ENABLED since 2026-04-01 (145 days)";
+/** F7_CONFIG_SIGNED_IN + durable enablement, aged. */
+export declare const F7_CONFIG_ENABLED: {
+    readonly dxSendEnabled: true;
+    readonly dxSendEnabledAt: "2026-04-01T00:00:00.000Z";
+    readonly apiUrl: "https://api.test";
+    readonly consoleUrl: "https://console.test";
+    readonly pat: "vct_alice";
+    readonly activeOrg: "alice";
+};
+/**
+ * Every shape the enablement read must treat as DISABLED.
+ *
+ * Rows B, C, E, F, G are TRUTHY IN JAVASCRIPT — `if (cfg.dxSendEnabled)` passes
+ * every one of them. That is the entire reason this fixture exists, and why the
+ * read is specified as `=== true`. The worst is B ("false"): what a person
+ * hand-editing this file writes when trying to turn the feature OFF.
+ *
+ * `raw` rows (K, L) are written as bytes rather than as an object, because the
+ * property under test is that an UNPARSEABLE config fails closed instead of
+ * throwing through into an unrelated verb.
+ */
+export interface MalformedRow {
+    id: string;
+    why: string;
+    /** A config object to serialize, or undefined when `raw` carries the bytes. */
+    patch?: Record<string, unknown>;
+    /** Literal file bytes, for the rows that are not valid JSON at all. */
+    raw?: string;
+}
+export declare const F7_CONFIG_MALFORMED_ENABLEMENT: MalformedRow[];
+/**
+ * F7_JOURNAL_FRICTION, as the record declares it: three runs of the same verb in
+ * a few minutes, which is a repetition cluster.
+ */
+export declare function f7JournalFriction(now?: number): JournalEntry[];

package/dist/dx/qa.f7.fixtures.js

@@ -0,0 +1,58 @@
+/** The honest baseline config, as the CLI itself writes it. */
+export const F7_CONFIG_SIGNED_IN = {
+    apiUrl: "https://api.test",
+    consoleUrl: "https://console.test",
+    pat: "vct_alice",
+    activeOrg: "alice",
+};
+/**
+ * The instant every fixture is dated against. 145 days after the grant in
+ * F7_CONFIG_ENABLED, and before DX_UNATTENDED_SUNSET.
+ */
+export const F7_NOW = Date.parse("2026-08-24T12:00:00.000Z");
+/** 145 days before F7_NOW. The AGE is the point — see qa.md on F7_CONFIG_ENABLED. */
+export const F7_ENABLED_AT = "2026-04-01T00:00:00.000Z";
+/**
+ * The single pinned human-facing shape. Every human surface must render this
+ * byte-for-byte; the age is the load-bearing half, so it is pinned as a literal
+ * rather than computed (a computed expectation would follow a broken
+ * implementation wherever it went).
+ */
+export const F7_PINNED_ENABLEMENT_LINE = "Unattended send: ENABLED since 2026-04-01 (145 days)";
+/** F7_CONFIG_SIGNED_IN + durable enablement, aged. */
+export const F7_CONFIG_ENABLED = {
+    ...F7_CONFIG_SIGNED_IN,
+    dxSendEnabled: true,
+    dxSendEnabledAt: F7_ENABLED_AT,
+};
+export const F7_CONFIG_MALFORMED_ENABLEMENT = [
+    { id: "A", why: 'truthy STRING "true"', patch: { dxSendEnabled: "true", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "B", why: 'truthy in JS, means false to a human', patch: { dxSendEnabled: "false", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "C", why: 'truthy in JS ("0")', patch: { dxSendEnabled: "0", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "D", why: "truthy, not the boolean (1)", patch: { dxSendEnabled: 1, dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "E", why: "truthy ({} — what a refactor grouping the fields produces)", patch: { dxSendEnabled: {}, dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "F", why: "truthy ([])", patch: { dxSendEnabled: [], dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "G", why: 'truthy ("garbage")', patch: { dxSendEnabled: "garbage", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "H", why: "key absent entirely", patch: {} },
+    { id: "I", why: "enabled true, dxSendEnabledAt absent", patch: { dxSendEnabled: true } },
+    { id: "J", why: 'enabled true, dxSendEnabledAt "not-a-date"', patch: { dxSendEnabled: true, dxSendEnabledAt: "not-a-date" } },
+    { id: "K", why: "file truncated mid-JSON", raw: '{"pat":"vct_alice","dxSendEn' },
+    { id: "L", why: "file empty (0 bytes)", raw: "" },
+];
+/**
+ * F7_JOURNAL_FRICTION, as the record declares it: three runs of the same verb in
+ * a few minutes, which is a repetition cluster.
+ */
+export function f7JournalFriction(now = F7_NOW) {
+    const entry = (minutesAgo) => ({
+        ts: new Date(now - minutesAgo * 60_000).toISOString(),
+        v: "0.7.0",
+        verb: "preview",
+        skel: "preview",
+        exit: 0,
+        ms: 800,
+        err: null,
+        wt: "abc123",
+    });
+    return [entry(3), entry(2), entry(1)];
+}

package/dist/lib/version.d.ts

@@ -1,3 +1,4 @@
+import type { Enablement } from "../dx/enablement.js";
 export interface VersionReport {
     cliVersion: string;
     nodeVersion: string;
@@ -8,6 +9,12 @@ export interface VersionReport {
     ignoredBindingApiUrl?: string;
     /** True when the resolved host is the built-in fallback (nothing configured). */
     isDefault: boolean;
+    /** True when this machine may send DX reports unattended. */
+    dxSendEnabled: boolean;
+    /** ISO8601 UTC of the grant. Present only when enabled. */
+    dxSendEnabledAt?: string;
+    /** The instant the age is computed against, so renderVersion stays pure. */
+    dxAgeAsOf: number;
 }
 export interface VersionEnv {
     envApiUrl?: string;
@@ -16,6 +23,10 @@ export interface VersionEnv {
     allowCustomApi?: boolean;
     nodeVersion: string;
     cliVersion: string;
+    /** Durable unattended-send state, already read. Absent reads as not enabled. */
+    enablement?: Enablement;
+    /** Injected so the age is testable without waiting a day. */
+    now?: number;
 }
 /**
  * Decide what to report. Pure, so the transcript is testable without a home
@@ -27,7 +38,15 @@ export declare function buildVersionReport(env: VersionEnv): VersionReport;
  * fact, not two.
  */
 export declare function renderVersion(r: VersionReport): string[];
-/** Read the machine's real state and produce the report. */
+/**
+ * Read the machine's real state and produce the report.
+ *
+ * Every read here is wrapped. This is the command people run WHEN THINGS ARE
+ * ALREADY BROKEN, and a truncated config.json — the state that most needs
+ * diagnosing — makes `loadMachineConfig` throw, since readJsonIfExists rethrows
+ * everything that is not ENOENT. A diagnostic that dies on the fault it exists to
+ * report is worse than one that reports less.
+ */
 export declare function versionReport(cwd: string, opts: {
     cliVersion: string;
     allowCustomApi?: boolean;

package/dist/lib/version.js

@@ -7,6 +7,7 @@
 // reads like a server outage rather than a misconfiguration. So this reports the
 // resolved host AND its provenance, using the same decideApiUrl the real verbs
 // use — a version command that re-derived the URL could disagree with them.
+import { enablementLine, loadEnablement } from "../dx/enablement.js";
 import { decideApiUrl, loadMachineConfig, locateProjectBinding, } from "../shared/config.js";
 /**
  * Decide what to report. Pure, so the transcript is testable without a home
@@ -34,6 +35,7 @@ export function buildVersionReport(env) {
         apiSource = "built-in default";
         isDefault = true;
     }
+    const enablement = env.enablement ?? { enabled: false };
     return {
         cliVersion: env.cliVersion,
         nodeVersion: env.nodeVersion,
@@ -41,6 +43,9 @@ export function buildVersionReport(env) {
         apiSource,
         ignoredBindingApiUrl: decided.ignoredBindingApiUrl,
         isDefault,
+        dxSendEnabled: enablement.enabled,
+        dxSendEnabledAt: enablement.enabled ? enablement.at : undefined,
+        dxAgeAsOf: env.now ?? Date.now(),
     };
 }
 /**
@@ -64,19 +69,50 @@ export function renderVersion(r) {
     if (r.ignoredBindingApiUrl) {
         out.push("", `  !  This folder's binding names a different API (${r.ignoredBindingApiUrl})`, "     and was ignored. Re-run with --allow-custom-api to use it.");
     }
-    out.push("", `  node    ${r.nodeVersion}`, "");
+    out.push("", `  node    ${r.nodeVersion}`);
+    // `version` is what people run when something is ALREADY broken, which is
+    // exactly when a forgotten enablement is most likely to be discovered. Printed
+    // only when enabled — see the note in dx/enablement.ts on why there is no `off`
+    // counterpart.
+    const dx = enablementLine({ enabled: r.dxSendEnabled, at: r.dxSendEnabledAt }, r.dxAgeAsOf);
+    if (dx !== undefined)
+        out.push("", `  ${dx}`);
+    out.push("");
     return out;
 }
-/** Read the machine's real state and produce the report. */
+/**
+ * Read the machine's real state and produce the report.
+ *
+ * Every read here is wrapped. This is the command people run WHEN THINGS ARE
+ * ALREADY BROKEN, and a truncated config.json — the state that most needs
+ * diagnosing — makes `loadMachineConfig` throw, since readJsonIfExists rethrows
+ * everything that is not ENOENT. A diagnostic that dies on the fault it exists to
+ * report is worse than one that reports less.
+ */
 export async function versionReport(cwd, opts) {
-    const machine = await loadMachineConfig();
-    const located = await locateProjectBinding(cwd);
+    const now = Date.now();
+    let machineApiUrl;
+    try {
+        machineApiUrl = (await loadMachineConfig()).apiUrl;
+    }
+    catch {
+        machineApiUrl = undefined;
+    }
+    let located;
+    try {
+        located = await locateProjectBinding(cwd);
+    }
+    catch {
+        located = undefined;
+    }
     return buildVersionReport({
         envApiUrl: process.env.VINCENTT_API_URL,
-        machineApiUrl: machine.apiUrl,
+        machineApiUrl,
         bindingApiUrl: located?.binding.apiUrl,
         allowCustomApi: opts.allowCustomApi,
         nodeVersion: process.version,
         cliVersion: opts.cliVersion,
+        enablement: await loadEnablement(now),
+        now,
     });
 }

package/dist/library/assetsCommand.d.ts

@@ -0,0 +1,32 @@
+import { type LibraryClient } from "./client.js";
+export interface AssetsDeps {
+    /** stdout — the JSON document under --json, the human screen otherwise. */
+    out: (line: string) => void;
+    /** stderr — EVERY human line when --json is on. */
+    err: (line: string) => void;
+    client: LibraryClient;
+    /** The project root `--download` writes under. */
+    cwd: string;
+}
+export interface SearchOptions {
+    query: string;
+    kind?: string;
+    render?: string;
+    palette?: string;
+    limit?: string;
+    json: boolean;
+}
+export declare function assetsSearch(deps: AssetsDeps, opts: SearchOptions): Promise<number>;
+export interface ShowOptions {
+    ids: string[];
+    json: boolean;
+}
+export declare function assetsShow(deps: AssetsDeps, opts: ShowOptions): Promise<number>;
+export interface AddOptions {
+    ids: string[];
+    json: boolean;
+    download: boolean;
+    force: boolean;
+    dir?: string;
+}
+export declare function assetsAdd(deps: AssetsDeps, opts: AddOptions): Promise<number>;

package/dist/library/assetsCommand.js

@@ -0,0 +1,264 @@
+// `vincentt assets search | show | add` — the three creator-facing f5 verbs.
+//
+// EXIT CODES ARE THE AGENT'S WHOLE CONTROL FLOW and the three are never collapsed:
+//   0  we answered — INCLUDING a zero-result answer, which is a correct answer to a
+//      well-formed question. A non-zero exit here teaches an agent that an empty
+//      library is a TOOL failure, and an agent's move on a tool failure is to retry
+//      or route around — where "route around" means inventing a URL.
+//   1  we answered and something you asked for is missing (partial resolution).
+//   4  we did not answer (unreachable / not signed in / no corpus loaded).
+// Exit 1 vs 4 matters because the correct recovery differs: re-search vs retry later.
+//
+// STREAM DISCIPLINE: under `--json`, stdout carries ONLY the JSON document. Every
+// human line — progress, warnings, errors — goes to stderr, always, so an agent
+// piping stdout into a parser never gets a mixed stream.
+import path from "node:path";
+import { LibraryError, LibraryUnreachableError, } from "./client.js";
+import { DOWNLOAD_DIR, downloadPath, exists, overwriteRefusalLines, writeAsset, } from "./download.js";
+import { dedupeForDisplay, parseIdArgs, parseSearchFlags } from "./parse.js";
+import { addLines, humanBytes, searchLines, showLines, unknownBlockLines, unreachableLines, } from "./render.js";
+import { isLibraryId } from "./wire.js";
+/**
+ * Map a thrown client error onto the exit-4 screen it deserves.
+ *
+ * A 401/403 is "not signed in"; a 503 library_unavailable is "we could not look" —
+ * and it is NEVER rendered as a zero-result answer with gaps. Collapsing those two
+ * would have the platform emit an inventory claim it cannot support: telling every
+ * agent "the library has no wearable assets" about a ~500-record library because a
+ * corpus failed to load.
+ */
+function failureScreen(err, retry) {
+    if (err instanceof LibraryUnreachableError) {
+        return { lines: unreachableLines("transport", retry), code: 4 };
+    }
+    if (err instanceof LibraryError) {
+        if (err.status === 401 || err.status === 403) {
+            return { lines: unreachableLines("auth", retry), code: 4 };
+        }
+        if (err.status === 429) {
+            return {
+                lines: [
+                    "",
+                    "✗ Too many library requests. Wait a moment and try again.",
+                    "",
+                    "  Nothing is wrong with your project.",
+                    "",
+                ],
+                code: 4,
+            };
+        }
+        return { lines: unreachableLines("unavailable", retry), code: 4 };
+    }
+    return { lines: unreachableLines("transport", retry), code: 4 };
+}
+export async function assetsSearch(deps, opts) {
+    const flags = parseSearchFlags({
+        kind: opts.kind,
+        render: opts.render,
+        palette: opts.palette,
+        limit: opts.limit,
+    });
+    if (!flags.ok) {
+        for (const l of flags.lines)
+            deps.err(l);
+        return 1;
+    }
+    const retry = `vincentt assets search "${opts.query}"`;
+    let res;
+    try {
+        res = await deps.client.search({ q: opts.query, ...flags.flags });
+    }
+    catch (err) {
+        const screen = failureScreen(err, retry);
+        for (const l of screen.lines)
+            deps.err(l);
+        return screen.code;
+    }
+    if (opts.json) {
+        // The agent's shape, and it is STABLE. `gaps` and `results` are always present
+        // even when empty: a key that appears only on failure is a key nobody handles.
+        deps.out(JSON.stringify({
+            query: res.query ?? opts.query,
+            ...(res.revision !== undefined ? { revision: res.revision } : {}),
+            resultCount: res.resultCount,
+            results: res.results,
+            gaps: res.gaps,
+        }, null, 2));
+        return 0;
+    }
+    for (const l of searchLines(res, opts.query))
+        deps.err(l);
+    // Zero results is exit 0. This is the single most important exit code in f5.
+    return 0;
+}
+/**
+ * Resolve ids through the ONE call shape the design mandates: a single id uses the
+ * fetch route, 2+ use ONE batch call — never N sequential fetches
+ * (D-multi-asset-is-mandatory). The ids go out AS GIVEN, duplicates intact.
+ */
+async function resolveIds(client, ids) {
+    if (ids.length === 1) {
+        const one = await client.fetchOne(ids[0]);
+        return one === undefined
+            ? { resolved: [], unknown: [ids[0]] }
+            : { resolved: [one], unknown: [] };
+    }
+    const res = await client.batch(ids);
+    return { resolved: res.resolved, unknown: res.unknown };
+}
+export async function assetsShow(deps, opts) {
+    const parsed = parseIdArgs(opts.ids);
+    if (!parsed.ok) {
+        for (const l of parsed.lines)
+            deps.err(l);
+        return 1;
+    }
+    let result;
+    try {
+        result = await resolveIds(deps.client, parsed.ids);
+    }
+    catch (err) {
+        const screen = failureScreen(err, `vincentt assets show ${parsed.ids.join(" ")}`);
+        for (const l of screen.lines)
+            deps.err(l);
+        return screen.code;
+    }
+    const shown = dedupeForDisplay(result.resolved, (a) => a.id);
+    const unknown = [...new Set(result.unknown)];
+    if (opts.json) {
+        deps.out(JSON.stringify({ resolved: result.resolved, unknown: result.unknown }, null, 2));
+        return unknown.length > 0 ? 1 : 0;
+    }
+    for (const a of shown)
+        for (const l of showLines(a))
+            deps.err(l);
+    if (unknown.length > 0) {
+        const malformed = unknown.some((id) => !isLibraryId(id));
+        for (const l of unknownBlockLines(unknown, shown.length, malformed))
+            deps.err(l);
+        return 1;
+    }
+    return 0;
+}
+export async function assetsAdd(deps, opts) {
+    const parsed = parseIdArgs(opts.ids);
+    if (!parsed.ok) {
+        for (const l of parsed.lines)
+            deps.err(l);
+        return 1;
+    }
+    let result;
+    try {
+        result = await resolveIds(deps.client, parsed.ids);
+    }
+    catch (err) {
+        const screen = failureScreen(err, `vincentt assets add ${parsed.ids.join(" ")}`);
+        for (const l of screen.lines)
+            deps.err(l);
+        return screen.code;
+    }
+    const shown = dedupeForDisplay(result.resolved, (a) => a.id);
+    const unknown = [...new Set(result.unknown)];
+    // The arity in the header counts what the CALLER asked for, de-duplicated for
+    // display — "4 of 5" must mean four of the five distinct things they named.
+    const requested = new Set(parsed.ids).size;
+    if (opts.json) {
+        deps.out(JSON.stringify({ resolved: result.resolved, unknown: result.unknown }, null, 2));
+        if (opts.download) {
+            // --json + --download still writes, and still announces every path — but on
+            // stderr, so stdout stays a single parseable document.
+            await runDownload(deps, shown, opts);
+        }
+        return unknown.length > 0 ? 1 : 0;
+    }
+    for (const l of addLines(shown, unknown.length, requested))
+        deps.err(l);
+    let downloadCode = 0;
+    if (opts.download) {
+        downloadCode = await runDownload(deps, shown, opts);
+    }
+    else {
+        // `add` is a verb that sounds like it writes files. This one sentence, on every
+        // successful add, stops a creator searching their repo for what it added — and
+        // it is the honest statement of "the platform informs, never performs".
+        deps.err("  Nothing was written. These are URLs to reference from your source.");
+        deps.err("");
+    }
+    if (unknown.length > 0) {
+        const malformed = unknown.some((id) => !isLibraryId(id));
+        for (const l of unknownBlockLines(unknown, shown.length, malformed))
+            deps.err(l);
+        if (!opts.download) {
+            deps.err("  Nothing was written.");
+            deps.err("");
+        }
+        return 1;
+    }
+    return downloadCode;
+}
+/**
+ * The `--download` side effect. Every written path is announced, per the rule that
+ * a state-changing command names its side effects on the creator's disk.
+ */
+async function runDownload(deps, records, opts) {
+    const baseDir = opts.dir !== undefined ? path.resolve(opts.dir) : path.join(deps.cwd, DOWNLOAD_DIR);
+    // The overwrite gate runs over ALL records BEFORE any byte is written, so a
+    // refusal never leaves a half-written set on disk.
+    if (!opts.force) {
+        for (const a of records) {
+            const target = downloadPath(baseDir, a);
+            if (await exists(target)) {
+                for (const l of overwriteRefusalLines(path.relative(deps.cwd, target)))
+                    deps.err(l);
+                return 1;
+            }
+        }
+    }
+    deps.err(`→ Downloading ${records.length} ${records.length === 1 ? "file" : "files"}…`);
+    const written = [];
+    for (const a of records) {
+        const target = downloadPath(baseDir, a);
+        let bytes;
+        try {
+            bytes = await deps.client.download(a.url);
+        }
+        catch (err) {
+            // A CDN failure is NOT a resolution failure: the ids resolved and the URLs
+            // above are correct and usable. Saying so is the difference between a
+            // creator retrying the download and a creator concluding the asset is gone.
+            deps.err("");
+            deps.err(`✗ Couldn't download ${a.id}.`);
+            deps.err("");
+            deps.err("  The URLs above are correct and still work — reference them directly");
+            deps.err("  instead, or try --download again in a moment.");
+            deps.err("");
+            if (written.length > 0) {
+                deps.err(`  ${written.length} file${written.length === 1 ? "" : "s"} already written:`);
+                for (const w of written)
+                    deps.err(`    ${w}`);
+                deps.err("");
+            }
+            else {
+                deps.err("  Nothing was written.");
+                deps.err("");
+            }
+            void err;
+            return 1;
+        }
+        const res = await writeAsset(target, bytes);
+        const rel = path.relative(deps.cwd, res.path);
+        written.push(rel);
+        const size = humanBytes(res.bytes);
+        deps.err(`✓ Wrote ${rel}${size ? `   ${size}` : ""}`);
+    }
+    deps.err("");
+    // The reference line CHANGES after a download: the correct reference is now the
+    // local path, and printing the CDN URL here would be actively wrong — the creator
+    // would ship both a copy and a remote load.
+    deps.err("  Reference them as /assets/library/<filename>, not as the library URL.");
+    deps.err("");
+    deps.err("  These are now your files, in your repo. Nothing links them back to the");
+    deps.err("  library and nothing updates them.");
+    deps.err("");
+    return 0;
+}