@vincentt-xr/cli 0.7.0 → 0.8.0

package/dist/library/qa.f5-b32.spec.js

@@ -0,0 +1,202 @@
+// QA-F5-C3 · B36's narrowed boundary — zero `/library` requests, and the deny
+// predicate is pinned.
+//
+// THIS IS THE CLAIM f5 IS JUDGED ON. B36: a project builds, previews and
+// publishes with the library unreachable, and no platform capability works
+// better because an asset came from us. The creator loses a catalogue, not a
+// toolchain.
+//
+// dev's b32.test.ts owns layers 1 and 4 (the static import check and the
+// predicate's four URLs) and says so. THIS FILE OWNS LAYERS 2 AND 3 — the live
+// arms — plus the predicate's behavioral half.
+//
+// ⚠ THE NEGATIVE ASSERTION IS THE CASE. A publish that succeeds while the
+// library is unreachable is ALSO what you observe if the call was attempted,
+// timed out and was swallowed by a try/catch — which would make f5 a dependency
+// WITH A TIMEOUT, silently adding seconds to every publish. Only "zero /library
+// requests recorded" distinguishes NOT A DEPENDENCY from A DEPENDENCY THAT
+// FAILS SOFT.
+//
+// ⚠ AND IT ONLY MEANS THAT BECAUSE THE API IS LIVE. Under a host-level deny
+// everything fails, and the fixture cannot tell "publish never called f5" from
+// "publish failed because nothing was reachable"
+// (D-B36-fixture-denies-a-path-prefix-not-a-host).
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { httpLibraryClient, LibraryUnreachableError } from "./client.js";
+function denyPath(prefix, host) {
+    const attempts = [];
+    const denied = [];
+    const realFetch = globalThis.fetch;
+    // TWO SEPARATE CONDITIONS on the PARSED url. Written this way deliberately —
+    // see the header, and layer 4 below, which is the case that fails when
+    // somebody "simplifies" it into `raw.includes(prefix)`.
+    const predicate = (u) => u.host === host && u.pathname.startsWith(prefix);
+    globalThis.fetch = (async (input, init) => {
+        const raw = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.href
+                : input.url;
+        const u = new URL(raw);
+        const attempt = { host: u.host, pathname: u.pathname };
+        attempts.push(attempt);
+        if (predicate(u)) {
+            denied.push(attempt);
+            // A refused connection, exactly as an unreachable host produces. The CLI
+            // must map this to LibraryUnreachableError → exit 4, never to an answer.
+            throw new TypeError("fetch failed");
+        }
+        return realFetch(input, init);
+    });
+    return {
+        attempts,
+        denied,
+        predicate,
+        restore: () => {
+            globalThis.fetch = realFetch;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// the live stack
+// ---------------------------------------------------------------------------
+//
+// Inherited from dev, never built here. The endpoint comes from the environment
+// so a port change is a config change rather than an edit to this file — the
+// ports are DERIVED from the task slug, not chosen.
+const API_URL = process.env.QA_F5_API_URL ?? "http://localhost:8088";
+const API_HOST = new URL(API_URL).host;
+let apiLive = false;
+beforeEach(async () => {
+    if (apiLive)
+        return;
+    try {
+        const res = await fetch(`${API_URL}/health`, { signal: AbortSignal.timeout(2000) });
+        apiLive = res.ok;
+    }
+    catch {
+        apiLive = false;
+    }
+});
+let fixture;
+afterEach(() => {
+    fixture?.restore();
+    fixture = undefined;
+});
+describe("QA-F5-C3 · B36 layer 4 — the deny predicate is /library-on-the-API-host only", () => {
+    it("(c) drives the predicate with four URLs, including the anti-drift pin", () => {
+        const f = denyPath("/library", "api.dev.vincentt.studio");
+        fixture = f;
+        const denied = f.predicate;
+        // 1. the f5 route on the API host — DENIED.
+        expect(denied(new URL("https://api.dev.vincentt.studio/library/assets"))).toBe(true);
+        expect(denied(new URL("https://api.dev.vincentt.studio/library/assets:batch"))).toBe(true);
+        // 2. every OTHER route on the SAME host — ALLOWED. f5 has no host of its
+        //    own, so a host deny takes publish down with it.
+        expect(denied(new URL("https://api.dev.vincentt.studio/publishes"))).toBe(false);
+        expect(denied(new URL("https://api.dev.vincentt.studio/projects"))).toBe(false);
+        // 3. THE ANTI-DRIFT PIN. The assets CDN serves library/v1/, so its paths
+        //    contain "/library" too. A predicate written as url.includes("/library")
+        //    denies the CDN and asserts a property f5 NO LONGER HAS
+        //    (D-add-prints-urls). This url is what fails when someone "simplifies"
+        //    the predicate.
+        expect(denied(new URL("https://assets.dev.vincentt.studio/library/v1/props/x.png")), "the assets CDN was DENIED. Under D-add-prints-urls it is on every published viewer's " +
+            "critical path; denying it asserts f5-independence of a published experience, which is " +
+            "explicitly NOT a claim f5 makes any more.").toBe(false);
+        // 4. the CDN at any other path — ALLOWED.
+        expect(denied(new URL("https://assets.dev.vincentt.studio/anything"))).toBe(false);
+        // The weaker form, demonstrated failing, so it is not silently reintroduced.
+        const substring = (raw) => raw.includes("/library");
+        expect(substring("https://assets.dev.vincentt.studio/library/v1/props/x.png")).toBe(true);
+        expect(denied(new URL("https://assets.dev.vincentt.studio/library/v1/props/x.png"))).toBe(false);
+    });
+});
+// The live arms need a running API. They are opt-in, mirroring the Go 4E tier's
+// QA_F5_RUN_SERVE_TIER: absent a stack they report BLOCKED rather than failing,
+// because a red CI check for "no stack here" trains people to ignore the check.
+// They must NEVER silently pass: B36's claim only means something against a
+// REACHABLE route, or the fixture cannot tell "publish never called f5" from
+// "publish failed because nothing was reachable".
+const RUN_LIVE = process.env.QA_F5_RUN_LIVE === "1";
+describe.skipIf(!RUN_LIVE)("QA-F5-C3 · B36 layers 2 and 3 — against the LIVE api", () => {
+    it("(b) an f5 call under the deny fixture is REFUSED and maps to exit 4, not to an answer", async () => {
+        if (!apiLive) {
+            throw new Error(`the api at ${API_URL} is not reachable, so QA-F5-C3's live arms cannot run.\n\n` +
+                `This case is BLOCKED, not passed. B36's assertion only means what it claims when ` +
+                `the API is LIVE: a stray f5 call must be a real request to a REACHABLE route, or ` +
+                `the fixture cannot tell "publish never called f5" from "publish failed because ` +
+                `nothing was reachable".\n\n` +
+                `Boot it:  dev-stack.sh up   (then re-run; override with QA_F5_API_URL)`);
+        }
+        const f = denyPath("/library", API_HOST);
+        fixture = f;
+        const client = httpLibraryClient({ apiUrl: API_URL, pat: "vct_qa_f5_not_a_real_token" });
+        let threw;
+        try {
+            await client.search({ q: "pastel pumpkin" });
+        }
+        catch (err) {
+            threw = err;
+        }
+        expect(threw, "the library search RESOLVED under a deny fixture. A denied request must surface as a " +
+            "transport failure, never as an answer.").toBeInstanceOf(LibraryUnreachableError);
+        // The attempt WAS made and WAS recorded — a fixture that recorded nothing
+        // would make every "zero attempts" assertion below vacuous.
+        expect(f.denied.length, "the deny fixture recorded ZERO denials. A fixture that never fires cannot prove an " +
+            "absence, and every assertion built on it passes for free.").toBeGreaterThan(0);
+        expect(f.denied[0].pathname.startsWith("/library")).toBe(true);
+        expect(f.denied[0].host).toBe(API_HOST);
+    });
+    it("(a) the NON-/library API surface is unaffected — publish's origin still answers", async () => {
+        if (!apiLive) {
+            throw new Error(`the api at ${API_URL} is not reachable; QA-F5-C3 is BLOCKED, not passed`);
+        }
+        const f = denyPath("/library", API_HOST);
+        fixture = f;
+        // The publish path's own origin, under the SAME fixture. This is what makes
+        // layer 2 STRONGER than a host deny: the chain runs against a LIVE, WORKING
+        // API, so a stray f5 call would be a real request to a reachable route
+        // rather than one failure among many.
+        const health = await fetch(`${API_URL}/health`);
+        expect(health.ok, "the API's own /health failed under the deny fixture. The fixture is denying more than " +
+            "the /library path prefix — probably the HOST — which takes publish down with it and " +
+            "makes the whole case fail for a reason unrelated to B36.").toBe(true);
+        const readyz = await fetch(`${API_URL}/readyz`);
+        expect([200, 503]).toContain(readyz.status);
+        // THE ASSERTION THAT ACTUALLY TESTS B36: across every non-f5 request made
+        // above, ZERO have a path beginning with /library.
+        const strays = f.attempts.filter((a) => a.host === API_HOST && a.pathname.startsWith("/library"));
+        expect(strays, `the non-f5 surface issued ${strays.length} request(s) under /library: ` +
+            `${JSON.stringify(strays)}.\n\n` +
+            `B36 says the library is not a dependency of the toolchain's core loop. A green ` +
+            `publish alone is ALSO what you observe if the call was attempted, timed out and was ` +
+            `swallowed — which would make f5 a dependency WITH A TIMEOUT, silently adding seconds ` +
+            `to every publish. Only the empty recorded list distinguishes the two.`).toEqual([]);
+    });
+    it("the f5 route EXISTS and is reachable when the fixture is NOT installed — the control", async () => {
+        if (!apiLive) {
+            throw new Error(`the api at ${API_URL} is not reachable; QA-F5-C3 is BLOCKED, not passed`);
+        }
+        // WITHOUT the fixture. If /library did not exist on this build, every
+        // "zero /library requests" assertion above would pass against a router that
+        // simply has no such route — certifying the boundary while proving nothing.
+        const res = await fetch(`${API_URL}/library/assets?q=pumpkin`);
+        expect(res.status, `GET /library/assets returned ${res.status}. A 404 means the route is NOT MOUNTED on ` +
+            `this build — which makes B36's negative assertion vacuous. The surface is gated on ` +
+            `LIBRARY_ASSETS_BASE_URL; unset, /library never mounts.`).not.toBe(404);
+        // 401 is the expected answer to an unauthenticated read: the route exists
+        // and refuses anonymous callers.
+        expect([200, 401, 403, 503]).toContain(res.status);
+    });
+});
+describe("QA-F5-C3 · live tier status", () => {
+    it("reports whether B36's live arms ran", () => {
+        if (!RUN_LIVE) {
+            console.warn("\nQA-F5-C3 live arms: BLOCKED (not passed, not failed).\n" +
+                "  B36 layers 2 and 3 need a running API. Layer 4 (the deny predicate and the\n" +
+                "  anti-drift pin) DID run and is green.\n" +
+                "  To run them:  dev-stack.sh up   then  QA_F5_RUN_LIVE=1 npm test\n");
+        }
+        expect(true).toBe(true);
+    });
+});

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

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

package/dist/library/qa.f5-cli.spec.js

@@ -0,0 +1,433 @@
+// QA f5 · 4C — the CLI surface. QA-F5-C1 and QA-F5-C2.
+//
+// This is the tier a BLIND CONSUMER's control flow depends on. Two properties of
+// this file are load-bearing:
+//
+//  1. QA-F5-C1 asserts that exit 1 and exit 4 DIFFER, not merely that each has
+//     the right value. "We answered and something is missing" and "we did not
+//     answer" have different correct recoveries (re-search vs retry later), and
+//     a build that collapses them passes every per-code assertion.
+//
+//  2. QA-F5-C2(a) is a CONTROL, not advice. The prose in AGENTS.md is advice;
+//     iteration 2 shipped exactly that guardrail prose and it is the same class
+//     as the alphaMap hallucination it cites. Under print-by-default the agent
+//     handles URLs as strings BY DESIGN, so the only thing standing between a
+//     hallucinated URL and a fetch is a parser that refuses one.
+//
+// Written from features/f5-asset-library/qa.md, not from the implementation.
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { assetsAdd, assetsSearch, assetsShow } from "./assetsCommand.js";
+import { LibraryError, LibraryUnreachableError } from "./client.js";
+import { looksLikeUrl, parseIdArgs } from "./parse.js";
+// ---------------------------------------------------------------------------
+// fixtures — VALID base32-lower ids
+// ---------------------------------------------------------------------------
+//
+// ⚠ The record's example ids (lib_7f3a2c67d4e5b6a7, lib_2b7e6d4a4c7f2537) are
+// 16-char HEX and contain 0/1/8/9 — characters ABSENT from base32-lower. They do
+// not satisfy the record's own ^lib_[a-z2-7]{16}$, which the API enforces at
+// three places. Fixtures here use ids the SERVER would actually mint, so a
+// resolution that works here works against a real API.
+const PUMPKIN = {
+    id: "lib_75eokepbmoh4g6ol",
+    url: "https://assets.vincentt.studio/library/v1/props/pastel-pumpkin-75eokepbmoh4g6ol.png",
+    kind: "prop",
+    aspect: "1:1",
+    width: 1024,
+    height: 1024,
+    has_alpha: true,
+    bytes: 184320,
+    format: "png",
+    subject: "pumpkin",
+    description: "A soft pastel-orange pumpkin with a cream stem.",
+    usage_hint: "Place as a standalone prop.",
+};
+const TRIO = {
+    ...PUMPKIN,
+    id: "lib_2b7e6dqa4c5fzs37",
+    url: "https://assets.vincentt.studio/library/v1/props/pumpkin-trio-2b7e6dqa4c5fzs37.png",
+    subject: "pumpkin trio",
+};
+const LANTERN = {
+    ...PUMPKIN,
+    id: "lib_lanternqqqqqqqq",
+    url: "https://assets.vincentt.studio/library/v1/props/lantern-lanternqqqqqqqq.png",
+    subject: "paper lantern",
+};
+const FRAME = {
+    ...PUMPKIN,
+    id: "lib_frameaqqqqqqqqq",
+    url: "https://assets.vincentt.studio/library/v1/frames/gold-frameaqqqqqqqqq.png",
+    kind: "frame",
+    aspect: "9:16",
+    width: 720,
+    height: 1280,
+    subject: "gold frame border",
+};
+const GAPS = [
+    { tag: "wearable", message: "the library has no wearable or face-filter assets yet" },
+    { tag: "face-filter", message: "the library has no wearable or face-filter assets yet" },
+];
+const tempDirs = [];
+async function tempCwd() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "qa-f5-"));
+    tempDirs.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir)
+            await fs.rm(dir, { recursive: true, force: true });
+    }
+});
+function harness(client, cwd = "/tmp/qa-f5-nonexistent") {
+    const stdout = [];
+    const stderr = [];
+    const calls = [];
+    const downloaded = [];
+    const full = {
+        search: async (p) => {
+            calls.push("search");
+            if (client.search)
+                return client.search(p);
+            throw new Error("search not stubbed");
+        },
+        fetchOne: async (id) => {
+            calls.push("fetchOne");
+            if (client.fetchOne)
+                return client.fetchOne(id);
+            throw new Error("fetchOne not stubbed");
+        },
+        batch: async (ids) => {
+            calls.push(`batch:${ids.join(",")}`);
+            if (client.batch)
+                return client.batch(ids);
+            throw new Error("batch not stubbed");
+        },
+        download: async (url) => {
+            calls.push("download");
+            downloaded.push(url);
+            if (client.download)
+                return client.download(url);
+            return new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+        },
+    };
+    return {
+        deps: { out: (l) => stdout.push(l), err: (l) => stderr.push(l), client: full, cwd },
+        stdout,
+        stderr,
+        calls,
+        downloaded,
+        cwd,
+    };
+}
+const search = (res) => ({
+    resultCount: res.results?.length ?? 0,
+    results: [],
+    gaps: [],
+    ...res,
+});
+const batch = (res) => ({
+    resolved: [],
+    unknown: [],
+    ...res,
+});
+// ---------------------------------------------------------------------------
+// QA-F5-C1 · The exit-code contract, across all five outcomes
+// ---------------------------------------------------------------------------
+describe("QA-F5-C1 · the exit-code contract", () => {
+    it("(a) search WITH results exits 0", async () => {
+        const h = harness({ search: async () => search({ results: [PUMPKIN], resultCount: 1 }) });
+        expect(await assetsSearch(h.deps, { query: "pastel pumpkin", json: false })).toBe(0);
+    });
+    it("(b) search with ZERO results exits 0, carries NO glyph, and --json is valid", async () => {
+        const h = harness({ search: async () => search({ resultCount: 0, gaps: GAPS }) });
+        const code = await assetsSearch(h.deps, { query: "christmas face filter", json: false });
+        // THE SINGLE MOST IMPORTANT EXIT CODE IN f5. 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 or shipping a box geometry. That is the exact behavior the
+        // feature exists to prevent.
+        expect(code).toBe(0);
+        const screen = h.stderr.join("\n");
+        for (const glyph of ["✗", "⚠", "Error", "error:", "failed"]) {
+            expect(screen.includes(glyph), `the zero-result screen contains ${JSON.stringify(glyph)}. A well-formed question with ` +
+                `no matching inventory is a CORRECT ANSWER; styling it as an error is what teaches ` +
+                `the agent to treat an honest empty as a failure:\n${screen}`).toBe(false);
+        }
+        // The gap message is VERBATIM from the corpus — the CLI reports an inventory
+        // claim, it does not compose one.
+        expect(screen).toContain(GAPS[0].message);
+        // --json: stdout is a SINGLE valid JSON document, and stderr carries nothing
+        // that could contaminate it.
+        const j = harness({ search: async () => search({ resultCount: 0, gaps: GAPS }) });
+        expect(await assetsSearch(j.deps, { query: "christmas face filter", json: true })).toBe(0);
+        expect(j.stdout).toHaveLength(1);
+        const doc = JSON.parse(j.stdout[0]);
+        expect(doc.resultCount).toBe(0);
+        expect(doc.results).toEqual([]);
+        expect(doc.gaps.length, "`gaps` is empty under --json on a zero-result search. The keys must ALWAYS be " +
+            "present and populated here: a key that appears only sometimes is a key nobody handles.").toBeGreaterThan(0);
+        expect(doc.gaps[0]).toHaveProperty("tag");
+        expect(doc.gaps[0]).toHaveProperty("message");
+    });
+    it("(c) a PARTIAL add exits 1, prints the good URLs FIRST and in full, and says nothing was written", async () => {
+        const h = harness({
+            batch: async () => batch({ resolved: [PUMPKIN, TRIO, LANTERN, FRAME], unknown: ["lib_ffffffffffffffff"] }),
+        });
+        const code = await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, TRIO.id, LANTERN.id, FRAME.id, "lib_ffffffffffffffff"],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(code).toBe(1);
+        const screen = h.stderr.join("\n");
+        // The four good URLs print FIRST and IN FULL.
+        for (const a of [PUMPKIN, TRIO, LANTERN, FRAME]) {
+            expect(screen, `the URL for ${a.id} is missing from the add screen`).toContain(a.url);
+        }
+        const firstUrlAt = screen.indexOf(PUMPKIN.url);
+        const failureAt = screen.indexOf("✗");
+        expect(failureAt, "the failure block is not last. An agent skimming the screen must see its four usable " +
+            "URLs before the thing that went wrong, or it discards the whole turn.").toBeGreaterThan(firstUrlAt);
+        // The header is a DIFFERENT SHAPE, not just a different number — a shape
+        // survives a skim and a number does not.
+        expect(screen).toContain("4 of 5 assets");
+        // The bad id is echoed VERBATIM so an agent can diff against what it sent.
+        expect(screen).toContain("lib_ffffffffffffffff");
+        // "Nothing was written." is present — `add` is a verb that SOUNDS like it
+        // writes files, and this is the honest statement of "the platform informs,
+        // never performs" (B35).
+        expect(screen).toContain("Nothing was written.");
+    });
+    it("(d) a TRANSPORT failure exits 4, with an empty stdout and the B36 paragraph on stderr", async () => {
+        const h = harness({
+            search: async () => {
+                throw new LibraryUnreachableError(new Error("ECONNREFUSED"));
+            },
+        });
+        const code = await assetsSearch(h.deps, { query: "pastel pumpkin", json: false });
+        expect(code).toBe(4);
+        expect(h.stdout, "stdout is not empty on a failure. Under --json an agent pipes stdout into a parser; " +
+            "any human line there corrupts the document.").toEqual([]);
+        const screen = h.stderr.join("\n").toLowerCase();
+        expect(screen.includes("publish") || screen.includes("preview") || screen.includes("build"), "the unreachable screen does not carry the B36 paragraph. A creator whose library call " +
+            "just failed needs to know that build, preview and publish are unaffected — otherwise " +
+            "an f5 outage reads as a toolchain outage:\n" + h.stderr.join("\n")).toBe(true);
+    });
+    it("(e) a 503 library_unavailable exits 4 and is NEVER rendered as a zero-result answer", async () => {
+        const h = harness({
+            search: async () => {
+                throw new LibraryError("library search failed (503)", 503, "library_unavailable");
+            },
+        });
+        const code = await assetsSearch(h.deps, { query: "pastel pumpkin", json: false });
+        expect(code).toBe(4);
+        expect(h.stdout).toEqual([]);
+        const screen = h.stderr.join("\n");
+        expect(screen.includes("No assets match"), "a 503 rendered as the ZERO-RESULT screen. \"we could not look\" and \"there is nothing " +
+            "there\" must never collapse: the agent's recovery from an honest empty (stop asking, " +
+            "build from props) is the WRONG move when the truth is that the corpus failed to load.").toBe(false);
+    });
+    it("the pair that must never collapse: (c) is 1 and (d)/(e) are 4, and they DIFFER", async () => {
+        const partial = harness({
+            batch: async () => batch({ resolved: [PUMPKIN], unknown: ["lib_ffffffffffffffff"] }),
+        });
+        const partialCode = await assetsAdd(partial.deps, {
+            ids: [PUMPKIN.id, "lib_ffffffffffffffff"],
+            json: false,
+            download: false,
+            force: false,
+        });
+        const down = harness({
+            batch: async () => {
+                throw new LibraryUnreachableError();
+            },
+        });
+        const downCode = await assetsAdd(down.deps, {
+            ids: [PUMPKIN.id, TRIO.id],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(partialCode).toBe(1);
+        expect(downCode).toBe(4);
+        expect(partialCode, "the partial-resolution and did-not-answer exit codes are EQUAL. They must differ: " +
+            "\"we answered and something is missing\" is re-search, \"we did not answer\" is retry " +
+            "later, and an agent that cannot tell them apart takes the wrong recovery every time.").not.toBe(downCode);
+    });
+});
+// ---------------------------------------------------------------------------
+// QA-F5-C2 · Ids and only ids, batching at 2+, and writing nothing
+// ---------------------------------------------------------------------------
+describe("QA-F5-C2 · the CLI accepts ids and only ids, and writes nothing", () => {
+    it("(a) a URL is an arg-parse error with ZERO network calls — the CONTROL", async () => {
+        const h = harness({});
+        const code = await assetsAdd(h.deps, {
+            ids: ["https://assets.vincentt.studio/library/v1/props/x.png"],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(code).not.toBe(0);
+        expect(h.calls, "a caller-supplied URL reached the network layer. THIS IS THE CONTROL, and the prose in " +
+            "AGENTS.md is advice: under print-by-default 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.").toEqual([]);
+        expect(h.stderr.join("\n")).toContain("ids, not URLs");
+        // There is NO --url flag anywhere in the accepted set. Asserted over the
+        // parser's own predicate rather than over a help string, because the help
+        // string is not what admits an argument.
+        //
+        // The set below is the catalog's scope: SCHEME-FUL and SCHEME-RELATIVE forms,
+        // i.e. the shapes that are unmistakably a URL and that a fetch would follow.
+        for (const u of [
+            "https://assets.vincentt.studio/library/v1/props/x.png",
+            "http://evil.test/x.png",
+            "//assets.vincentt.studio/x.png",
+            "file:///etc/passwd",
+            "ftp://evil.test/x.png",
+        ]) {
+            expect(looksLikeUrl(u), `${u} is not recognized as a URL by the parser`).toBe(true);
+            expect(parseIdArgs([u]).ok, `${u} was accepted as an id`).toBe(false);
+        }
+        // THE STRONGER FORM OF THE SAME CONTROL, and the one that actually closes the
+        // hole: whatever the parser admits, the only string that ever reaches a fetch
+        // is a SERVER-RETURNED record.url.
+        //
+        // A `data:` or bare-path argument is NOT refused by looksLikeUrl (it has no
+        // `//`), and that is acceptable precisely because of this: it goes to the
+        // server as an id, comes back in unknown[], and never reaches download(). The
+        // refusal above is the cheap first line; this is the property.
+        const smuggleCwd = await tempCwd();
+        const smuggle = harness({ batch: async () => batch({ resolved: [PUMPKIN], unknown: ["data:image/png;base64,AAAA"] }) }, smuggleCwd);
+        await assetsAdd(smuggle.deps, {
+            ids: [PUMPKIN.id, "data:image/png;base64,AAAA"],
+            json: false,
+            download: true,
+            force: false,
+        });
+        for (const url of smuggle.downloaded) {
+            expect(url, `download() was called with ${url}, which is not a url the SERVER returned. Every ` +
+                `byte fetched by --download must come from a record the API resolved; a ` +
+                `caller-supplied string reaching a fetch is the hallucinated-URL failure this ` +
+                `control exists to prevent.`).toBe(PUMPKIN.url);
+        }
+    });
+    it("(b) a MALFORMED id goes to unknown[] via the SERVER, not a client-side 400", async () => {
+        const h = harness({
+            batch: async () => batch({ resolved: [PUMPKIN], unknown: ["pastel-pumpkin.png"] }),
+        });
+        const code = await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, "pastel-pumpkin.png"],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(code).toBe(1);
+        // The id REACHED the wire. A merely malformed id is NOT a shape the CLI must
+        // refuse to transmit: refusing it client-side would destroy its siblings,
+        // which D-multi-asset-is-mandatory forbids.
+        expect(h.calls.some((c) => c.startsWith("batch:") && c.includes("pastel-pumpkin.png")), `the malformed id never reached the server. calls=${JSON.stringify(h.calls)}`).toBe(true);
+        // The teaching line prints — advice that AGREES with a control, at the moment
+        // the agent is actually making the mistake.
+        expect(h.stderr.join("\n")).toContain("Ids look like lib_");
+    });
+    it("(c) three ids issue EXACTLY ONE batch call, never three fetches", async () => {
+        const h = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO, LANTERN] }) });
+        await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, TRIO.id, LANTERN.id],
+            json: false,
+            download: false,
+            force: false,
+        });
+        const batchCalls = h.calls.filter((c) => c.startsWith("batch:"));
+        const fetchCalls = h.calls.filter((c) => c === "fetchOne");
+        expect(batchCalls.length, `expected ONE batch call, got calls=${JSON.stringify(h.calls)}. N sequential fetches is ` +
+            `the behavior D-multi-asset-is-mandatory exists to eliminate — and the limiter's ` +
+            `ceil(n/2) discount only rewards batching if the CLI actually batches.`).toBe(1);
+        expect(fetchCalls).toHaveLength(0);
+    });
+    it("(d) duplicates go out AS GIVEN and are de-duplicated for DISPLAY only", async () => {
+        const h = harness({ batch: async () => batch({ resolved: [PUMPKIN, PUMPKIN, TRIO] }) });
+        await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, PUMPKIN.id, TRIO.id],
+            json: false,
+            download: false,
+            force: false,
+        });
+        const call = h.calls.find((c) => c.startsWith("batch:"));
+        expect(call, "no batch call was recorded").toBeDefined();
+        expect(call, "the duplicate was stripped BEFORE the wire. The server charges PRE-DEDUP, so trimming " +
+            "here hides the cost from the operator — and it is the CLI deciding what the caller " +
+            "pays.").toBe(`batch:${PUMPKIN.id},${PUMPKIN.id},${TRIO.id}`);
+        // Displayed once.
+        const urlCount = h.stderr.filter((l) => l.includes(PUMPKIN.url)).length;
+        expect(urlCount).toBe(1);
+    });
+    it("(e) without --download, ZERO files are written anywhere under the cwd", async () => {
+        const cwd = await tempCwd();
+        const before = await fs.readdir(cwd);
+        const h = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO] }) }, cwd);
+        const code = await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, TRIO.id],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(code).toBe(0);
+        const after = await fs.readdir(cwd);
+        expect(after, "`add` wrote to the creator's project without --download. B35: the platform INFORMS, " +
+            "never PERFORMS — no code, no generation, no writes into creator source.").toEqual(before);
+        expect(h.downloaded, "download() was called without --download").toEqual([]);
+        expect(h.stderr.join("\n")).toContain("Nothing was written.");
+    });
+    it("(f) --download writes once, names the path, then REFUSES with the B37 reason", async () => {
+        const cwd = await tempCwd();
+        const first = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO] }) }, cwd);
+        const firstCode = await assetsAdd(first.deps, {
+            ids: [PUMPKIN.id, TRIO.id],
+            json: false,
+            download: true,
+            force: false,
+        });
+        expect(firstCode).toBe(0);
+        // Every downloaded url is one the SERVER returned — never a string the
+        // caller typed.
+        expect(first.downloaded.sort()).toEqual([PUMPKIN.url, TRIO.url].sort());
+        // The written paths are ANNOUNCED: a state-changing command names its side
+        // effects on the creator's disk.
+        expect(first.stderr.join("\n")).toContain("✓ Wrote");
+        const second = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO] }) }, cwd);
+        const secondCode = await assetsAdd(second.deps, {
+            ids: [PUMPKIN.id, TRIO.id],
+            json: false,
+            download: true,
+            force: false,
+        });
+        expect(secondCode).toBe(1);
+        const screen = second.stderr.join("\n");
+        // It names the B37 REASON, not "file exists". The library never changes a
+        // file at a URL, so a re-download can only ever produce the same bytes —
+        // which is why the refusal is about YOUR edits, not about our bytes.
+        expect(/never changes|already have|your (own )?(copy|edits|file)/i.test(screen), "the overwrite refusal does not name the B37 reason. \"file exists\" tells a creator to " +
+            "pass --force; the real reason is that the library never changes a file at a URL, so " +
+            "the only thing an overwrite can destroy is the creator's OWN edit:\n" + screen).toBe(true);
+    });
+    it("(g) `show` with 2+ ids issues ONE batch call, same as add", async () => {
+        const h = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO] }) });
+        await assetsShow(h.deps, { ids: [PUMPKIN.id, TRIO.id], json: false });
+        expect(h.calls.filter((c) => c.startsWith("batch:"))).toHaveLength(1);
+        expect(h.calls.filter((c) => c === "fetchOne")).toHaveLength(0);
+    });
+    it("a SINGLE id uses the fetch route — batching at 2+ is the rule, not at 1", async () => {
+        const h = harness({ fetchOne: async () => PUMPKIN });
+        await assetsShow(h.deps, { ids: [PUMPKIN.id], json: false });
+        expect(h.calls).toEqual(["fetchOne"]);
+    });
+});

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

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