@indigoai-us/hq-cli 5.345.154 → 5.345.156

package/dist/commands/integrations-core.d.ts

@@ -120,6 +120,16 @@ interface GatewayMessage {
 }
 export type GatewayErrorShape = "string_error" | "object_no_code" | "object_code" | "string_code" | "nested_code" | "empty" | "redacted_empty";
 export type GatewayFailureCode = "invalid_envelope";
+/** Default client wait for a background (202) integration job. */
+export declare const ASYNC_GATEWAY_DEADLINE_MS: number;
+/** Upper bound for `hq integrations call --timeout`, in seconds. */
+export declare const MAX_CALL_TIMEOUT_SECONDS: number;
+/**
+ * Parse `--timeout <seconds>` for `hq integrations call` into milliseconds.
+ * Bounds how long the CLI waits for a background job; it never shortens the
+ * gateway's own limits.
+ */
+export declare function parseCallTimeoutMs(raw: string | undefined): number;
 export declare class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -338,7 +348,9 @@ export declare function resolveConnection(token: string, companyUid: string, app
 }, recoveryOpts?: {
     allowSingleRevoked?: boolean;
 }): Promise<AdminConnection>;
-export declare function callGateway(token: string, params: Record<string, unknown>, idempotencyKey?: string, method?: "tools/call" | "tools/list"): Promise<GatewayMessage>;
+export declare function callGateway(token: string, params: Record<string, unknown>, idempotencyKey?: string, method?: "tools/call" | "tools/list", opts?: {
+    waitMs?: number;
+}): Promise<GatewayMessage>;
 /**
  * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`
  * where `text` is the provider's JSON. Unwrap to the inner payload; fall back

package/dist/commands/integrations-core.js

@@ -19,7 +19,43 @@ import { connectionHealthNotice } from "../lib/integrations/health.js";
 import { bareProvider } from "../lib/integrations/provider-slug.js";
 export { bareProvider } from "../lib/integrations/provider-slug.js";
 const ASYNC_GATEWAY_POLL_INTERVAL_MS = 1_000;
-const ASYNC_GATEWAY_DEADLINE_MS = 4 * 60_000 + 30_000;
+/** Default client wait for a background (202) integration job. */
+export const ASYNC_GATEWAY_DEADLINE_MS = 4 * 60_000 + 30_000;
+/** Upper bound for `hq integrations call --timeout`, in seconds. */
+export const MAX_CALL_TIMEOUT_SECONDS = 30 * 60;
+/**
+ * Parse `--timeout <seconds>` for `hq integrations call` into milliseconds.
+ * Bounds how long the CLI waits for a background job; it never shortens the
+ * gateway's own limits.
+ */
+export function parseCallTimeoutMs(raw) {
+    if (raw === undefined)
+        return ASYNC_GATEWAY_DEADLINE_MS;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new IntegrationsCliError(`--timeout must be a whole number of seconds (got "${raw}").`, { expected: true });
+    }
+    const seconds = Number(trimmed);
+    if (seconds < 1 || seconds > MAX_CALL_TIMEOUT_SECONDS) {
+        throw new IntegrationsCliError(`--timeout must be between 1 and ${MAX_CALL_TIMEOUT_SECONDS} seconds (got ${seconds}).`, { expected: true });
+    }
+    return seconds * 1_000;
+}
+/**
+ * Statuses the gateway returns when an inline (non-background) tools/call ran
+ * into the IntegrationMcpFunction 30s wall or its provider budget.
+ */
+function isInlineTimeoutStatus(status) {
+    return status === 500 || status === 502 || status === 504;
+}
+function inlineTimeoutHint(status) {
+    return (`${upstreamUnavailableMessage(status)} ` +
+        "If this was a long-running call (for example a large analytical read), it may have hit the " +
+        "gateway's 30-second limit: the gateway ran it inline, not as a background job. Long calls " +
+        "run as background jobs only when async integration jobs are enabled for your company; ask " +
+        "HQ support to enable them. Once enabled, hq integrations call waits for the result " +
+        "automatically (see --timeout).");
+}
 export class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -627,9 +663,9 @@ function gatewaySubcommandFor(params, method) {
         return "tools_call";
     return "other";
 }
