@vincentt-xr/cli 0.7.0 → 0.9.0

package/dist/library/render.d.ts

@@ -0,0 +1,39 @@
+import type { AssetRecord, Gap, SearchResponse } from "./wire.js";
+/** `prop · 1:1 · alpha` — the placement contract, from facts the bytes cannot get wrong. */
+export declare function contractLine(a: AssetRecord): string;
+/** `pumpkin · prop · 1:1 · 1024x1024 · alpha` — `add`'s confirmation line (byte facts). */
+export declare function byteFactsLine(a: AssetRecord): string;
+/** Human byte size, e.g. `180 KB`. Absent bytes render as an absent size. */
+export declare function humanBytes(bytes: number | undefined): string | undefined;
+/**
+ * One search result, in the five-line layout the design fixes:
+ *   1  id + the placement contract   (byte facts — decides usability)
+ *   2  subject — description         (the noun leads; the agent matched on a noun)
+ *   3  usage_hint, UNLABELLED        (it is an instruction and reads as one)
+ *   4  style · render   then palette (the NEXT query's vocabulary)
+ *   5  the URL, whole and alone      (the payload)
+ * Any line whose fields are absent is simply not emitted.
+ */
+export declare function searchRecordLines(a: AssetRecord): string[];
+/** The `Narrow it:` footer — a vocabulary with real example values, not a usage string. */
+export declare function narrowFooter(results: AssetRecord[]): string;
+/** The zero-result screen. Exit 0, and DELIBERATELY no glyph. */
+export declare function zeroResultLines(query: string, gaps: Gap[], revision?: string): string[];
+/** The full human search screen. */
+export declare function searchLines(res: SearchResponse, query: string): string[];
+/**
+ * `add`'s success block. The URL is the FIRST line of each entry because `add`
+ * exists to produce URLs; the byte facts follow as confirmation that the right one
+ * arrived.
+ */
+export declare function addLines(resolved: AssetRecord[], unknownCount: number, requestedCount: number): string[];
+/**
+ * The failure block for unresolved ids. Last, `✗`, and the offending string echoed
+ * VERBATIM on its own indented line so an agent can diff its own input without
+ * parsing our sentence.
+ */
+export declare function unknownBlockLines(unknown: string[], resolvedCount: number, malformed: boolean): string[];
+/** `show`'s stacked key/value block — the "tell me everything" verb. */
+export declare function showLines(a: AssetRecord): string[];
+/** The three exit-4 screens. Each states that the creator's PROJECT is unaffected. */
+export declare function unreachableLines(kind: "transport" | "auth" | "unavailable", retry: string): string[];

package/dist/library/render.js

