@bli-cockpit/cli 0.2.270 → 0.2.272

package/dist/pdf-page-image.js

@@ -0,0 +1,114 @@
+/**
+ * One decoded PDF page image to a small grayscale PNG the image describe door takes (BLI-23347).
+ *
+ * A scanned PDF page is one big raster (a 7.4 MB scan decodes to 2550x3300 RGB, 25 MB). The describer
+ * takes at most 3 MB and reads text fine at about 1,600 px on the long side, so the raster is box-filtered
+ * down, turned to 8-bit grey and PNG-encoded, trying smaller sizes until it fits. Pure: pixels in, bytes
+ * out, no pdf library and no native dependency, so it runs the same on macOS and Windows.
+ */
+import { createHash } from "node:crypto";
+import { deflateSync } from "node:zlib";
+/** Long-side sizes tried in order; the first PNG under the byte limit wins. */
+const LONG_SIDES = [1600, 1200, 900, 640];
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(buffer) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buffer.length; i += 1)
+        c = CRC_TABLE[(c ^ buffer[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, body) {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(body.length, 0);
+    head.write(type, 4, "latin1");
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), body])), 0);
+    return Buffer.concat([head, body, crc]);
+}
+/** Grey level (0-255) of every pixel, one byte each. */
+function toGrey(raster) {
+    const { width, height, kind, data } = raster;
+    const grey = new Uint8Array(width * height);
+    if (kind === 1) {
+        const stride = Math.ceil(width / 8);
+        for (let y = 0; y < height; y += 1) {
+            for (let x = 0; x < width; x += 1)
+                grey[y * width + x] = (data[y * stride + (x >> 3)] >> (7 - (x & 7))) & 1 ? 255 : 0;
+        }
+        return grey;
+    }
+    const step = kind === 2 ? 3 : 4;
+    for (let i = 0, p = 0; i < grey.length; i += 1, p += step) {
+        const luma = (data[p] * 299 + data[p + 1] * 587 + data[p + 2] * 114) / 1000;
+        // Transparent pixels read as paper, not as black.
+        const alpha = kind === 3 ? data[p + 3] / 255 : 1;
+        grey[i] = Math.round(luma * alpha + 255 * (1 - alpha));
+    }
+    return grey;
+}
+/** Box-filter `grey` (width x height) down to `toWidth` x `toHeight`. */
+function shrink(grey, width, height, toWidth, toHeight) {
+    if (toWidth === width && toHeight === height)
+        return grey;
+    const out = new Uint8Array(toWidth * toHeight);
+    for (let y = 0; y < toHeight; y += 1) {
+        const y0 = Math.floor((y * height) / toHeight);
+        const y1 = Math.max(y0 + 1, Math.floor(((y + 1) * height) / toHeight));
+        for (let x = 0; x < toWidth; x += 1) {
+            const x0 = Math.floor((x * width) / toWidth);
+            const x1 = Math.max(x0 + 1, Math.floor(((x + 1) * width) / toWidth));
+            let sum = 0;
+            for (let yy = y0; yy < y1; yy += 1)
+                for (let xx = x0; xx < x1; xx += 1)
+                    sum += grey[yy * width + xx];
+            out[y * toWidth + x] = Math.round(sum / ((y1 - y0) * (x1 - x0)));
+        }
+    }
+    return out;
+}
+/** An 8-bit grey PNG with the Sub filter on every row. */
+export function encodeGreyPng(grey, width, height) {
+    const rows = Buffer.alloc((width + 1) * height);
+    for (let y = 0; y < height; y += 1) {
+        const at = y * (width + 1);
+        rows[at] = 1;
+        for (let x = 0; x < width; x += 1)
+            rows[at + 1 + x] = (grey[y * width + x] - (x > 0 ? grey[y * width + x - 1] : 0)) & 0xff;
+    }
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width, 0);
+    header.writeUInt32BE(height, 4);
+    header[8] = 8; // bit depth
+    header[9] = 0; // grey
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        chunk("IHDR", header),
+        chunk("IDAT", deflateSync(rows, { level: 6 })),
+        chunk("IEND", Buffer.alloc(0)),
+    ]);
+}
+/** The raster as a PNG of at most `maxBytes`, or null when even the smallest size is too big. */
+export function rasterToPagePng(raster, maxBytes) {
+    const { width, height } = raster;
+    if (!(width > 0 && height > 0) || raster.data.length < (raster.kind === 1 ? Math.ceil(width / 8) * height : width * height * (raster.kind === 2 ? 3 : 4)))
+        return null;
+    const grey = toGrey(raster);
+    for (const longSide of LONG_SIDES) {
+        const scale = Math.min(1, longSide / Math.max(width, height));
+        const toWidth = Math.max(1, Math.round(width * scale));
+        const toHeight = Math.max(1, Math.round(height * scale));
+        const bytes = encodeGreyPng(shrink(grey, width, height, toWidth, toHeight), toWidth, toHeight);
+        if (bytes.length <= maxBytes)
+            return { bytes, sha256: createHash("sha256").update(bytes).digest("hex"), width: toWidth, height: toHeight };
+    }
+    return null;
+}

