@indigoai-us/hq-cli 5.345.153 → 5.345.155

package/dist/commands/library-add.js

@@ -29,10 +29,10 @@ import https from "node:https";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { formatCloudAssetBlock, formatCloudPlaceholder, isCoveredByAny, parseCloudPlaceholder, resolvePullScope, } from "@indigoai-us/hq-cloud";
-import { PLACEHOLDER_SUFFIX, companyOffloadKey, containedPath, durablePlaceholderFs, renderPointer, resolvePlaceholder, } from "./storage-offload.js";
+import { CONTENT_SHA256_METADATA_KEY, PLACEHOLDER_SUFFIX, companyOffloadKey, containedPath, durablePlaceholderFs, renderPointer, resolvePlaceholder, } from "./storage-offload.js";
 import { formatPlanGateError, formatUpgradeRefusal, planGateErrorFromResponse, } from "../utils/plan-gate-error.js";
 /** Metadata key hq-pro binds to `checksumSha256` (sync's content hash). */
-const CONTENT_SHA256_META_KEY = "hq-content-sha256";
+const CONTENT_SHA256_META_KEY = CONTENT_SHA256_METADATA_KEY;
 const MEDIA_TYPES = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -42,6 +42,7 @@ const MEDIA_TYPES = {
     ".svg": "image/svg+xml",
     ".avif": "image/avif",
     ".heic": "image/heic",
+    ".heif": "image/heif",
     ".mp4": "video/mp4",
     ".mov": "video/quicktime",
     ".webm": "video/webm",
@@ -136,6 +137,41 @@ export function resolveLibraryDir(hqRoot, options) {
     }
     return { slug, dirRel, dirAbs };
 }
