@indigoai-us/hq-cli 5.345.143 → 5.345.145

package/dist/commands/library-caption.js

@@ -0,0 +1,393 @@
+/**
+ * AI captions for library assets (US-006): `hq library add` captions each
+ * image or video it adds, and `hq library describe <placeholder>` re-runs it.
+ *
+ * Captioning runs on the user's machine through the local Claude Code CLI
+ * (`claude -p`, via the provider-launcher seam). No cloud caption service is
+ * called. Up to 4 frames are written to a private temp dir: an image is used
+ * as-is when it is a png/jpeg/gif/webp under the frame limit, otherwise ffmpeg
+ * re-encodes it to a 1024px JPEG. A video is sampled at up to 4 seek points,
+ * falling back to the first frame. Claude Code reads the frames with its Read
+ * tool only and replies with JSON { description, tags }.
+ *
+ * Captioning never fails an upload. When Claude Code is not installed, not
+ * signed in, errors, or times out, the item gets one plain "skipped" note.
+ */
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { captureProviderRun } from "../lib/provider-launcher.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { formatCloudPlaceholder, parseCloudPlaceholder, } from "@indigoai-us/hq-cloud";
+import { contentTypeFor, mediaKindFor, offloadTimestamp, replacePlaceholderText, } from "./library-add.js";
+import { resolvePlaceholder } from "./storage-offload.js";
+/** Frame limits for a local caption run. */
+export const CAPTION_MAX_FRAMES = 4;
+export const CAPTION_MAX_FRAME_BYTES = 3_750_000;
+export const CAPTION_MAX_TOTAL_BYTES = 4_000_000;
+/** Tags kept on an asset after merging suggestions (placeholders are capped at 4KB). */
+const MAX_ASSET_TAGS = 20;
+const FFMPEG_TIMEOUT_MS = 60_000;
+export const CAPTION_TIMEOUT_MS = 120_000;
+export const LOCAL_CAPTION_PROVIDER = "claude";
+const FRAME_EDGE_PX = 1024;
+export const runLocalClaude = (args, options) => captureProviderRun("claude", args, options);
+/** png / jpeg / gif / webp by magic bytes (formats Claude Code can read). */
+export function isCaptionableImage(bytes) {
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+        return true;
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return true;
+    if (bytes.length >= 6 && /^GIF8[79]a$/.test(bytes.subarray(0, 6).toString("latin1")))
+        return true;
+    return (bytes.length >= 12 &&
+        bytes.subarray(0, 4).toString("latin1") === "RIFF" &&
+        bytes.subarray(8, 12).toString("latin1") === "WEBP");
+}
+/** Keep frames in order while they fit the per-frame and total byte limits. */
+export function fitFrames(frames) {
+    const out = [];
+    let total = 0;
+    for (const frame of frames) {
+        if (out.length >= CAPTION_MAX_FRAMES)
+            break;
+        if (frame.length === 0 || frame.length > CAPTION_MAX_FRAME_BYTES)
+            continue;
+        if (total + frame.length > CAPTION_MAX_TOTAL_BYTES)
+            break;
+        out.push(frame);
+        total += frame.length;
+    }
+    return out;
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function captionPrompt(frameNames, mediaKind, title) {
+    const what = mediaKind === "video" ? `${frameNames.length} frame(s) sampled from a video` : "an image";
+    const files = frameNames.join(", ");
+    return [
+        `Read these files in the current directory: ${files}. They show ${what}${title ? ` titled "${title}"` : ""}.`,
+        "Write a one or two sentence plain description of what it shows, and up to 8 short lowercase tags.",
+        'Reply with only a JSON object: {"description": "...", "tags": ["..."]}',
+    ].join("\n");
+}
+/** Pull { description, tags } out of `claude -p --output-format json` output. */
+export function parseLocalCaption(stdout) {
+    let text = stdout.trim();
+    try {
+        const envelope = JSON.parse(text);
+        if (envelope.is_error === true)
+            return null;
+        if (typeof envelope.result === "string")
+            text = envelope.result;
+    }
+    catch {
+        // Plain text output: look for the JSON object directly.
+    }
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        const body = JSON.parse(text.slice(start, end + 1));
+        const description = typeof body.description === "string" ? body.description.trim() : "";
+        if (!description)
+            return null;
+        const tags = Array.isArray(body.tags)
+            ? body.tags.filter((tag) => typeof tag === "string" && tag.trim().length > 0).map((tag) => tag.trim())
+            : [];
+        return { description, tags };
+    }
+    catch {
+        return null;
+    }
+}
+/** Map a local Claude Code run to an outcome, with one plain note when skipped. */
+export function captionOutcomeFromRun(run) {
+    switch (run.kind) {
+        case "not-installed":
+            return { kind: "skipped", note: "Captioning skipped: Claude Code is not installed on this machine." };
+        case "not-signed-in":
+            return { kind: "skipped", note: "Captioning skipped: Claude Code is not signed in (run claude /login)." };
+        case "timed-out":
+            return { kind: "skipped", note: "Captioning skipped: Claude Code took too long to answer." };
+        case "error":
+            return { kind: "skipped", note: `Captioning skipped: Claude Code exited with an error (code ${run.code}).` };
+        case "ok": {
+            const parsed = parseLocalCaption(run.stdout);
+            if (!parsed)
+                return { kind: "skipped", note: "Captioning skipped: Claude Code's reply was not readable." };
+            return { kind: "captioned", reply: { ...parsed, captionedBy: `local:${LOCAL_CAPTION_PROVIDER}` } };
+        }
+    }
+}
+function frameExtension(bytes) {
+    if (bytes[0] === 0x89)
+        return ".png";
+    if (bytes[0] === 0x47)
+        return ".gif";
+    if (bytes[0] === 0x52)
+        return ".webp";
+    return ".jpg";
+}
+/** Extract frames from `file` and caption them with local Claude Code. Never throws. */
+export async function requestCaption(file, request, deps) {
+    let frames;
+    try {
+        frames = fitFrames(await deps.extractFrames(file, request.mediaKind));
+    }
+    catch (err) {
+        return { kind: "skipped", note: `Captioning skipped: could not read frames (${err.message}).` };
+    }
+    if (frames.length === 0)
+        return { kind: "skipped", note: "Captioning skipped: could not read a frame to describe." };
+    let dir;
+    try {
+        dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "hq-caption-frames-"));
+        const names = [];
+        for (const [i, frame] of frames.entries()) {
+            const name = `frame-${i + 1}${frameExtension(frame)}`;
+            await fs.promises.writeFile(path.join(dir, name), frame, { mode: 0o600 });
+            names.push(name);
+        }
+        const args = [
+            "-p",
+            captionPrompt(names, request.mediaKind, request.title),
+            "--output-format", "json",
+            "--tools", "Read",
+            "--allowedTools", "Read",
+            "--add-dir", dir,
+            "--no-session-persistence",
+            "--strict-mcp-config",
+            "--disable-slash-commands",
+        ];
+        return captionOutcomeFromRun(await deps.runLocal(args, { cwd: dir, timeoutMs: CAPTION_TIMEOUT_MS }));
+    }
+    catch (err) {
+        return { kind: "skipped", note: `Captioning skipped: ${err.message}` };
+    }
+    finally {
+        if (dir)
+            await fs.promises.rm(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Merge a caption into an asset. The user's tags stay first and suggested tags
+ * follow, deduplicated case-insensitively. A description a person wrote is
+ * kept unless `replaceDescription` is set (`hq library describe`).
+ */
+export function mergeCaption(asset, reply, options) {
+    const tags = [...asset.tags];
+    for (const tag of reply.tags) {
+        if (tags.length >= MAX_ASSET_TAGS)
+            break;
+        if (!tags.some((have) => have.toLowerCase() === tag.toLowerCase()))
+            tags.push(tag);
+    }
+    const keepDescription = !options.replaceDescription && asset.captionedBy === "person" && !!asset.description;
+    return {
+        ...asset,
+        tags,
+        ...(keepDescription ? {} : { description: reply.description, captionedBy: reply.captionedBy }),
+        updatedAt: options.updatedAt,
+    };
+}
+/** Re-render a placeholder with a merged caption and replace it atomically. */
+async function writeCaption(file, reply, options) {
+    const placeholder = parseCloudPlaceholder(await fs.promises.readFile(file, "utf8"));
+    if (!placeholder)
+        throw new Error("The placeholder is no longer readable.");
+    const before = placeholder.asset ?? { tags: [], media: { kind: options.mediaKind } };
+    const asset = mergeCaption(before, reply, {
+        replaceDescription: options.replaceDescription,
+        updatedAt: offloadTimestamp(options.now),
+    });
+    await replacePlaceholderText(file, formatCloudPlaceholder({ ...placeholder, asset }));
+    return asset;
+}
+/** Spool a stream to a private temp file; the caller removes `dir`. */
+async function spoolToTemp(stream, name) {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "hq-caption-"));
+    const file = path.join(dir, `source${path.extname(name).toLowerCase()}`);
+    await pipeline(stream, fs.createWriteStream(file, { mode: 0o600 }));
+    return { dir, file };
+}
+/**
+ * Caption one asset `hq library add` just wrote. A URL source is read again
+ * into a temp file (it is never written into the tree); a local file is read
+ * in place. Never throws.
+ */
+export async function captionAddedAsset(request, deps) {
+    let spool;
+    try {
+        let file = request.source.input;
+        if (request.source.kind === "url") {
+            spool = await spoolToTemp((await deps.openSource(request.source)).stream, request.source.name);
+            file = spool.file;
+        }
+        const outcome = await requestCaption(file, request, deps);
+        if (outcome.kind !== "captioned")
+            return { status: outcome.kind, note: outcome.note };
+        await writeCaption(request.placeholderAbs, outcome.reply, {
+            replaceDescription: false,
+            now: deps.now(),
+            mediaKind: request.mediaKind,
+        });
+        return { status: "captioned", captionedBy: outcome.reply.captionedBy };
+    }
+    catch (err) {
+        return { status: "failed", note: `The AI caption was not saved: ${err.message}` };
+    }
+    finally {
+        if (spool)
+            await fs.promises.rm(spool.dir, { recursive: true, force: true });
+    }
+}
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+/** Download a company vault object to a temp file, checking size and sha256. */
+async function downloadAsset(companyUid, key, expected, deps) {
+    const res = await deps.presign({ company: companyUid, key, op: "get" });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw new Error(`Could not get a download URL: ${asString(body.error) ?? `HTTP ${res.status}`}`);
+    }
+    const row = (Array.isArray(body.results) ? body.results[0] : body);
+    const url = asString(row?.url);
+    if (!url)
+        throw new Error(`Could not get a download URL: ${asString(row?.error) ?? "no URL returned"}`);
+    const spool = await spoolToTemp(await deps.download(url), expected.name);
+    try {
+        const bytes = await fs.promises.readFile(spool.file);
+        const sha256 = crypto.createHash("sha256").update(bytes).digest("hex");
+        if (bytes.length !== expected.size || (expected.sha256 !== null && sha256 !== expected.sha256)) {
+            throw new Error("The downloaded file does not match the placeholder's size and sha256.");
+        }
+        return spool;
+    }
+    catch (err) {
+        await fs.promises.rm(spool.dir, { recursive: true, force: true });
+        throw err;
+    }
+}
+/**
+ * `hq library describe <placeholder>`: download the asset, caption it again,
+ * and replace the description and captioned-by. Suggested tags are added to
+ * the existing tags. A caption that does not succeed is an error here.
+ */
+export async function runLibraryDescribe(target, deps) {
+    const file = resolvePlaceholder(deps.hqRoot, target);
+    const placeholderPath = toPosix(path.relative(fs.realpathSync(path.resolve(deps.hqRoot)), file));
+    const placeholder = parseCloudPlaceholder(await fs.promises.readFile(file, "utf8"));
+    if (!placeholder || placeholder.vault !== "company") {
+        throw new Error(`'${placeholderPath}' is not a company library placeholder.`);
+    }
+    if (placeholder.orphaned)
+        throw new Error(`'${placeholderPath}' points at a file that was deleted from the vault.`);
+    const slug = /^companies\/([^/]+)\//.exec(placeholderPath)?.[1];
+    if (!slug)
+        throw new Error(`'${placeholderPath}' is not inside companies/<slug>/.`);
+    const name = path.posix.basename(placeholder.path);
+    const kind = placeholder.asset?.media?.kind ?? mediaKindFor(contentTypeFor(name));
+    if (kind === "other")
+        throw new Error(`'${placeholderPath}' is not an image or video, so it cannot be described.`);
+    const company = await deps.resolveCompany(slug);
+    const spool = await downloadAsset(company.uid, placeholder.key, { size: placeholder.size, sha256: placeholder.sha256, name }, deps);
+    try {
+        const outcome = await requestCaption(spool.file, { mediaKind: kind, title: placeholder.asset?.title }, deps);
+        if (outcome.kind !== "captioned")
+            throw new Error(outcome.note);
+        const asset = await writeCaption(file, outcome.reply, { replaceDescription: true, now: deps.now(), mediaKind: kind });
+        return {
+            placeholderPath,
+            description: asset.description ?? outcome.reply.description,
+            tags: asset.tags,
+            captionedBy: outcome.reply.captionedBy,
+        };
+    }
+    finally {
+        await fs.promises.rm(spool.dir, { recursive: true, force: true });
+    }
+}
+const runTool = (command, args) => new Promise((resolve, reject) => {
+    execFile(command, args, { timeout: FFMPEG_TIMEOUT_MS, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+        if (err) {
+            const code = err.code;
+            reject(code === "ENOENT" ? new Error(`${command} is not installed`) : err);
+            return;
+        }
+        resolve({ stdout: String(stdout) });
+    });
+});
+const SCALE_FILTER = `scale=${FRAME_EDGE_PX}:${FRAME_EDGE_PX}:force_original_aspect_ratio=decrease`;
+/** One JPEG frame of `file` at `seconds` (fast seek: the nearest keyframe). */
+async function jpegFrame(run, file, out, seconds) {
+    const seek = seconds !== undefined && seconds > 0 ? ["-ss", seconds.toFixed(3)] : [];
+    try {
+        await run("ffmpeg", ["-v", "error", "-y", ...seek, "-i", file, "-frames:v", "1", "-vf", SCALE_FILTER, "-q:v", "4", out]);
+        const bytes = await fs.promises.readFile(out);
+        return bytes.length > 0 ? bytes : null;
+    }
+    catch (err) {
+        if (err.message.endsWith("is not installed"))
+            throw err;
+        return null;
+    }
+}
+/** Seek points at 10%, 35%, 60% and 85% of a known duration. */
+export function videoSeekPoints(durationSeconds) {
+    if (durationSeconds === null || !Number.isFinite(durationSeconds) || durationSeconds <= 0)
+        return [];
+    return [0.1, 0.35, 0.6, 0.85].map((share) => durationSeconds * share);
+}
+/** Frames for captioning: the image itself when it fits, otherwise ffmpeg JPEGs. */
+export async function extractCaptionFrames(file, mediaKind, run = runTool) {
+    if (mediaKind === "image") {
+        const stat = await fs.promises.stat(file);
+        if (stat.size <= CAPTION_MAX_FRAME_BYTES) {
+            const bytes = await fs.promises.readFile(file);
+            if (isCaptionableImage(bytes))
+                return [bytes];
+        }
+    }
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "hq-frames-"));
+    try {
+        if (mediaKind === "image") {
+            const frame = await jpegFrame(run, file, path.join(dir, "image.jpg"));
+            return frame ? [frame] : [];
+        }
+        let duration = null;
+        try {
+            const { stdout } = await run("ffprobe", [
+                "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", file,
+            ]);
+            const parsed = Number.parseFloat(stdout.trim());
+            duration = Number.isFinite(parsed) ? parsed : null;
+        }
+        catch {
+            // No duration: fall back to the first frame.
+        }
+        const frames = [];
+        const points = videoSeekPoints(duration);
+        for (const [i, seconds] of points.entries()) {
+            const frame = await jpegFrame(run, file, path.join(dir, `frame-${i}.jpg`), seconds);
+            if (frame)
+                frames.push(frame);
+        }
+        if (frames.length === 0) {
+            const first = await jpegFrame(run, file, path.join(dir, "first.jpg"));
+            if (first)
+                frames.push(first);
+        }
+        return frames;
+    }
+    finally {
+        await fs.promises.rm(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=library-caption.js.map

package/dist/commands/library-link.d.ts

@@ -0,0 +1,32 @@
+/** Default and cap for --expires, in minutes (hq-pro caps presign at 3600 s). */
+export declare const LIBRARY_LINK_DEFAULT_MINUTES = 15;
+export declare const LIBRARY_LINK_MAX_MINUTES = 60;
+export interface LibraryLinkOptions {
+    /** cmp_ uid, or a slug on a Cognito session. */
+    company?: string;
+    /** Link lifetime in minutes (1..60). */
+    expiresMinutes?: number;
+}
+export interface LibraryLinkDeps {
+    /** HQ root; only called for a placeholder target. */
+    hqRoot: () => string;
+    /** True when the call runs under HQ_API_KEY (slugs cannot be resolved). */
+    apiKey: boolean;
+    /** Company ref (slug or uid, or undefined for the default) → cmp_ uid. */
+    resolveCompany: (ref: string | undefined) => Promise<string>;
+    /** POST /v1/files/presign. */
+    presign: (body: Record<string, unknown>) => Promise<Response>;
+}
+export interface LibraryLinkResult {
+    key: string;
+    company: string;
+    placeholderPath?: string;
+    url: string;
+    expiresIn: number;
+    expiresAt?: string;
+}
+/** Validate --expires minutes; returns seconds for the presign body. */
+export declare function linkExpirySeconds(minutes: number | undefined): number;
+export declare function isVaultKey(target: string): boolean;
+export declare function runLibraryLink(target: string, options: LibraryLinkOptions, deps: LibraryLinkDeps): Promise<LibraryLinkResult>;
+//# sourceMappingURL=library-link.d.ts.map

package/dist/commands/library-link.js

@@ -0,0 +1,95 @@
+/**
+ * `hq library link <placeholder|vault-key>` (US-009) — mint a short-lived
+ * download link for a library asset, for handing to a tool that fetches by URL
+ * (for example the Meta Marketing API's adimages / advideos upload by URL).
+ *
+ * Runs on a Cognito session or on an `HQ_API_KEY` with `files:read` (the
+ * library-agent preset). Under a key, vaultApiFetch rewrites /v1/files/presign
+ * to /v1/keys/files/presign; the key is company-bound, so the company comes
+ * from --company <cmp_uid>, HQ_COMPANY_UID, or the key's own membership.
+ *
+ * Wire contract (hq-pro files-presign):
+ *   POST /v1/files/presign
+ *   body  { company: <cmp_uid>, key, op: "get", expiresIn: <seconds> }
+ *   200   { results: [{ key, op, url, expiresIn, expiresAt } | { key, op, error, code }] }
+ *
+ * The URL is a bearer credential until it expires. It goes to stdout only and
+ * never into an error message.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseCloudPlaceholder } from "@indigoai-us/hq-cloud";
+import { resolvePlaceholder } from "./storage-offload.js";
+/** Default and cap for --expires, in minutes (hq-pro caps presign at 3600 s). */
+export const LIBRARY_LINK_DEFAULT_MINUTES = 15;
+export const LIBRARY_LINK_MAX_MINUTES = 60;
+/** Vault keys written by `hq library add` / `hq storage offload`. */
+const VAULT_KEY_PREFIX = ".hq-offload/";
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** Validate --expires minutes; returns seconds for the presign body. */
+export function linkExpirySeconds(minutes) {
+    const value = minutes ?? LIBRARY_LINK_DEFAULT_MINUTES;
+    if (!Number.isInteger(value) || value < 1 || value > LIBRARY_LINK_MAX_MINUTES) {
+        throw new Error(`--expires must be a whole number of minutes from 1 to ${LIBRARY_LINK_MAX_MINUTES}.`);
+    }
+    return value * 60;
+}
+export function isVaultKey(target) {
+    return target.startsWith(VAULT_KEY_PREFIX);
+}
+export async function runLibraryLink(target, options, deps) {
+    const expiresIn = linkExpirySeconds(options.expiresMinutes);
+    let key;
+    let placeholderPath;
+    let companyRef = options.company;
+    if (isVaultKey(target)) {
+        key = target;
+    }
+    else {
+        const hqRoot = deps.hqRoot();
+        const file = resolvePlaceholder(hqRoot, target);
+        placeholderPath = path
+            .relative(fs.realpathSync(path.resolve(hqRoot)), file)
+            .split(path.sep)
+            .join("/");
+        const placeholder = parseCloudPlaceholder(await fs.promises.readFile(file, "utf8"));
+        if (!placeholder || placeholder.vault !== "company") {
+            throw new Error(`'${placeholderPath}' is not a company library placeholder.`);
+        }
+        if (placeholder.orphaned) {
+            throw new Error(`'${placeholderPath}' points at a file that was deleted from the vault.`);
+        }
+        key = placeholder.key;
+        // On a session the placeholder's companies/<slug>/ names the company. A
+        // key is company-bound and cannot resolve slugs, so it uses its own.
+        if (companyRef === undefined && !deps.apiKey) {
+            companyRef = /^companies\/([^/]+)\//.exec(placeholderPath)?.[1];
+            if (!companyRef)
+                throw new Error(`'${placeholderPath}' is not inside companies/<slug>/; pass --company.`);
+        }
+    }
+    const company = await deps.resolveCompany(companyRef);
+    const res = await deps.presign({ company, key, op: "get", expiresIn });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw new Error(`Could not mint a download link: ${asString(body.error) ?? asString(body.message) ?? `HTTP ${res.status}`}`);
+    }
+    const row = (Array.isArray(body.results) ? body.results[0] : undefined);
+    const url = asString(row?.url);
+    if (!url) {
+        throw new Error(`Could not mint a download link for ${key}: ${asString(row?.error) ?? "no URL returned"}`);
+    }
+    return {
+        key,
+        company,
+        ...(placeholderPath ? { placeholderPath } : {}),
+        url,
+        expiresIn: typeof row?.expiresIn === "number" ? row.expiresIn : expiresIn,
+        ...(asString(row?.expiresAt) ?? asString(body.expiresAt)
+            ? { expiresAt: asString(row?.expiresAt) ?? asString(body.expiresAt) }
+            : {}),
+    };
+}
+//# sourceMappingURL=library-link.js.map

package/dist/commands/library.d.ts

@@ -0,0 +1,72 @@
+import { Command } from "commander";
+import { type CloudPlaceholder } from "@indigoai-us/hq-cloud";
+import { type SearchCollection } from "../lib/search-index/index.js";
+import { type LibraryAddResult } from "./library-add.js";
+/** Mirrors hq-pro's MAX_ASSET_SEARCH_TAGS / tag length bound. */
+export declare const MAX_LIBRARY_SEARCH_TAGS = 20;
+export interface LibrarySearchOptions {
+    tags: string[];
+    company?: string;
+    count?: number;
+}
+export interface LibraryAssetHit {
+    placeholderPath: string;
+    originalPath?: string;
+    title: string;
+    tags: string[];
+    mediaKind?: string;
+    vaultKey?: string;
+    snippet?: string;
+}
+export interface LibrarySearchResult {
+    source: "cloud" | "local";
+    /** Set on a local result: the transport code that forced the fallback. */
+    fallbackReason?: string;
+    results: LibraryAssetHit[];
+}
+export interface LibrarySearchDeps {
+    getToken: () => Promise<string>;
+    post: (token: string, body: Record<string, unknown>) => Promise<Response>;
+    searchLocal: (query: string, options: LibrarySearchOptions) => LibraryAssetHit[];
+}
+/** Split repeatable / comma-listed `--tag` values into a validated tag list. */
+export declare function normalizeTags(values: readonly string[]): string[];
+/** Case-insensitive: every requested tag must be on the asset (hq-pro assetHasTags). */
+export declare function hasAllTags(assetTags: readonly string[], wanted: readonly string[]): boolean;
+/** Map one /v1/search result to a hit; null when it carries no asset metadata. */
+export declare function hitFromCloudResult(result: unknown): LibraryAssetHit | null;
+/**
+ * Testable core. Cloud search first; a transport failure (offline, DNS, reset)
+ * falls back to the local qmd index. HTTP errors are not a fallback: a 401 or
+ * 400 is reported, since the local index cannot answer for the vault.
+ */
+export declare function runLibrarySearch(query: string, options: LibrarySearchOptions, deps: LibrarySearchDeps): Promise<LibrarySearchResult>;
+/** A local hit, or null for a placeholder that is not a company library asset. */
+export declare function hitFromPlaceholder(placeholder: CloudPlaceholder | null, tags: readonly string[], snippet?: string): LibraryAssetHit | null;
+/** Asset collections to search, narrowed to one company when asked. */
+export declare function assetCollections(collections: readonly SearchCollection[], company?: string): SearchCollection[];
+export interface LocalSearchEnv {
+    collections: readonly SearchCollection[];
+    runQmd: (args: string[]) => {
+        stdout: string;
+        stderr: string;
+    };
+    readFile: (file: string) => string | null;
+    listPlaceholders: (directory: string) => string[];
+}
+/**
+ * Search the local qmd `<co>-assets` collections. With a query, qmd ranks
+ * hits and `--full` returns each placeholder's text (qmd normalises file
+ * paths, so the text, not the path, is the reliable record). Without a query
+ * (tags only), the collection directories are listed and filtered by tag.
+ */
+export declare function searchLocalAssets(query: string, options: LibrarySearchOptions, env: LocalSearchEnv): LibraryAssetHit[];
+/**
+ * `hq library ls`: every company library placeholder under `directory`
+ * (HQ-relative paths), filtered by tag. Sorted by placeholder path.
+ */
+export declare function listLibraryAssets(hqRoot: string, directory: string, tags: readonly string[], env?: Pick<LocalSearchEnv, "readFile" | "listPlaceholders">): LibraryAssetHit[];
+export declare function formatLibraryResult(result: LibrarySearchResult): string;
+export declare function formatLibraryAddResult(result: LibraryAddResult): string;
+export declare function registerLibraryCommand(program: Command): void;
+//# sourceMappingURL=library.d.ts.map