package/dist/pdf-transcript-step.js

@@ -0,0 +1,218 @@
+/**
+ * The PDF step of the transcript prepare path (BLI-23347): turn each base64 PDF into a marker block, in the
+ * same pass and under the same budgets as images. Drop mode only.
+ *
+ * The session (`image-description-session.ts`) holds the image state; this module plugs into it through ONE
+ * seam, `addPdfsToFinds`, which takes the images the session found and returns the same shape with the PDFs
+ * added:
+ *
+ *  - every PDF occurrence is a stand-in `EmbeddedImage` carrying `replacement` (its marker text, set once the
+ *    conversion is complete), so the swap in `replaceImagesWithMarkers` and `slimLineStream` needs no PDF code;
+ *  - a scanned PDF's page images join `unique`, so the existing describe door, budgets, backoff and state do
+ *    the describing; the PDF is replaced only when every page image has a description (an undescribed PDF is
+ *    kept, exactly as an undescribed image is);
+ *  - the FIRST copy of a PDF in the transcript gets the full marker block, every later copy a one-line reference.
+ *
+ * Conversion results are cached on disk by sha256 (`pdf-conversion-cache.ts`), so a transcript rebuilt every
+ * tick converts each PDF once. A PDF that cannot be converted (too big, the budget spent, unreadable) is left
+ * as it is and says why in the log; it is not counted, so it never keeps a transcript "pending" forever.
+ */
+import { createHash } from "node:crypto";
+import { formatImageMarker, formatPdfMarker, formatPdfReference } from "@bli-cockpit/telemetry-core";
+import { convertPdf } from "./pdf-convert.js";
+import { readCachedPdf, writeCachedPdf } from "./pdf-conversion-cache.js";
+import { bytesMayHoldPdf, scanPdfsInLine } from "./pdf-byte-scan.js";
+const TAG = "[pdf-step]";
+/** Largest PDF decoded for conversion: the document, its pdf.js structures and one page raster must fit comfortably. */
+export const MAX_PDF_BYTES = 25 * 1024 * 1024;
+/** Time spent converting across one sync; later PDFs wait for the next tick (the cache keeps finished ones). */
+export const MAX_PDF_RUN_MS = 60_000;
+const BLOCK_CHARS = 48 * 1024;
+const runStates = new WeakMap();
+function runStateOf(key) {
+    let state = runStates.get(key);
+    if (!state) {
+        state = { spentMs: 0, records: new Map() };
+        runStates.set(key, state);
+    }
+    return state;
+}
+/** `text` in a JSON string that sits `depth` strings deep: one escaping pass per level, plus the string's own. */
+function jsonEscaped(text, depth) {
+    let out = JSON.stringify(text).slice(1, -1);
+    if (depth === 1)
+        out = JSON.stringify(out).slice(1, -1);
+    return out;
+}
+/** The decoded bytes of a base64 run, in blocks, into one exact-size buffer. */
+function decode(payload, byteSize) {
+    const out = Buffer.alloc(byteSize);
+    let at = 0;
+    const length = payload.length;
+    for (let from = 0; from < length; from += BLOCK_CHARS) {
+        const block = Buffer.from(typeof payload === "string" ? payload.slice(from, from + BLOCK_CHARS) : payload.toString("latin1", from, Math.min(length, from + BLOCK_CHARS)), "base64");
+        if (at + block.length > byteSize)
+            return null;
+        block.copy(out, at);
+        at += block.length;
+    }
+    return at === byteSize ? new Uint8Array(out.buffer, out.byteOffset, out.length) : null;
+}
+const prefix = (sha256) => sha256.slice(0, 16);
+export async function planPdfs(found, ctx) {
+    const state = runStateOf(ctx.key);
+    const distinct = new Map();
+    const order = new Map();
+    for (const pdf of found)
+        order.set(pdf.sha256, [...(order.get(pdf.sha256) ?? []), pdf]);
+    const pageImages = new Map();
+    const payloads = new Map();
+    for (const [sha256, copies] of order) {
+        const first = copies[0];
+        const started = Date.now();
+        // A PDF given up on earlier in this sync is not tried again.
+        if (state.records.has(sha256) && state.records.get(sha256) === null)
+            continue;
+        let entry = state.records.get(sha256) ?? (await readCachedPdf(ctx.stateDir, sha256));
+        const cacheHit = entry !== null;
+        const needsPages = entry?.kind === "scanned" && entry.pageImages.some((page) => !ctx.isDescribed(page.sha256));
+        if (!entry || needsPages) {
+            const skip = first.byteSize > MAX_PDF_BYTES ? "pdf_too_large" : state.spentMs > MAX_PDF_RUN_MS ? "pdf_time_budget_spent" : null;
+            if (skip) {
+                console.error(TAG + " PDF left as it is", JSON.stringify({ reason: skip, sha256_prefix: prefix(sha256), byte_size: first.byteSize, copies: copies.length }));
+                state.records.set(sha256, null);
+                continue;
+            }
+            const bytes = decode(await ctx.readBase64(first), first.byteSize);
+            if (!bytes || createHash("sha256").update(bytes).digest("hex") !== sha256)
+                throw ctx.sourceChanged();
+            const converted = await convertPdf(bytes);
+            state.spentMs += Date.now() - started;
+            if (converted.kind === "failed") {
+                console.error(TAG + " PDF left as it is", JSON.stringify({ reason: converted.reason, sha256_prefix: prefix(sha256), byte_size: first.byteSize, pages: converted.pages, copies: copies.length }));
+                state.records.set(sha256, null);
+                continue;
+            }
+            if (converted.kind === "text") {
+                entry = { kind: "text", pages: converted.pages, notes: converted.notes, body: converted.body };
+            }
+            else if (converted.pageImages.length === 0) {
+                console.error(TAG + " PDF left as it is", JSON.stringify({ reason: "scanned_without_page_images", sha256_prefix: prefix(sha256), byte_size: first.byteSize, pages: converted.pages, copies: copies.length }));
+                state.records.set(sha256, null);
+                continue;
+            }
+            else {
+                entry = { kind: "scanned", pages: converted.pages, notes: converted.notes, pageImages: converted.pageImages.map(({ page, png }) => ({ page, sha256: png.sha256, byteSize: png.bytes.length })) };
+                for (const { png } of converted.pageImages) {
+                    if (ctx.isDescribed(png.sha256) || payloads.has(png.sha256))
+                        continue;
+                    payloads.set(png.sha256, png.bytes.toString("base64"));
+                }
+            }
+            await writeCachedPdf(ctx.stateDir, sha256, entry);
+        }
+        if (!entry)
+            continue;
+        state.records.set(sha256, entry);
+        if (entry.kind === "scanned") {
+            for (const page of entry.pageImages) {
+                if (ctx.isDescribed(page.sha256) || !payloads.has(page.sha256))
+                    continue;
+                pageImages.set(page.sha256, { replaceStart: -1, replaceEnd: -1, base64Start: -1, base64End: -1, sha256: page.sha256, mediaType: "image/png", byteSize: page.byteSize });
+            }
+        }
+        console.error(TAG + " PDF converted", JSON.stringify({ kind: entry.kind, sha256_prefix: prefix(sha256), byte_size: first.byteSize, pages: entry.pages, chars: entry.kind === "text" ? entry.body.length : null, page_images: entry.kind === "scanned" ? entry.pageImages.length : null, copies: copies.length, cache: cacheHit ? "hit" : "miss", elapsed_ms: Date.now() - started }));
+        distinct.set(sha256, { pdf: first, copies, entry });
+    }
+    const occurrences = [];
+    const standIns = new Map();
+    let counted = 0;
+    for (const pdf of found) {
+        if (!distinct.has(pdf.sha256))
+            continue;
+        const standIn = { replaceStart: pdf.replaceStart, replaceEnd: pdf.replaceEnd, base64Start: pdf.base64Start, base64End: pdf.base64End, sha256: pdf.sha256, mediaType: "image/png", byteSize: pdf.byteSize };
+        standIns.set(pdf, standIn);
+        occurrences.push(standIn);
+        counted += 1;
+    }
+    const settle = () => {
+        let replacedCount = 0;
+        let charsSaved = 0;
+        for (const { copies, entry } of distinct.values()) {
+            const ready = entry.kind === "text" || entry.pageImages.every((page) => ctx.isDescribed(page.sha256));
+            if (!ready)
+                continue;
+            const facts = { sha256: copies[0].sha256, pages: entry.pages, byteSize: copies[0].byteSize };
+            const full = entry.kind === "text"
+                ? formatPdfMarker({ ...facts, method: "text-layer", notes: entry.notes }, entry.body)
+                : formatPdfMarker({ ...facts, method: "page-images", notes: entry.notes }, entry.pageImages.map((page) => `page ${page.page}: ${formatImageMarker({ sha256: page.sha256, mediaType: "image/png", byteSize: page.byteSize })}`).join("\n"));
+            const reference = formatPdfReference(facts);
+            copies.forEach((pdf, index) => {
+                const standIn = standIns.get(pdf);
+                const text = index === 0 ? full : reference;
+                standIn.replacement = jsonEscaped(text, pdf.escapeDepth);
+                replacedCount += 1;
+                charsSaved += pdf.replaceEnd - pdf.replaceStart - standIn.replacement.length;
+            });
+        }
+        return { replacedCount, charsSaved };
+    };
+    return { occurrences, pageImages, payloads, counted, settle };
+}
+/**
+ * The session's finds with the PDFs added; `finds` itself when there are none. Call only in drop mode.
+ */
+export async function addPdfsToFinds(finds, found, ctx) {
+    if (found.length === 0)
+        return finds;
+    const step = await planPdfs(found, ctx);
+    if (step.counted === 0)
+        return finds;
+    const images = finds.images ? [...finds.images, ...step.occurrences].sort((a, b) => a.replaceStart - b.replaceStart) : undefined;
+    return {
+        ...finds,
+        total: finds.total + step.counted,
+        unique: new Map([...finds.unique, ...step.pageImages]),
+        base64For: (image) => step.payloads.get(image.sha256) ?? finds.base64For(image),
+        swapped: (replace) => {
+            const base = finds.swapped(replace);
+            const pdf = step.settle();
+            return { replacedCount: base.replacedCount + pdf.replacedCount, charsSaved: base.charsSaved + pdf.charsSaved };
+        },
+        ...(images ? { images } : {}),
+        extraOccurrences: step.occurrences,
+    };
+}
+/** The PDFs of a whole transcript's text, with character offsets (the text path; files at the streaming size use the census). */
+export function pdfsOfText(text) {
+    if (!text.includes("JVBERi0") && !text.includes("data:application/pdf"))
+        return [];
+    const bytes = Buffer.from(text, "utf8");
+    if (!bytesMayHoldPdf(bytes))
+        return [];
+    const byteOffsets = scanPdfsInLine(bytes);
+    const out = [];
+    let consumedBytes = 0;
+    let consumedChars = 0;
+    const charAt = (byteOffset) => {
+        consumedChars += bytes.toString("utf8", consumedBytes, byteOffset).length;
+        consumedBytes = byteOffset;
+        return consumedChars;
+    };
+    for (const pdf of byteOffsets) {
+        const replaceStart = charAt(pdf.replaceStart);
+        const base64Start = replaceStart + (pdf.base64Start - pdf.replaceStart);
+        const length = pdf.base64End - pdf.base64Start;
+        const replaceEnd = base64Start + length;
+        consumedBytes = pdf.replaceEnd;
+        consumedChars = replaceEnd;
+        out.push({ ...pdf, replaceStart, replaceEnd, base64Start, base64End: replaceEnd });
+    }
+    return out;
+}
+/** Merge two lists already sorted by `replaceStart`. */
+export function mergeOccurrences(a, b) {
+    if (!b || b.length === 0)
+        return a;
+    return [...a, ...b].sort((x, y) => x.replaceStart - y.replaceStart);
+}

