@yadsh/dsh-qa-surface 0.4.0 → 0.6.0

package/lib/documents/providers/pandoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pandoc.js","sourceRoot":"","sources":["../../../src/documents/providers/pandoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAQ7C,OAAO,EAAE,eAAe,EAAE,UAAU,EAAsB,MAAM,cAAc,CAAC;AAC/E,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,GACb,MAAM,aAAa,CAAC;AAYrB,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,MAAM,gBAAgB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzC,SAAS,WAAW,CAClB,OAA8B,EAC9B,IAAuB,EACvB,OAKC;IAED,OAAO,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE;QAC1C,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,cAAc,EAAE,gBAAgB;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,MAAM;QACvB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACnE,GAAG,CAAC,OAAO,CAAC,iBAAiB,KAAK,SAAS;YACzC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC;KACtD,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,OAA8B,EAC9B,OAAe;IAEf,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC;IAC5E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,WAAW,CAAC,EAAE;YACjE,SAAS,EAAE,kBAAkB;YAC7B,cAAc,EAAE,CAAC,GAAG,IAAI;YACxB,OAAO;YACP,OAAO,EAAE,uBAAuB;YAChC,GAAG,CAAC,OAAO,CAAC,iBAAiB,KAAK,SAAS;gBACzC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC;SACtD,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,OAAO,kBAAkB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,MAAM,OAAO,kBAAkB;IAIA,OAAO;IAH3B,IAAI,GAAG,QAAQ,CAAC;IACjB,aAAa,CAA0C;IAE/D,YAA6B,OAA8B;uBAA9B,OAAO;IAA0B,CAAC;IAE/D,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,aAAa,KAAK,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7D,OAAO,MAAM,IAAI,CAAC,aAAa,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAsB;QACjC,MAAM,IAAI,GAAG;YACX,KAAK,CAAC,UAAU;YAChB,YAAY;YACZ,WAAW;YACX,YAAY,KAAK,CAAC,UAAU,EAAE;YAC9B,GAAG,CAAC,KAAK,CAAC,gBAAgB,KAAK,SAAS;gBACtC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,mBAAmB,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC;YAClD,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS;gBAC/B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,mBAAmB,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;YAC3C,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,oBAAoB,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;YACzE,GAAG,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC;SACrC,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE;YACnD,GAAG,EAAE,KAAK,CAAC,OAAO;YAClB,OAAO,EAAE,IAAI,CAAC,IAAI;YAClB,MAAM,EAAE,gBAAgB;YACxB,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;SAChE,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,aAAa,CACrB,eAAe,EACf,kEAAkE,EAClE,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CACvB,CAAC;QACJ,CAAC;QACD,eAAe,CAAC,MAAM,EAAE;YACtB,OAAO,EAAE,IAAI,CAAC,IAAI;YAClB,OAAO,EAAE,gBAAgB;YACzB,YAAY,EAAE,eAAe;SAC9B,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,YAAY,CACjC,KAAK,CAAC,UAAU,EAChB,IAAI,CAAC,IAAI,EACT,eAAe,CAChB,CAAC;QACF,OAAO;YACL,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,MAAM,EAAE,MAAM,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC;YACzC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACrD,QAAQ,EAAE,EAAE;SACb,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,sBAAsB;IAIJ,OAAO;IAH3B,IAAI,GAAG,OAAO,CAAC;IAChB,aAAa,CAA0C;IAE/D,YAA6B,OAA8B;uBAA9B,OAAO;IAA0B,CAAC;IAE/D,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,aAAa,KAAK,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7D,OAAO,MAAM,IAAI,CAAC,aAAa,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAqB;QAChC,MAAM,IAAI,GAAG;YACX,KAAK,CAAC,UAAU;YAChB,YAAY;YACZ,UAAU;YACV,cAAc;YACd,oBAAoB;YACpB,YAAY,KAAK,CAAC,UAAU,EAAE;YAC9B,GAAG,CAAC,KAAK,CAAC,gBAAgB,KAAK,SAAS;gBACtC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;YACpE,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS;gBAC/B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,mBAAmB,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;YAC3C,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS;gBAC9B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,gBAAgB,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;YACvC,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,oBAAoB,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;YACzE,GAAG,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC;SACrC,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE;YACnD,GAAG,EAAE,KAAK,CAAC,OAAO;YAClB,OAAO,EAAE,IAAI,CAAC,IAAI;YAClB,MAAM,EAAE,0BAA0B;YAClC,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;SAChE,CAAC,CAAC;QACH,eAAe,CAAC,MAAM,EAAE;YACtB,OAAO,EAAE,IAAI,CAAC,IAAI;YAClB,OAAO,EAAE,0BAA0B;YACnC,YAAY,EAAE,eAAe;SAC9B,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,YAAY,CACjC,KAAK,CAAC,UAAU,EAChB,IAAI,CAAC,IAAI,EACT,eAAe,CAChB,CAAC;QACF,OAAO;YACL,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,MAAM,EAAE,MAAM,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC;YACzC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACrD,QAAQ,EAAE,EAAE;SACb,CAAC;IACJ,CAAC;CACF"}

