@vincentt-xr/cli 0.7.0 → 0.8.0

package/dist/library/client.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedConfig } from "../shared/config.js";
+import { type AssetRecord, type BatchResponse, type SearchResponse } from "./wire.js";
+/** The API said no, with a code we can act on. */
+export declare class LibraryError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+/** We could not reach the API at all — a transport failure, not an answer. */
+export declare class LibraryUnreachableError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(cause?: unknown | undefined);
+}
+export interface SearchParams {
+    q: string;
+    kind?: string;
+    render?: string;
+    palette?: string;
+    limit?: number;
+}
+/**
+ * The transport seam. Every f5 command takes one of these, so the whole surface is
+ * testable against a recording stub with no socket — and so the deny fixture in
+ * QA-F5-C3 has exactly one place to observe.
+ */
+export interface LibraryClient {
+    search(params: SearchParams): Promise<SearchResponse>;
+    fetchOne(id: string): Promise<AssetRecord | undefined>;
+    batch(ids: string[]): Promise<BatchResponse>;
+    /** Download asset BYTES from a URL the SERVER returned. Only `--download` calls this. */
+    download(url: string): Promise<Uint8Array>;
+}
+/**
+ * The real HTTP client, PAT-authed like every other machine call.
+ *
+ * A thrown TypeError from `fetch` is a transport failure (DNS, refused connection,
+ * a deny fixture) and becomes LibraryUnreachableError → exit 4. An HTTP status is
+ * an ANSWER and becomes LibraryError, which the commands map by code. Collapsing
+ * the two would merge "we did not answer" into "we answered no", and the agent's
+ * correct recovery differs between them (retry later vs re-search).
+ */
+export declare function httpLibraryClient(cfg: ResolvedConfig): LibraryClient;

package/dist/library/client.js

@@ -0,0 +1,137 @@
+// The f5 library API client — THE module B36 layer 1 pins.
+//
+// B36 asserts that `create` / `build` / `preview` / `publish` make ZERO requests to
+// any f5 route (implementation 2.7). The mechanical form of that assertion is an
+// import check: this module must be imported by exactly the assets/library command
+// modules and their tests. A hit in any other command module fails the check, which
+// is why every f5 network call is funnelled through here rather than spread across
+// the verbs.
+//
+// It builds request PATHS from ids and filters. It never accepts a URL from a
+// caller: there is no `--url` flag anywhere in the CLI and no code path where a
+// CLI-supplied URL reaches a fetch. That is a security control, not a style choice
+// (D-add-prints-urls degraded the no-invented-URLs rule from prevention to
+// detection, and this is the one arm that stayed prevention).
+import { parseBatchResponse, parseFetchResponse, parseSearchResponse, } from "./wire.js";
+/** The API said no, with a code we can act on. */
+export class LibraryError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "LibraryError";
+    }
+}
+/** We could not reach the API at all — a transport failure, not an answer. */
+export class LibraryUnreachableError extends Error {
+    cause;
+    constructor(cause) {
+        super("Can't reach the asset library.");
+        this.cause = cause;
+        this.name = "LibraryUnreachableError";
+    }
+}
+async function errorCode(res) {
+    try {
+        const body = (await res.clone().json());
+        return typeof body?.code === "string" ? body.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The real HTTP client, PAT-authed like every other machine call.
+ *
+ * A thrown TypeError from `fetch` is a transport failure (DNS, refused connection,
+ * a deny fixture) and becomes LibraryUnreachableError → exit 4. An HTTP status is
+ * an ANSWER and becomes LibraryError, which the commands map by code. Collapsing
+ * the two would merge "we did not answer" into "we answered no", and the agent's
+ * correct recovery differs between them (retry later vs re-search).
+ */
+export function httpLibraryClient(cfg) {
+    const base = cfg.apiUrl.replace(/\/$/, "");
+    const auth = { authorization: `Bearer ${cfg.pat}` };
+    const call = async (pathname, init) => {
+        try {
+            return await fetch(`${base}${pathname}`, {
+                ...init,
+                headers: { ...(init?.headers ?? {}), ...auth },
+            });
+        }
+        catch (err) {
+            throw new LibraryUnreachableError(err);
+        }
+    };
+    const fail = async (res, what) => {
+        throw new LibraryError(`${what} failed (${res.status})`, res.status, await errorCode(res));
+    };
+    return {
+        async search(params) {
+            const qs = new URLSearchParams({ q: params.q });
+            if (params.kind !== undefined)
+                qs.set("kind", params.kind);
+            if (params.render !== undefined)
+                qs.set("render", params.render);
+            if (params.palette !== undefined)
+                qs.set("palette", params.palette);
+            if (params.limit !== undefined)
+                qs.set("limit", String(params.limit));
+            // No `cursor`, no `page`. Cut from v1 (D-nextCursor-is-cut-from-v1): a
+            // revision-scoped cursor is only valid on the box and the moment that issued
+            // it. A caller wanting more re-queries with a larger --limit.
+            const res = await call(`/library/assets?${qs.toString()}`);
+            if (!res.ok)
+                await fail(res, "library search");
+            return parseSearchResponse(await readJson(res));
+        },
+        async fetchOne(id) {
+            const res = await call(`/library/assets/${encodeURIComponent(id)}`);
+            if (res.status === 404)
+                return undefined;
+            if (!res.ok)
+                await fail(res, "library fetch");
+            return parseFetchResponse(await readJson(res));
+        },
+        async batch(ids) {
+            const res = await call(`/library/assets:batch`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ ids }),
+            });
+            if (!res.ok)
+                await fail(res, "library batch");
+            return parseBatchResponse(await readJson(res));
+        },
+        async download(url) {
+            // The url argument is ALWAYS a server-returned record.url, never anything a
+            // caller typed: `add` resolves ids first and downloads only what came back.
+            // parseAssetRecord already drops any record whose url is not https, so this
+            // is the second assertion of the same invariant, at the point of the fetch.
+            if (!url.startsWith("https://")) {
+                throw new LibraryError(`refusing to download a non-https url`, 0);
+            }
+            let res;
+            try {
+                res = await fetch(url);
+            }
+            catch (err) {
+                throw new LibraryUnreachableError(err);
+            }
+            if (!res.ok) {
+                throw new LibraryError(`download failed (${res.status})`, res.status);
+            }
+            return new Uint8Array(await res.arrayBuffer());
+        },
+    };
+}

