@md2nativedocx/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# @md2nativedocx/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convert **Markdown to native Word (`.docx`)** — a complete document conversion (text, tables, footnotes, math)
+in which every embedded **Mermaid** diagram becomes real Word objects (editable OOXML shapes, SmartArt, charts),
+not flattened PNGs. (`md` = Markdown, the input; *native* describes the Word output.) Standalone CLI counterpart to the
+[md2nativedocx VS Code extension](https://marketplace.visualstudio.com/items?itemName=md2nativedocx.md2nativedocx),
+useful for CI pipelines, scripts, Git hooks, or any editor other than VS Code.
+
+Full project: <https://github.com/nicolasbridelance/md2nativedocx>
+
+## Requirements
+
+- Node.js 18+
+- [Pandoc](https://pandoc.org) 3.1.3+ on `PATH` (or point `MD2NATIVEDOCX_PANDOC_BIN` at a specific
+  binary). Unlike the VS Code extension, this standalone CLI does not auto-download Pandoc for you.
+
+## Install
+
+```sh
+npm install -g @md2nativedocx/cli
+```
+
+## Usage
+
+```sh
+md2nativedocx report.md -o report.docx
+```
+
+```
+Usage: md2nativedocx <input.md> -o <output.docx> [options]
+
+Options:
+  -o, --output <file>   Output .docx path (required)
+  -h, --help            Show this help
+```
+
+Every ` ```mermaid ` code block in the Markdown becomes native, editable Word objects, never an embedded
+image: a SmartArt graphic when the diagram fits one (processes, cycles, org charts, mindmaps, timelines,
+kanban boards…), a Word chart with editable data for `pie`, `xychart` and `radar`, and individually
+selectable shapes otherwise. Everything else (headings, tables, lists, LaTeX math, ...) is handled by
+Pandoc as usual. Per-type detail:
+[`docs/coverage.md`](https://github.com/nicolasbridelance/md2nativedocx/blob/main/docs/coverage.md).
+
+| Variable | Effect |
+|---|---|
+| `MD2NATIVEDOCX_ENABLE_SMARTART=0` | No SmartArt: every diagram as shapes |
+| `MD2NATIVEDOCX_NATIVE_CHARTS=0` (or `pie,xychart`) | No Word charts (or only those types) |
+| `MD2NATIVEDOCX_SMARTART_STYLE` | SmartArt look: `simple`, `subtle`, `moderate`, `intense-accent`, `colorful` (default), `colorful-moderate`, `intense` |
+
+## Configuration
+
+Page layout, typography, table of contents, and other export options are set via environment
+variables (the same ones the VS Code extension's settings map to) — see
+[`docs/specs/export_customization_SPEC.md`](https://github.com/nicolasbridelance/md2nativedocx/blob/main/docs/specs/export_customization_SPEC.md)
+in the main repository for the full list.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Written. Diagram warnings, if any, are on stderr and in the `.log` next to the output. |
+| `1` | No document: input file not found, Pandoc missing or failed, post-processing failed. |
+| `2` | Bad command line: unknown option, missing input or `-o`, a path outside the working directory. |
+
+## From Node: `convert()`
+
+The same conversion as a function, for a Node application, a build script or a server, without spawning
+the CLI. Pandoc must still be installed.
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { convert, ConversionError } from '@md2nativedocx/cli';
+
+const { document, warnings } = await convert('# Report\n\n```mermaid\ngraph LR\n  A --> B\n```\n', {
+  layout: { pageSize: 'A4', margins: 'narrow' },
+  toc: true,
+});
+await writeFile('report.docx', document);
+```
+
+`convert()` takes Markdown text, or `{ path }` of a file, and resolves to `{ document, warnings,
+pandocStderr }`; `document` is the `.docx` as a `Buffer`. It reads no environment variable: every setting
+is an option (types in `src/convert.d.mts`, mirroring the variables above). A failure is a
+`ConversionError` whose `stage` is `setup`, `pandoc` or `postprocess`. To render a single diagram without
+Pandoc, use `renderDiagram()` from `@md2nativedocx/core`.
+
+## License
+
+CC0-1.0 (public domain). See the [main repository](https://github.com/nicolasbridelance/md2nativedocx)
+for compliance/licensing details, including third-party notices for Pandoc (GPL-2.0-or-later,
+invoked as a separate subprocess, never bundled).

package/assets/README.md

@@ -0,0 +1,27 @@
+# `reference.docx`
+
+Passed to Pandoc via `--reference-doc` so generated documents use Word's current default look
+(Aptos font scheme, modern "Office" theme colors, flat non-bold heading hierarchy) instead of
+Pandoc's own bundled default, which is the original 2007-2010 Office theme verbatim (Calibri
+headings / Cambria body, bold colored H1-H3, accent1 `#4F81BD`) — confirmed by inspecting
+Pandoc 3.1.3's `--print-default-data-file reference.docx` directly, not assumed.
+
+No real Word install was available to generate this by hand (the usual method: open Pandoc's
+default reference.docx in Word, tweak styles via the UI, save). Built instead by editing the
+OOXML directly:
+
+- `word/theme/theme1.xml`: `majorFont`/`minorFont` latin typeface set to `Aptos Display`/`Aptos`;
+  color scheme swapped from the 2007 palette to the modern one (`accent1` `#4472C4`, etc.).
+- `word/styles.xml`: `docDefaults` body text 12pt → 11pt, paragraph spacing single/10pt-after →
+  1.08 line spacing/8pt-after (Word's actual `Normal.dotm` defaults since the 2013 theme, not
+  changed by the later Aptos font rollout); `Heading1`-`Heading3` no longer bold, `Heading4`-
+  `Heading5` no longer italic (the 2007 theme's bold/italic emphasis ladder isn't how the current
+  built-in Word style gallery renders headings); heading/hyperlink accent colors updated to match.
+
+**Assumptions to verify in a real Word** (no Word install in this environment — verified so far
+only structurally, via `xmllint`, and visually via LibreOffice, which substitutes a fallback font
+since Aptos isn't installed here either): the exact non-bold/non-italic heading styling, and
+whether Word's *current* built-in template still matches this reconstruction if Microsoft has
+changed it again since. Regenerate by editing `word/theme/theme1.xml` and `word/styles.xml` the
+same way if it needs correcting — no other part of this file matters (do not hand-edit
+`document.xml`, numbering, or anything else in the package).

package/bin/md2nativedocx.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+/**
+ * md2nativedocx CLI.
+ *
+ * `npx md2nativedocx rapport.md -o rapport.docx` packages the Pandoc invocation
+ * with the md2nativedocx Lua filter, producing a .docx with native, editable
+ * OOXML vector shapes for every ```mermaid block — or, for a flowchart shape
+ * `classifyTopology()` accepts (chain/tree/cycle, spec §4), an editable native
+ * SmartArt diagram instead (spec §7 step 5). See postprocess.mjs's
+ * `injectSmartArtParts` doc comment for how that dispatch is wired end to end.
+ *
+ * The conversion itself is `convert()` (src/convert.mjs), the package's
+ * library entry point; this file only reads the `MD2NATIVEDOCX_*` variables
+ * into its options (src/envOptions.mjs), handles files and arguments, and
+ * reports warnings, errors and the Word compatibility check.
+ *
+ * Security (AGENTS.md):
+ *   * Rule #4: Pandoc is invoked via execFile with an argument array — never a
+ *     shell string that interpolates a file path (src/convert.mjs).
+ *   * Path traversal: input/output paths are resolved and validated against the
+ *     expected root before any file operation.
+ *   * Errors are typed (ParseError/TranslationError) and mapped to exit codes.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { basename, extname } from 'node:path';
+import { existsSync, writeFileSync } from 'node:fs';
+import { CliError, resolveSafePath } from '../src/cliSupport.mjs';
+import { ConversionError, convert } from '../src/convert.mjs';
+import { hasLayoutOptions, readConvertOptionsFromEnv } from '../src/envOptions.mjs';
+
+// `-o something.pptx` takes the Pandoc-free deck path (packages/pptx), dispatched before anything a
+// .docx export needs.
+{
+  const argv = process.argv.slice(2);
+  const outIndex = argv.findIndex((a) => a === '-o' || a === '--output');
+  if (outIndex !== -1 && /\.pptx$/i.test(argv[outIndex + 1] ?? '')) {
+    const { runPptxCli } = await import('../src/pptxExport.mjs');
+    process.exit(await runPptxCli(argv, process.cwd()));
+  }
+}
+
+const USAGE = `Usage: md2nativedocx <input.md> -o <output.docx|output.pptx> [options]
+
+A .pptx output is a slide deck: one slide per \`\`\`mermaid block, titled with the nearest
+preceding heading (text outside diagrams is not exported).
+
+Options:
+  -o, --output <file>   Output .docx or .pptx path (required)
+  --show-source         .pptx only: show each diagram's Mermaid source beside it
+  -h, --help            Show this help
+`;
+
+function parseArgs(argv) {
+  const args = { input: null, output: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') {
+      args.help = true;
+    } else if (a === '-o' || a === '--output') {
+      args.output = argv[++i];
+      if (!args.output) throw new CliError('Missing value for --output', 2);
+    } else if (a.startsWith('-')) {
+      throw new CliError(`Unknown option: ${a}`, 2);
+    } else if (args.input === null) {
+      args.input = a;
+    } else {
+      throw new CliError(`Unexpected argument: ${a}`, 2);
+    }
+  }
+  return args;
+}
+
+async function main() {
+  const cwd = process.cwd();
+  const options = readConvertOptionsFromEnv(process.env);
+  // A custom reference document wins over page/typography options (spec §2.1, option (a)). Said as an
+  // info line, not with the `md2nativedocx: ` prefix that counts as a warning: nothing is wrong with
+  // the export, the user should just know.
+  if (options.referenceDoc && hasLayoutOptions(options.layout)) {
+    process.stderr.write(
+      'md2nativedocx (info): page/typography options are ignored because a custom reference document (MD2NATIVEDOCX_REFERENCE_DOC) is set.\n',
+    );
+  }
+
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof CliError) {
+      process.stderr.write(`${err.message}\n${USAGE}`);
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+
+  if (args.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+  if (!args.input) {
+    process.stderr.write(`Missing input file.\n${USAGE}`);
+    process.exit(2);
+  }
+  if (!args.output) {
+    process.stderr.write(`Missing output file (-o).\n${USAGE}`);
+    process.exit(2);
+  }
+
+  // Validate paths (anti path traversal): a path outside the working directory is a usage error (exit 2),
+  // as on the .pptx path.
+  let input;
+  let output;
+  try {
+    input = resolveSafePath(args.input, cwd);
+    output = resolveSafePath(args.output, cwd);
+  } catch (err) {
+    if (err instanceof CliError) {
+      process.stderr.write(`${err.message}\n`);
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+  if (!existsSync(input)) {
+    process.stderr.write(`Input file not found: ${args.input}\n`);
+    process.exit(1);
+  }
+
+  let result;
+  try {
+    result = await convert({ path: input }, { ...options, cwd });
+  } catch (err) {
+    if (err instanceof ConversionError) {
+      process.stderr.write(`md2nativedocx: ${err.message}\n`);
+      // `exportService.ts` (VS Code) reads Pandoc's own message, e.g. to tell a missing Pandoc apart.
+      if (err.stage === 'pandoc' && err.pandocStderr) process.stderr.write(err.pandocStderr);
+      process.exit(1);
+    }
+    throw err;
+  }
+  writeFileSync(output, result.document);
+
+  // Surface the diagrams' non-fatal notices: never let a successful export silently hide something the
+  // author should know about.
+  const warnings = result.warnings.map((w) => `md2nativedocx: ${w}`);
+  const wordCompatibility = runWordCompatibilityCheck(output);
+  const logPath = writeExportLog({ input, output, warnings, rawStderr: result.pandocStderr, wordCompatibility });
+  if (warnings.length > 0) {
+    process.stdout.write(`Warnings: ${warnings.length} (see ${basename(logPath)})\n`);
+    for (const warning of warnings) process.stderr.write(`${warning}\n`);
+  }
+  process.stdout.write(`Wrote ${basename(output)}\n`);
+}
+
+/**
+ * Word compatibility check (ADR 0007 part D) — validates the generated
+ * `.docx` against the exact schema real Word enforces strictly, via
+ * `scripts/oxml-validator/`'s DLL (Microsoft's own Open XML SDK). See
+ * `AGENTS.md` → "Diagnosing 'Word won't open the file'" and ADR 0006 for
+ * why this exists: neither well-formed-XML checks nor LibreOffice (which
+ * this project already uses for `test:visual`) can catch a schema
+ * violation Word rejects outright — that gap cost 7 rounds of
+ * manually-compared, individually-disproven hypotheses in the SmartArt
+ * "cycle" corruption incident before this validator found the real cause
+ * in a single pass.
+ *
+ * Opt-in via `MD2NATIVEDOCX_OXML_VALIDATOR_DLL` (the vendored DLL path,
+ * set by the VS Code extension's `dotnetProvisioner.ts` when
+ * `md2nativedocx.wordCompatibilityCheck.enabled` is on) — unset for a
+ * standalone `npx md2nativedocx` install, which doesn't ship the DLL, so
+ * this is a no-op there unless a user sets both env vars by hand.
+ * `MD2NATIVEDOCX_DOTNET_BIN` mirrors `MD2NATIVEDOCX_PANDOC_BIN`'s own
+ * "defaults to the bare command name, letting a provisioner override it"
+ * convention.
+ *
+ * Never throws: an export that already succeeded must never be reported as
+ * failed because this optional, best-effort check couldn't run (`dotnet`
+ * missing, DLL missing, unexpected crash) — same rule already applied to
+ * `extractWarnings`/`readWarningCount` elsewhere in this pipeline. Returns
+ * `null` when not run at all (env var unset), or
+ * `{ ran: true, diagramErrors, otherErrors }` /
+ * `{ ran: false, reason }` otherwise.
+ */
+function runWordCompatibilityCheck(docxPath) {
+  const dllPath = process.env.MD2NATIVEDOCX_OXML_VALIDATOR_DLL;
+  if (!dllPath) return null;
+
+  const dotnetBin = process.env.MD2NATIVEDOCX_DOTNET_BIN || 'dotnet';
+  try {
+    const stdout = execFileSync(dotnetBin, [dllPath, docxPath, '--json'], { encoding: 'utf8' });
+    const report = JSON.parse(stdout.trim().split('\n').pop());
+    const diagramErrors = report.errors.filter((e) => e.Part?.startsWith('/word/diagrams/'));
+    const otherErrors = report.errors.filter((e) => !e.Part?.startsWith('/word/diagrams/'));
+    return { ran: true, diagramErrors, otherErrors };
+  } catch (err) {
+    // execFileSync throws on a non-zero exit (errorCount > 0 also exits 1,
+    // per scripts/oxml-validator/OpenXmlValidator.cs) -- but it still wrote
+    // the JSON report to stdout first, captured on the error object.
+    const stdout = err.stdout?.toString();
+    if (stdout) {
+      try {
+        const report = JSON.parse(stdout.trim().split('\n').pop());
+        if (Array.isArray(report.errors)) {
+          const diagramErrors = report.errors.filter((e) => e.Part?.startsWith('/word/diagrams/'));
+          const otherErrors = report.errors.filter((e) => !e.Part?.startsWith('/word/diagrams/'));
+          return { ran: true, diagramErrors, otherErrors };
+        }
+      } catch {
+        // Fall through to the generic "could not run" case below.
+      }
+    }
+    return { ran: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** Write a plain-text log next to the output .docx (same basename, `.log`
+ * extension) so a click-right export (no VS Code Problems panel in view) has
+ * somewhere durable to point to — spec §10, "surface warnings". Written on
+ * every successful export, not just when there are warnings, for a
+ * consistent, discoverable location. */
+function writeExportLog({ input, output, warnings, rawStderr, wordCompatibility }) {
+  const logPath = extname(output).toLowerCase() === '.docx'
+    ? output.slice(0, -extname(output).length) + '.log'
+    : `${output}.log`;
+  const lines = [
+    'md2nativedocx export log',
+    `Date: ${new Date().toISOString()}`,
+    `Input: ${input}`,
+    `Output: ${output}`,
+    `Warnings: ${warnings.length}`,
+    '',
+  ];
+  if (warnings.length > 0) {
+    lines.push(...warnings.map((w) => `- ${w.replace(/^md2nativedocx:\s*(warning:\s*)?/, '')}`), '');
+  } else {
+    lines.push('No warnings.', '');
+  }
+  lines.push('--- Word compatibility check ---', ...formatWordCompatibility(wordCompatibility), '');
+  if (rawStderr && rawStderr.trim().length > 0) {
+    lines.push('--- Raw Pandoc/tool output ---', rawStderr.trimEnd(), '');
+  }
+  writeFileSync(logPath, lines.join('\n'), 'utf8');
+  return logPath;
+}
+
+/** Renders {@link runWordCompatibilityCheck}'s result as `.log` lines. Kept
+ * separate from that function so the "not run at all" (feature off) case
+ * reads as a plain, unalarming note rather than something that looks like a
+ * missing/failed check — most exports won't have this env var set at all
+ * (standalone CLI usage, or the VS Code setting turned off). */
+function formatWordCompatibility(result) {
+  if (result === null) {
+    return ['Not checked (md2nativedocx.wordCompatibilityCheck is off, or this is a standalone CLI export).'];
+  }
+  if (!result.ran) {
+    return [`Not checked (could not run: ${result.reason}).`];
+  }
+  if (result.diagramErrors.length === 0) {
+    const note = result.otherErrors.length > 0
+      ? ` (${result.otherErrors.length} pre-existing schema note(s) elsewhere, unrelated to this export's diagram content — see TODO.md)`
+      : '';
+    return [`0 error(s) — validated against the same schema Word itself enforces.${note}`];
+  }
+  const lines = [`${result.diagramErrors.length} error(s) found in the generated diagram content:`];
+  for (const e of result.diagramErrors) {
+    lines.push(`  - ${e.Path}: ${e.Description}`);
+  }
+  return lines;
+}
+
+main().catch((err) => {
+  process.stderr.write(`md2nativedocx: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@md2nativedocx/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Complete Markdown to Word (.docx) converter, or PowerPoint (.pptx), with editable diagrams — all 29 Mermaid types become real shapes, SmartArt and charts that readers can change in Word, not flattened PNGs.",
+  "license": "CC0-1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicolasbridelance/md2nativedocx",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/nicolasbridelance/md2nativedocx#readme",
+  "bugs": {
+    "url": "https://github.com/nicolasbridelance/md2nativedocx/issues"
+  },
+  "keywords": [
+    "mermaid",
+    "mermaid-to-docx",
+    "markdown-to-docx",
+    "markdown-to-word",
+    "docx",
+    "pptx",
+    "word",
+    "powerpoint",
+    "diagram",
+    "editable",
+    "pandoc",
+    "ooxml",
+    "drawingml",
+    "markdown"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/convert.d.mts",
+      "default": "./src/convert.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./src/convert.d.mts",
+  "bin": {
+    "md2nativedocx": "bin/md2nativedocx.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets"
+  ],
+  "scripts": {
+    "build": "echo \"cli: no build step (plain JS)\"",
+    "typecheck": "echo \"cli: no typecheck step\"",
+    "test": "node --test test/*.test.mjs",
+    "pretest:ci": "mkdir -p reports",
+    "test:ci": "node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=reports/junit.xml test/*.test.mjs"
+  },
+  "dependencies": {
+    "@md2nativedocx/pandoc-filter": "0.1.0",
+    "@md2nativedocx/pptx": "0.1.0",
+    "adm-zip": "^0.6.1"
+  }
+}

package/src/chartParts.mjs

@@ -0,0 +1,177 @@
+/**
+ * Native-chart hand-off (ADR 0011): completes the `c:chart` wiring for every diagram the core bridge
+ * dispatched to a native Word chart, and builds the embedded `.xlsx` workbook behind it.
+ *
+ * Same discipline as `postprocess.mjs`'s `injectSmartArtParts`, and within AGENTS.md rule 7's
+ * allowlist (new parts under `word/charts/` and `word/embeddings/`): it only **adds** parts, relationships and content types, never rewrites a part
+ * Pandoc wrote beyond swapping its own placeholder, and is a no-op when the document has no native
+ * chart. Every relationship it adds is internal (no `TargetMode`, rule 3). The workbook is a small zip
+ * written with `adm-zip`, already a dependency of this package, so no new dependency (rule 6).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { AdmZip, readZipEntry, setZipEntry } from './zipUtils.mjs';
+
+const PLACEHOLDER_RE = /CHART_PLACEHOLDER:([A-Za-z0-9-]+)/g;
+const REL_BASE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+const CHART_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.drawingml.chart+xml';
+const XLSX_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+const XML_DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+
+/** Strict XML escaping of user-controlled text (AGENTS.md rule #2). */
+function esc(text) {
+  return String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/** Column letters for a 0-based index: A..Z, AA..AZ, … */
+function col(index) {
+  let n = index;
+  let out = '';
+  do {
+    out = String.fromCharCode(65 + (n % 26)) + out;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return out;
+}
+
+function textCell(ref, text) {
+  return `<c r="${ref}" t="inlineStr"><is><t xml:space="preserve">${esc(text)}</t></is></c>`;
+}
+
+/**
+ * Build the embedded workbook: one sheet, a header row, then one row per category (label, then one
+ * value per series; an `undefined`/`null` value is an empty cell).
+ *
+ * @param {{ sheetName: string, header: string[], rows: Array<[string, ...Array<number|null|undefined>]> }} data
+ * @returns {Buffer} the `.xlsx` file
+ */
+export function buildWorkbookXlsx(data) {
+  const headerRow = `<row r="1">${data.header.map((h, c) => textCell(`${col(c)}1`, h)).join('')}</row>`;
+  const dataRows = data.rows.map((row, i) => {
+    const r = i + 2;
+    const [label, ...values] = row;
+    const cells = values
+      .map((value, c) => {
+        if (value === undefined || value === null) return '';
+        const n = Number(value);
+        if (!Number.isFinite(n)) throw new Error('md2nativedocx: chart value is not a finite number');
+        return `<c r="${col(c + 1)}${r}"><v>${n}</v></c>`;
+      })
+      .join('');
+    return `<row r="${r}">${textCell(`A${r}`, label)}${cells}</row>`;
+  });
+  const rows = [headerRow, ...dataRows].join('');
+  const main = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
+  const zip = new AdmZip();
+  const add = (name, xml) => zip.addFile(name, Buffer.from(XML_DECL + xml, 'utf8'));
+  add(
+    '[Content_Types].xml',
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+      '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+      '<Default Extension="xml" ContentType="application/xml"/>' +
+      '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>' +
+      '<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>' +
+      '<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>' +
+      '</Types>',
+  );
+  add(
+    '_rels/.rels',
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="${REL_BASE}/officeDocument" Target="xl/workbook.xml"/></Relationships>`,
+  );
+  add(
+    'xl/workbook.xml',
+    `<workbook xmlns="${main}" xmlns:r="${REL_BASE}"><sheets><sheet name="${esc(data.sheetName)}" sheetId="1" r:id="rId1"/></sheets></workbook>`,
+  );
+  add(
+    'xl/_rels/workbook.xml.rels',
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+      `<Relationship Id="rId1" Type="${REL_BASE}/worksheet" Target="worksheets/sheet1.xml"/>` +
+      `<Relationship Id="rId2" Type="${REL_BASE}/styles" Target="styles.xml"/>` +
+      '</Relationships>',
+  );
+  add('xl/worksheets/sheet1.xml', `<worksheet xmlns="${main}"><sheetData>${rows}</sheetData></worksheet>`);
+  add(
+    'xl/styles.xml',
+    `<styleSheet xmlns="${main}"><fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts>` +
+      '<fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills>' +
+      '<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>' +
+      '<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>' +
+      '<cellXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/></cellXfs></styleSheet>',
+  );
+  return zip.toBuffer();
+}
+
+function nextChartNumber(zip) {
+  let max = 0;
+  for (const entry of zip.getEntries()) {
+    const m = /^word\/charts\/chart(\d+)\.xml$/.exec(entry.entryName);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return max + 1;
+}
+
+/**
+ * Complete the native-chart wiring for every placeholder in `docxPath`'s `word/document.xml`.
+ * Must run after `postProcessDocx` (it reads the namespace-fixed, id-renumbered document).
+ *
+ * @param {string} docxPath
+ * @param {string} chartDir directory the core bridge wrote `<id>/chart.xml`, `data.json`, `meta.json` into
+ */
+export function injectChartParts(docxPath, chartDir) {
+  const archive = resolve(docxPath);
+  const zip = new AdmZip(archive);
+  let documentXml = readZipEntry(zip, 'word/document.xml');
+  const ids = [...new Set([...documentXml.matchAll(PLACEHOLDER_RE)].map((m) => m[1]))];
+  if (ids.length === 0) return;
+  if (!chartDir) throw new Error('md2nativedocx: document.xml references native charts but no chartDir was given');
+
+  let contentTypes = readZipEntry(zip, '[Content_Types].xml');
+  let relsXml = readZipEntry(zip, 'word/_rels/document.xml.rels');
+  let n = nextChartNumber(zip);
+  const newParts = [];
+
+  for (const id of ids) {
+    const dir = join(chartDir, id);
+    if (!existsSync(dir)) throw new Error(`md2nativedocx: no chart parts found for "${id}" in ${chartDir}`);
+    const chartXml = readFileSync(join(dir, 'chart.xml'), 'utf8');
+    const meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf8'));
+    const chartPath = `word/charts/chart${n}.xml`;
+    const relId = `rIdChart${n}`;
+    relsXml = relsXml.replace(
+      '</Relationships>',
+      `<Relationship Id="${relId}" Type="${REL_BASE}/chart" Target="charts/chart${n}.xml"/></Relationships>`,
+    );
+    contentTypes = contentTypes.replace('</Types>', `<Override PartName="/${chartPath}" ContentType="${CHART_CONTENT_TYPE}"/></Types>`);
+    newParts.push([chartPath, chartXml]);
+
+    if (meta.hasWorkbook) {
+      const data = JSON.parse(readFileSync(join(dir, 'data.json'), 'utf8'));
+      const workbookPath = `word/embeddings/Microsoft_Excel_Sheet${n}.xlsx`;
+      newParts.push([workbookPath, buildWorkbookXlsx(data)]);
+      newParts.push([
+        `word/charts/_rels/chart${n}.xml.rels`,
+        XML_DECL +
+          '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+          `<Relationship Id="rId1" Type="${REL_BASE}/package" Target="../embeddings/Microsoft_Excel_Sheet${n}.xlsx"/>` +
+          '</Relationships>',
+      ]);
+      if (!/Extension="xlsx"/i.test(contentTypes)) {
+        contentTypes = contentTypes.replace('</Types>', `<Default Extension="xlsx" ContentType="${XLSX_CONTENT_TYPE}"/></Types>`);
+      }
+    }
+    documentXml = documentXml.split(`CHART_PLACEHOLDER:${id}`).join(relId);
+    n += 1;
+  }
+
+  setZipEntry(zip, 'word/document.xml', documentXml);
+  setZipEntry(zip, '[Content_Types].xml', contentTypes);
+  setZipEntry(zip, 'word/_rels/document.xml.rels', relsXml);
+  for (const [path, content] of newParts) setZipEntry(zip, path, content);
+  zip.writeZip(archive);
+}

package/src/cliSupport.mjs

@@ -0,0 +1,28 @@
+/**
+ * Small helpers shared by every CLI entry path (the Pandoc/.docx path in `bin/md2nativedocx.mjs` and
+ * the .pptx path in `pptxExport.mjs`).
+ */
+
+import { resolve, isAbsolute } from 'node:path';
+
+/** Typed error for CLI-level failures. */
+export class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+  }
+}
+
+/** Resolve and validate a path (anti path traversal via `..`). */
+export function resolveSafePath(rawPath, cwd) {
+  const abs = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
+  // Reject relative paths that escape the working directory via `..`.
+  if (!isAbsolute(rawPath)) {
+    const root = resolve(cwd);
+    if (!abs.startsWith(root + '/') && abs !== root) {
+      throw new CliError(`Path escapes the working directory: ${rawPath}`, 2);
+    }
+  }
+  return abs;
+}