package/lib/documents/providers/process.js

@@ -0,0 +1,164 @@
+/**
+ * Hardened child-process runner for document backends (§26.1, §28, §47).
+ *
+ * Every backend invocation goes through here. The contract mirrors the one the
+ * git tools use, because the threat is the same shape — a document is
+ * untrusted input and the backend is a powerful external program:
+ *
+ * - argv array only, built by the provider, never by the model, no shell;
+ * - an explicit environment allow-list, so ambient secrets and proxies do not
+ *   reach the backend;
+ * - output is byte-capped and the process is killed when the cap or the
+ *   timeout hits; a killed run is reported as `timedOut`/`truncated` rather
+ *   than being confused with a backend that failed on its own;
+ * - the caller's abort signal terminates the child and its descendants.
+ */
+import { spawn } from "node:child_process";
+import { DocumentError, sanitizeBackendOutput } from "../errors.js";
+const DEFAULT_STDERR_MAX_BYTES = 16 * 1024;
+const KILL_ESCALATION_MS = 500;
+/**
+ * Ambient variables a document backend legitimately needs. Everything else —
+ * API keys, proxy settings, cloud credentials — is withheld: a converter
+ * parsing a hostile document should not be able to read the deployment's
+ * secrets out of its own environment (§26.5).
+ */
+export function buildProcessEnv(extra, source = process.env) {
+    const allowed = {};
+    for (const key of [
+        "PATH",
+        "HOME",
+        "USERPROFILE",
+        "LANG",
+        "LC_ALL",
+        "TMPDIR",
+        "TEMP",
+        "TMP",
+        "SystemRoot",
+        "windir",
+        "PATHEXT",
+        "COMSPEC",
+        "PROGRAMFILES",
+        "PROGRAMFILES(X86)",
+        "PROGRAMDATA",
+        "LOCALAPPDATA",
+        "APPDATA",
+    ]) {
+        const value = source[key];
+        if (value !== undefined)
+            allowed[key] = value;
+    }
+    return { ...allowed, ...(extra ?? {}) };
+}
+export async function runProcess(program, argv, options) {
+    const args = [...(options.programPrefixArgs ?? []), ...argv];
+    return await new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(program, [...args], {
+                ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+                env: buildProcessEnv(options.env),
+                stdio: ["ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            reject(new DocumentError("BACKEND_UNAVAILABLE", `${options.backend} could not be started: ${sanitizeBackendOutput(error.message)}`, { backend: options.backend }));
+            return;
+        }
+        let settled = false;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let truncated = false;
+        let timedOut = false;
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const stdoutCap = Math.max(1, Math.floor(options.maxStdoutBytes));
+        const stderrCap = Math.max(1, Math.floor(options.maxStderrBytes ?? DEFAULT_STDERR_MAX_BYTES));
+        const kill = () => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            child.kill();
+            const escalation = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill("SIGKILL");
+            }, KILL_ESCALATION_MS);
+            escalation.unref?.();
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            kill();
+        }, Math.max(1, Math.floor(options.timeoutMs)));
+        timer.unref?.();
+        const onAbort = () => kill();
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const detach = () => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+        };
+        child.stdout?.on("data", (chunk) => {
+            if (stdoutBytes >= stdoutCap) {
+                truncated = true;
+                kill();
+                return;
+            }
+            const remaining = stdoutCap - stdoutBytes;
+            if (chunk.length > remaining) {
+                stdoutChunks.push(chunk.subarray(0, remaining));
+                stdoutBytes = stdoutCap;
+                truncated = true;
+                kill();
+                return;
+            }
+            stdoutChunks.push(chunk);
+            stdoutBytes += chunk.length;
+        });
+        child.stderr?.on("data", (chunk) => {
+            if (stderrBytes >= stderrCap)
+                return;
+            const remaining = stderrCap - stderrBytes;
+            if (chunk.length > remaining) {
+                stderrChunks.push(chunk.subarray(0, remaining));
+                stderrBytes = stderrCap;
+                return;
+            }
+            stderrChunks.push(chunk);
+            stderrBytes += chunk.length;
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            detach();
+            reject(new DocumentError("BACKEND_UNAVAILABLE", `${options.backend} could not be started: ${sanitizeBackendOutput(error.message)}`, { backend: options.backend }));
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            detach();
+            resolve({
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                exitCode: code,
+                truncated,
+                timedOut,
+            });
+        });
+    });
+}
+/** Map a finished run that the provider expected to succeed onto an error. */
+export function expectProcessOk(result, options) {
+    if (result.timedOut) {
+        throw new DocumentError("BACKEND_TIMEOUT", `${options.backend} exceeded its time budget while ${options.context}`, { backend: options.backend, details: { timeoutMs: true } });
+    }
+    if (result.exitCode === 0)
+        return;
+    const detail = sanitizeBackendOutput(result.stderr) ||
+        sanitizeBackendOutput(result.stdout);
+    throw new DocumentError(options.fallbackCode, `${options.backend} failed while ${options.context}${detail === "" ? "" : `: ${detail}`}`, {
+        backend: options.backend,
+        details: { exitCode: result.exitCode },
+    });
+}
+//# sourceMappingURL=process.js.map