package/dist/library/download.d.ts

@@ -0,0 +1,46 @@
+import type { AssetRecord } from "./wire.js";
+/** Where downloads land, relative to the project root. */
+export declare const DOWNLOAD_DIR: string;
+/**
+ * Slugify a subject for use in a filename.
+ *
+ * Everything outside [a-z0-9-] is dropped rather than escaped, which removes `/`,
+ * `\`, `.` and `%` as a class instead of enumerating them. A subject that reduces
+ * to nothing yields "asset", so the filename never starts with the separator or
+ * collapses into the extension.
+ */
+export declare function safeSubject(subject: string | undefined): string;
+/** The extension, from `format` — admitted only as png/webp, else png. */
+export declare function safeExt(format: string | undefined): string;
+/**
+ * `<subject>-<id>.<ext>`, e.g. `pumpkin-lib_7f3a2c67d4e5b6a7.png`.
+ *
+ * Throws when `id` is not id-shaped. The id is the one component that could carry
+ * a separator if a compromised or drifted API returned something unexpected, and a
+ * throw here is strictly better than composing a path from it: the id has ALREADY
+ * been validated against the same regex on the way in, so a failure means the wire
+ * disagrees with the contract and writing anything at that point is guesswork.
+ */
+export declare function downloadFilename(a: AssetRecord): string;
+/**
+ * The absolute path a record downloads to, under `dir`.
+ *
+ * The join is re-checked against the resolved base: even with a validated filename,
+ * asserting containment is one line and it is the assertion that stays true if
+ * someone later relaxes downloadFilename.
+ */
+export declare function downloadPath(baseDir: string, a: AssetRecord): string;
+export interface WriteResult {
+    path: string;
+    bytes: number;
+}
+/** Does the file already exist? (Used for the refuse-to-overwrite gate.) */
+export declare function exists(p: string): Promise<boolean>;
+export declare function writeAsset(p: string, bytes: Uint8Array): Promise<WriteResult>;
+/**
+ * The overwrite refusal names the INTERESTING reason, not "file exists": B37 means
+ * the bytes at a library URL never change, so the copy on disk is already identical
+ * and re-downloading achieves nothing. That teaches immutability in passing and is
+ * more useful than a bare flag suggestion.
+ */
+export declare function overwriteRefusalLines(relPath: string): string[];

package/dist/library/download.js