@@ -0,0 +1,305 @@
+// The human renderers for `vincentt assets`. Pure string builders — no I/O, no
+// exit codes — so every line the designer specified is unit-assertable.
+//
+// The reader is a LANGUAGE MODEL with a human over its shoulder, so everything
+// here is designed to be true when read as plain text with color stripped. There
+// is no color, no spinner and no box drawing in this file.
+//
+// Every field read is guarded (see wire.ts). A record missing `usage_hint` loses
+// that LINE; it does not lose the record, and it never throws.
+/** `prop · 1:1 · alpha` — the placement contract, from facts the bytes cannot get wrong. */
+export function contractLine(a) {
+    // `kind` may legitimately be ABSENT (unclassifiable). It is omitted rather than
+    // printed as "unknown", which would read as a classification we did not make.
+    const parts = [a.kind, a.aspect, a.has_alpha === true ? "alpha" : undefined].filter((p) => typeof p === "string" && p.length > 0);
+    return parts.join(" · ");
+}
+/** `pumpkin · prop · 1:1 · 1024x1024 · alpha` — `add`'s confirmation line (byte facts). */
+export function byteFactsLine(a) {
+    const dims = a.width !== undefined && a.height !== undefined ? `${a.width}x${a.height}` : undefined;
+    const parts = [
+        a.subject,
+        a.kind,
+        a.aspect,
+        dims,
+        a.has_alpha === true ? "alpha" : undefined,
+    ].filter((p) => typeof p === "string" && p.length > 0);
+    return parts.join(" · ");
+}
+/** Human byte size, e.g. `180 KB`. Absent bytes render as an absent size. */
+export function humanBytes(bytes) {
+    if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
+        return undefined;
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const kb = bytes / 1024;
+    if (kb < 1024)
+        return `${Math.round(kb)} KB`;
+    return `${(kb / 1024).toFixed(1)} MB`;
+}
+function wrap(text, width, indent) {
+    const words = text.split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return [];
+    const lines = [];
+    let line = "";
+    for (const w of words) {
+        if (line.length === 0)
+            line = w;
+        else if (`${line} ${w}`.length <= width)
+            line = `${line} ${w}`;
+        else {
+            lines.push(indent + line);
+            line = w;
+        }
+    }
+    if (line.length > 0)
+        lines.push(indent + line);
+    return lines;
+}
+/**
+ * One search result, in the five-line layout the design fixes:
+ *   1  id + the placement contract   (byte facts — decides usability)
+ *   2  subject — description         (the noun leads; the agent matched on a noun)
+ *   3  usage_hint, UNLABELLED        (it is an instruction and reads as one)
+ *   4  style · render   then palette (the NEXT query's vocabulary)
+ *   5  the URL, whole and alone      (the payload)
+ * Any line whose fields are absent is simply not emitted.
+ */
+export function searchRecordLines(a) {
+    const out = [];
+    const contract = contractLine(a);
+    out.push(`  ${a.id}${contract ? `   ${contract}` : ""}`);
+    const subject = a.subject;
+    const description = a.description;
+    if (subject !== undefined && description !== undefined) {
+        // The description is lowercased at the join only when it starts a sentence
+        // after the em-less "subject — " lead, matching the approved transcript.
+        const d = description.charAt(0).toLowerCase() + description.slice(1);
+        out.push(...wrap(`${subject} — ${d}`, 72, "    "));
+    }
+    else if (subject !== undefined) {
+        out.push(`    ${subject}`);
+    }
+    else if (description !== undefined) {
+        out.push(...wrap(description, 72, "    "));
+    }
+    if (a.usage_hint !== undefined)
+        out.push(...wrap(a.usage_hint, 72, "    "));
+    const styleTokens = [...(a.style ?? [])];
+    if (a.render !== undefined)
+        styleTokens.unshift(a.render);
+    const left = styleTokens.join(" · ");
+    const right = (a.palette ?? []).join(", ");
+    if (left || right) {
+        out.push(`    ${left}${left && right ? "   ·   " : ""}${right}`);
+    }
+    out.push(`    ${a.url}`);
+    return out;
+}
+/** The `Narrow it:` footer — a vocabulary with real example values, not a usage string. */
+export function narrowFooter(results) {
+    // Real values are pulled from the results the caller is looking at: an agent that
+    // has never seen the corpus does not know `--render` takes `3d-clay` and not
+    // `clay`. This is the cheapest schema disclosure available and it costs one line.
+    const render = results.find((r) => r.render !== undefined)?.render ?? "3d-clay";
+    const palette = results.flatMap((r) => r.palette ?? [])[0] ?? "sage";
+    return `  Narrow it:  --kind prop|frame   --render ${render}   --palette ${palette}   --limit 20`;
+}
+/** The zero-result screen. Exit 0, and DELIBERATELY no glyph. */
+export function zeroResultLines(query, gaps, revision) {
+    const out = ["", `  No assets match "${query}".`, ""];
+    // The inventory sentence is served VERBATIM from the corpus's gaps array — it is
+    // a fact about what we own, not a phrase the CLI composed. Closing the gap is a
+    // corpus change, not a code change. De-duplicated because two tags legitimately
+    // carry the same message ("wearable" and "face-filter" both explain one absence).
+    // VERBATIM — not re-cased, not re-punctuated. The moment the CLI edits this
+    // string it is composing an inventory claim rather than reporting one, and the
+    // whole point is that closing a gap is a CORPUS change, not a code change.
+    const messages = [...new Set(gaps.map((g) => g.message))];
+    for (const m of messages) {
+        out.push(...wrap(m, 70, "  "));
+        out.push("");
+    }
+    // The anti-"Did you mean". When the miss is an inventory fact, a suggested
+    // rephrasing would imply one exists that works. It does not, and implying it is
+    // a lie of exactly the class this feature exists to prevent.
+    out.push("  There is nothing to try differently on this query. What the library has:");
+    out.push("");
+    out.push("    --kind prop     objects to place in a scene        1:1, transparent");
+    out.push("    --kind frame    full-screen camera overlays        9:16, transparent centre");
+    if (revision !== undefined) {
+        out.push("");
+        out.push(`  library revision ${revision}`);
+    }
+    out.push("");
+    return out;
+}
+/** The full human search screen. */
+export function searchLines(res, query) {
+    if (res.resultCount === 0 || res.results.length === 0) {
+        return zeroResultLines(query, res.gaps, res.revision);
+    }
+    const out = [""];
+    const noun = res.resultCount === 1 ? "asset" : "assets";
+    // The revision is the one piece of platform bookkeeping on the screen: it makes
+    // "the library changed under me" answerable without SSH. Absent on an older API,
+    // in which case the header degrades to just the count.
+    out.push(`  ${res.resultCount} ${noun}${res.revision !== undefined ? ` · library revision ${res.revision}` : ""}`);
+    out.push("");
+    for (const a of res.results) {
+        out.push(...searchRecordLines(a));
+        out.push("");
+    }
+    const shown = res.results.length;
+    if (res.resultCount > shown) {
+        out.push(`  … ${res.resultCount - shown} more`);
+        out.push("");
+    }
+    out.push(narrowFooter(res.results));
+    out.push("");
+    return out;
+}
+/**
+ * `add`'s success block. The URL is the FIRST line of each entry because `add`
+ * exists to produce URLs; the byte facts follow as confirmation that the right one
+ * arrived.
+ */
+export function addLines(resolved, unknownCount, requestedCount) {
+    const out = [""];
+    // The header changes SHAPE when something is missing — "4 assets" vs
+    // "4 of 5 assets" — because a different shape survives a skim and a different
+    // number does not.
+    out.push(unknownCount > 0
+        ? `  ${resolved.length} of ${requestedCount} assets`
+        : `  ${resolved.length} ${resolved.length === 1 ? "asset" : "assets"}`);
+    out.push("");
+    for (const a of resolved) {
+        out.push(`  ${a.url}`);
+        const facts = byteFactsLine(a);
+        if (facts)
+            out.push(`    ${facts}`);
+        out.push("");
+    }
+    return out;
+}
+/**
+ * The failure block for unresolved ids. Last, `✗`, and the offending string echoed
+ * VERBATIM on its own indented line so an agent can diff its own input without
+ * parsing our sentence.
+ */
+export function unknownBlockLines(unknown, resolvedCount, malformed) {
+    const out = [];
+    const n = unknown.length;
+    out.push(`✗ ${n} ${n === 1 ? "id is" : "ids are"} not in the library:`);
+    out.push("");
+    for (const id of unknown)
+        out.push(`    ${id}`);
+    out.push("");
+    // Printed ONLY when a passed id was not even id-shaped. This is f5's closest
+    // thing to teaching the invented-URL rule, at the moment the agent is actually
+    // making that mistake — and it is advice that AGREES with a control, never the
+    // control itself (the control is that no verb accepts a URL).
+    if (malformed) {
+        out.push("  Ids look like lib_7f3a2c67d4e5b6a7. Search returns them; nothing else does.");
+    }
+    if (resolvedCount > 0) {
+        // The sentence that prevents the expensive mistake: an agent that reads exit 1
+        // and nothing else discards the whole turn; one that reads this keeps its good
+        // resolutions and re-searches for the one that missed.
+        out.push(malformed
+            ? `  The ${resolvedCount} above resolved and ${resolvedCount === 1 ? "is" : "are"} safe to use.`
+            : `  The ${resolvedCount} above resolved and ${resolvedCount === 1 ? "is" : "are"} safe to use. Search for the missing one:`);
+        if (!malformed)
+            out.push(`  vincentt assets search "<what you wanted>"`);
+    }
+    out.push("");
+    return out;
+}
+/** `show`'s stacked key/value block — the "tell me everything" verb. */
+export function showLines(a) {
+    const out = ["", `  ${a.id}`, ""];
+    if (a.retired === true) {
+        // Retirement removes an asset from SEARCH, never from SERVING (B37). The `!`
+        // is advisory and never `✗`: the only reason an agent holds a retired id is
+        // that a project already references it, and the useful instruction is to do
+        // nothing.
+        out.push("! This asset is no longer in search results. The URL below keeps working");
+        out.push("  forever — if you are already using it, nothing needs to change.");
+        out.push("");
+    }
+    if (a.subject !== undefined)
+        out.push(`  ${a.subject}`);
+    if (a.description !== undefined)
+        out.push(...wrap(a.description, 74, "  "));
+    if (a.usage_hint !== undefined) {
+        out.push("");
+        out.push(...wrap(a.usage_hint, 74, "  "));
+    }
+    out.push("");
+    const row = (label, value) => {
+        if (value !== undefined && value.length > 0)
+            out.push(`  ${label.padEnd(10)}${value}`);
+    };
+    row("kind", a.kind);
+    const size = a.width !== undefined && a.height !== undefined
+        ? `${a.width} x ${a.height}${a.aspect !== undefined ? `  (${a.aspect})` : ""}`
+        : undefined;
+    row("size", size);
+    if (a.has_alpha !== undefined) {
+        const coverage = a.occupies_canvas !== undefined
+            ? ` · covers ${Math.round(a.occupies_canvas * 100)}% of the canvas`
+            : "";
+        row("alpha", `${a.has_alpha ? "yes" : "no"}${coverage}`);
+    }
+    const size2 = humanBytes(a.bytes);
+    row("format", a.format !== undefined ? `${a.format}${size2 ? ` · ${size2}` : ""}` : size2);
+    row("render", a.render);
+    row("view", a.view);
+    row("text", a.text_in_image);
+    row("style", (a.style ?? []).join(", "));
+    row("palette", (a.palette ?? []).join(", "));
+    out.push("");
+    out.push(`  ${a.url}`);
+    out.push("");
+    return out;
+}
+/** The three exit-4 screens. Each states that the creator's PROJECT is unaffected. */
+export function unreachableLines(kind, retry) {
+    if (kind === "auth") {
+        return [
+            "",
+            "✗ You're not signed in.",
+            "",
+            "  The library is a platform call, so it needs an account. Your project is",
+            "  unaffected — build, preview and publish don't use the library.",
+            "",
+            "  Sign in:  vincentt login",
+            "",
+        ];
+    }
+    if (kind === "unavailable") {
+        return [
+            "",
+            "✗ The library is temporarily unavailable.",
+            "",
+            "  Nothing is wrong with your project. Try again in a moment:",
+            `  ${retry}`,
+            "",
+        ];
+    }
+    // B36 said out loud at the only moment anyone cares. A creator whose tool just
+    // failed is one thought from "is my project broken?", and the answer is no,
+    // definitively. It also pre-empts the wrong recovery: an agent that believes the
+    // library is required starts improvising URLs.
+    return [
+        "",
+        "✗ Can't reach the asset library.",
+        "",
+        "  Your project is unaffected — build, preview and publish don't use the",
+        "  library. Any library URL you already have keeps working.",
+        "",
+        `  Try again in a moment:  ${retry}`,
+        "",
+    ];
+}