package/lib/documents/providers/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../../src/documents/providers/process.ts"],"names":[],"mappings":"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"}

package/lib/documents/providers/registry.js

@@ -0,0 +1,152 @@
+/**
+ * Backend registry and selection (§22, §23, §14.3, §45).
+ *
+ * Tools never import a concrete provider: they ask the registry for the
+ * renderer, extractor or converter that fits the request, and the registry
+ * decides — from configuration and from what is actually available — which
+ * implementation that is. Swapping Docling for another extractor, or Typst for
+ * another PDF engine, is a change here and nowhere else.
+ */
+import { DocumentError } from "../errors.js";
+import { DoclingExtractor } from "./docling.js";
+import { LibreOfficePdfConverter } from "./libreoffice.js";
+import { MarkItDownExtractor } from "./markitdown.js";
+import { PandocDocxRenderer, PandocTypstPdfRenderer } from "./pandoc.js";
+export function createProviders(config, seams = {}) {
+    const pandocOptions = {
+        executable: config.pandoc.executable,
+        timeoutMs: config.pandoc.timeoutMs,
+        ...(seams.pandoc?.programPrefixArgs === undefined
+            ? {}
+            : { programPrefixArgs: seams.pandoc.programPrefixArgs }),
+        ...(seams.pandoc?.versionProbe === undefined
+            ? {}
+            : { versionProbe: seams.pandoc.versionProbe }),
+    };
+    const pandoc = new PandocDocxRenderer(pandocOptions);
+    const docling = config.docling.enabled
+        ? new DoclingExtractor({
+            baseUrl: config.docling.baseUrl,
+            timeoutMs: config.docling.timeoutMs,
+            maxResponseBytes: config.limits.maxResponseBytes,
+            maxImages: config.limits.maxExtractedImages,
+            ...(seams.fetchImpl === undefined
+                ? {}
+                : { fetchImpl: seams.fetchImpl }),
+        })
+        : undefined;
+    const markitdown = config.markitdown.enabled
+        ? new MarkItDownExtractor({
+            executable: config.markitdown.executable,
+            timeoutMs: config.markitdown.timeoutMs,
+            maxStdoutBytes: config.limits.maxExtractedMarkdownBytes,
+            ...(seams.markitdown?.programPrefixArgs === undefined
+                ? {}
+                : { programPrefixArgs: seams.markitdown.programPrefixArgs }),
+            ...(seams.markitdown?.versionProbe === undefined
+                ? {}
+                : { versionProbe: seams.markitdown.versionProbe }),
+        })
+        : undefined;
+    return {
+        docx: pandoc,
+        typstPdf: config.typst.enabled
+            ? new PandocTypstPdfRenderer(pandocOptions)
+            : undefined,
+        converter: new LibreOfficePdfConverter({
+            executable: config.libreoffice.executable,
+            timeoutMs: config.libreoffice.timeoutMs,
+            ...(seams.libreoffice?.programPrefixArgs === undefined
+                ? {}
+                : { programPrefixArgs: seams.libreoffice.programPrefixArgs }),
+            ...(seams.libreoffice?.versionProbe === undefined
+                ? {}
+                : { versionProbe: seams.libreoffice.versionProbe }),
+        }),
+        docling,
+        doclingHealth: docling === undefined
+            ? undefined
+            : async () => await docling.health(),
+        markitdown,
+        markitdownHealth: markitdown === undefined
+            ? undefined
+            : async () => await markitdown.health(),
+    };
+}
+/**
+ * The PDF route (§14.3):
+ *
+ * ```text
+ * DOCX + PDF requested          → office
+ * PDF only, template has Typst  → typst
+ * otherwise                     → office
+ * ```
+ *
+ * A deployment that asked for `typst` without enabling the engine is answered
+ * with `BACKEND_UNAVAILABLE` instead of silently rendering an office PDF in
+ * the wrong layout.
+ */
+export function selectPdfMode(options) {
+    const wantsDocx = options.formats.includes("docx");
+    const resolve = () => {
+        if (options.requested === "office")
+            return "office";
+        if (options.requested === "typst")
+            return "typst";
+        if (wantsDocx)
+            return "office";
+        return options.templateHasTypst ? "typst" : "office";
+    };
+    const mode = resolve();
+    if (mode === "typst" && !options.typstEnabled) {
+        throw new DocumentError("BACKEND_UNAVAILABLE", options.requested === "typst"
+            ? "the Typst PDF route is not enabled in this deployment"
+            : "this template only provides a Typst layout, but the Typst PDF route is not enabled", { backend: "typst" });
+    }
+    return mode;
+}
+export function selectExtractor(providers, config, mode, format) {
+    const docling = providers.docling;
+    const markitdown = providers.markitdown;
+    if (mode === "fast") {
+        if (markitdown !== undefined && markitdown.supports(format)) {
+            return {
+                extractor: markitdown,
+                fallbacks: docling === undefined ? [] : [docling],
+            };
+        }
+        if (docling === undefined) {
+            throw new DocumentError("BACKEND_UNAVAILABLE", "no document extractor is enabled in this deployment", { backend: "docling" });
+        }
+        return { extractor: docling, fallbacks: [] };
+    }
+    if (docling !== undefined && docling.supports(format)) {
+        const fallbacks = config.extraction.allowFallback &&
+            markitdown !== undefined &&
+            markitdown.supports(format)
+            ? [markitdown]
+            : [];
+        return { extractor: docling, fallbacks };
+    }
+    if (markitdown !== undefined && markitdown.supports(format)) {
+        return { extractor: markitdown, fallbacks: [] };
+    }
+    throw new DocumentError("BACKEND_UNAVAILABLE", `no enabled extractor supports ${format.toUpperCase()} documents`, { backend: "docling" });
+}
+/** Run the selected extractor, falling back only when it is unreachable. */
+export async function extractWithFallback(selection, input) {
+    try {
+        return { document: await selection.extractor.extract(input) };
+    }
+    catch (error) {
+        const unreachable = error instanceof DocumentError &&
+            (error.code === "BACKEND_UNAVAILABLE" ||
+                error.code === "BACKEND_TIMEOUT");
+        const next = selection.fallbacks[0];
+        if (!unreachable || next === undefined)
+            throw error;
+        const document = await next.extract(input);
+        return { document, fellBackFrom: selection.extractor.name };
+    }
+}
+//# sourceMappingURL=registry.js.map

