@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/certification/cli.mjs

@@ -0,0 +1,191 @@
+/**
+ * lib/certification/cli.mjs — certification scenario inspection and execution.
+ */
+
+import { listScenarios } from './scenarios.mjs';
+import { buildCertificationStatus, formatCertificationStatus } from './status.mjs';
+import { loadCanonicalScenarios, validateCanonicalScenarios } from './canonical-scenarios.mjs';
+import { listCertificationModels } from './model-routing.mjs';
+import { LIVE_OPT_IN_ENV, previewCertificationRun, runCertificationScenario } from './runner.mjs';
+import {
+  listCertificationRunIds,
+  readCertificationRun,
+} from './store.mjs';
+import { formatReleaseCandidateGate, runReleaseCandidateGate } from './rc-gate.mjs';
+import { buildDemoParityReport, writeDemoParityReport } from './demo-parity.mjs';
+
+function printUsage() {
+  process.stderr.write(
+    'Usage: construct certify <list|show|scenarios|models|demos|parity|status|gate|run> …\n' +
+    '  status [--json] [capability-id]  (omit id for full rollup; pass capability id for detail)\n' +
+    '  gate [--json]  (release candidate certification freshness; blocks stale or failing release capabilities)\n' +
+    '  parity [--json] [--write]  (cross-surface demo parity report; --write persists under tests/certification/demos/)\n' +
+    `  run <scenario-id> [--dry-run] [--json]  (live scenarios require ${LIVE_OPT_IN_ENV}=1)\n` +
+    '  models [--json]  (lists routable models; paid models require CONSTRUCT_CERTIFY_ALLOW_PAID=1)\n' +
+    '  demos [--json]  (canonical demo scenario catalog for Tauri/web/VHS parity)\n',
+  );
+}
+
+export async function runCertificationCli(args = [], { projectDir = process.cwd(), repoRoot = projectDir, env = process.env } = {}) {
+  const sub = args[0] || 'list';
+  const rest = args.slice(1);
+
+  if (sub === 'list') {
+    const ids = listCertificationRunIds({ rootDir: projectDir });
+    if (rest.includes('--json')) {
+      process.stdout.write(`${JSON.stringify(ids, null, 2)}\n`);
+      return 0;
+    }
+    if (!ids.length) {
+      process.stdout.write('No certification runs recorded under .cx/certification/runs/\n');
+      return 0;
+    }
+    for (const id of ids) process.stdout.write(`${id}\n`);
+    return 0;
+  }
+
+  if (sub === 'models') {
+    const models = listCertificationModels({ env }).map((entry) => ({
+      id: entry.id,
+      tier: entry.tier,
+      resolvedId: entry.resolvedId,
+      label: entry.label,
+    }));
+    if (rest.includes('--json')) {
+      process.stdout.write(`${JSON.stringify(models, null, 2)}\n`);
+      return 0;
+    }
+    for (const model of models) {
+      process.stdout.write(`${model.tier.padEnd(16)} ${model.id}\n`);
+    }
+    return 0;
+  }
+
+  if (sub === 'demos') {
+    const { catalog } = loadCanonicalScenarios({ rootDir: repoRoot });
+    const validation = validateCanonicalScenarios({ rootDir: repoRoot, catalog });
+    if (rest.includes('--json')) {
+      process.stdout.write(`${JSON.stringify({ ...catalog, validation }, null, 2)}\n`);
+      return validation.pass ? 0 : 1;
+    }
+    for (const demo of catalog.demos ?? []) {
+      process.stdout.write(`${demo.id}  tape=${demo.tape ?? demo.tapePath}\n`);
+    }
+    if (!validation.pass) {
+      for (const err of validation.errors) process.stderr.write(`error: ${err}\n`);
+      return 1;
+    }
+    return 0;
+  }
+
+  if (sub === 'parity') {
+    const json = rest.includes('--json');
+    const report = rest.includes('--write')
+      ? writeDemoParityReport({ rootDir: repoRoot }).report
+      : buildDemoParityReport({ rootDir: repoRoot });
+    if (json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      return report.pass ? 0 : 1;
+    }
+    process.stdout.write(`Demo parity: ${report.pass ? 'PASS' : 'FAIL'} (${report.demoCount} demos)\n`);
+    if (report.mismatches.length) {
+      for (const mismatch of report.mismatches) {
+        process.stderr.write(`  ${mismatch.demoId}/${mismatch.surface}: ${mismatch.detail}\n`);
+      }
+    }
+    return report.pass ? 0 : 1;
+  }
+
+  if (sub === 'scenarios') {
+    const scenarios = listScenarios({ repoRoot }).map((entry) => {
+      const preview = previewCertificationRun(entry.id, { repoRoot, env });
+      return {
+        id: entry.id,
+        capabilityId: entry.capabilityId,
+        mode: entry.mode ?? 'hermetic',
+        requiresEnv: entry.requiresEnv ?? null,
+        modelTier: preview.model.tier,
+        modelSummary: preview.modelSummary,
+      };
+    });
+    if (rest.includes('--json')) {
+      process.stdout.write(`${JSON.stringify(scenarios, null, 2)}\n`);
+      return 0;
+    }
+    for (const scenario of scenarios) {
+      const live = scenario.mode === 'live' ? ` live(${scenario.requiresEnv ?? LIVE_OPT_IN_ENV}=1)` : '';
+      process.stdout.write(`${scenario.id}  ${scenario.capabilityId}${live}  ${scenario.modelSummary}\n`);
+    }
+    return 0;
+  }
+
+  if (sub === 'status') {
+    const json = rest.includes('--json');
+    const capabilityId = rest.find((arg) => !arg.startsWith('-')) ?? null;
+    const report = buildCertificationStatus({ rootDir: repoRoot, capabilityId });
+    if (json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      return 0;
+    }
+    formatCertificationStatus(report, { capabilityId });
+    process.stdout.write('\n');
+    return 0;
+  }
+
+  if (sub === 'show') {
+    const target = rest.find((arg) => !arg.startsWith('-'));
+    if (!target) {
+      process.stderr.write('Usage: construct certify show <run-id|capability-id> [--json]\n');
+      return 1;
+    }
+    const json = rest.includes('--json');
+    if (target.startsWith('cert-')) {
+      const { run } = readCertificationRun(target, { rootDir: projectDir });
+      process.stdout.write(`${JSON.stringify(run, null, 2)}\n`);
+      return 0;
+    }
+    const report = buildCertificationStatus({ rootDir: repoRoot, capabilityId: target });
+    if (json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      return 0;
+    }
+    formatCertificationStatus(report, { capabilityId: target });
+    process.stdout.write('\n');
+    return 0;
+  }
+
+  if (sub === 'gate') {
+    const json = rest.includes('--json');
+    const result = await runReleaseCandidateGate({ rootDir: repoRoot, projectDir, env });
+    if (json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      return result.pass ? 0 : 1;
+    }
+    process.stdout.write(formatReleaseCandidateGate(result));
+    return result.pass ? 0 : 1;
+  }
+
+  if (sub === 'run') {
+    const scenarioId = rest.find((arg) => !arg.startsWith('-'));
+    if (!scenarioId) {
+      process.stderr.write(`Usage: construct certify run <scenario-id> [--dry-run] [--json]\n`);
+      return 1;
+    }
+    const dryRun = rest.includes('--dry-run');
+    const preview = previewCertificationRun(scenarioId, { repoRoot, env });
+    if (!rest.includes('--json')) {
+      process.stdout.write(`${preview.modelSummary}\n`);
+    }
+    const result = await runCertificationScenario(scenarioId, { projectDir, repoRoot, env, dryRun });
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(result.run, null, 2)}\n`);
+    else {
+      process.stdout.write(`scenario: ${result.run.scenarioId}\n`);
+      process.stdout.write(`verdict: ${result.run.verdict.status} (${result.run.verdict.source})\n`);
+      if (!dryRun) process.stdout.write(`run-id: ${result.run.id}\n`);
+    }
+    return result.exitCode ?? 1;
+  }
+
+  printUsage();
+  return 1;
+}

package/lib/certification/dashboard-api.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/certification/dashboard-api.mjs — dashboard-safe certification status payload.
+ *
+ * Mirrors construct certify status for GET /api/certification/status without secrets.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { buildCertificationStatus } from './status.mjs';
+import { loadCertificationStatus } from './stale-impact.mjs';
+import { certificationRunDir, certificationRunsRoot, listCertificationRunIds, readCertificationRun } from './store.mjs';
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+function buildStaleRows({ rootDir }) {
+  const { status } = loadCertificationStatus({ rootDir });
+  if (!status?.capabilities) return [];
+  return Object.entries(status.capabilities)
+    .filter(([, entry]) => entry.status === 'stale')
+    .map(([capabilityId, entry]) => ({
+      capabilityId,
+      staleSince: entry.staleSince ?? null,
+      staleReason: entry.staleReason ?? null,
+      stalePaths: entry.stalePaths ?? [],
+    }));
+}
+
+export function buildCertificationDashboard({ rootDir = process.cwd() } = {}) {
+  const root = findConstructRoot(rootDir);
+  const report = buildCertificationStatus({ rootDir: root });
+  const runs = [];
+  for (const runId of listCertificationRunIds({ rootDir: root }).slice(-20)) {
+    try {
+      const { run } = readCertificationRun(runId, { rootDir: root });
+      const dir = certificationRunDir(runId, root);
+      runs.push({
+        id: run.id,
+        scenarioId: run.scenarioId,
+        capabilityId: run.capabilityId,
+        status: run.verdict?.status ?? 'unknown',
+        createdAt: run.createdAt,
+        artifactPath: path.relative(root, path.join(dir, 'run.json')),
+      });
+    } catch { /* skip corrupt */ }
+  }
+  return {
+    generatedAt: report.generatedAt,
+    capabilities: report.capabilities,
+    specialists: report.specialists,
+    skills: report.skills,
+    artifactTypes: report.artifactTypes,
+    documentCategories: report.documentCategories,
+    demos: report.demos,
+    stale: buildStaleRows({ rootDir: root }),
+    runs,
+    runsDir: path.relative(root, certificationRunsRoot(root)),
+    artifactLinks: {
+      runsRoot: '.cx/certification/runs',
+      recentRunIds: runs.map((r) => r.id),
+    },
+  };
+}

package/lib/certification/demo-parity.mjs

@@ -0,0 +1,116 @@
+/**
+ * lib/certification/demo-parity.mjs — cross-surface demo parity report generator.
+ *
+ * Compares Tauri, web cockpit, and VHS terminal harness markers for each canonical
+ * demo. Mismatches are recorded for follow-up beads; acceptable divergences cite
+ * platform constraints with evidence paths.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { loadCanonicalScenarios } from './canonical-scenarios.mjs';
+
+const SURFACE_MARKERS = Object.freeze({
+  tauri: {
+    label: 'Tauri desktop',
+    probe: (root, demo) => {
+      const launcher = path.join(root, 'tests/functional/chat-desktop-launcher.functional.test.mjs');
+      if (!fs.existsSync(launcher)) return { ok: false, detail: 'missing desktop launcher test' };
+      const src = fs.readFileSync(launcher, 'utf8');
+      return { ok: /surface=desktop/.test(src), detail: launcher };
+    },
+  },
+  web: {
+    label: 'Web cockpit',
+    probe: (root, demo) => {
+      const routeStrip = path.join(root, 'apps/chat/web/components/route-strip.tsx');
+      const tokens = path.join(root, 'apps/chat/web/theme/tokens.css');
+      if (!fs.existsSync(routeStrip) || !fs.existsSync(tokens)) {
+        return { ok: false, detail: 'missing web cockpit markers' };
+      }
+      return { ok: true, detail: routeStrip };
+    },
+  },
+  terminal: {
+    label: 'VHS terminal',
+    probe: (root, demo) => {
+      const tape = demo.tape ?? demo.tapePath;
+      if (!tape) return { ok: false, detail: 'demo missing tape path' };
+      const abs = path.join(root, tape);
+      return { ok: fs.existsSync(abs), detail: abs };
+    },
+  },
+});
+
+const ACCEPTABLE_DIVERGENCES = Object.freeze([
+  {
+    id: 'tauri-native-chrome',
+    surface: 'tauri',
+    reason: 'Desktop shell uses native window chrome; web uses browser viewport.',
+    evidence: 'apps/chat/desktop/',
+  },
+  {
+    id: 'vhs-terminal-only',
+    surface: 'terminal',
+    reason: 'VHS tapes assert terminal UX; Tauri/web use GUI interaction models.',
+    evidence: 'templates/demos/tapes/',
+  },
+]);
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+export function buildDemoParityReport({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const { catalog } = loadCanonicalScenarios({ rootDir: root });
+  const demos = [];
+  const mismatches = [];
+
+  for (const demo of catalog.demos ?? []) {
+    const surfaces = {};
+    for (const [surfaceId, marker] of Object.entries(SURFACE_MARKERS)) {
+      const result = marker.probe(root, demo);
+      surfaces[surfaceId] = {
+        label: marker.label,
+        ok: result.ok,
+        evidence: result.detail,
+      };
+      if (!result.ok) {
+        mismatches.push({
+          demoId: demo.id,
+          surface: surfaceId,
+          detail: result.detail,
+          followUpBead: `construct-xp5k.7.5:${demo.id}:${surfaceId}`,
+        });
+      }
+    }
+    demos.push({ id: demo.id, capabilityId: demo.capabilityId, surfaces });
+  }
+
+  return {
+    schema: 'construct/certification/demo-parity/1',
+    generatedAt: new Date().toISOString(),
+    demoCount: demos.length,
+    pass: mismatches.length === 0,
+    demos,
+    mismatches,
+    acceptableDivergences: ACCEPTABLE_DIVERGENCES,
+  };
+}
+
+export function writeDemoParityReport({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const report = buildDemoParityReport({ rootDir: root });
+  const out = path.join(root, 'tests', 'certification', 'demos', 'parity-report.json');
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`);
+  return { path: out, report };
+}