-export async function callGateway(token, params, idempotencyKey, method = "tools/call") {
+export async function callGateway(token, params, idempotencyKey, method = "tools/call", opts = {}) {
     const gatewaySubcommand = gatewaySubcommandFor(params, method);
-    const deadline = Date.now() + ASYNC_GATEWAY_DEADLINE_MS;
+    const deadline = Date.now() + (opts.waitMs ?? ASYNC_GATEWAY_DEADLINE_MS);
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/mcp",
@@ -663,6 +699,15 @@ export async function callGateway(token, params, idempotencyKey, method = "tools
     }
     if (res.status !== 202 && (!res.ok || !terminalMessage)) {
         raiseIfUnauthorized(res);
+        if (method === "tools/call" &&
+            params.acceptAsync === true &&
+            isInlineTimeoutStatus(res.status)) {
+            throw new IntegrationsCliError(inlineTimeoutHint(res.status), {
+                expected: true,
+                status: res.status,
+                gatewaySubcommand,
+            });
+        }
         raiseIfUpstreamUnavailable(res);
         // Carry the HTTP status so a reportable transport failure (e.g. a 501 that
         // is neither 401 nor an upstream-availability status, so it is captured)
@@ -773,7 +818,7 @@ async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, dea
             break;
         await new Promise((resolve) => setTimeout(resolve, Math.min(ASYNC_GATEWAY_POLL_INTERVAL_MS, remainingMs)));
     }
-    throw new IntegrationsCliError(`Timed out waiting for integration job ${jobId}; the server job may still finish. To safely retry, rerun with --idempotency-key ${idempotencyKey}.`, { expected: true });
+    throw new IntegrationsCliError(`Timed out waiting for integration job ${jobId}; the server job may still finish. To safely retry, rerun with --idempotency-key ${idempotencyKey} (add --timeout <seconds> to wait longer).`, { expected: true });
 }
 /**
  * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`

package/dist/commands/integrations.js

@@ -56,7 +56,7 @@ import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { redactSensitiveUrl, redactSensitiveUrls, redactUrlsInText } from "../utils/redact-url.js";
-import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, fetchUsableApps, isBuiltInGatewayProvider, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, parseCallTimeoutMs, fetchConnections, fetchUsableApps, isBuiltInGatewayProvider, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
 import { registerConnectCommands } from "./integrations-connect.js";
 import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
@@ -483,8 +483,10 @@ export function registerIntegrationsCommand(program) {
         .option("--args <json>", "Tool arguments as a JSON object (default {}); use - to read the JSON from stdin")
         .option("--args-file <path>", "Read tool arguments from a JSON file (use - for stdin); avoids shell quoting of apostrophes and parentheses")
         .option("--idempotency-key <key>", "Stable key so retries execute at most once (default: generated)")
+        .option("--timeout <seconds>", "How long to wait for a long call that runs as a background job (default 270, max 1800)")
         .option("--json", "Machine-readable output")
         .action(async (tool, opts) => {
+        const waitMs = parseCallTimeoutMs(opts.timeout);
         const parsedArgs = await resolveCallArgs(opts);
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
@@ -522,7 +524,7 @@ export function registerIntegrationsCommand(program) {
                 },
             };
         }
-        const message = await callGateway(token, gatewayParams, idempotencyKey);
+        const message = await callGateway(token, gatewayParams, idempotencyKey, "tools/call", { waitMs });
         const payload = unwrapGatewayResult(message.result);
         const queued = queuedOutcome(payload);
         if (queued) {

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

@@ -23,8 +23,12 @@ export interface PutResponse {
 export interface LibraryAddDeps {
     hqRoot: string;
     now: () => Date;
-    /** Resolve the slug to an active company membership. */
-    resolveCompany: (slug: string) => Promise<LibraryCompany>;
+    /**
+     * Resolve `--company` (a slug or a cmp_ uid) to the company. `folderSlug` is
+     * the companies/<slug>/ of an explicit `--to`, for callers that cannot map a
+     * uid to its folder on their own (an HQ_API_KEY).
+     */
+    resolveCompany: (ref: string, folderSlug?: string) => Promise<LibraryCompany>;
     /** POST /v1/files/presign. */
     presign: (body: Record<string, unknown>) => Promise<Response>;
     /** Open a fresh byte stream of a source. Called once to hash and once to upload. */

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