package/lib/documents/providers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/documents/providers/registry.ts"],"names":[],"mappings":"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"}

package/lib/documents/providers/shared.js

@@ -0,0 +1,75 @@
+/**
+ * Shared plumbing of the document providers.
+ *
+ * Providers report what they wrote through {@link verifyOutput}: a backend
+ * that exits 0 but leaves no file behind is a failure, and one that leaves an
+ * empty file is a failure too — the caller must never be handed a path that
+ * looks like an artifact and is not.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { DocumentError, sanitizeBackendOutput } from "../errors.js";
+export async function verifyOutput(outputPath, backend, code) {
+    const details = await stat(outputPath).catch(() => undefined);
+    if (details === undefined || !details.isFile()) {
+        throw new DocumentError(code, `${backend} reported success but produced no output`, { backend });
+    }
+    if (details.size === 0) {
+        throw new DocumentError(code, `${backend} produced an empty file`, {
+            backend,
+        });
+    }
+    return { path: outputPath, size: details.size };
+}
+/** `--metadata=key=value` pairs, sanitized of control characters. */
+export function metadataArguments(metadata) {
+    if (metadata === undefined)
+        return [];
+    const args = [];
+    for (const [key, value] of Object.entries(metadata)) {
+        const cleanKey = key.replace(/[^A-Za-z0-9_-]+/gu, "-").slice(0, 40);
+        if (cleanKey === "")
+            continue;
+        // Newlines would let a value impersonate the next CLI argument in a log;
+        // argv itself is already structured, so collapsing is enough.
+        /* eslint-disable-next-line no-control-regex -- newlines and NULs must not survive into a log */
+        const cleanValue = value.replace(/[\r\n\u0000]+/gu, " ").slice(0, 4_000);
+        args.push(`--metadata=${cleanKey}=${cleanValue}`);
+    }
+    return args;
+}
+/** First line of a `--version` run, reduced to the version token. */
+export function parseVersionOutput(stdout, program) {
+    const firstLine = sanitizeBackendOutput(stdout.split(/\r?\n/u)[0] ?? "", 200);
+    const match = /(\d+\.\d+(?:\.\d+)?)/u.exec(firstLine);
+    if (match !== null)
+        return match[1];
+    return firstLine === "" || firstLine === program ? undefined : firstLine;
+}
+export function backendInfo(provider, version) {
+    return version === undefined ? { provider } : { provider, version };
+}
+/** Read a text output produced by a backend, with a bounded size. */
+export async function readTextOutput(filePath, backend, maxBytes) {
+    const details = await stat(filePath).catch(() => undefined);
+    if (details === undefined) {
+        throw new DocumentError("EXTRACTION_FAILED", `${backend} produced no output`, {
+            backend,
+        });
+    }
+    if (details.size > maxBytes) {
+        const raw = await readFile(filePath);
+        return {
+            text: raw.subarray(0, maxBytes).toString("utf8"),
+            truncated: true,
+        };
+    }
+    return { text: await readFile(filePath, "utf8"), truncated: false };
+}
+export function truncationWarning(backend, contentType) {
+    return {
+        code: "MARKDOWN_TRUNCATED",
+        message: `the extracted ${contentType} exceeded the configured inline budget and was truncated`,
+        backend,
+    };
+}
+//# sourceMappingURL=shared.js.map