package/dist/library/wire.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The asset id shape. Base32-lower, matching the server's `^lib_[a-z2-7]{16}$`
+ * exactly.
+ *
+ * The alphabet is the house convention across this API (f3 sessions {32}, f4
+ * uploads {26}, preview host labels, publish keys) and it excludes 0/1/8/9 so an
+ * id read off a terminal carries no visually ambiguous characters. 16 chars is
+ * 80 bits, which is what makes the key pattern unguessable, one of the four
+ * counters to an agent inventing a URL.
+ *
+ * The CLI briefly accepted hex as well, because every EXAMPLE id written into
+ * the design record was hex and contradicted the record's own regex. User ruling
+ * 2026-08-23: the regex is authoritative and the examples were wrong. Matching
+ * the server exactly is what keeps a client-side reject and a server-side
+ * `unknown[]` from ever disagreeing.
+ */
+export declare const LIB_ID_RE: RegExp;
+export declare function isLibraryId(s: string): boolean;
+/**
+ * An asset record as the API emits it. Only `id` and `url` are structurally
+ * required; everything else is optional BECAUSE THE WIRE SAYS SO, not as a
+ * convenience:
+ *   • `kind` may be ABSENT — a real state (unclassifiable), never "" and never
+ *     "unknown". Coercing absence to a string would invent a classification.
+ *   • `text_in_image` is omitted when not confidently read, never "".
+ *   • `retired` rides fetch and batch but NOT search (a search never returns a
+ *     retired asset), so its absence is normal rather than a defect.
+ */
+export interface AssetRecord {
+    id: string;
+    url: string;
+    kind?: "prop" | "frame";
+    width?: number;
+    height?: number;
+    aspect?: string;
+    has_alpha?: boolean;
+    bytes?: number;
+    format?: string;
+    subject?: string;
+    style?: string[];
+    palette?: string[];
+    render?: string;
+    view?: string;
+    description?: string;
+    usage_hint?: string;
+    text_in_image?: string;
+    occupies_canvas?: number;
+    retired?: boolean;
+}
+export interface Gap {
+    tag: string;
+    message: string;
+}
+export interface SearchResponse {
+    query?: string;
+    /** The corpus the answer came from. Absent on an older API — the header line degrades away. */
+    revision?: string;
+    resultCount: number;
+    results: AssetRecord[];
+    gaps: Gap[];
+}
+export interface BatchResponse {
+    resolved: AssetRecord[];
+    /** Verbatim echoes of unresolvable inputs. Disjoint from `resolved`. */
+    unknown: string[];
+}
+/**
+ * Parse one asset record.
+ *
+ * `kind` is admitted ONLY as "prop" or "frame". Anything else — including "" and
+ * "unknown" — parses to ABSENT rather than being passed through, because a record
+ * whose kind is the literal string "unknown" would render as a real classification
+ * on the line an agent uses to decide whether the asset is usable at all.
+ *
+ * Returns undefined when `id`/`url` are missing: a record with no URL is not a
+ * usable result, and dropping it is better than rendering an entry whose payload
+ * line is blank.
+ */
+export declare function parseAssetRecord(raw: unknown): AssetRecord | undefined;
+/**
+ * Parse the search envelope.
+ *
+ * `resultCount` is taken from the wire when present and otherwise derived from the
+ * array, so a truncated envelope still renders a truthful count rather than 0 —
+ * and 0 is the one value that must never be invented, because zero results is a
+ * meaningful product answer (the honest-empty path) rather than an absence.
+ */
+export declare function parseSearchResponse(raw: unknown): SearchResponse;
+/**
+ * Parse the batch envelope. `unknown[]` entries are echoed VERBATIM by the server
+ * and are kept as raw strings — they are the caller's own input coming back, which
+ * is what lets an agent diff against what it sent without parsing our prose.
+ */
+export declare function parseBatchResponse(raw: unknown): BatchResponse;
+/** A single record from `GET /library/assets/{id}` — the same record shape, unwrapped. */
+export declare function parseFetchResponse(raw: unknown): AssetRecord | undefined;

