@vincentt-xr/cli 0.7.0 → 0.9.0

package/dist/lib/version.d.ts

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

package/dist/lib/version.js

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

package/dist/library/assetsCommand.d.ts

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

package/dist/library/assetsCommand.js

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

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[];