package/lib/documents/providers/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/documents/providers/shared.ts"],"names":[],"mappings":"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"}

package/lib/documents/runtime.js

@@ -0,0 +1,114 @@
+/**
+ * The runtime facade the tools talk to.
+ *
+ * One instance lives in the plugin and survives across calls, so the backend
+ * registry, the concurrency semaphores and the version caches are shared
+ * instead of rebuilt per request. The four operations are the whole surface:
+ * everything else in this subsystem is an implementation detail behind them.
+ */
+import { ArtifactStore } from "./artifacts/store.js";
+import { applyDocumentsEnvOverrides, resolveDocumentsConfig, } from "./config.js";
+import { documentCapabilities, documentHealth, } from "./capabilities.js";
+import { DocumentError } from "./errors.js";
+import { createProviders, } from "./providers/registry.js";
+import { convertDocument } from "./orchestrator/convert-document.js";
+import { createDocument } from "./orchestrator/create-document.js";
+import { inspectDocument } from "./orchestrator/inspect-document.js";
+import { toMarkdown } from "./orchestrator/extract-document.js";
+import { createRuntimeDeps, silentDocumentLogger, } from "./orchestrator/runtime-deps.js";
+import { loadScopeTemplates, resolveDocumentScope, } from "./orchestrator/scope.js";
+import { loadTemplateRegistry } from "./templates/registry.js";
+import { CONVERSION_ROUTES } from "./orchestrator/convert-document.js";
+export class DocumentRuntime {
+    config;
+    providers;
+    deps;
+    seams;
+    constructor(options) {
+        this.config = options.config;
+        this.seams = options.seams ?? {};
+        this.providers =
+            options.providers ?? createProviders(this.config, this.seams);
+        this.deps = createRuntimeDeps({
+            config: this.config,
+            providers: this.providers,
+            logger: options.logger ?? silentDocumentLogger,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+    }
+    async create(input, scope) {
+        return await createDocument(this.deps, input, scope);
+    }
+    async toMarkdown(input, scope) {
+        return await toMarkdown(this.deps, input, scope);
+    }
+    async convert(input, scope) {
+        return await convertDocument(this.deps, input, scope);
+    }
+    async inspect(input, scope) {
+        return await inspectDocument(this.deps, input, scope);
+    }
+    async health(options = {}) {
+        const healthOptions = {
+            config: this.config,
+            providers: this.providers,
+            ...(options.probeProcessBackends === undefined
+                ? {}
+                : { probeProcessBackends: options.probeProcessBackends }),
+        };
+        return await documentHealth(healthOptions);
+    }
+    async capabilities(scope) {
+        const templates = scope === undefined
+            ? await loadTemplateRegistry(undefined)
+            : await loadScopeTemplates(this.config, scope.workspaceRoot);
+        return documentCapabilities({
+            config: this.config,
+            providers: this.providers,
+            templates,
+        });
+    }
+    /** Routes this runtime advertises, in documentation order. */
+    routes() {
+        return CONVERSION_ROUTES;
+    }
+    /**
+     * Retention sweep (§41). Meaningful only for a pinned storage root: with the
+     * default per-workspace layout the plugin cannot enumerate workspaces, and a
+     * sweep that guessed would delete other projects' artifacts.
+     */
+    async cleanup(options = {}) {
+        if (!this.config.retention.enabled || this.config.storage.root === null)
+            return undefined;
+        const store = new ArtifactStore({ root: this.config.storage.root });
+        const removed = await store.cleanup({
+            maxAgeDays: this.config.retention.maxAgeDays,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+        if (removed.removed.length > 0) {
+            this.deps.logger.info("documents.retention", {
+                removed: removed.removed.length,
+            });
+        }
+        return removed;
+    }
+}
+/** Build a runtime from raw (schema-parsed) configuration. */
+export function createDocumentRuntime(options) {
+    const withEnv = applyDocumentsEnvOverrides(options.config, options.env ?? process.env);
+    const resolved = resolveDocumentsConfig(withEnv);
+    if (!resolved.enabled) {
+        throw new DocumentError("BACKEND_UNAVAILABLE", "the document subsystem is disabled in this deployment");
+    }
+    return new DocumentRuntime({
+        config: resolved,
+        ...(options.logger === undefined ? {} : { logger: options.logger }),
+        ...(options.seams === undefined ? {} : { seams: options.seams }),
+        ...(options.providers === undefined
+            ? {}
+            : { providers: options.providers }),
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+}
+export { resolveDocumentScope };
+//# sourceMappingURL=runtime.js.map

package/lib/documents/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/documents/runtime.ts"],"names":[],"mappings":"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"}