package/dist/slim/slim-stream.js

@@ -84,7 +84,8 @@ export async function slimLineStream(lines, kind, occurrences, replace, sink) {
             const image = occurrences[next];
             if (image.replaceEnd > end)
                 throw new TranscriptNotStreamable("images_changed_between_passes");
-            if (replace(image))
+            // BLI-23347: a stand-in that carries its own replacement (a PDF) is always swapped.
+            if (image.replacement !== undefined || replace(image))
                 chosen.push(image);
         }
         let line;
@@ -95,7 +96,7 @@ export async function slimLineStream(lines, kind, occurrences, replace, sink) {
             const pieces = [];
             let cursor = 0;
             for (const image of chosen) {
-                const marker = formatImageMarker({ sha256: image.sha256, mediaType: image.mediaType, byteSize: image.byteSize });
+                const marker = image.replacement ?? formatImageMarker({ sha256: image.sha256, mediaType: image.mediaType, byteSize: image.byteSize });
                 pieces.push(bytes.subarray(cursor, image.replaceStart - start), Buffer.from(marker, "utf8"));
                 cursor = image.replaceEnd - start;
                 replacedCount += 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.270",
+  "version": "0.2.272",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,9 +27,10 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-surface-doors.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-cli-doctor-json.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.81",
-    "@bli-cockpit/mcp": "0.1.165",
-    "@bli-cockpit/telemetry-core": "0.1.88"
+    "@bli-cockpit/memory-mcp": "0.1.82",
+    "@bli-cockpit/mcp": "0.1.166",
+    "@bli-cockpit/telemetry-core": "0.1.89",
+    "unpdf": "1.8.1"
   },
   "repository": {
     "type": "git",