@vincentt-xr/cli 0.7.0 → 0.9.0

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 {};

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 {};