+/**
+ * The company and library folder for `add`. `--company` may be a slug or a
+ * cmp_ uid; the folder always uses the company's slug, so a uid never becomes
+ * a companies/cmp_…/ folder. A slug that disagrees with `--to` is refused
+ * before any lookup, as it always was.
+ */
+async function resolveLibraryTarget(options, deps) {
+    const companyIsUid = options.company !== undefined && isCompanyUid(options.company);
+    if (!companyIsUid)
+        resolveLibraryDir(deps.hqRoot, options);
+    const folderSlug = options.to === undefined ? undefined : resolveLibraryDir(deps.hqRoot, { to: options.to }).slug;
+    const company = await deps.resolveCompany((options.company ?? folderSlug), folderSlug);
+    if (isCompanyUid(company.slug)) {
+        throw new Error(`No company folder is known for ${company.uid}; library folders are companies/<slug>/. ` +
+            "Pass --company <slug> or --to companies/<slug>/<dir>.");
+    }
+    if (folderSlug !== undefined && company.slug !== folderSlug) {
+        throw new Error(`--to is inside companies/${folderSlug}/, but --company ${options.company} is ${company.slug}.`);
+    }
+    return { company, ...resolveLibraryDir(deps.hqRoot, { company: company.slug, to: options.to }) };
+}
+function isCompanyUid(ref) {
+    return ref.startsWith("cmp_");
+}
+/**
+ * Capabilities an API key lacks, from hq-pro's keyed-route 403
+ * (`{ error, granted, missing }`). Empty for any other response.
+ */
+function missingKeyCapabilities(status, body) {
+    if (status !== 403)
+        return [];
+    if (typeof body.missing === "string" && body.missing)
+        return [body.missing];
+    return Array.isArray(body.missing) ? body.missing.filter((c) => typeof c === "string") : [];
+}
 async function hashStream(stream) {
     const hash = crypto.createHash("sha256");
     let size = 0;
@@ -212,8 +248,7 @@ async function uploadVerified(source, digest, grant, deps) {
 export async function runLibraryAdd(inputs, options, deps) {
     if (inputs.length === 0)
         throw new Error("Pass at least one file or URL.");
-    const { slug, dirRel, dirAbs } = resolveLibraryDir(deps.hqRoot, options);
-    const company = await deps.resolveCompany(slug);
+    const { company, slug, dirRel, dirAbs } = await resolveLibraryTarget(options, deps);
     const items = [];
     const planned = [];
     const claimed = new Set();
@@ -268,9 +303,13 @@ export async function runLibraryAdd(inputs, options, deps) {
     }
     const body = (await response.json().catch(() => ({})));
     if (!response.ok) {
-        const msg = typeof body.error === "string" ? body.error : `HTTP ${response.status}`;
+        const missing = missingKeyCapabilities(response.status, body);
+        const msg = missing.length > 0
+            ? `This API key cannot upload (missing ${missing.join(", ")}). Use a key made with ` +
+                "`hq api-keys create --preset library-agent --allow-upload`, or unset HQ_API_KEY and run signed in."
+            : `Could not get an upload URL: ${typeof body.error === "string" ? body.error : `HTTP ${response.status}`}`;
         for (const p of planned)
-            p.item.error = `Could not get an upload URL: ${msg}`;
+            p.item.error = msg;
         return { company: slug, items };
     }
     const rows = Array.isArray(body.results) ? body.results : [];

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

@@ -105,8 +105,45 @@ export declare function runLibraryDescribe(target: string, deps: LibraryDescribe
 export type RunTool = (command: string, args: string[]) => Promise<{
     stdout: string;
 }>;
+/**
+ * HEIC / HEIF by content, or by a .heic/.heif/.hif name (any case) when the
+ * bytes are not a format Claude Code reads directly. AVIF (also a HEIF
+ * container) is not included.
+ */
+export declare function isHeifImage(head: Buffer, name: string): boolean;
+/** Width and height from a JPEG's start-of-frame marker, or null. */
+export declare function jpegDimensions(bytes: Buffer): {
+    width: number;
+    height: number;
+} | null;
+/** A decoded frame is a non-empty JPEG within the frame byte and edge limits. */
+export declare function isUsableJpegFrame(bytes: Buffer): boolean;
+/** The EXIF orientation (1-8) in a JPEG's APP1 segment, or 1 when there is none. */
+export declare function jpegExifOrientation(bytes: Buffer): number;
+/** The JPEG without its APP1 (EXIF and XMP) segments. */
+export declare function stripJpegApp1(bytes: Buffer): Buffer;
+interface TileGrid {
+    width: number;
+    height: number;
+    left: number;
+    top: number;
+    tiles: Array<{
+        stream: number;
+        x: number;
+        y: number;
+    }>;
+}
+/**
+ * The primary tile grid from `ffprobe -show_stream_groups -of json`: the
+ * "Tile Grid" group marked default, else the first one. Null when the output
+ * does not have the expected shape (older ffmpeg has no tile grid groups).
+ */
+export declare function primaryTileGrid(ffprobeJson: string): TileGrid | null;
+/** ffmpeg filter graph that assembles a tile grid, crops it and scales it to the frame size. */
+export declare function tileGridFilter(grid: TileGrid): string;
 /** Seek points at 10%, 35%, 60% and 85% of a known duration. */
 export declare function videoSeekPoints(durationSeconds: number | null): number[];
 /** Frames for captioning: the image itself when it fits, otherwise ffmpeg JPEGs. */
-export declare function extractCaptionFrames(file: string, mediaKind: CaptionMediaKind, run?: RunTool): Promise<Buffer[]>;
+export declare function extractCaptionFrames(file: string, mediaKind: CaptionMediaKind, run?: RunTool, platform?: NodeJS.Platform): Promise<Buffer[]>;
+export {};
 //# sourceMappingURL=library-caption.d.ts.map

package/dist/commands/library-caption.js

@@ -5,8 +5,11 @@
  * 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,
+ * as-is when it is a png/jpeg/gif/webp under the frame limit, otherwise it is
+ * re-encoded to a 1024px JPEG. A HEIC/HEIF is decoded to its primary image
+ * with sips (macOS), ImageMagick, or ffmpeg's tile grid; any other image, and
+ * a HEIC none of those can decode, goes through ffmpeg's default stream. 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 }.
  *
@@ -339,6 +342,297 @@ async function jpegFrame(run, file, out, seconds) {
         return null;
     }
 }
+// ── HEIC / HEIF primary image ───────────────────────────────────────────────
+/** ftyp brands of HEVC-coded HEIF images (HEIC) and generic HEIF image files. */
+const HEIF_BRANDS = new Set(["heic", "heix", "heim", "heis", "hevc", "hevx", "hevm", "hevs", "mif1", "msf1", "mif2"]);
+/** HEVC-specific brands: these mark a file as HEIC even when it also lists AVIF brands. */
+const HEVC_BRANDS = new Set(["heic", "heix", "heim", "heis", "hevc", "hevx", "hevm", "hevs"]);
+const AVIF_BRANDS = new Set(["avif", "avis"]);
+const HEIF_EXTENSIONS = new Set([".heic", ".heif", ".hif"]);
+/** Bytes read to sniff the ftyp box. */
+const HEIF_SNIFF_BYTES = 64;
+/** A decoded frame smaller than this on either edge is not a usable picture. */
+const MIN_FRAME_EDGE_PX = 16;
+/** The brands in a leading ISO BMFF `ftyp` box, or null when there is none. */
+function ftypBrands(head) {
+    if (head.length < 16 || head.subarray(4, 8).toString("latin1") !== "ftyp")
+        return null;
+    const boxSize = head.readUInt32BE(0);
+    const end = Math.min(head.length, boxSize >= 16 ? boxSize : head.length);
+    const brands = [head.subarray(8, 12).toString("latin1")];
+    for (let at = 16; at + 4 <= end; at += 4)
+        brands.push(head.subarray(at, at + 4).toString("latin1"));
+    return brands;
+}
+/**
+ * HEIC / HEIF by content, or by a .heic/.heif/.hif name (any case) when the
+ * bytes are not a format Claude Code reads directly. AVIF (also a HEIF
+ * container) is not included.
+ */
+export function isHeifImage(head, name) {
+    const brands = ftypBrands(head);
+    if (brands) {
+        if (brands.some((brand) => HEVC_BRANDS.has(brand)))
+            return true;
+        if (brands.some((brand) => AVIF_BRANDS.has(brand)))
+            return false;
+        if (brands.some((brand) => HEIF_BRANDS.has(brand)))
+            return true;
+    }
+    return HEIF_EXTENSIONS.has(path.extname(name).toLowerCase()) && !isCaptionableImage(head);
+}
+/** Width and height from a JPEG's start-of-frame marker, or null. */
+export function jpegDimensions(bytes) {
+    if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return null;
+    let at = 2;
+    while (at + 4 <= bytes.length) {
+        if (bytes[at] !== 0xff)
+            return null;
+        const marker = bytes[at + 1];
+        if (marker === 0xff) {
+            at += 1;
+            continue;
+        }
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            at += 2;
+            continue;
+        }
+        if (marker === 0xd9 || marker === 0xda)
+            return null;
+        const length = bytes.readUInt16BE(at + 2);
+        if (length < 2)
+            return null;
+        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isSof) {
+            if (at + 9 > bytes.length)
+                return null;
+            return { height: bytes.readUInt16BE(at + 5), width: bytes.readUInt16BE(at + 7) };
+        }
+        at += 2 + length;
+    }
+    return null;
+}
+/** A decoded frame is a non-empty JPEG within the frame byte and edge limits. */
+export function isUsableJpegFrame(bytes) {
+    if (bytes.length === 0 || bytes.length > CAPTION_MAX_FRAME_BYTES)
+        return false;
+    if (!(bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff))
+        return false;
+    const size = jpegDimensions(bytes);
+    if (!size)
+        return false;
+    const edges = [size.width, size.height];
+    return edges.every((edge) => edge >= MIN_FRAME_EDGE_PX && edge <= FRAME_EDGE_PX);
+}
+/** Run one decoder that writes `out`, and keep its output only when it is a usable JPEG. */
+async function decodedFrame(run, command, args, out) {
+    try {
+        await fs.promises.rm(out, { force: true });
+        await run(command, args);
+        const bytes = await fs.promises.readFile(out);
+        return isUsableJpegFrame(bytes) ? bytes : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The EXIF orientation (1-8) in a JPEG's APP1 segment, or 1 when there is none. */
+export function jpegExifOrientation(bytes) {
+    for (const segment of jpegSegments(bytes)) {
+        if (segment.marker !== 0xe1)
+            continue;
+        const body = bytes.subarray(segment.start + 4, segment.end);
+        if (body.length < 14 || body.subarray(0, 6).toString("latin1") !== "Exif\0\0")
+            continue;
+        const tiff = body.subarray(6);
+        const order = tiff.subarray(0, 2).toString("latin1");
+        if (order !== "II" && order !== "MM")
+            continue;
+        const u16 = (at) => (order === "II" ? tiff.readUInt16LE(at) : tiff.readUInt16BE(at));
+        const u32 = (at) => (order === "II" ? tiff.readUInt32LE(at) : tiff.readUInt32BE(at));
+        const ifd = u32(4);
+        if (ifd + 2 > tiff.length)
+            continue;
+        const count = u16(ifd);
+        for (let i = 0; i < count; i++) {
+            const entry = ifd + 2 + i * 12;
+            if (entry + 12 > tiff.length)
+                break;
+            if (u16(entry) === 0x0112) {
+                const value = u16(entry + 8);
+                return value >= 1 && value <= 8 ? value : 1;
+            }
+        }
+    }
+    return 1;
+}
+/** Marker segments before the scan: `start` is the 0xFF byte, `end` is past the segment. */
+function jpegSegments(bytes) {
+    const segments = [];
+    if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return segments;
+    let at = 2;
+    while (at + 4 <= bytes.length && bytes[at] === 0xff) {
+        const marker = bytes[at + 1];
+        if (marker === 0xda || marker === 0xd9)
+            break;
+        const length = bytes.readUInt16BE(at + 2);
+        if (length < 2 || at + 2 + length > bytes.length)
+            break;
+        segments.push({ marker, start: at, end: at + 2 + length });
+        at += 2 + length;
+    }
+    return segments;
+}
+/** The JPEG without its APP1 (EXIF and XMP) segments. */
+export function stripJpegApp1(bytes) {
+    const drop = jpegSegments(bytes).filter((segment) => segment.marker === 0xe1);
+    if (drop.length === 0)
+        return bytes;
+    const parts = [];
+    let at = 0;
+    for (const segment of drop) {
+        parts.push(bytes.subarray(at, segment.start));
+        at = segment.end;
+    }
+    parts.push(bytes.subarray(at));
+    return Buffer.concat(parts);
+}
+/** sips steps that turn stored pixels upright for each EXIF orientation (rotations are clockwise). */
+const SIPS_UPRIGHT = {
+    2: [["-f", "horizontal"]],
+    3: [["-r", "180"]],
+    4: [["-f", "vertical"]],
+    5: [["-r", "90"], ["-f", "horizontal"]],
+    6: [["-r", "90"]],
+    7: [["-r", "90"], ["-f", "vertical"]],
+    8: [["-r", "270"]],
+};
+/**
+ * sips keeps the stored pixel order and copies the EXIF orientation, so a
+ * HEIC shot upside down or sideways decodes rotated. Rotate the pixels
+ * upright with sips and drop the EXIF/XMP segments so nothing rotates them
+ * again. When a rotation step fails, the frame is kept with its EXIF intact.
+ */
+async function uprightSipsFrame(run, frame, out) {
+    const steps = SIPS_UPRIGHT[jpegExifOrientation(frame)];
+    if (!steps)
+        return stripJpegApp1(frame);
+    try {
+        for (const step of steps)
+            await run("sips", [...step, out]);
+        const rotated = await fs.promises.readFile(out);
+        const upright = stripJpegApp1(rotated);
+        return isUsableJpegFrame(upright) ? upright : frame;
+    }
+    catch {
+        return frame;
+    }
+}
+function nonNegativeInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+/**
+ * The primary tile grid from `ffprobe -show_stream_groups -of json`: the
+ * "Tile Grid" group marked default, else the first one. Null when the output
+ * does not have the expected shape (older ffmpeg has no tile grid groups).
+ */
+export function primaryTileGrid(ffprobeJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(ffprobeJson);
+    }
+    catch {
+        return null;
+    }
+    const groups = parsed.stream_groups;
+    if (!Array.isArray(groups))
+        return null;
+    const grids = groups.filter((g) => !!g && g.type === "Tile Grid");
+    const group = grids.find((g) => g.disposition?.default === 1) ?? grids[0];
+    const component = Array.isArray(group?.components) ? group.components[0] : undefined;
+    if (!component || !Array.isArray(component.subcomponents))
+        return null;
+    const width = nonNegativeInt(component.width);
+    const height = nonNegativeInt(component.height);
+    const left = nonNegativeInt(component.horizontal_offset) ?? 0;
+    const top = nonNegativeInt(component.vertical_offset) ?? 0;
+    if (!width || !height)
+        return null;
+    const tiles = [];
+    for (const sub of component.subcomponents) {
+        const stream = nonNegativeInt(sub?.stream_index);
+        const x = nonNegativeInt(sub?.tile_horizontal_offset);
+        const y = nonNegativeInt(sub?.tile_vertical_offset);
+        if (stream === null || x === null || y === null)
+            return null;
+        tiles.push({ stream, x, y });
+    }
+    return tiles.length > 0 ? { width, height, left, top, tiles } : null;
+}
+/** ffmpeg filter graph that assembles a tile grid, crops it and scales it to the frame size. */
+export function tileGridFilter(grid) {
+    const inputs = grid.tiles.map((tile) => `[0:${tile.stream}]`).join("");
+    const crop = `crop=${grid.width}:${grid.height}:${grid.left}:${grid.top}`;
+    if (grid.tiles.length === 1)
+        return `${inputs}${crop},${SCALE_FILTER}[frame]`;
+    const layout = grid.tiles.map((tile) => `${tile.x}_${tile.y}`).join("|");
+    return `${inputs}xstack=inputs=${grid.tiles.length}:layout=${layout}:fill=black,${crop},${SCALE_FILTER}[frame]`;
+}
+/**
+ * The primary image of a HEIC / HEIF as a 1024px JPEG. ffmpeg's default video
+ * stream in an iPhone HEIC is a single tile or, for Portrait photos, the
+ * depth/segmentation matte, so the primary image is decoded with sips
+ * (macOS), then ImageMagick (libheif), then by assembling ffmpeg's primary
+ * tile grid. Null when none of them produced a usable frame.
+ */
+async function heifPrimaryFrame(run, file, dir, platform) {
+    const out = path.join(dir, "primary.jpg");
+    const edge = String(FRAME_EDGE_PX);
+    if (platform === "darwin") {
+        const frame = await decodedFrame(run, "sips", ["-s", "format", "jpeg", "-s", "formatOptions", "80", "-Z", edge, file, "--out", out], out);
+        if (frame)
+            return uprightSipsFrame(run, frame, out);
+    }
+    // The explicit heic: coder and [0] make ImageMagick decode only the primary image as HEIF.
+    const imArgs = [`heic:${file}[0]`, "-auto-orient", "-resize", `${edge}x${edge}>`, "-quality", "80", out];
+    const magick = await decodedFrame(run, "magick", imArgs, out);
+    if (magick)
+        return magick;
+    // On Windows `convert` is the system disk-conversion tool, not ImageMagick.
+    if (platform !== "win32") {
+        const convert = await decodedFrame(run, "convert", imArgs, out);
+        if (convert)
+            return convert;
+    }
+    try {
+        const { stdout } = await run("ffprobe", ["-v", "error", "-show_stream_groups", "-of", "json", file]);
+        const grid = primaryTileGrid(stdout);
+        if (grid) {
+            const args = ["-v", "error", "-y", "-i", file, "-filter_complex", tileGridFilter(grid), "-map", "[frame]",
+                "-frames:v", "1", "-q:v", "4", "-update", "1", out];
+            const frame = await decodedFrame(run, "ffmpeg", args, out);
+            if (frame)
+                return frame;
+        }
+    }
+    catch {
+        // No ffprobe, or one without stream groups: fall back to ffmpeg's default stream.
+    }
+    return null;
+}
+async function readHead(file) {
+    const handle = await fs.promises.open(file, "r");
+    try {
+        const head = Buffer.alloc(HEIF_SNIFF_BYTES);
+        const { bytesRead } = await handle.read(head, 0, HEIF_SNIFF_BYTES, 0);
+        return head.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
 /** Seek points at 10%, 35%, 60% and 85% of a known duration. */
 export function videoSeekPoints(durationSeconds) {
     if (durationSeconds === null || !Number.isFinite(durationSeconds) || durationSeconds <= 0)
@@ -346,7 +640,8 @@ export function videoSeekPoints(durationSeconds) {
     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) {
+export async function extractCaptionFrames(file, mediaKind, run = runTool, platform = process.platform) {
+    let heif = false;
     if (mediaKind === "image") {
         const stat = await fs.promises.stat(file);
         if (stat.size <= CAPTION_MAX_FRAME_BYTES) {
@@ -354,9 +649,15 @@ export async function extractCaptionFrames(file, mediaKind, run = runTool) {
             if (isCaptionableImage(bytes))
                 return [bytes];
         }
+        heif = isHeifImage(await readHead(file), file);
     }
     const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "hq-frames-"));
     try {
+        if (heif) {
+            const primary = await heifPrimaryFrame(run, file, dir, platform);
+            if (primary)
+                return [primary];
+        }
         if (mediaKind === "image") {
             const frame = await jpegFrame(run, file, path.join(dir, "image.jpg"));
             return frame ? [frame] : [];

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

@@ -10,10 +10,14 @@ export interface LibraryLinkOptions {
 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). */
+    /** True when the call runs under HQ_API_KEY (no membership lookup). */
     apiKey: boolean;
-    /** Company ref (slug or uid, or undefined for the default) → cmp_ uid. */
-    resolveCompany: (ref: string | undefined) => Promise<string>;
+    /**
+     * Company ref (slug or uid, or undefined for the default) → cmp_ uid. Under
+     * a key, `placeholderSlug` is the placeholder's companies/<slug>/, a
+     * fallback when neither --company nor HQ_COMPANY_UID names the company.
+     */
+    resolveCompany: (ref: string | undefined, placeholderSlug?: string) => Promise<string>;
     /** POST /v1/files/presign. */
     presign: (body: Record<string, unknown>) => Promise<Response>;
 }

package/dist/commands/library-link.js

@@ -6,7 +6,8 @@
  * 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.
+ * from --company (a cmp_ uid, or a slug mapped through companies/manifest.yaml),
+ * HQ_COMPANY_UID, or the placeholder's companies/<slug>/ via the manifest.
  *
  * Wire contract (hq-pro files-presign):
  *   POST /v1/files/presign
@@ -44,6 +45,7 @@ export async function runLibraryLink(target, options, deps) {
     let key;
     let placeholderPath;
     let companyRef = options.company;
+    let placeholderSlug;
     if (isVaultKey(target)) {
         key = target;
     }
@@ -63,14 +65,18 @@ export async function runLibraryLink(target, options, deps) {
         }
         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.
+        // key is company-bound: its resolver prefers HQ_COMPANY_UID and gets the
+        // slug only as a fallback.
+        placeholderSlug = /^companies\/([^/]+)\//.exec(placeholderPath)?.[1];
         if (companyRef === undefined && !deps.apiKey) {
-            companyRef = /^companies\/([^/]+)\//.exec(placeholderPath)?.[1];
+            companyRef = placeholderSlug;
             if (!companyRef)
                 throw new Error(`'${placeholderPath}' is not inside companies/<slug>/; pass --company.`);
         }
     }
-    const company = await deps.resolveCompany(companyRef);
+    const company = deps.apiKey && placeholderSlug !== undefined
+        ? await deps.resolveCompany(companyRef, placeholderSlug)
+        : await deps.resolveCompany(companyRef);
     const res = await deps.presign({ company, key, op: "get", expiresIn });
     const body = (await res.json().catch(() => ({})));
     if (!res.ok) {

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

@@ -0,0 +1,122 @@
+import { Command } from "commander";
+export interface LibraryRemoveOptions {
+    /** Company slug (or cmp_ uid); every target must be in this company. */
+    company?: string;
+    purge?: boolean;
+    dryRun?: boolean;
+    yes?: boolean;
+}
+/** Server reply for POST /v1/files/delete (the fields rm reads). */
+export interface VaultDeleteReply {
+    matched: number;
+    deleted: number;
+}
+export interface LibraryRemoveDeps {
+    hqRoot: string;
+    /** Company slug → cmp_ uid. */
+    resolveCompany: (slug: string) => Promise<string>;
+    /**
+     * POST /v1/files/delete for one exact key. Throws an Error whose message is
+     * ready to show (permission and auth errors included).
+     */
+    deleteKey: (companyUid: string, key: string, dryRun: boolean) => Promise<VaultDeleteReply>;
+    /** POST /v1/search. Only called for `--purge`. */
+    searchAssets: (body: Record<string, unknown>) => Promise<Response>;
+    /** Every key in the company vault (company-relative). Only called for `--purge`. */
+    listVaultKeys: (companyUid: string) => Promise<string[]>;
+    /** Text of small vault objects; null for one that cannot be read. Only called for `--purge`. */
+    readVaultObjects: (companyUid: string, keys: readonly string[]) => Promise<Map<string, string | null>>;
+    /** Ask a yes/no question. Only called without --yes and --dry-run. */
+    confirm: (message: string) => Promise<boolean>;
+    /** Preview and progress lines. */
+    log: (line: string) => void;
+    /** sha256 of a local file. */
+    hashFile?: (file: string) => Promise<string>;
+    /** Delete one local file. */
+    removeFile?: (file: string) => Promise<void>;
+}
+export type StepState = "removed" | "would-remove" | "absent" | "kept" | "failed" | "not-run";
+export interface LibraryRemoveItem {
+    /** HQ-relative placeholder path. */
+    placeholderPath: string;
+    /** HQ-relative original path (the file the placeholder stands in for). */
+    originalPath: string;
+    /** Company-relative vault key of the synced placeholder. */
+    vaultKey: string;
+    /** The blob the placeholder points at. */
+    blobKey: string;
+    original: StepState;
+    placeholder: StepState;
+    vault: StepState;
+    error?: string;
+}
+export interface LibraryRemoveBlob {
+    key: string;
+    state: StepState;
+    error?: string;
+}
+export interface LibraryRemoveResult {
+    company: string;
+    companyUid: string;
+    dryRun: boolean;
+    purge: boolean;
+    /** False when the confirmation was declined. */
+    confirmed: boolean;
+    items: LibraryRemoveItem[];
+    blobs: LibraryRemoveBlob[];
+    /** Commands that undo the vault side. */
+    undo: string[];
+}
+/** Local company placeholders, other than `exclude`, that point at `blobKey`. */
+export declare function localBlobReferences(hqRoot: string, slug: string, blobKey: string, exclude: ReadonlySet<string>): string[];
+/**
+ * Placeholders in the company vault, other than `exclude` (company-relative
+ * keys), that point at any of `blobKeys`. Returns blob key → placeholder keys.
+ *
+ * Two passes:
+ *   1. a quick asset search (`kind: "asset"`, query "hqcloud", which every
+ *      placeholder path carries). Each hit returns its vaultKey, so a shared
+ *      blob is usually found in one call. This pass cannot prove a blob is
+ *      unused: hq-pro does not index the hashes and keys in a placeholder,
+ *      caps a search at 50 hits with no paging, and may lag a fresh upload.
+ *      Its errors are ignored; pass 2 decides.
+ *   2. when pass 1 finds nothing, every `.hqcloud` key the caller can list
+ *      (GET /v1/files/list, as `hq files search` does), read in one batched
+ *      presign and parsed. This lists the whole company vault, so it can take
+ *      minutes on a large one. Any listing or read failure throws: a purge
+ *      must not go ahead on a guess.
+ */
+export declare function cloudBlobReferences(blobKeys: readonly string[], slug: string, companyUid: string, exclude: ReadonlySet<string>, deps: Pick<LibraryRemoveDeps, "searchAssets" | "listVaultKeys" | "readVaultObjects" | "log">): Promise<Map<string, string[]>>;
+/** GET /v1/files/list for every key in the company vault, following the cursor. */
+export declare function listAllVaultKeys(companyUid: string, list: (query: Record<string, string>) => Promise<Response>): Promise<string[]>;
+/**
+ * Read small vault objects: one batched presign (op "get") per 1000 keys, then
+ * a GET per URL. A key that cannot be presigned or read maps to null. Errors
+ * never include a URL, which carries a signature.
+ */
+export declare function readSmallVaultObjects(companyUid: string, keys: readonly string[], presign: (body: Record<string, unknown>) => Promise<Response>, get?: (url: string) => Promise<Response>): Promise<Map<string, string | null>>;
+/**
+ * Testable core. Checks every target, previews, confirms, then removes in the
+ * order described at the top of this file.
+ */
+export declare function runLibraryRemove(targets: readonly string[], options: LibraryRemoveOptions, deps: LibraryRemoveDeps): Promise<LibraryRemoveResult>;
+export declare function formatLibraryRemoveResult(result: LibraryRemoveResult): string;
+/**
+ * User-facing message for a failed POST /v1/files/delete. `err` is duck-typed
+ * on `status` (files.ts's FilesDeleteHttpError) so this module does not load
+ * files.ts at startup.
+ */
+export declare function vaultDeleteErrorMessage(err: unknown, key: string, apiKey: boolean, format: (err: never, key: string) => string): string;
+/**
+ * Company resolver for rm. A session resolves slugs through the API. An
+ * HQ_API_KEY cannot (hq-pro serves no keyed membership lookup), so it maps the
+ * placeholder folder's slug, or an explicit `--company` slug or uid, through
+ * companies/manifest.yaml with library.ts's libraryCompanyForApiKey; hq-pro
+ * still checks the uid against the key on every delete.
+ */
+export declare function removeCompanyResolver(credential: {
+    kind: "api-key" | "cognito";
+    token: string;
+}, hqRoot: string, explicit: string | undefined): Promise<(slug: string) => Promise<string>>;
+export declare function registerLibraryRemoveCommand(library: Command): void;
+//# sourceMappingURL=library-remove.d.ts.map