@@ -0,0 +1,98 @@
+// `--download` — the NON-DEFAULT opt-in. `add` prints URLs and writes nothing by
+// default (D-add-prints-urls); this path exists for offline demos and for a creator
+// who wants the byte in their repo to edit.
+//
+// The filename is composed from `subject` + `id`, both of which the corpus schema
+// validated server-side, and NEVER from a wire string like `url` or `key`. That is
+// what makes path traversal on the derived filename impossible rather than merely
+// unlikely — but the composition is defended here too, because "the server
+// validated it" is a property of a system the CLI is versioned separately from.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { isLibraryId } from "./wire.js";
+/** Where downloads land, relative to the project root. */
+export const DOWNLOAD_DIR = path.join("public", "assets", "library");
+/**
+ * Slugify a subject for use in a filename.
+ *
+ * Everything outside [a-z0-9-] is dropped rather than escaped, which removes `/`,
+ * `\`, `.` and `%` as a class instead of enumerating them. A subject that reduces
+ * to nothing yields "asset", so the filename never starts with the separator or
+ * collapses into the extension.
+ */
+export function safeSubject(subject) {
+    const s = (subject ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return s.length > 0 ? s : "asset";
+}
+/** The extension, from `format` — admitted only as png/webp, else png. */
+export function safeExt(format) {
+    return format === "webp" ? "webp" : "png";
+}
+/**
+ * `<subject>-<id>.<ext>`, e.g. `pumpkin-lib_7f3a2c67d4e5b6a7.png`.
+ *
+ * Throws when `id` is not id-shaped. The id is the one component that could carry
+ * a separator if a compromised or drifted API returned something unexpected, and a
+ * throw here is strictly better than composing a path from it: the id has ALREADY
+ * been validated against the same regex on the way in, so a failure means the wire
+ * disagrees with the contract and writing anything at that point is guesswork.
+ */
+export function downloadFilename(a) {
+    if (!isLibraryId(a.id)) {
+        throw new Error(`refusing to derive a filename from a non-id: ${a.id}`);
+    }
+    return `${safeSubject(a.subject)}-${a.id}.${safeExt(a.format)}`;
+}
+/**
+ * The absolute path a record downloads to, under `dir`.
+ *
+ * The join is re-checked against the resolved base: even with a validated filename,
+ * asserting containment is one line and it is the assertion that stays true if
+ * someone later relaxes downloadFilename.
+ */
+export function downloadPath(baseDir, a) {
+    const base = path.resolve(baseDir);
+    const full = path.resolve(base, downloadFilename(a));
+    if (full !== path.join(base, path.basename(full))) {
+        throw new Error(`refusing to write outside ${base}`);
+    }
+    return full;
+}
+/** Does the file already exist? (Used for the refuse-to-overwrite gate.) */
+export async function exists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function writeAsset(p, bytes) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, bytes);
+    return { path: p, bytes: bytes.byteLength };
+}
+/**
+ * The overwrite refusal names the INTERESTING reason, not "file exists": B37 means
+ * the bytes at a library URL never change, so the copy on disk is already identical
+ * and re-downloading achieves nothing. That teaches immutability in passing and is
+ * more useful than a bare flag suggestion.
+ */
+export function overwriteRefusalLines(relPath) {
+    return [
+        "",
+        `✗ ${relPath} already exists.`,
+        "",
+        "  The library never changes a file at a URL, so the copy you have is the",
+        "  same bytes. Pass --force to overwrite it anyway.",
+        "",
+        "  Nothing was written.",
+        "",
+    ];
+}

package/dist/library/parse.d.ts

@@ -0,0 +1,43 @@
+/** An argument that is unmistakably a URL rather than an id. */
+export declare function looksLikeUrl(arg: string): boolean;
+export interface IdArgsOk {
+    ok: true;
+    /** The ids AS GIVEN, duplicates intact — the server charges pre-dedup. */
+    ids: string[];
+}
+export interface IdArgsError {
+    ok: false;
+    lines: string[];
+}
+/**
+ * Validate the positional ids for `show` / `add`.
+ *
+ * A URL is a USAGE error (exit 1, zero network calls). A merely malformed id
+ * (`pastel-pumpkin.png`) is NOT: it goes to the server and comes back in
+ * `unknown[]`, so the other ids in the same call still resolve. Those two cases
+ * look similar and are deliberately different — one is a shape the CLI must never
+ * transmit, the other is a lookup that must not destroy its siblings.
+ */
+export declare function parseIdArgs(args: string[]): IdArgsOk | IdArgsError;
+/** De-duplicate for DISPLAY, preserving first-occurrence order. */
+export declare function dedupeForDisplay<T>(items: T[], key: (t: T) => string): T[];
+export interface SearchFlags {
+    kind?: string;
+    render?: string;
+    palette?: string;
+    limit?: number;
+}
+export type SearchFlagResult = {
+    ok: true;
+    flags: SearchFlags;
+} | {
+    ok: false;
+    lines: string[];
+};
+/** `--limit` is clamped by the SERVER at 50; the CLI only rejects nonsense. */
+export declare function parseSearchFlags(raw: {
+    kind?: string;
+    render?: string;
+    palette?: string;
+    limit?: string;
+}): SearchFlagResult;