package/dist/library/wire.js

@@ -0,0 +1,167 @@
+// The f5 asset-library wire shapes, and the ONE parser every renderer reads through.
+//
+// The envelope is camelCase (resultCount, gaps, resolved, unknown) while the asset
+// RECORD is snake_case (has_alpha, usage_hint, text_in_image, occupies_canvas).
+// That mix is deliberate and it is the API's only mixed-convention response
+// (implementation 2.12): the record's vocabulary sits beside English prose in an
+// agent's context, so it reads as prose-adjacent rather than as code identifiers.
+// NEITHER SIDE IS NORMALIZED HERE. Rewriting the record to camelCase would silently
+// break every agent prompt in the wild that reads `usage_hint`.
+//
+// EVERY field is read defensively, for the reason lib/diagnostics.ts records: the
+// CLI and the API are versioned separately on a creator's machine — `npx vincentt`
+// fetches whatever the registry has and points it at whatever API the config
+// resolves to. A field a renderer reads unguarded is a field whose removal from the
+// API crashes the command, which is exactly what removing `sessions` did once.
+// A missing optional field must degrade to a missing LINE, never to an exception.
+/**
+ * The asset id shape. Base32-lower, matching the server's `^lib_[a-z2-7]{16}$`
+ * exactly.
+ *
+ * The alphabet is the house convention across this API (f3 sessions {32}, f4
+ * uploads {26}, preview host labels, publish keys) and it excludes 0/1/8/9 so an
+ * id read off a terminal carries no visually ambiguous characters. 16 chars is
+ * 80 bits, which is what makes the key pattern unguessable, one of the four
+ * counters to an agent inventing a URL.
+ *
+ * The CLI briefly accepted hex as well, because every EXAMPLE id written into
+ * the design record was hex and contradicted the record's own regex. User ruling
+ * 2026-08-23: the regex is authoritative and the examples were wrong. Matching
+ * the server exactly is what keeps a client-side reject and a server-side
+ * `unknown[]` from ever disagreeing.
+ */
+export const LIB_ID_RE = /^lib_[a-z2-7]{16}$/;
+export function isLibraryId(s) {
+    return LIB_ID_RE.test(s);
+}
+function obj(v) {
+    return typeof v === "object" && v !== null ? v : {};
+}
+function str(o, k) {
+    return typeof o[k] === "string" ? o[k] : undefined;
+}
+function num(o, k) {
+    return typeof o[k] === "number" && Number.isFinite(o[k]) ? o[k] : undefined;
+}
+function bool(o, k) {
+    return typeof o[k] === "boolean" ? o[k] : undefined;
+}
+function strArray(o, k) {
+    const v = o[k];
+    if (!Array.isArray(v))
+        return undefined;
+    return v.filter((x) => typeof x === "string");
+}
+/**
+ * Parse one asset record.
+ *
+ * `kind` is admitted ONLY as "prop" or "frame". Anything else — including "" and
+ * "unknown" — parses to ABSENT rather than being passed through, because a record
+ * whose kind is the literal string "unknown" would render as a real classification
+ * on the line an agent uses to decide whether the asset is usable at all.
+ *
+ * Returns undefined when `id`/`url` are missing: a record with no URL is not a
+ * usable result, and dropping it is better than rendering an entry whose payload
+ * line is blank.
+ */
+export function parseAssetRecord(raw) {
+    const o = obj(raw);
+    const id = str(o, "id");
+    const url = str(o, "url");
+    if (id === undefined || url === undefined)
+        return undefined;
+    // The wire is an input too. A record whose url is not https is dropped rather
+    // than rendered, so a compromised or misconfigured API cannot point --download
+    // at file:// or a link-local address.
+    if (!url.startsWith("https://"))
+        return undefined;
+    const kindRaw = str(o, "kind");
+    const kind = kindRaw === "prop" || kindRaw === "frame" ? kindRaw : undefined;
+    // An empty string is the "not confidently read" case the API omits; treat a
+    // stray "" the same way rather than rendering an empty labelled line.
+    const textInImage = str(o, "text_in_image");
+    return {
+        id,
+        url,
+        ...(kind !== undefined ? { kind } : {}),
+        ...(num(o, "width") !== undefined ? { width: num(o, "width") } : {}),
+        ...(num(o, "height") !== undefined ? { height: num(o, "height") } : {}),
+        ...(str(o, "aspect") !== undefined ? { aspect: str(o, "aspect") } : {}),
+        ...(bool(o, "has_alpha") !== undefined ? { has_alpha: bool(o, "has_alpha") } : {}),
+        ...(num(o, "bytes") !== undefined ? { bytes: num(o, "bytes") } : {}),
+        ...(str(o, "format") !== undefined ? { format: str(o, "format") } : {}),
+        ...(str(o, "subject") !== undefined ? { subject: str(o, "subject") } : {}),
+        ...(strArray(o, "style") !== undefined ? { style: strArray(o, "style") } : {}),
+        ...(strArray(o, "palette") !== undefined ? { palette: strArray(o, "palette") } : {}),
+        ...(str(o, "render") !== undefined ? { render: str(o, "render") } : {}),
+        ...(str(o, "view") !== undefined ? { view: str(o, "view") } : {}),
+        ...(str(o, "description") !== undefined
+            ? { description: str(o, "description") }
+            : {}),
+        ...(str(o, "usage_hint") !== undefined ? { usage_hint: str(o, "usage_hint") } : {}),
+        ...(textInImage ? { text_in_image: textInImage } : {}),
+        ...(num(o, "occupies_canvas") !== undefined
+            ? { occupies_canvas: num(o, "occupies_canvas") }
+            : {}),
+        ...(bool(o, "retired") !== undefined ? { retired: bool(o, "retired") } : {}),
+    };
+}
+function parseGaps(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const g of raw) {
+        const o = obj(g);
+        const tag = str(o, "tag");
+        const message = str(o, "message");
+        // Both fields are load-bearing and carry different jobs: the agent BRANCHES on
+        // `tag` and QUOTES `message`. A half-formed gap is dropped rather than rendered
+        // with an invented half.
+        if (tag !== undefined && message !== undefined)
+            out.push({ tag, message });
+    }
+    return out;
+}
+/**
+ * Parse the search envelope.
+ *
+ * `resultCount` is taken from the wire when present and otherwise derived from the
+ * array, so a truncated envelope still renders a truthful count rather than 0 —
+ * and 0 is the one value that must never be invented, because zero results is a
+ * meaningful product answer (the honest-empty path) rather than an absence.
+ */
+export function parseSearchResponse(raw) {
+    const o = obj(raw);
+    const results = Array.isArray(o.results)
+        ? o.results.map(parseAssetRecord).filter((r) => r !== undefined)
+        : [];
+    return {
+        ...(str(o, "query") !== undefined ? { query: str(o, "query") } : {}),
+        ...(str(o, "revision") !== undefined ? { revision: str(o, "revision") } : {}),
+        resultCount: num(o, "resultCount") ?? results.length,
+        results,
+        gaps: parseGaps(o.gaps),
+    };
+}
+/**
+ * Parse the batch envelope. `unknown[]` entries are echoed VERBATIM by the server
+ * and are kept as raw strings — they are the caller's own input coming back, which
+ * is what lets an agent diff against what it sent without parsing our prose.
+ */
+export function parseBatchResponse(raw) {
+    const o = obj(raw);
+    const resolved = Array.isArray(o.resolved)
+        ? o.resolved.map(parseAssetRecord).filter((r) => r !== undefined)
+        : [];
+    const unknown = Array.isArray(o.unknown)
+        ? o.unknown.filter((x) => typeof x === "string")
+        : [];
+    return { resolved, unknown };
+}
+/** A single record from `GET /library/assets/{id}` — the same record shape, unwrapped. */
+export function parseFetchResponse(raw) {
+    const o = obj(raw);
+    // Tolerate both a bare record and an { asset: … } envelope: /me already taught
+    // this codebase that an envelope can appear on a route that once returned bare.
+    return parseAssetRecord(o.asset !== undefined ? o.asset : o);
+}

