@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/document-export.mjs

@@ -1,32 +1,136 @@
 /**
- * lib/document-export.mjs — markdown → PDF / DOCX / HTML export via external
- * binaries (Pandoc + Typst), per ADR-0024.
+ * lib/document-export.mjs — artifact export to PDF / DOCX / DOC / deck / PPTX / HTML /
+ * RTF / ODT / EPUB / LaTeX / TXT / MD / MDX via external binaries (Pandoc + Typst,
+ * LibreOffice for legacy .doc, pptxgenjs for PPTX), per ADR-0024.
  *
- * Bound to system-binary tooling discovered at runtime, never bundled in core
- * (ADR-0001 zero-npm-core; ADR-0014 optional-capability pattern). Both engines
- * are spawned as separate processes — Pandoc isolates its GPLv2+ licence at
- * the process boundary; Typst is the Apache-2.0 PDF engine driven through
- * Pandoc's `--pdf-engine=typst` flag, so a single Pandoc invocation produces
- * every target format the contract supports.
- *
- * detect(format) reports availability without spawning the engine for real.
- * exportMarkdown({ inputPath, outputPath, format, env }) spawns the engine and
- * returns a structured result. Both surface actionable "install X" guidance
- * when a required binary is absent; neither throws on missing tooling.
+ * Export **source** is Construct-authored markdown (typed artifacts). **Output**
+ * spans many distributable formats. Ingest (separate pipeline) accepts PDF, Office,
+ * email, AV, and plain text — see docs/reference/document-io.md.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  resolvePdfTemplatePath,
+  parseArtifactMetadata,
+  pandocMetadataArgs,
+  preprocessMarkdownForPdfExport,
+  distributionFontsDir,
+} from './publish-template.mjs';
+import {
+  preprocessMarkdownDiagrams,
+  buildDistributionDiagramEnv,
+  countDiagramFences,
+} from './diagram-export.mjs';
+import { exportDeckPptx, pptxgenPresent } from './deck-export-pptx.mjs';
+import { pdfUsesBundledBrandSans } from './brand-fonts.mjs';
+import { convertDocxToDoc, libreOfficeInstallHint, libreOfficePresent, resolveLibreOfficeBin } from './libreoffice-export.mjs';
+import { resolveExportBranding } from './export-branding.mjs';
+
+export const EXPORT_FORMATS = ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'];
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
-export const EXPORT_FORMATS = ['pdf', 'docx', 'html'];
+// Pandoc drives typeset formats; pptxgenjs builds slide decks; legacy `.doc` has no
+// pandoc writer — export DOCX first, then LibreOffice headless down-converts.
 
 const FORMAT_ENGINES = {
-  pdf: { engine: 'pandoc', pdfEngine: 'typst', extraBinaries: ['typst'] },
-  docx: { engine: 'pandoc', pdfEngine: null, extraBinaries: [] },
-  html: { engine: 'pandoc', pdfEngine: null, extraBinaries: [] },
+  pdf: { engine: 'pandoc', writer: null, pdfEngine: 'typst', extraBinaries: ['typst'] },
+  docx: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
+  doc: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [], via: 'libreoffice', intermediate: 'docx' },
+  deck: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
+  pptx: { engine: 'pptxgenjs', writer: null, pdfEngine: null, extraBinaries: [] },
+  html: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
+  rtf: { engine: 'pandoc', writer: 'rtf', pdfEngine: null, extraBinaries: [] },
+  odt: { engine: 'pandoc', writer: 'odt', pdfEngine: null, extraBinaries: [] },
+  epub: { engine: 'pandoc', writer: 'epub', pdfEngine: null, extraBinaries: [] },
+  tex: { engine: 'pandoc', writer: 'latex', pdfEngine: null, extraBinaries: [] },
+  txt: { engine: 'pandoc', writer: 'plain', pdfEngine: null, extraBinaries: [] },
+  md: { engine: 'copy', writer: null, pdfEngine: null, extraBinaries: [] },
+  mdx: { engine: 'copy', writer: null, pdfEngine: null, extraBinaries: [] },
 };
 
+export function htmlTemplatePath(repoRoot = REPO_ROOT) {
+  const p = path.join(repoRoot, 'templates', 'distribution', 'construct-web.html');
+  return fs.existsSync(p) ? p : null;
+}
+
+export function deckTemplatePath(repoRoot = REPO_ROOT) {
+  const p = path.join(repoRoot, 'templates', 'distribution', 'construct-deck.html');
+  return fs.existsSync(p) ? p : null;
+}
+
+export function docxReferencePath(repoRoot = REPO_ROOT) {
+  const p = path.join(repoRoot, 'templates', 'distribution', 'construct-reference.docx');
+  return fs.existsSync(p) ? p : null;
+}
+
+export { resolvePdfTemplatePath } from './publish-template.mjs';
+
+export function pdfEngineFontOpts(repoRoot = REPO_ROOT) {
+  const fontPath = distributionFontsDir(repoRoot);
+  return [
+    '--pdf-engine-opt', `--font-path=${fontPath}`,
+    '--pdf-engine-opt', '--ignore-system-fonts',
+    '--pdf-engine-opt', '--ignore-embedded-fonts',
+  ];
+}
+
+export function countPdfEmbeddedImages(pdfPath) {
+  try {
+    const data = fs.readFileSync(pdfPath);
+    const text = data.toString('latin1');
+    const raster = (text.match(/\/Subtype\s*\/Image/g) || []).length;
+    const vector = (text.match(/\/Subtype\s*\/Form/g) || []).length;
+    return raster + vector;
+  } catch {
+    return 0;
+  }
+}
+
+export function pdfRenderedDiagrams(pdfPath, sourceContent) {
+  const expected = countDiagramFences(sourceContent);
+  if (expected === 0) return true;
+  const embedded = countPdfEmbeddedImages(pdfPath);
+  if (embedded >= expected) return true;
+  try {
+    const text = fs.readFileSync(pdfPath).toString('latin1');
+    const rawD2 = /direction:\s*(right|down|left|up)/.test(text);
+    const rawMermaid = /flowchart\s+(TD|LR|BT|RL)/.test(text);
+    return !rawD2 && !rawMermaid && embedded > 0;
+  } catch {
+    return false;
+  }
+}
+
+export { pdfUsesBundledBrandSans } from './brand-fonts.mjs';
+
+/** @deprecated use pdfUsesBundledBrandSans */
+export function pdfUsesBundledInter(pdfPath) {
+  return pdfUsesBundledBrandSans(pdfPath);
+}
+
+export function diagramFilterPath() {
+  return path.join(REPO_ROOT, 'vendor', 'pandoc-ext', 'diagram.lua');
+}
+
+export function detectPdfTemplate({
+  artifactType = null,
+  cwd = process.cwd(),
+  repoRoot = REPO_ROOT,
+} = {}) {
+  const templatePath = resolvePdfTemplatePath({ artifactType, cwd, repoRoot });
+  return {
+    present: Boolean(templatePath),
+    path: templatePath,
+    message: templatePath
+      ? `PDF template: ${path.relative(repoRoot, templatePath)}`
+      : 'PDF template missing: templates/distribution/construct-pdf.typ',
+  };
+}
+
 function whichBin(name, env = process.env) {
   const cmd = process.platform === 'win32' ? 'where' : 'which';
   const result = spawnSync(cmd, [name], { encoding: 'utf8', env });
@@ -45,28 +149,90 @@ function binVersion(name, args = ['--version'], env = process.env) {
 function installHint(name) {
   if (name === 'pandoc') return 'Install pandoc to enable document export (e.g. `brew install pandoc` on macOS, `apt install pandoc` on Debian/Ubuntu, or https://pandoc.org/installing.html).';
   if (name === 'typst') return 'Install typst to enable PDF export via Pandoc (`brew install typst` on macOS, https://github.com/typst/typst/releases for binaries).';
+  if (name === 'construct-pdf.typ') return 'Bundled PDF template missing from templates/distribution/construct-pdf.typ (Construct install integrity issue).';
+  if (name === 'd2') return 'Install d2 for diagram blocks (`brew install d2`).';
+  if (name === 'mmdc') return 'Install mermaid-cli for mermaid blocks (`npm install -g @mermaid-js/mermaid-cli`).';
+  if (name === 'pptxgenjs') return 'Install pptxgenjs to enable PPTX export (`npm install pptxgenjs` in the Construct package).';
+  if (name === 'construct-deck.html') return 'Bundled deck template missing from templates/distribution/construct-deck.html (Construct install integrity issue).';
+  if (name === 'construct-reference.docx') return 'Bundled branded reference doc missing from templates/distribution/construct-reference.docx; construct-branded DOCX export degrades to pandoc default styling. Regenerate from a source checkout with `node scripts/build-reference-docx.mjs`.';
+  if (name === 'libreoffice') return libreOfficeInstallHint();
   return `Install ${name} to enable this export format.`;
 }
 
-// detect returns the same structure regardless of format so callers can render
-// availability uniformly. `present` is the single boolean a caller should gate
-// on; `missing` enumerates the binaries to install when present is false.
+export function detect(format, env = process.env, {
+  figures = false,
+  artifactType = null,
+  branding = 'construct',
+  cwd = process.cwd(),
+  repoRoot = REPO_ROOT,
+} = {}) {
+  const brandingPolicy = resolveExportBranding(format, branding);
+  const config = format === 'pptx' && brandingPolicy.applied === 'plain'
+    ? { engine: 'pandoc', writer: 'pptx', pdfEngine: null, extraBinaries: [] }
+    : FORMAT_ENGINES[format];
+  if (!config) return { ok: false, format, branding: brandingPolicy, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+  if (config.engine === 'copy') {
+    return { ok: true, format, branding: brandingPolicy, figures: false, present: true, binaries: [], missing: [], message: `Ready: source emit (${format})` };
+  }
+  const required = [];
+  if (config.engine === 'pptxgenjs') {
+    required.push('pptxgenjs');
+  } else {
+    required.push(config.engine, ...(config.extraBinaries || []));
+  }
+  if (format === 'pdf' && brandingPolicy.applied === 'construct') {
+    const template = detectPdfTemplate({ artifactType, cwd, repoRoot });
+    if (!template.present) required.push('construct-pdf.typ');
+  }
+  if (format === 'deck' && brandingPolicy.applied === 'construct' && !deckTemplatePath(repoRoot)) {
+    required.push('construct-deck.html');
+  }
+  if (format === 'html' && brandingPolicy.applied === 'construct' && !htmlTemplatePath(repoRoot)) required.push('construct-web.html');
+
+  // The DOCX reference doc only restyles pandoc output; pandoc emits a valid file without it and
+  // the export passes --reference-doc only when present, so unlike the PDF/HTML/deck templates a
+  // missing reference degrades gracefully rather than blocking the export.
 
-export function detect(format, env = process.env) {
-  const config = FORMAT_ENGINES[format];
-  if (!config) return { ok: false, format, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
-  const required = [config.engine, ...(config.extraBinaries || [])];
-  const status = required.map((name) => ({ name, path: whichBin(name, env), version: null }));
-  for (const s of status) if (s.path) s.version = binVersion(s.name, ['--version'], env);
+  if (format === 'doc' && !libreOfficePresent(env)) {
+    required.push('libreoffice');
+  }
+  if (figures) {
+    if (!fs.existsSync(diagramFilterPath())) required.push('diagram.lua');
+    if (!whichBin('d2', env) && !whichBin('dot', env)) required.push('d2');
+    if (!whichBin('mmdc', env)) required.push('mmdc');
+  }
+  const status = required.map((name) => {
+    if (name.endsWith('.lua')) {
+      return { name, path: fs.existsSync(diagramFilterPath()) ? diagramFilterPath() : null, version: null };
+    }
+    if (name === 'construct-deck.html') {
+      return { name, path: deckTemplatePath(repoRoot), version: null };
+    }
+    if (name === 'construct-web.html') return { name, path: htmlTemplatePath(repoRoot), version: null };
+    if (name === 'pptxgenjs') {
+      return { name, path: pptxgenPresent() ? 'bundled' : null, version: null };
+    }
+    if (name === 'libreoffice') {
+      return { name, path: libreOfficePresent(env) ? resolveLibreOfficeBin(env) : null, version: null };
+    }
+    return { name, path: whichBin(name, env), version: null };
+  });
+  for (const s of status) {
+    if (s.path && !s.name.endsWith('.lua') && s.name !== 'pptxgenjs' && s.name !== 'libreoffice') {
+      s.version = binVersion(s.name, ['--version'], env);
+    }
+  }
   const missing = status.filter((s) => !s.path).map((s) => s.name);
   return {
     ok: true,
     format,
+    branding: brandingPolicy,
+    figures,
     present: missing.length === 0,
     binaries: status,
     missing,
     message: missing.length === 0
-      ? `Ready: ${status.map((s) => `${s.name} (${s.version?.split(' ').slice(0, 2).join(' ') ?? 'unknown'})`).join(', ')}`
+      ? `Ready: ${status.map((s) => `${s.name} (${s.version?.split(' ').slice(0, 2).join(' ') ?? 'bundled'})`).join(', ')}`
       : missing.map(installHint).join(' '),
   };
 }
@@ -76,31 +242,194 @@ function defaultOutputPath(inputPath, format) {
   return path.join(parsed.dir, `${parsed.name}.${format}`);
 }
 
-// exportMarkdown is the single contract callers depend on (CLI / MCP / SDK).
-// Returns { ok, format, inputPath, outputPath, engine, missing?, message }.
-// ok=false with a populated `missing` means a required binary is absent — the
-// caller surfaces `message` (which carries the install hint) instead of
-// retrying or crashing.
+export function parsePublishFrontmatter(inputPath) {
+  try {
+    const content = fs.readFileSync(inputPath, 'utf8');
+    if (!content.startsWith('---')) return null;
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) return null;
+    const block = content.slice(3, end);
+    const publish = {};
+    let inPublish = false;
+    for (const line of block.split('\n')) {
+      if (/^publish:\s*$/.test(line)) { inPublish = true; continue; }
+      if (inPublish && /^\S/.test(line) && !line.startsWith(' ')) inPublish = false;
+      if (!inPublish) continue;
+      const m = line.match(/^\s+(\w+):\s*(.+)$/);
+      if (m) publish[m[1]] = m[2].replace(/^["']|["']$/g, '').trim();
+    }
+    return Object.keys(publish).length ? publish : null;
+  } catch {
+    return null;
+  }
+}
 
-export function exportMarkdown({ inputPath, outputPath, format, env = process.env, spawnFn = spawnSync } = {}) {
+function prepareExportInput(inputPath, { format = 'html', figures = false, metadata = null } = {}) {
+  let raw = fs.readFileSync(inputPath, 'utf8');
+  let processed = raw;
+  if ((format === 'pdf' || format === 'html') && metadata?.title) {
+    processed = preprocessMarkdownForPdfExport(processed, metadata);
+  }
+  if (figures) {
+    processed = preprocessMarkdownDiagrams(processed);
+  }
+  if (processed === raw) return { inputPath, cleanup: null };
+  const tmp = path.join(path.dirname(inputPath), `.construct-export-${path.basename(inputPath)}`);
+  fs.writeFileSync(tmp, processed, 'utf8');
+  return {
+    inputPath: tmp,
+    cleanup: () => { try { fs.unlinkSync(tmp); } catch { /* skip */ } },
+  };
+}
+
+// md and mdx are emitted straight from the authored source: the artifact already
+// is Markdown, and Construct-authored Markdown is MDX-compatible (fenced diagrams,
+// YAML frontmatter), so no transform is needed beyond writing the target file.
+
+function exportSourceCopy({ inputPath, target, format }) {
+  const content = fs.readFileSync(inputPath, 'utf8');
+  fs.writeFileSync(target, content, 'utf8');
+  return {
+    ok: true,
+    format,
+    inputPath,
+    outputPath: target,
+    engine: 'copy',
+    message: `Wrote ${path.relative(process.cwd(), target)}`,
+  };
+}
+
+export function exportMarkdown({
+  inputPath,
+  outputPath,
+  format,
+  figures = false,
+  branding = 'construct',
+  artifactType = null,
+  env = process.env,
+  spawnFn = spawnSync,
+  cwd = process.cwd(),
+  repoRoot = REPO_ROOT,
+} = {}) {
   if (!inputPath) return { ok: false, format, message: 'exportMarkdown: inputPath is required.' };
   if (!EXPORT_FORMATS.includes(format)) return { ok: false, format, inputPath, message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
   if (!fs.existsSync(inputPath)) return { ok: false, format, inputPath, message: `exportMarkdown: input does not exist: ${inputPath}` };
 
-  const detection = detect(format, env);
+  const metadata = parseArtifactMetadata(inputPath);
+  const resolvedType = artifactType || metadata.artifactType || null;
+  const effectiveEnv = figures ? buildDistributionDiagramEnv(env) : env;
+
+  const brandingPolicy = resolveExportBranding(format, branding);
+  const detection = detect(format, effectiveEnv, { figures, artifactType: resolvedType, branding, cwd, repoRoot });
   if (!detection.present) {
     return { ok: false, format, inputPath, missing: detection.missing, message: detection.message };
   }
 
-  const config = FORMAT_ENGINES[format];
-  const target = outputPath || defaultOutputPath(inputPath, format);
+  const config = format === 'pptx' && brandingPolicy.applied === 'plain'
+    ? { engine: 'pandoc', writer: 'pptx', pdfEngine: null, extraBinaries: [] }
+    : FORMAT_ENGINES[format];
+  const target = path.resolve(outputPath || defaultOutputPath(inputPath, format));
   fs.mkdirSync(path.dirname(target), { recursive: true });
 
+  if (config.engine === 'copy') {
+    return { ...exportSourceCopy({ inputPath, target, format }), branding: brandingPolicy };
+  }
+
+  if (format === 'pptx' && brandingPolicy.applied === 'construct') {
+    return { ...exportDeckPptx({ inputPath, outputPath: target, metadata, repoRoot }), branding: brandingPolicy };
+  }
+
+  if (format === 'doc') {
+    const intermediate = path.join(path.dirname(target), `.construct-export-${path.basename(inputPath, path.extname(inputPath))}.docx`);
+    const docxResult = exportMarkdown({
+      inputPath,
+      outputPath: intermediate,
+      format: 'docx',
+      figures,
+      branding,
+      artifactType: resolvedType,
+      env: effectiveEnv,
+      spawnFn,
+      cwd,
+      repoRoot,
+    });
+    if (!docxResult.ok) return { ...docxResult, format: 'doc' };
+    const loResult = convertDocxToDoc({ docxPath: intermediate, outputPath: target, env: effectiveEnv, spawnFn });
+    try { fs.unlinkSync(intermediate); } catch { /* skip */ }
+    if (!loResult.ok) {
+      return {
+        ok: false,
+        format: 'doc',
+        inputPath,
+        outputPath: target,
+        missing: loResult.missing,
+        message: loResult.message,
+      };
+    }
+    return {
+      ok: true,
+      format: 'doc',
+      inputPath,
+      outputPath: target,
+      engine: 'libreoffice',
+      pdfEngine: null,
+      figures,
+      template: null,
+      branding: brandingPolicy,
+      message: loResult.message,
+    };
+  }
+
+  const prepared = prepareExportInput(inputPath, { format, figures, metadata });
+  const templatePath = format === 'pdf' && brandingPolicy.applied === 'construct'
+    ? resolvePdfTemplatePath({ artifactType: resolvedType, cwd, repoRoot })
+    : null;
+
+  const metadataArgs = pandocMetadataArgs({
+    title: metadata.title,
+    subtitle: metadata.subtitle,
+    date: metadata.date,
+    status: metadata.status,
+    owner: metadata.owner,
+    artifactType: resolvedType || metadata.artifactType,
+    version: metadata.version,
+    docId: metadata.docId,
+    classification: metadata.classification,
+  });
+
   const args = ['-f', 'markdown', '-o', target, '--standalone'];
+  if (config.writer) args.push('-t', config.writer);
   if (config.pdfEngine) args.push(`--pdf-engine=${config.pdfEngine}`);
-  args.push(inputPath);
+  if (format === 'pdf') {
+    if (templatePath) args.push('--template', templatePath);
+    if (brandingPolicy.applied === 'construct') args.push(...pdfEngineFontOpts(repoRoot));
+    args.push(...metadataArgs);
+  } else if (format === 'html') {
+    const htmlTpl = htmlTemplatePath(repoRoot);
+    if (htmlTpl && brandingPolicy.applied === 'construct') args.push('--template', htmlTpl);
+    args.push('--embed-resources');
+    args.push(...metadataArgs);
+  } else if (format === 'deck') {
+    const deckTpl = deckTemplatePath(repoRoot);
+    if (deckTpl && brandingPolicy.applied === 'construct') args.push('--template', deckTpl);
+    args.push('--section-divs');
+    args.push('--embed-resources');
+    args.push(...metadataArgs);
+  } else if (format === 'docx') {
+    const ref = docxReferencePath(repoRoot);
+    if (ref && brandingPolicy.applied === 'construct') args.push('--reference-doc', ref);
+    args.push(...metadataArgs);
+  }
+  if (figures && fs.existsSync(diagramFilterPath())) {
+    args.push('--lua-filter', diagramFilterPath());
+  }
+  args.push(path.resolve(prepared.inputPath));
+
+  const spawnCwd = (format === 'pdf' && templatePath) ? path.dirname(templatePath) : path.dirname(prepared.inputPath);
+
+  const result = spawnFn(config.engine, args, { encoding: 'utf8', env: effectiveEnv, cwd: spawnCwd });
+  if (prepared.cleanup) prepared.cleanup();
 
-  const result = spawnFn(config.engine, args, { encoding: 'utf8', env });
   if (result.status !== 0) {
     return {
       ok: false,
@@ -112,6 +441,20 @@ export function exportMarkdown({ inputPath, outputPath, format, env = process.en
     };
   }
 
+  if (format === 'pdf' && figures) {
+    const source = fs.readFileSync(inputPath, 'utf8');
+    const expectedDiagrams = countDiagramFences(source);
+    if (expectedDiagrams > 0 && !pdfRenderedDiagrams(target, source)) {
+      return {
+        ok: false,
+        format,
+        inputPath,
+        outputPath: target,
+        message: `Export wrote PDF but rendered 0/${expectedDiagrams} diagram(s). Ensure d2 and mmdc are installed; mmdc needs Chrome (set PUPPETEER_EXECUTABLE_PATH or install Google Chrome). Pandoc stderr: ${(result.stderr || '').trim().slice(0, 300)}`,
+      };
+    }
+  }
+
   return {
     ok: true,
     format,
@@ -119,6 +462,9 @@ export function exportMarkdown({ inputPath, outputPath, format, env = process.en
     outputPath: target,
     engine: config.engine,
     pdfEngine: config.pdfEngine,
+    figures,
+    template: templatePath,
+    branding: brandingPolicy,
     message: `Wrote ${path.relative(process.cwd(), target)}`,
   };
 }

package/lib/document-extract.mjs

@@ -45,6 +45,31 @@ export const CALENDAR_EXTS = new Set(['.ics']);
 export const AUDIO_VIDEO_EXTS = new Set(['.mp3', '.wav', '.m4a', '.mp4', '.mov', '.avi', '.mkv', '.flac', '.ogg', '.webm', '.m4v']);
 
 export const ZIP_DOCUMENT_EXTS = new Set(['.docx', '.xlsx', '.pptx', '.odt', '.ods']);
+
+// Office zip formats with no Node-native backend — callers must route through docling
+// or opt into the legacy zip-xml path via CONSTRUCT_ALLOW_LEGACY_EXTRACT=1.
+const OFFICE_REQUIRES_DOCLING_EXTS = new Set(['.xlsx', '.pptx', '.odt', '.ods']);
+
+function legacyExtractAllowed(env = process.env) {
+  return env.CONSTRUCT_ALLOW_LEGACY_EXTRACT === '1';
+}
+
+function makeOfficeRequiresDoclingError(extension) {
+  const err = new Error(
+    `${extension} extraction requires docling. Run \`construct install --with-docling\`, use high-fidelity ingest, or set CONSTRUCT_ALLOW_LEGACY_EXTRACT=1 for the legacy zip-xml path.`,
+  );
+  err.code = 'OFFICE_REQUIRES_DOCLING';
+  err.extension = extension;
+  return err;
+}
+
+function makePdfRequiresDoclingError() {
+  const err = new Error(
+    'PDF extraction requires docling, the node-native unpdf backend, or CONSTRUCT_ALLOW_LEGACY_EXTRACT=1 for pdftotext/PDFKit.',
+  );
+  err.code = 'PDF_REQUIRES_DOCLING';
+  return err;
+}
 export const RICH_TEXT_EXTS = new Set(['.doc', '.rtf']);
 export const MDLS_DOCUMENT_EXTS = new Set(['.xls', '.ppt', '.pages', '.numbers', '.key']);
 export const EMAIL_DOCUMENT_EXTS = new Set(['.eml', '.msg']);
@@ -685,6 +710,9 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
     const envelope = extractCalendar(resolvedPath);
     extracted = { text: envelope.text, method: 'ics', droppedInfo: envelope.droppedInfo, structured: envelope.structured };
   } else if (ZIP_DOCUMENT_EXTS.has(extension)) {
+    if (!legacyExtractAllowed()) {
+      throw makeOfficeRequiresDoclingError(extension);
+    }
     extracted = extractZipDocument(resolvedPath, extension);
   } else if (RICH_TEXT_EXTS.has(extension)) {
     extracted = extractRichText(resolvedPath, extension);
@@ -693,6 +721,9 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   } else if (EMAIL_DOCUMENT_EXTS.has(extension)) {
     extracted = extractEml(resolvedPath);
   } else if (extension === '.pdf') {
+    if (!legacyExtractAllowed()) {
+      throw makePdfRequiresDoclingError();
+    }
     extracted = extractPdf(resolvedPath);
   } else {
     throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
@@ -731,9 +762,9 @@ function buildExtractionResult(resolvedPath, extension, extracted, maxChars) {
 }
 
 // Node-native extraction for the everyday adapter path: unpdf (PDF) and mammoth
-// (DOCX) are optional pure-JS deps, so plain documents ingest with no Python venv
-// and no system binary. Missing dep, an empty parse, or any other type delegates
-// to the sync system-binary extractor — the choice degrades, never fails hard.
+// (DOCX) are optional pure-JS deps. XLSX/PPTX/ODT/ODS have no Node backend and
+// fail loud with OFFICE_REQUIRES_DOCLING. Legacy zip-xml and pdftotext paths run
+// only when CONSTRUCT_ALLOW_LEGACY_EXTRACT=1; otherwise extraction errors clearly.
 
 async function extractWithUnpdf(filePath) {
   const { extractText, getDocumentProxy } = await import('unpdf');
@@ -753,6 +784,10 @@ export async function extractDocumentTextNodeNative(filePath, { maxChars = null
   if (!existsSync(resolvedPath)) throw new Error(`File not found: ${resolvedPath}`);
   const extension = extname(resolvedPath).toLowerCase();
 
+  if (OFFICE_REQUIRES_DOCLING_EXTS.has(extension)) {
+    throw makeOfficeRequiresDoclingError(extension);
+  }
+
   const nodeBackend = extension === '.pdf' ? { fn: extractWithUnpdf, method: 'unpdf' }
     : extension === '.docx' ? { fn: extractWithMammoth, method: 'mammoth' }
       : null;
@@ -763,7 +798,12 @@ export async function extractDocumentTextNodeNative(filePath, { maxChars = null
       if (text) {
         return buildExtractionResult(resolvedPath, extension, { text, method: nodeBackend.method, droppedInfo: [], structured: null }, maxChars);
       }
-    } catch { /* optional dep absent or parse failure — fall through to the sync extractor */ }
+    } catch { /* optional dep absent or parse failure — legacy path only when explicitly allowed */ }
+    if (!legacyExtractAllowed()) {
+      if (extension === '.docx') throw makeOfficeRequiresDoclingError(extension);
+      throw makePdfRequiresDoclingError();
+    }
+    return extractDocumentText(resolvedPath, { maxChars });
   }
 
   return extractDocumentText(resolvedPath, { maxChars });