@md2nativedocx/cli 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,115 @@
-# 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|output.odt|output.pptx> [options]
+
+Options:
+  -o, --output <file>   Output .docx, .odt or .pptx path (required)
+  --show-source         .pptx only: show each diagram's Mermaid source beside it
+  -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` |
+
+### LibreOffice (`.odt`)
+
+```sh
+md2nativedocx report.md -o report.odt
+```
+
+Writes an OpenDocument text for LibreOffice: the document as Pandoc converts it, and each flowchart as one
+group of native LibreOffice shapes (boxes, diamonds, cylinders…) with connectors attached to them, which
+follow a box you move (*F3* enters the group), subgraphs as containers, `classDef`/`style`/`linkStyle`
+colours kept. Other diagram types become a note in their place for now. The page is A4 with 2.54 cm
+margins; the page and typography variables below, SmartArt and charts apply to `.docx` only. Pandoc
+writes the whole file, with a reference document and template shipped in `assets/` (see
+`THIRD_PARTY_NOTICES.md` for the template's BSD-3 notice).
+
+From code: `convert(markdown, { format: 'odt' })`.
+
+## 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. |
+
+## Very large diagrams
+
+A diagram with more than 500 nodes (subgraph boxes included) or 800 edges is not laid out: the document
+still converts, the diagram is replaced by a grey note saying why, and a warning goes to stderr and the
+`.log`. This keeps one pathological block from running for minutes. In `@md2nativedocx/core`, `renderDiagram()`
+throws a `DiagramTooLargeError` instead, and takes `maxNodes`, `maxEdges` and `maxSourceLength` to change the limits.
+
+## 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/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,38 @@
+# Third-party notices
+
+Everything in this package is CC0-1.0 except the file below.
+
+## `assets/md2nativedocx.opendocument`
+
+Derived from Pandoc's `opendocument` template (Pandoc 3.1.3, `data/templates/default.opendocument`).
+Pandoc's templates are dual-licensed under the GNU GPL (version 2 or later) and the BSD 3-Clause
+license; this derived file is distributed under the BSD 3-Clause license. The only change is a loop
+added inside `office:automatic-styles`, filled by this project's Lua filter with the styles of the
+diagrams it draws. That change is distributed under the same license.
+
+```
+Copyright (c) 2014-2023, John MacFarlane <jgm@berkeley.edu>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted
+provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice, this list of conditions
+    and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright notice, this list of
+    conditions and the following disclaimer in the documentation and/or other materials provided
+    with the distribution.
+  * Neither the name of John MacFarlane nor the names of other contributors may be used to endorse
+    or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+Pandoc itself is not part of this package: it is run as a separate program (GPL-2.0-or-later).

package/assets/README.md