package/dist/publish/api.d.ts

@@ -46,6 +46,26 @@ export interface ApiErrorDetail {
     mismatched?: number;
     reason?: string;
     path?: string;
+    /**
+     * f10's plan-limit refusal. Bytes are DECIMAL on the wire (1 GB = 10^9), the
+     * same units formatBytes already renders.
+     */
+    figureBytes?: number;
+    allowanceBytes?: number;
+    cutOffAt?: string;
+    from?: string;
+    to?: string;
+    /** The tier in force, when the API names one. */
+    planTier?: string;
+    planName?: string;
+    /**
+     * The org that owns THIS project, as the API names it. It is not the machine's
+     * configured active org and must win over it: a project can belong to an org
+     * the CLI is not currently pointed at, and naming the wrong one in a refusal
+     * tells the creator's agent to go look at an org that was never cut off.
+     */
+    orgName?: string;
+    orgSlug?: string;
 }
 export declare class PublishApiError extends Error {
     readonly status: number;

package/dist/publish/command.d.ts

@@ -18,6 +18,9 @@ export interface PublishDeps {
     sleep: (ms: number) => Promise<void>;
     fetchImpl?: typeof fetch;
     orgName?: () => Promise<string>;
+    /** The active org's slug, for the usage deep link on a plan-limit refusal. */
+    orgSlug?: () => Promise<string | undefined>;
+    consoleUrl?: string;
 }
 export interface PublishOptions {
     distDir?: string;