package/dist/library/parse.js

@@ -0,0 +1,109 @@
+// Argument parsing for the `assets` verb group.
+//
+// THE CONTROL LIVES HERE. Every f5 verb accepts ids and only ids: there is no
+// `--url` flag anywhere in the CLI, and an argument that looks like a URL is
+// refused by the PARSER, before any network call is made. Under
+// D-add-prints-urls the agent handles URLs as strings by design, so a parser that
+// refuses one is the only thing standing between a hallucinated URL and a fetch.
+// The AGENTS.md prose is advice; this function is the control.
+/** An argument that is unmistakably a URL rather than an id. */
+export function looksLikeUrl(arg) {
+    // Scheme-ful and scheme-relative forms both count. This is deliberately broad:
+    // a false positive costs one clear error message, while a false negative puts a
+    // caller-supplied string on the path to a fetch.
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(arg) || arg.startsWith("//");
+}
+/**
+ * Validate the positional ids for `show` / `add`.
+ *
+ * A URL is a USAGE error (exit 1, zero network calls). A merely malformed id
+ * (`pastel-pumpkin.png`) is NOT: it goes to the server and comes back in
+ * `unknown[]`, so the other ids in the same call still resolve. Those two cases
+ * look similar and are deliberately different — one is a shape the CLI must never
+ * transmit, the other is a lookup that must not destroy its siblings.
+ */
+export function parseIdArgs(args) {
+    if (args.length === 0) {
+        return {
+            ok: false,
+            lines: [
+                "",
+                "✗ No asset ids given.",
+                "",
+                "  Ids look like lib_7f3a2c67d4e5b6a7. Search returns them; nothing else does.",
+                "",
+                '  Find one:  vincentt assets search "<what you want>"',
+                "",
+            ],
+        };
+    }
+    const urls = args.filter(looksLikeUrl);
+    if (urls.length > 0) {
+        return {
+            ok: false,
+            lines: [
+                "",
+                "✗ This command takes asset ids, not URLs.",
+                "",
+                `    ${urls[0]}`,
+                "",
+                "  Ids look like lib_7f3a2c67d4e5b6a7. Search returns them; nothing else does.",
+                "",
+                '  Find one:  vincentt assets search "<what you want>"',
+                "",
+            ],
+        };
+    }
+    // Duplicates are NOT trimmed here. The CLI de-duplicates for DISPLAY only,
+    // because the server charges pre-dedup and pre-trimming would hide that cost
+    // from the operator.
+    return { ok: true, ids: args };
+}
+/** De-duplicate for DISPLAY, preserving first-occurrence order. */
+export function dedupeForDisplay(items, key) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const k = key(item);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(item);
+    }
+    return out;
+}
+/** `--limit` is clamped by the SERVER at 50; the CLI only rejects nonsense. */
+export function parseSearchFlags(raw) {
+    const flags = {};
+    if (raw.kind !== undefined) {
+        if (raw.kind !== "prop" && raw.kind !== "frame") {
+            return {
+                ok: false,
+                lines: [
+                    "",
+                    `✗ --kind takes prop or frame, not "${raw.kind}".`,
+                    "",
+                    "    --kind prop     objects to place in a scene",
+                    "    --kind frame    full-screen camera overlays",
+                    "",
+                ],
+            };
+        }
+        flags.kind = raw.kind;
+    }
+    if (raw.render !== undefined)
+        flags.render = raw.render;
+    if (raw.palette !== undefined)
+        flags.palette = raw.palette;
+    if (raw.limit !== undefined) {
+        const n = Number(raw.limit);
+        if (!Number.isInteger(n) || n < 1) {
+            return {
+                ok: false,
+                lines: ["", `✗ --limit takes a whole number, not "${raw.limit}".`, ""],
+            };
+        }
+        flags.limit = n;
+    }
+    return { ok: true, flags };
+}

package/dist/library/qa.f5-b32.spec.d.ts

@@ -0,0 +1 @@
+export {};