package/lib/certification/document-io-fixtures.mjs

@@ -0,0 +1,246 @@
+/**
+ * lib/certification/document-io-fixtures.mjs — intake fixture catalog for document I/O tests.
+ *
+ * Maps docs/reference/document-io.md supported intake categories to committed
+ * files under tests/fixtures/document-io/<category>/.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json')) && fs.existsSync(path.join(current, 'tests'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+export const DOCUMENT_IO_CATEGORIES = Object.freeze([
+  {
+    id: 'plain-text',
+    label: 'Plain text / code',
+    extensions: ['.md', '.txt', '.json', '.yaml', '.csv', '.html', '.xml'],
+    files: ['sample.md', 'sample.txt', 'sample.json', 'sample.yaml', 'sample.csv', 'sample.html', 'sample.xml'],
+  },
+  {
+    id: 'transcripts',
+    label: 'Transcripts',
+    extensions: ['.vtt', '.srt', '.lrc'],
+    files: ['sample.vtt', 'sample.srt', 'sample.lrc'],
+  },
+  {
+    id: 'calendar',
+    label: 'Calendar',
+    extensions: ['.ics'],
+    files: ['sample.ics'],
+  },
+  {
+    id: 'email',
+    label: 'Email',
+    extensions: ['.eml', '.msg'],
+    files: ['sample.eml', 'sample.msg'],
+  },
+  {
+    id: 'pdf',
+    label: 'PDF',
+    extensions: ['.pdf'],
+    files: ['sample.pdf'],
+  },
+  {
+    id: 'word',
+    label: 'Word',
+    extensions: ['.docx', '.doc'],
+    files: ['sample.docx', 'sample.doc'],
+  },
+  {
+    id: 'excel',
+    label: 'Excel',
+    extensions: ['.xlsx', '.xls', '.ods'],
+    files: ['sample.xlsx', 'sample.xls', 'sample.ods'],
+  },
+  {
+    id: 'powerpoint',
+    label: 'PowerPoint',
+    extensions: ['.pptx', '.ppt'],
+    files: ['sample.pptx', 'sample.ppt'],
+  },
+  {
+    id: 'rich-text',
+    label: 'Rich text',
+    extensions: ['.rtf'],
+    files: ['sample.rtf'],
+  },
+  {
+    id: 'apple-iwork',
+    label: 'Apple iWork',
+    extensions: ['.pages', '.numbers', '.key'],
+    files: ['sample.pages', 'sample.numbers', 'sample.key'],
+  },
+  {
+    id: 'audio-video',
+    label: 'Audio/video',
+    extensions: ['.mp3', '.wav', '.mp4', '.mov'],
+    files: ['sample.mp3', 'sample.wav', 'sample.mp4', 'sample.mov'],
+  },
+  {
+    id: 'unsupported',
+    label: 'Unsupported (negative)',
+    extensions: ['.xyz'],
+    files: ['sample.xyz'],
+    negative: true,
+  },
+]);
+
+export function documentIoFixtureRoot(rootDir = process.cwd()) {
+  return path.join(findConstructRoot(rootDir), 'tests', 'fixtures', 'document-io');
+}
+
+export function documentIoFixturePath(categoryId, fileName, { rootDir } = {}) {
+  return path.join(documentIoFixtureRoot(rootDir), categoryId, fileName);
+}
+
+export function validateDocumentIoFixtures({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const errors = [];
+  for (const category of DOCUMENT_IO_CATEGORIES) {
+    for (const file of category.files) {
+      const abs = documentIoFixturePath(category.id, file, { rootDir: root });
+      if (!fs.existsSync(abs)) errors.push(`missing fixture: tests/fixtures/document-io/${category.id}/${file}`);
+    }
+  }
+  return {
+    categoryCount: DOCUMENT_IO_CATEGORIES.length,
+    errors,
+    pass: errors.length === 0,
+  };
+}
+
+export function writeDocumentIoFixtures({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const base = documentIoFixtureRoot(root);
+
+  const samples = {
+    'plain-text/sample.md': '# Fixture\n\nDocument I/O plain-text sample.\n',
+    'plain-text/sample.txt': 'Document I/O plain-text fixture.\n',
+    'plain-text/sample.json': '{"fixture": "document-io", "category": "plain-text"}\n',
+    'plain-text/sample.yaml': 'fixture: document-io\ncategory: plain-text\n',
+    'plain-text/sample.csv': 'name,value\nfixture,1\n',
+    'plain-text/sample.html': '<!doctype html><html><body><p>Document I/O fixture</p></body></html>\n',
+    'plain-text/sample.xml': '<?xml version="1.0"?><fixture category="plain-text">document-io</fixture>\n',
+    'transcripts/sample.vtt': 'WEBVTT\n\n00:00:00.000 --> 00:00:02.000\nDocument I/O transcript fixture.\n',
+    'transcripts/sample.srt': '1\n00:00:00,000 --> 00:00:02,000\nDocument I/O transcript fixture.\n',
+    'transcripts/sample.lrc': '[00:00.00]Document I/O transcript fixture.\n',
+    'calendar/sample.ics': [
+      'BEGIN:VCALENDAR',
+      'VERSION:2.0',
+      'BEGIN:VEVENT',
+      'UID:fixture-document-io@construct',
+      'DTSTART:20260622T120000Z',
+      'SUMMARY:Document I/O calendar fixture',
+      'END:VEVENT',
+      'END:VCALENDAR',
+      '',
+    ].join('\n'),
+    'email/sample.eml': [
+      'From: fixture@construct.test',
+      'To: intake@construct.test',
+      'Subject: Document I/O email fixture',
+      'Content-Type: text/plain; charset=utf-8',
+      '',
+      'Email body for document-io fixture.',
+      '',
+    ].join('\n'),
+    'email/sample.msg': 'MSG fixture stub — binary Outlook format not generated in tests.\n',
+    'pdf/sample.pdf': '%PDF-1.1\n1 0 obj<<>>endobj\ntrailer<<>>\n%%EOF\n',
+    'word/sample.doc': 'DOC fixture stub for docling-only legacy format.\n',
+    'rich-text/sample.rtf': '{\\rtf1\\ansi Document I/O RTF fixture.}\n',
+    'apple-iwork/sample.pages': 'iWork pages fixture stub for docling path.\n',
+    'apple-iwork/sample.numbers': 'iWork numbers fixture stub for docling path.\n',
+    'apple-iwork/sample.key': 'iWork key fixture stub for docling path.\n',
+    'audio-video/sample.mp3': 'ID3fixture',
+    'audio-video/sample.wav': 'RIFF....WAVEfmt ',
+    'audio-video/sample.mp4': '....ftypmp42',
+    'audio-video/sample.mov': '....ftypqt  ',
+    'unsupported/sample.xyz': 'unsupported extension negative fixture\n',
+  };
+
+  const minimalZip = (content) => {
+    const crcTable = [];
+    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);
+      crcTable[n] = c;
+    }
+    const crc32 = (buf) => {
+      let c = 0xffffffff;
+      for (let i = 0; i < buf.length; i += 1) c = crcTable[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+      return (c ^ 0xffffffff) >>> 0;
+    };
+    const name = Buffer.from('word/document.xml', 'utf8');
+    const data = Buffer.from(content, 'utf8');
+    const crc = crc32(data);
+    const local = Buffer.alloc(30 + name.length + data.length);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(10, 4);
+    local.writeUInt16LE(0, 6);
+    local.writeUInt16LE(0, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(0, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(data.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    name.copy(local, 30);
+    data.copy(local, 30 + name.length);
+    const central = Buffer.alloc(46 + name.length);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(10, 6);
+    central.writeUInt16LE(0, 8);
+    central.writeUInt16LE(0, 10);
+    central.writeUInt16LE(0, 12);
+    central.writeUInt16LE(0, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(data.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(0, 38);
+    central.writeUInt32LE(0, 42);
+    name.copy(central, 46);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(0, 4);
+    end.writeUInt16LE(0, 6);
+    end.writeUInt16LE(1, 8);
+    end.writeUInt16LE(1, 10);
+    end.writeUInt32LE(central.length, 12);
+    end.writeUInt32LE(local.length, 16);
+    end.writeUInt16LE(0, 20);
+    return Buffer.concat([local, central, end]);
+  };
+
+  const officeXml = '<?xml version="1.0"?><fixture>document-io</fixture>';
+  samples['word/sample.docx'] = minimalZip(officeXml);
+  samples['excel/sample.xlsx'] = minimalZip(officeXml);
+  samples['excel/sample.xls'] = 'XLS fixture stub for docling path.\n';
+  samples['excel/sample.ods'] = minimalZip(officeXml);
+  samples['powerpoint/sample.pptx'] = minimalZip(officeXml);
+  samples['powerpoint/sample.ppt'] = 'PPT fixture stub for docling path.\n';
+
+  const written = [];
+  for (const [rel, content] of Object.entries(samples)) {
+    const abs = path.join(base, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+    written.push(`tests/fixtures/document-io/${rel}`);
+  }
+  return { written };
+}