@@ -0,0 +1,65 @@
+# `reference.docx`
+
+Passed to Pandoc via `--reference-doc` so generated documents use Word's current default look
+(Aptos font scheme, the modern "Office" colour scheme, accent1 `#4472C4`, flat non-bold heading
+hierarchy, 11 pt body text with 1.08 line spacing and 8 pt after) instead of Pandoc's own bundled
+default, which is the 2007-2010 Office look (Calibri/Cambria, bold coloured headings).
+
+**Written by this project, from scratch (2026-10-08).** Every part comes from
+`packages/cli/reference-docx-src/` and is assembled by:
+
+```bash
+node scripts/build-reference-docx.mjs
+```
+
+Edit a part there, rebuild, and commit both. The build is reproducible (fixed timestamps).
+
+Why: the previous file was derived from Pandoc's default `reference.docx`, which Pandoc distributes
+under GPL-2+ only (its templates are dual GPL-2+/BSD-3, its other data files are not), while this
+project is CC0. The maintainer chose to rebuild it (ADR 0013, `docs/adr/0013-odf-output-phase-0.md`).
+The new parts keep the same visual values: a LibreOffice render of a document using every Pandoc
+style (title block, abstract, headings, lists, footnote, code, table with caption, definition list,
+diagram) is pixel-identical to the previous one. They contain no sample text and no relationship to
+anything outside the package (the old file carried an unused `http://example.com` link from
+Pandoc's sample document).
+
+What the rest of the code relies on (`src/referenceDocBuilder.mjs`, tested in
+`test/reference-doc-builder.test.mjs`):
+
+- `word/theme/theme1.xml`: `<a:majorFont><a:latin typeface="…" />`, the same for `minorFont`, and
+  `<a:accent1><a:srgbClr val="RRGGBB"/></a:accent1>`;
+- `word/styles.xml`: `w:docDefaults` with `w:sz`/`w:szCs` and a `w:pPrDefault`; accent colours as
+  `w:themeColor="accent1"` with a literal `w:val` fallback (LibreOffice does not resolve theme
+  colours); a `Table` style with a `firstRow` conditional `w:tcPr`;
+- `word/document.xml`: an empty `<w:sectPr />`, which `patchSectPr` fills.
+
+Styles Pandoc adds at conversion time (syntax highlighting `SourceCode`, `*Tok`) are not in this
+file: Pandoc writes them itself.
+
+**To verify in a real Word** (no Word in this environment; checked with LibreOffice and the Open XML
+validator): heading styling and whether Word's current built-in template still matches.
+
+# `reference.odt` and `md2nativedocx.opendocument`
+
+The two files handed to Pandoc for a `.odt` (ADR 0013; `AGENTS.md` rule 7: nothing touches the
+`.odt` Pandoc writes). Both are built by:
+
+```bash
+node scripts/build-odt-assets.mjs
+```
+
+- **`reference.odt`**, written by this project (CC0) from `packages/cli/reference-odt-src/`, never
+  Pandoc's own (GPL-2+). Pandoc keeps its `styles.xml` and writes the rest. It defines the styles
+  Pandoc's ODT writer refers to (headings, title block, code, quotations, tables, captions,
+  definition lists, footnotes, links), an A4 page with 2.54 cm margins, and the arrow markers and
+  dash pattern the diagrams use (`ODF_GRAPHIC_DEFINITIONS` in `@md2nativedocx/core`, kept equal by
+  `test/odt.test.mjs`). LibreOffice does **not** supply its built-in look for a style a document
+  references without defining (headings came out as plain text with a minimal `styles.xml`,
+  2026-10-08), so each one is written here.
+- **`md2nativedocx.opendocument`**, Pandoc 3.1.3's `opendocument` template plus one loop inside
+  `office:automatic-styles` for the diagram styles. BSD-3-Clause, see `../THIRD_PARTY_NOTICES.md`.
+  The build refuses any other Pandoc version, and `test/odt.test.mjs` checks the file still differs
+  from `pandoc -D opendocument` by that loop only.
+
+Known Pandoc 3.1.3 limitation, not ours: a front-matter `abstract` is written as bare text outside
+any paragraph, which the ODF validator rejects (same with Pandoc's own reference document).

package/assets/md2nativedocx.opendocument

@@ -0,0 +1,171 @@
+$-- md2nativedocx: Pandoc's opendocument template (Pandoc 3.1.3), with one addition: the
+$-- md2n-automatic-styles loop in office:automatic-styles, filled by the md2nativedocx Lua filter.
+$-- Copyright (c) 2014-2023, John MacFarlane. BSD-3-Clause, see THIRD_PARTY_NOTICES.md.
+<?xml version="1.0" encoding="utf-8" ?>
+<office:document-content xmlns:office="urn:oasis:names:tc:opendocument:xmlns:office:1.0" xmlns:style="urn:oasis:names:tc:opendocument:xmlns:style:1.0" xmlns:text="urn:oasis:names:tc:opendocument:xmlns:text:1.0" xmlns:table="urn:oasis:names:tc:opendocument:xmlns:table:1.0" xmlns:draw="urn:oasis:names:tc:opendocument:xmlns:drawing:1.0" xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:meta="urn:oasis:names:tc:opendocument:xmlns:meta:1.0" xmlns:number="urn:oasis:names:tc:opendocument:xmlns:datastyle:1.0" xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0" xmlns:chart="urn:oasis:names:tc:opendocument:xmlns:chart:1.0" xmlns:dr3d="urn:oasis:names:tc:opendocument:xmlns:dr3d:1.0" xmlns:math="http://www.w3.org/1998/Math/MathML" xmlns:form="urn:oasis:names:tc:opendocument:xmlns:form:1.0" xmlns:script="urn:oasis:names:tc:opendocument:xmlns:script:1.0" xmlns:ooo="http://openoffice.org/2004/office" xmlns:ooow="http://openoffice.org/2004/writer" xmlns:oooc="http://openoffice.org/2004/calc" xmlns:dom="http://www.w3.org/2001/xml-events" xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" office:version="1.3">
+  <office:font-face-decls>
+    <style:font-face style:name="Courier New" style:font-family-generic="modern" style:font-pitch="fixed" svg:font-family="'Courier New'" />
+  </office:font-face-decls>
+  <office:automatic-styles>
+    $automatic-styles$
+$for(md2n-automatic-styles)$
+    $md2n-automatic-styles$
+$endfor$
+  </office:automatic-styles>
+$for(header-includes)$
+  $header-includes$
+$endfor$
+<office:body>
+<office:text>
+$if(title)$
+<text:p text:style-name="Title">$title$</text:p>
+$endif$
+$if(subtitle)$
+<text:p text:style-name="Subtitle">$subtitle$</text:p>
+$endif$
+$for(author)$
+<text:p text:style-name="Author">$author$</text:p>
+$endfor$
+$if(date)$
+<text:p text:style-name="Date">$date$</text:p>
+$endif$
+$if(abstract)$
+$abstract$
+$endif$
+$for(include-before)$
+$include-before$
+$endfor$
+$if(toc)$
+<text:table-of-content>
+  <text:table-of-content-source text:outline-level="$toc-depth$">
+    <text:index-title-template text:style-name="Contents_20_Heading">$toc-title$</text:index-title-template>
+    <text:table-of-content-entry-template text:outline-level="1"
+    text:style-name="Contents_20_1">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="2"
+    text:style-name="Contents_20_2">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="3"
+    text:style-name="Contents_20_3">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="4"
+    text:style-name="Contents_20_4">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="5"
+    text:style-name="Contents_20_5">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="6"
+    text:style-name="Contents_20_6">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="7"
+    text:style-name="Contents_20_7">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="8"
+    text:style-name="Contents_20_8">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="9"
+    text:style-name="Contents_20_9">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="10"
+    text:style-name="Contents_20_10">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+  </text:table-of-content-source>
+</text:table-of-content>
+$endif$
+$body$
+$for(include-after)$
+$include-after$
+$endfor$
+</office:text>
+</office:body>
+</office:document-content>

package/bin/md2nativedocx.mjs

@@ -0,0 +1,209 @@
+#!/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 { basename, extname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { CliError, resolveSafePath } from '../src/cliSupport.mjs';
+import { ConversionError, convert } from '../src/convert.mjs';
+import { writeOutputSafely } from '../src/writeOutputSafely.mjs';
+import { formatWordCompatibility, runWordCompatibilityCheck } from '../src/wordCheck.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.odt|output.pptx> [options]
+
+A .odt output is for LibreOffice: flowcharts become native, editable shapes and connectors;
+other diagram types become a note for now.
+
+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, .odt 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);
+  }
+
+  const format = extname(output).toLowerCase() === '.odt' ? 'odt' : 'docx';
+  if (format === 'odt' && hasLayoutOptions(options.layout)) {
+    process.stderr.write('md2nativedocx (info): page/typography options apply to .docx only; the .odt uses A4 with 2.54 cm margins.\n');
+  }
+  // MD2NATIVEDOCX_REFERENCE_DOC names a Word template; a .odt keeps the bundled reference.odt.
+  const formatOptions = format === 'odt' && options.referenceDoc && extname(options.referenceDoc).toLowerCase() !== '.odt'
+    ? { ...options, referenceDoc: undefined }
+    : options;
+
+  let result;
+  try {
+    result = await convert({ path: input }, { ...formatOptions, cwd, format });
+  } 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;
+  }
+  try {
+    writeOutputSafely(output, result.document);
+  } catch (err) {
+    if (err instanceof ConversionError) {
+      process.stderr.write(`md2nativedocx: ${err.message}\n`);
+      process.exit(2);
+    }
+    throw err;
+  }
+
+  // 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 = format === 'docx' ? runWordCompatibilityCheck(output) : null;
+  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`);
+}
+
+/** 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 = ['.docx', '.odt'].includes(extname(output).toLowerCase())
+    ? 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(), '');
+  }
+  writeOutputSafely(logPath, lines.join('\n'));
+  return logPath;
+}
+
+main().catch((err) => {
+  process.stderr.write(`md2nativedocx: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});