document-cli 3.0.11 → 3.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/document-cli) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/document-cli) [![Release](https://img.shields.io/github/v/release/ExaDev/document-cli)](https://github.com/ExaDev/document-cli/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/document-cli/ci.yml?branch=main)](https://github.com/ExaDev/document-cli/actions)
 
-> A command-line interface and an interactive terminal (Ink) app for [`documents.js`](https://github.com/ExaDev/documents.js): every docx/pptx/odt/odp/ods/odg/odf/pdf/odm/odb/xlsx/csv/svg/markdown conversion, bridge, and editor documents.js exposes, wired up as a scriptable subcommand or a full-screen terminal editor. Installs as either `document-cli` or `doculi`.
+> A command-line interface and an interactive terminal (Ink) app for [`documents.js`](https://github.com/ExaDev/documents.js): every docx/pptx/odt/odp/ods/odg/odf/pdf/odm/odb/xlsx/csv/svg/markdown conversion, bridge, and editor documents.js exposes, plus the outline projection [`document-outline.js`](https://github.com/ExaDev/document-outline.js) builds over any readable document, wired up as a scriptable subcommand or a full-screen terminal editor. Installs as either `document-cli` or `doculi`.
 
 `document-cli` adds no conversion or editing logic of its own — it is a dispatch layer over `documents.js`'s existing conversion functions, `DocumentConverter` port, live-view editors, and `.odb`/PDF readers. What it adds is two ways to drive them without writing TypeScript: a scriptable, Unix-shaped CLI (stdin/stdout, exit codes, `--json` diagnostics) for pipelines, and a full-screen Ink terminal app for browsing and editing a document interactively.
 
@@ -15,6 +15,7 @@ graph TD
     mdcodec("markdown-codec")
     bytecodec("byte-codec")
     documents("documents.js")
+    outline("document-outline.js")
     mcp("document-mcp")
     cli("document-cli")
 
@@ -23,6 +24,7 @@ graph TD
     schema --> pdfcodec
     schema --> mdcodec
     schema --> documents
+    schema --> outline
     ooxml --> documents
     odf --> documents
     pdfcodec --> documents
@@ -32,6 +34,7 @@ graph TD
     documents --> mcp
     pdfcodec --> mcp
     documents --> cli
+    outline --> cli
     odf --> cli
     pdfcodec --> cli
 
@@ -42,6 +45,7 @@ graph TD
     click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec"
     click bytecodec "https://github.com/ExaDev/byte-codec" "byte-codec"
     click documents "https://github.com/ExaDev/documents.js" "documents.js"
+    click outline "https://github.com/ExaDev/document-outline.js" "document-outline.js"
     click mcp "https://github.com/ExaDev/document-mcp" "document-mcp"
     click cli "https://github.com/ExaDev/document-cli" "document-cli"
 
@@ -93,7 +97,7 @@ document-cli convert report.docx report.pdf
 document-cli convert report.docx - --to pdf > report.pdf
 ```
 
-**`formats`** — lists every `source -> target` pair the commands above support (`--json` for a machine-readable array), plus a pointer to the commands not on that list because they don't fit the source/target shape (`odm-to-pdf`, `odb-to-csv`, `odb-to-xlsx`, `odb-tables`, `odb-forms`, `odb-reports`, `pdf-inspect`, `from-package`, `fonts`, `docx-extras`, `metadata`, `set-metadata`).
+**`formats`** — lists every `source -> target` pair the commands above support (`--json` for a machine-readable array), plus a pointer to the commands not on that list because they don't fit the source/target shape (`odm-to-pdf`, `odb-to-csv`, `odb-to-xlsx`, `odb-tables`, `odb-forms`, `odb-reports`, `pdf-inspect`, `from-package`, `fonts`, `docx-extras`, `metadata`, `set-metadata`, `outline`).
 
 **`from-package <input> [output]`** — reads back a `DocumentPackage` JSON file a previous conversion wrote via `--dump-package` (below) and exports it to a real target format, closing the round trip `--dump-package` otherwise has no return path for. Target resolution matches `convert`: an output path's own extension, or `--to <format>` when it doesn't have one. The package this command reads is the tree form since documents.js 3.0.0 — content grouped one group per container (section, slide, sheet, draw page) under `children`, with the minted `styles` table at the root — flattened once at this boundary, exactly as documents.js's own builders do. `pdf` rebuilds the layout from the package's own recorded positions — each content node's `frames` plus the package's `pages` geometry (`layoutDocumentFromPackage` → `writePdf`; a package no longer carries a separate `layout` half at all); every other format builds a fresh package from the flattened content through the identical `buildXPackage` function the matching `pdf-to-X`/bridge conversion already uses — `xlsx` included, via `ooxml.js`'s own `buildXlsxPackage`. `odf` is the one target rejected outright, since a standalone formula document has no write path from `ContentDocument` at all; a `csv` or `svg` target is written through the identical `buildCsvText`/`buildSvgText` functions the codec registry's own write wrappers call, so the `--delimiter`/`--sheet`/`--page` selection flags below reach it exactly as they do a live conversion. Only a file genuinely written by a current `--dump-package` round-trips here: the `$schema` URI a dump carries pins the document-schema.js release that wrote it, and any pre-4.0.0 dump — the flat `{ formatVersion, content, pages }` envelope documents.js 1.x/2.x wrote, whatever its `formatVersion` — is rejected with an error naming the pinned release, the flat-to-tree change, and the remedy, rather than a raw validation wall. A layout-document dump (a document-schema.js 3.x layout artefact, e.g. an old `pdf-inspect --full` output) gets its own pointer: that schema moved to pdf-codec.
 
@@ -164,6 +168,13 @@ document-cli set-metadata report.docx report.docx --set-title "Q3 Report" --set-
 document-cli set-metadata report.docx report.odt --set-keywords "draft,internal"
 ```
 
+**`outline <input>`** — prints a document's outline: the table-of-contents projection over the tree-form `DocumentPackage` a conversion of that document builds — headings nested by heading level, list items nested under their heading or slide, one group per slide (labelled `Slide N`), sheet (labelled with the sheet's own name), or draw page (labelled `Page N`) — rendered as indented text, two spaces per nesting depth. Leaves render their own text (a paragraph's runs, a table's cell text, an image's alt text, a formula's LaTeX) or their kind in brackets when they carry none (`[page-break]`, `[vector]`, `[embeddedObject]`). Works on any of the twelve readable formats: the command runs the cheapest conversion that still leaves a package behind — a PDF-bypassing bridge to a sibling format, so no layout engine runs (`docx`→`odt`, `markdown`→`docx`, `ods`→`xlsx`, ...); `pdf` reconstructs through `pdf-to-docx` and `odf` renders through `odf-to-pdf`, the one conversion each of those formats has — and projects that package's tree through [`document-outline.js`](https://github.com/ExaDev/document-outline.js)'s own `buildOutline`, this command being that package's first real consumer. `--json` emits the outline tree itself — groups as `{ text, level, children }`, leaves as the package leaves they are — rather than a CLI-private shape; the internal conversion's diagnostics (a pdf reconstruction's parse warnings, say) reach stderr exactly as they would on the matching conversion command. `--from <format>` names the source format when the input path carries no recognised extension to infer it from — the only way to outline a document read from stdin (`-`), which otherwise has no extension to read at all. Heading nesting depends on the source document actually carrying a heading-level signal on disk (`w:outlineLvl` for docx, `text:outline-level` for odt) — present in anything authored by Word or LibreOffice, and always present for a markdown source, whose own reader parses `#`/`##` headings directly; a docx or odt this ecosystem's own writers produce does not currently stamp that signal even though the paragraph still carries its `Heading1`/`Heading2`-style reference, so outlining a docx/odt generated by this CLI's own conversions loses heading nesting specifically (list nesting and slide/sheet/page grouping are unaffected):
+
+```sh
+document-cli outline report.docx
+document-cli outline slides.pptx --json
+```
+
 **`tui [file]`** — launches the interactive terminal app; see [The TUI](#the-tui) below.
 
 ### Shared flags
@@ -180,7 +191,7 @@ The explicit conversions, `convert`, `odm-to-pdf`, `odb-to-xlsx`, `odb-to-csv`,
 
 Three further flags select what a csv or svg edge of a conversion works on, threaded straight into documents.js's own `ConversionOptions`: `--delimiter <char>` (the field delimiter a csv source reads with, or a csv target writes with — default `,`), `--sheet <name>` (the sheet a csv target writes, required when the source document has more than one), and `--page <index>` (the 0-based page an svg target draws, required when the source document has more than one). On the explicit commands they are registered only where the pair can reach the edge in question — `--delimiter` on any pair with a csv edge, `--sheet` on a csv target, `--page` on an svg target — and unconditionally on `convert` and `from-package`, whose target is only known once the output path or `--to` resolves at run time (the same registration reasoning the font flags below document). Leaving `--sheet` or `--page` unanswered on an ambiguous document fails with exit `3`, naming the sheets or page count to pick from:
 
-`--dump-package <file>` is one flag further, registered only on the explicit conversions and `convert` — it writes the intermediate `DocumentPackage` (the tree form: content grouped one group per container, the content nodes carrying their own rendered `frames`, plus the `pages` geometry those frames index into and the minted `styles` table at the root) that conversion built to a JSON file, tagged with its own version-pinned `$schema` — the URI *is* the package's version — so `from-package` (above) can read it back in. Every conversion populates one, `odf-to-pdf` included — its dump carries a `formula`-kind content and the one A4 page it renders (the formula's glyphs travel through the PDF writer's own positioned-formula channel rather than as frame-stamped page content); every PDF-bypassing bridge (`ods-to-xlsx`, `docx-to-pptx`, `odg-to-svg`, and every other content-format pair above) populates one too, just with `pages` always absent, since a bridge never runs a layout engine. `odm-to-pdf`/`odb-*`/`set-metadata` don't expose the flag at all, since none of them goes through `DocumentConverter.convert` in the first place. `odb-tables`, `odb-forms`, `odb-reports`, `fonts`, `docx-extras`, `metadata`, `formats`, and `pdf-inspect` each take only their own `--json` (plus `pdf-inspect`'s own `--full`); `odb-query` takes `--sql <text>`/`--query <savedName>` (mutually exclusive) alongside its own `--json`, with none of the shared flags above since it only reads and writes nothing; `from-package` and `set-metadata` each take `--to <format>` alongside the shared flags in this table; `odb-render-report` takes `--report <name>` and `--to <format>` alongside the shared flags and the font flags below; `tui` takes no flags at all, only an optional positional file.
+`--dump-package <file>` is one flag further, registered only on the explicit conversions and `convert` — it writes the intermediate `DocumentPackage` (the tree form: content grouped one group per container, the content nodes carrying their own rendered `frames`, plus the `pages` geometry those frames index into and the minted `styles` table at the root) that conversion built to a JSON file, tagged with its own version-pinned `$schema` — the URI *is* the package's version — so `from-package` (above) can read it back in. Every conversion populates one, `odf-to-pdf` included — its dump carries a `formula`-kind content and the one A4 page it renders (the formula's glyphs travel through the PDF writer's own positioned-formula channel rather than as frame-stamped page content); every PDF-bypassing bridge (`ods-to-xlsx`, `docx-to-pptx`, `odg-to-svg`, and every other content-format pair above) populates one too, just with `pages` always absent, since a bridge never runs a layout engine. `odm-to-pdf`/`odb-*`/`set-metadata` don't expose the flag at all, since none of them goes through `DocumentConverter.convert` in the first place. `odb-tables`, `odb-forms`, `odb-reports`, `fonts`, `docx-extras`, `metadata`, `formats`, and `pdf-inspect` each take only their own `--json` (plus `pdf-inspect`'s own `--full`); `odb-query` takes `--sql <text>`/`--query <savedName>` (mutually exclusive) alongside its own `--json`, with none of the shared flags above since it only reads and writes nothing; `from-package` and `set-metadata` each take `--to <format>` alongside the shared flags in this table; `outline` takes the shared flags except `--out` (it prints to stdout and writes no file), plus its own `--from <format>` for a source format extension inference can't resolve — it runs a conversion internally to obtain the package it projects, so its diagnostics and `--timeout` behave like any conversion's; `odb-render-report` takes `--report <name>` and `--to <format>` alongside the shared flags and the font flags below; `tui` takes no flags at all, only an optional positional file.
 
 ### Real fonts
 
@@ -251,7 +262,7 @@ The global bindings below apply everywhere; individual screens (a docx run's own
 
 The package splits into two independent layers sharing one thin format-detection module, `src/format.ts` (extension ⇄ `DocumentFormat` inference), so a change to how a format is recognised from a path never needs making twice:
 
-- **`src/commands/` + `src/runtime/`** is the CLI proper. `commands/shared.ts`'s `buildConversionAction(source, target)` is the one implementation behind every `<source>-to-<target>` command and the generic `convert` — it partially applies a format pair and hands back a ready commander action, so the conversion-running logic (read input, call `createLocalDocumentConverter().convert`, write output, report diagnostics, map errors to exit codes) exists exactly once regardless of which pair is invoked. `commands/{odm,odb,pdf-inspect,fonts,docx-extras,metadata}.ts` each call their own documents.js function directly instead, since none of them fits the generic `DocumentConverter` port's bytes-in/bytes-out shape (`odmToPdf` needs a `resolveSubDocument` callback, `.odb` extraction/query/report-rendering has no PDF conversion or port entry at all, `pdf-inspect` reads without converting, and `fonts`/`docx-extras`/`metadata` each read a document without producing one). `commands/set-metadata.ts` also bypasses `buildConversionAction` despite writing a file, since `setDocumentMetadata(source, target, bytes, overrides)` patches a document rather than converting one and requires source and target to match. `src/odb-structure.ts` sits alongside `src/format.ts` as a module shared by both layers: it turns an `OdbForm`/`OdbReport` into a flat array of already-indented lines, which the `odb-forms`/`odb-reports` commands join with newlines and the TUI's own form/report detail screens render one per list row; `src/docx-extras-format.ts` and `src/sql-result-format.ts` are the same idea for their own commands — the first turns a `DocxExtras` value into the flat line list `docx-extras` prints and the TUI's own `DocxExtrasScreen` renders, the second turns an `SqlResultSet` into an aligned plain-text table for `odb-query`. `src/runtime/` holds the process-level concerns every command shares: `abort.ts`'s `createRuntimeSignal` (one `SIGINT` listener and an optional timeout, combined into a single signal), `io.ts`'s stdin/stdout/file `-`-aware read and write helpers, `exit-codes.ts`'s exit-code constants and `mapErrorToExit`, `diagnostics.ts`'s stderr reporter, `fonts.ts`'s `loadProvidedFonts` (validating every `--font-file` path into documents.js's own `ProvidedFont` shape, shared by every font-accepting command and the TUI's own PDF-export and report-render screens), and `metadata-format.ts`'s `formatMetadataLines` (shared by `metadata`, `pdf-inspect`, and the TUI's own metadata screen).
+- **`src/commands/` + `src/runtime/`** is the CLI proper. `commands/shared.ts`'s `buildConversionAction(source, target)` is the one implementation behind every `<source>-to-<target>` command and the generic `convert` — it partially applies a format pair and hands back a ready commander action, so the conversion-running logic (read input, call `createLocalDocumentConverter().convert`, write output, report diagnostics, map errors to exit codes) exists exactly once regardless of which pair is invoked. `commands/{odm,odb,pdf-inspect,fonts,docx-extras,metadata}.ts` each call their own documents.js function directly instead, since none of them fits the generic `DocumentConverter` port's bytes-in/bytes-out shape (`odmToPdf` needs a `resolveSubDocument` callback, `.odb` extraction/query/report-rendering has no PDF conversion or port entry at all, `pdf-inspect` reads without converting, and `fonts`/`docx-extras`/`metadata` each read a document without producing one); `commands/outline.ts` does go through the port, but only to take `ConversionResult.package` — its output bytes are discarded and document-outline.js's `buildOutline` projects the tree instead, the one command here whose product is neither the converted bytes nor a direct documents.js read. `commands/set-metadata.ts` also bypasses `buildConversionAction` despite writing a file, since `setDocumentMetadata(source, target, bytes, overrides)` patches a document rather than converting one and requires source and target to match. `src/odb-structure.ts` sits alongside `src/format.ts` as a module shared by both layers: it turns an `OdbForm`/`OdbReport` into a flat array of already-indented lines, which the `odb-forms`/`odb-reports` commands join with newlines and the TUI's own form/report detail screens render one per list row; `src/docx-extras-format.ts` and `src/sql-result-format.ts` are the same idea for their own commands — the first turns a `DocxExtras` value into the flat line list `docx-extras` prints and the TUI's own `DocxExtrasScreen` renders, the second turns an `SqlResultSet` into an aligned plain-text table for `odb-query`. `src/runtime/` holds the process-level concerns every command shares: `abort.ts`'s `createRuntimeSignal` (one `SIGINT` listener and an optional timeout, combined into a single signal), `io.ts`'s stdin/stdout/file `-`-aware read and write helpers, `exit-codes.ts`'s exit-code constants and `mapErrorToExit`, `diagnostics.ts`'s stderr reporter, `fonts.ts`'s `loadProvidedFonts` (validating every `--font-file` path into documents.js's own `ProvidedFont` shape, shared by every font-accepting command and the TUI's own PDF-export and report-render screens), and `metadata-format.ts`'s `formatMetadataLines` (shared by `metadata`, `pdf-inspect`, and the TUI's own metadata screen).
 - **`src/tui/`** is the Ink app, entered lazily. `src/cli.ts` only imports `./tui/index.js` inside a dynamic `import()`, called just once dispatch has already decided the TUI is actually running — a plain `document-cli docx-to-pdf a b` invocation never loads React, Ink, or any TUI screen module at all, and `tsdown.config.ts`'s bin build correctly code-splits the TUI into its own lazily-loaded chunk as a result. Inside the TUI, `state/reducer.ts` and `state/types.ts` hold the single `AppState` (a screen stack, the open document, undo history, overlays), `format/open-document.ts` is the one place bytes become an open document for every format, and `screens/editors/<format>/` holds each format's own screen components — reusing shared building blocks (`screens/shared/paragraph-family.tsx`, `slide-family.tsx`) between docx/odt and pptx/odp respectively, the same way documents.js's own odp editor reuses its odt paragraph/run classes.
 - **`src/index.ts`** re-exports the CLI's command-layer, format, and exit-code logic (not the TUI, which stays behind its own lazy import) as this package's `"."` library export, for a caller that wants `document-cli`'s conversion-running logic directly rather than spawning the bin as a subprocess.
 - **One package, two npm names.** `package.json`'s `bin` field lists `document-cli` and `doculi` unconditionally, both pointing at the same built entry point — there is no separate build, alias package, or npm alias mechanism involved, just two keys in one `bin` object.
@@ -270,7 +281,7 @@ pnpm test:workers  # turbo run _test:workers -> vitest run --config vitest.worke
 
 ## Gotchas
 
-- **The lazy TUI import is load-bearing, not incidental.** `src/cli.ts` computes the dispatch token before doing anything else and only reaches `await import('./tui/index.js')` on the bare/`tui` branch — every other command path (all explicit conversions, `convert`, `formats`, `from-package`, `odm-to-pdf`, `odb-*`, `pdf-inspect`, `fonts`, `docx-extras`, `metadata`, `set-metadata`) never touches that import at all. This is what keeps a scripted, high-frequency CLI invocation from paying React/Ink's module-load cost on every call.
+- **The lazy TUI import is load-bearing, not incidental.** `src/cli.ts` computes the dispatch token before doing anything else and only reaches `await import('./tui/index.js')` on the bare/`tui` branch — every other command path (all explicit conversions, `convert`, `formats`, `from-package`, `odm-to-pdf`, `odb-*`, `pdf-inspect`, `fonts`, `docx-extras`, `metadata`, `set-metadata`, `outline`) never touches that import at all. This is what keeps a scripted, high-frequency CLI invocation from paying React/Ink's module-load cost on every call.
 - **A bare invocation and an explicit `tui` invocation fail differently on non-interactive stdout.** `document-cli` with no arguments and redirected stdout prints help and exits `0`, on the assumption that a bare invocation piped somewhere was more likely a forgotten argument than a deliberate TUI request. `document-cli tui` with redirected stdout is unambiguous, so it fails outright (exit `2`) rather than silently reinterpreting it as a help request.
 - **`tsdown.config.ts` disables `fixedExtension` on both build passes.** `platform: 'node'` defaults tsdown's `fixedExtension` to `true`, which would emit `dist/cli.mjs`/`dist/index.mjs` regardless of `package.json`'s own `"type": "module"` — mismatching the `.js`/`.cjs` paths `bin` and `exports` actually name. Both entries set `fixedExtension: false` explicitly so the build output matches what's published.
 - **`readOdbTables` needs `decodeOdbPackage` from `documents.js`, not `decodePackage`.** `documents.js`'s own `decodePackage` re-exports `ooxml.js`'s OOXML-only reader and cannot decode an ODF `.odb` container at all; `decodeDocumentPackage(format, bytes)` dispatches to `odf.js` internally for every real `DocumentFormat` member (odt/odp/ods/odg/odf), but `.odb` is deliberately not one of those (it has no PDF conversion and no write direction — see documents.js's own README), so it has no format string to pass either. `decodeOdbPackage` is the `.odb`-specific sibling that decodes the identical raw ODF container directly — `commands/odb.ts` and the TUI's `format/open-document.ts` both use it for exactly this reason. `odf.js` and `pdf-codec` are devDependencies only: every runtime reach into them (the spreadsheet grid's `cellReference`/`columnIndexToLetters` for A1-style cell/column labelling, font-file inspection via `describeFontFace`) now goes through `documents.js`'s own re-exports, and `odf.js` survives in `devDependencies` solely because `src/test-support/embedded-font-fixture.ts` builds real ODF package fixtures from its low-level XML primitives.

package/dist/cli.js

@@ -5,6 +5,7 @@ import { writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { CsvSheetNotFoundError, CsvSheetNotSpecifiedError, HsqldbSqlEvaluationError, HsqldbSqlParseError, HsqldbSqlUnsupportedError, OdbNoEmbeddedDataSourceError, OdbReportNotSpecifiedError, OdbTableNotFoundError, OdbTableNotSpecifiedError, OdbUnsupportedFormatError, OdmUnresolvedSectionError, PdfEncryptedError, PdfParseError, SvgMultiPageNotSpecifiedError, SvgPageNotFoundError, UnrecognizedDocumentSchemaError, UnsupportedFontSourceFormatError, buildCsvText, buildDocumentBytes, buildSvgText, createLocalDocumentConverter, decodeOdbPackage, decodePackage, documentFromJson, documentPackageWithSchema, encodeCsvText, encodeSvgText, evaluateSelect, extractSourceFontsForFormat, flattenPackage, hsqldbCellDisplayText, odbReportToDocx, odbReportToOdt, odbReportToPdf, odbToCsv, odbToXlsx, odmToPdf, parseSelect, readDocumentMetadata, readDocxExtras, readOdbForms, readOdbInventory, readOdbReportContent, readOdbReports, readOdbTables, readPdf, setDocumentMetadata } from "documents.js";
 import { existsSync, readFileSync } from "node:fs";
+import { buildOutline, isOutlineNode, outlineLeafText } from "document-outline.js";
 //#region src/runtime/abort.ts
 function combineSignals(a, b) {
 	const controller = new AbortController();
@@ -381,7 +382,7 @@ function registerFontsCommand(program) {
 }
 //#endregion
 //#region src/commands/formats.ts
-const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, odb-forms, odb-reports, odb-query, odb-render-report, pdf-inspect, from-package, fonts, docx-extras, metadata, set-metadata";
+const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, odb-forms, odb-reports, odb-query, odb-render-report, pdf-inspect, from-package, fonts, docx-extras, metadata, set-metadata, outline";
 function registerFormatsCommand(program) {
 	program.command("formats").description("list every source -> target conversion this CLI supports via a <source>-to-<target> command").option("--json", "emit the conversion list as a JSON array instead of a human-readable table", false).action((options) => {
 		const { conversions } = createLocalDocumentConverter();
@@ -956,6 +957,103 @@ function registerOdmCommand(program) {
 	});
 }
 //#endregion
+//#region src/commands/outline.ts
+const OUTLINE_CONVERSION_TARGET = {
+	docx: "odt",
+	odt: "docx",
+	markdown: "docx",
+	pptx: "odp",
+	odp: "pptx",
+	xlsx: "ods",
+	ods: "xlsx",
+	csv: "xlsx",
+	odg: "odp",
+	svg: "odg",
+	pdf: "docx",
+	odf: "pdf"
+};
+const INDENT = "  ";
+function singleLineText(text) {
+	return text.replaceAll(/\s+/g, " ").trim();
+}
+function leafKindLabel(leaf) {
+	if ("kind" in leaf) return leaf.kind;
+	if ("objectKind" in leaf) return leaf.objectKind;
+	return "formula";
+}
+function appendOutlineLines(children, depth, lines) {
+	for (const child of children) if (isOutlineNode(child)) {
+		lines.push(`${INDENT.repeat(depth)}${singleLineText(child.text)}`);
+		appendOutlineLines(child.children, depth + 1, lines);
+	} else {
+		const text = singleLineText(outlineLeafText(child));
+		lines.push(text === "" ? `${INDENT.repeat(depth)}[${leafKindLabel(child)}]` : `${INDENT.repeat(depth)}${text}`);
+	}
+}
+function resolveSourceFormat(input, from) {
+	if (from !== void 0) {
+		if (!isDocumentFormat(from)) return { errorMessage: `unknown --from format '${from}'; expected one of ${KNOWN_DOCUMENT_FORMATS}` };
+		return { format: from };
+	}
+	if (input === "-") return { errorMessage: `cannot infer a source format from stdin; pass --from <format> (${KNOWN_DOCUMENT_FORMATS})` };
+	const inferred = inferFormatFromExtension(input);
+	if (inferred === void 0) return { errorMessage: `cannot infer a source format from '${input}'; rename the file with a recognised extension (${KNOWN_DOCUMENT_FORMATS}) or pass --from <format>` };
+	return { format: inferred };
+}
+async function runOutline(input, options) {
+	const command = "outline";
+	const source = resolveSourceFormat(input, options.from);
+	if ("errorMessage" in source) {
+		process.stderr.write(`[${command}] ${source.errorMessage}\n`);
+		return 2;
+	}
+	const target = OUTLINE_CONVERSION_TARGET[source.format];
+	const { signal, getAbortReason } = createRuntimeSignal({ timeoutMs: options.timeout });
+	const reporter = createDiagnosticReporter({
+		json: options.json,
+		quiet: options.quiet,
+		command
+	});
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const result = await createLocalDocumentConverter().convert({
+			source: {
+				format: source.format,
+				bytes: new Uint8Array(inputBytes)
+			},
+			targetFormat: target
+		}, {
+			signal,
+			images: createFilesystemMarkdownImageResolver(input === "-" ? "." : dirname(resolve(input)))
+		});
+		for (const diagnostic of result.diagnostics) reporter.report(diagnostic);
+		if (result.package === void 0) throw new Error(`the ${source.format}-to-${target} conversion produced no intermediate DocumentPackage`);
+		const outline = buildOutline(result.package);
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify(outline, void 0, 2)}\n`);
+			return 0;
+		}
+		const lines = [];
+		appendOutlineLines(outline, 0, lines);
+		if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+		return 0;
+	} catch (error) {
+		process.stderr.write(`[${command}] ${formatError(error, options.verbose)}\n`);
+		return mapErrorToExit(error, getAbortReason());
+	}
+}
+function registerOutlineCommand(program) {
+	const command = program.command("outline <input>").description(`print a document's outline -- headings, list items, and slide/sheet/page groups as indented text (${KNOWN_DOCUMENT_FORMATS})`);
+	addTimeoutOption(command);
+	command.option("--json", "emit the outline tree as JSON instead of indented text (diagnostics as NDJSON on stderr)", false);
+	addQuietOption(command);
+	addVerboseOption(command);
+	command.option("--from <format>", `source format when it cannot be inferred from the input path, e.g. reading from stdin (${KNOWN_DOCUMENT_FORMATS})`);
+	command.action(async (input, options) => {
+		process.exitCode = await runOutline(input, options);
+	});
+}
+//#endregion
 //#region src/commands/pdf-inspect.ts
 function buildItemKindHistogram(items) {
 	const histogram = /* @__PURE__ */ new Map();
@@ -1103,7 +1201,7 @@ function registerSetMetadataCommand(program) {
 }
 //#endregion
 //#region package.json
-var version = "3.0.11";
+var version = "3.1.0";
 //#endregion
 //#region src/program.ts
 function createProgram() {
@@ -1123,6 +1221,7 @@ function createProgram() {
 	registerFontsCommand(program);
 	registerDocxExtrasCommand(program);
 	registerMetadataCommand(program);
+	registerOutlineCommand(program);
 	registerSetMetadataCommand(program);
 	return program;
 }

package/dist/index.cjs

@@ -4,6 +4,7 @@ let node_path = require("node:path");
 let documents_js = require("documents.js");
 let node_fs = require("node:fs");
 let commander = require("commander");
+let document_outline_js = require("document-outline.js");
 //#region src/format.ts
 const EXTENSION_TO_FORMAT = {
 	docx: "docx",
@@ -433,9 +434,9 @@ function registerConversionCommands(program) {
 }
 //#endregion
 //#region src/docx-extras-format.ts
-const INDENT$1 = "  ";
+const INDENT$2 = "  ";
 function indent$1(depth) {
-	return INDENT$1.repeat(depth);
+	return INDENT$2.repeat(depth);
 }
 function commentLine(comment, position) {
 	const author = comment.author ?? "(no author)";
@@ -557,7 +558,7 @@ function registerFontsCommand(program) {
 }
 //#endregion
 //#region src/commands/formats.ts
-const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, odb-forms, odb-reports, odb-query, odb-render-report, pdf-inspect, from-package, fonts, docx-extras, metadata, set-metadata";
+const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, odb-forms, odb-reports, odb-query, odb-render-report, pdf-inspect, from-package, fonts, docx-extras, metadata, set-metadata, outline";
 function registerFormatsCommand(program) {
 	program.command("formats").description("list every source -> target conversion this CLI supports via a <source>-to-<target> command").option("--json", "emit the conversion list as a JSON array instead of a human-readable table", false).action((options) => {
 		const { conversions } = (0, documents_js.createLocalDocumentConverter)();
@@ -715,9 +716,9 @@ function registerMetadataCommand(program) {
 }
 //#endregion
 //#region src/odb-structure.ts
-const INDENT = "  ";
+const INDENT$1 = "  ";
 function indent(depth) {
-	return INDENT.repeat(depth);
+	return INDENT$1.repeat(depth);
 }
 function quoted(value) {
 	return `"${value}"`;
@@ -1288,6 +1289,103 @@ function registerOdmCommand(program) {
 	});
 }
 //#endregion
+//#region src/commands/outline.ts
+const OUTLINE_CONVERSION_TARGET = {
+	docx: "odt",
+	odt: "docx",
+	markdown: "docx",
+	pptx: "odp",
+	odp: "pptx",
+	xlsx: "ods",
+	ods: "xlsx",
+	csv: "xlsx",
+	odg: "odp",
+	svg: "odg",
+	pdf: "docx",
+	odf: "pdf"
+};
+const INDENT = "  ";
+function singleLineText(text) {
+	return text.replaceAll(/\s+/g, " ").trim();
+}
+function leafKindLabel(leaf) {
+	if ("kind" in leaf) return leaf.kind;
+	if ("objectKind" in leaf) return leaf.objectKind;
+	return "formula";
+}
+function appendOutlineLines(children, depth, lines) {
+	for (const child of children) if ((0, document_outline_js.isOutlineNode)(child)) {
+		lines.push(`${INDENT.repeat(depth)}${singleLineText(child.text)}`);
+		appendOutlineLines(child.children, depth + 1, lines);
+	} else {
+		const text = singleLineText((0, document_outline_js.outlineLeafText)(child));
+		lines.push(text === "" ? `${INDENT.repeat(depth)}[${leafKindLabel(child)}]` : `${INDENT.repeat(depth)}${text}`);
+	}
+}
+function resolveSourceFormat(input, from) {
+	if (from !== void 0) {
+		if (!isDocumentFormat(from)) return { errorMessage: `unknown --from format '${from}'; expected one of ${KNOWN_DOCUMENT_FORMATS}` };
+		return { format: from };
+	}
+	if (input === "-") return { errorMessage: `cannot infer a source format from stdin; pass --from <format> (${KNOWN_DOCUMENT_FORMATS})` };
+	const inferred = inferFormatFromExtension(input);
+	if (inferred === void 0) return { errorMessage: `cannot infer a source format from '${input}'; rename the file with a recognised extension (${KNOWN_DOCUMENT_FORMATS}) or pass --from <format>` };
+	return { format: inferred };
+}
+async function runOutline(input, options) {
+	const command = "outline";
+	const source = resolveSourceFormat(input, options.from);
+	if ("errorMessage" in source) {
+		process.stderr.write(`[${command}] ${source.errorMessage}\n`);
+		return 2;
+	}
+	const target = OUTLINE_CONVERSION_TARGET[source.format];
+	const { signal, getAbortReason } = createRuntimeSignal({ timeoutMs: options.timeout });
+	const reporter = createDiagnosticReporter({
+		json: options.json,
+		quiet: options.quiet,
+		command
+	});
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const result = await (0, documents_js.createLocalDocumentConverter)().convert({
+			source: {
+				format: source.format,
+				bytes: new Uint8Array(inputBytes)
+			},
+			targetFormat: target
+		}, {
+			signal,
+			images: createFilesystemMarkdownImageResolver(input === "-" ? "." : (0, node_path.dirname)((0, node_path.resolve)(input)))
+		});
+		for (const diagnostic of result.diagnostics) reporter.report(diagnostic);
+		if (result.package === void 0) throw new Error(`the ${source.format}-to-${target} conversion produced no intermediate DocumentPackage`);
+		const outline = (0, document_outline_js.buildOutline)(result.package);
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify(outline, void 0, 2)}\n`);
+			return 0;
+		}
+		const lines = [];
+		appendOutlineLines(outline, 0, lines);
+		if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+		return 0;
+	} catch (error) {
+		process.stderr.write(`[${command}] ${formatError(error, options.verbose)}\n`);
+		return mapErrorToExit(error, getAbortReason());
+	}
+}
+function registerOutlineCommand(program) {
+	const command = program.command("outline <input>").description(`print a document's outline -- headings, list items, and slide/sheet/page groups as indented text (${KNOWN_DOCUMENT_FORMATS})`);
+	addTimeoutOption(command);
+	command.option("--json", "emit the outline tree as JSON instead of indented text (diagnostics as NDJSON on stderr)", false);
+	addQuietOption(command);
+	addVerboseOption(command);
+	command.option("--from <format>", `source format when it cannot be inferred from the input path, e.g. reading from stdin (${KNOWN_DOCUMENT_FORMATS})`);
+	command.action(async (input, options) => {
+		process.exitCode = await runOutline(input, options);
+	});
+}
+//#endregion
 //#region src/commands/pdf-inspect.ts
 function buildItemKindHistogram(items) {
 	const histogram = /* @__PURE__ */ new Map();
@@ -1435,7 +1533,7 @@ function registerSetMetadataCommand(program) {
 }
 //#endregion
 //#region package.json
-var version = "3.0.11";
+var version = "3.1.0";
 //#endregion
 //#region src/program.ts
 function createProgram() {
@@ -1455,6 +1553,7 @@ function createProgram() {
 	registerFontsCommand(program);
 	registerDocxExtrasCommand(program);
 	registerMetadataCommand(program);
+	registerOutlineCommand(program);
 	registerSetMetadataCommand(program);
 	return program;
 }

package/dist/index.js

@@ -3,6 +3,7 @@ import { basename, dirname, extname, join, resolve } from "node:path";
 import { CsvSheetNotFoundError, CsvSheetNotSpecifiedError, HsqldbSqlEvaluationError, HsqldbSqlParseError, HsqldbSqlUnsupportedError, OdbNoEmbeddedDataSourceError, OdbReportNotSpecifiedError, OdbTableNotFoundError, OdbTableNotSpecifiedError, OdbUnsupportedFormatError, OdmUnresolvedSectionError, PdfEncryptedError, PdfParseError, SvgMultiPageNotSpecifiedError, SvgPageNotFoundError, UnrecognizedDocumentSchemaError, UnsupportedFontSourceFormatError, buildCsvText, buildDocumentBytes, buildSvgText, createLocalDocumentConverter, decodeOdbPackage, decodePackage, describeFontFace, documentFromJson, documentPackageWithSchema, encodeCsvText, encodeSvgText, evaluateSelect, extractSourceFontsForFormat, flattenPackage, hsqldbCellDisplayText, odbReportToDocx, odbReportToOdt, odbReportToPdf, odbToCsv, odbToXlsx, odmToPdf, parseSelect, readDocumentMetadata, readDocxExtras, readOdbForms, readOdbInventory, readOdbReportContent, readOdbReports, readOdbTables, readPdf, setDocumentMetadata } from "documents.js";
 import { existsSync, readFileSync } from "node:fs";
 import { Command, InvalidArgumentError } from "commander";
+import { buildOutline, isOutlineNode, outlineLeafText } from "document-outline.js";
 //#region src/format.ts
 const EXTENSION_TO_FORMAT = {
 	docx: "docx",
@@ -432,9 +433,9 @@ function registerConversionCommands(program) {
 }
 //#endregion
 //#region src/docx-extras-format.ts
-const INDENT$1 = "  ";
+const INDENT$2 = "  ";
 function indent$1(depth) {
-	return INDENT$1.repeat(depth);
+	return INDENT$2.repeat(depth);
 }
 function commentLine(comment, position) {
 	const author = comment.author ?? "(no author)";
@@ -556,7 +557,7 @@ function registerFontsCommand(program) {
 }
 //#endregion
 //#region src/commands/formats.ts
-const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, odb-forms, odb-reports, odb-query, odb-render-report, pdf-inspect, from-package, fonts, docx-extras, metadata, set-metadata";
+const COMMANDS_NOT_LISTED = "odm-to-pdf, odb-to-csv, odb-to-xlsx, odb-tables, odb-forms, odb-reports, odb-query, odb-render-report, pdf-inspect, from-package, fonts, docx-extras, metadata, set-metadata, outline";
 function registerFormatsCommand(program) {
 	program.command("formats").description("list every source -> target conversion this CLI supports via a <source>-to-<target> command").option("--json", "emit the conversion list as a JSON array instead of a human-readable table", false).action((options) => {
 		const { conversions } = createLocalDocumentConverter();
@@ -714,9 +715,9 @@ function registerMetadataCommand(program) {
 }
 //#endregion
 //#region src/odb-structure.ts
-const INDENT = "  ";
+const INDENT$1 = "  ";
 function indent(depth) {
-	return INDENT.repeat(depth);
+	return INDENT$1.repeat(depth);
 }
 function quoted(value) {
 	return `"${value}"`;
@@ -1287,6 +1288,103 @@ function registerOdmCommand(program) {
 	});
 }
 //#endregion
+//#region src/commands/outline.ts
+const OUTLINE_CONVERSION_TARGET = {
+	docx: "odt",
+	odt: "docx",
+	markdown: "docx",
+	pptx: "odp",
+	odp: "pptx",
+	xlsx: "ods",
+	ods: "xlsx",
+	csv: "xlsx",
+	odg: "odp",
+	svg: "odg",
+	pdf: "docx",
+	odf: "pdf"
+};
+const INDENT = "  ";
+function singleLineText(text) {
+	return text.replaceAll(/\s+/g, " ").trim();
+}
+function leafKindLabel(leaf) {
+	if ("kind" in leaf) return leaf.kind;
+	if ("objectKind" in leaf) return leaf.objectKind;
+	return "formula";
+}
+function appendOutlineLines(children, depth, lines) {
+	for (const child of children) if (isOutlineNode(child)) {
+		lines.push(`${INDENT.repeat(depth)}${singleLineText(child.text)}`);
+		appendOutlineLines(child.children, depth + 1, lines);
+	} else {
+		const text = singleLineText(outlineLeafText(child));
+		lines.push(text === "" ? `${INDENT.repeat(depth)}[${leafKindLabel(child)}]` : `${INDENT.repeat(depth)}${text}`);
+	}
+}
+function resolveSourceFormat(input, from) {
+	if (from !== void 0) {
+		if (!isDocumentFormat(from)) return { errorMessage: `unknown --from format '${from}'; expected one of ${KNOWN_DOCUMENT_FORMATS}` };
+		return { format: from };
+	}
+	if (input === "-") return { errorMessage: `cannot infer a source format from stdin; pass --from <format> (${KNOWN_DOCUMENT_FORMATS})` };
+	const inferred = inferFormatFromExtension(input);
+	if (inferred === void 0) return { errorMessage: `cannot infer a source format from '${input}'; rename the file with a recognised extension (${KNOWN_DOCUMENT_FORMATS}) or pass --from <format>` };
+	return { format: inferred };
+}
+async function runOutline(input, options) {
+	const command = "outline";
+	const source = resolveSourceFormat(input, options.from);
+	if ("errorMessage" in source) {
+		process.stderr.write(`[${command}] ${source.errorMessage}\n`);
+		return 2;
+	}
+	const target = OUTLINE_CONVERSION_TARGET[source.format];
+	const { signal, getAbortReason } = createRuntimeSignal({ timeoutMs: options.timeout });
+	const reporter = createDiagnosticReporter({
+		json: options.json,
+		quiet: options.quiet,
+		command
+	});
+	try {
+		const inputBytes = await readInput(input, { signal });
+		const result = await createLocalDocumentConverter().convert({
+			source: {
+				format: source.format,
+				bytes: new Uint8Array(inputBytes)
+			},
+			targetFormat: target
+		}, {
+			signal,
+			images: createFilesystemMarkdownImageResolver(input === "-" ? "." : dirname(resolve(input)))
+		});
+		for (const diagnostic of result.diagnostics) reporter.report(diagnostic);
+		if (result.package === void 0) throw new Error(`the ${source.format}-to-${target} conversion produced no intermediate DocumentPackage`);
+		const outline = buildOutline(result.package);
+		if (options.json) {
+			process.stdout.write(`${JSON.stringify(outline, void 0, 2)}\n`);
+			return 0;
+		}
+		const lines = [];
+		appendOutlineLines(outline, 0, lines);
+		if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+		return 0;
+	} catch (error) {
+		process.stderr.write(`[${command}] ${formatError(error, options.verbose)}\n`);
+		return mapErrorToExit(error, getAbortReason());
+	}
+}
+function registerOutlineCommand(program) {
+	const command = program.command("outline <input>").description(`print a document's outline -- headings, list items, and slide/sheet/page groups as indented text (${KNOWN_DOCUMENT_FORMATS})`);
+	addTimeoutOption(command);
+	command.option("--json", "emit the outline tree as JSON instead of indented text (diagnostics as NDJSON on stderr)", false);
+	addQuietOption(command);
+	addVerboseOption(command);
+	command.option("--from <format>", `source format when it cannot be inferred from the input path, e.g. reading from stdin (${KNOWN_DOCUMENT_FORMATS})`);
+	command.action(async (input, options) => {
+		process.exitCode = await runOutline(input, options);
+	});
+}
+//#endregion
 //#region src/commands/pdf-inspect.ts
 function buildItemKindHistogram(items) {
 	const histogram = /* @__PURE__ */ new Map();
@@ -1434,7 +1532,7 @@ function registerSetMetadataCommand(program) {
 }
 //#endregion
 //#region package.json
-var version = "3.0.11";
+var version = "3.1.0";
 //#endregion
 //#region src/program.ts
 function createProgram() {
@@ -1454,6 +1552,7 @@ function createProgram() {
 	registerFontsCommand(program);
 	registerDocxExtrasCommand(program);
 	registerMetadataCommand(program);
+	registerOutlineCommand(program);
 	registerSetMetadataCommand(program);
 	return program;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document-cli",
-  "version": "3.0.11",
+  "version": "3.1.0",
   "description": "CLI and interactive Ink TUI for documents.js: every docx/pptx/odt/odp/ods/odg/odf/pdf/odm/odb/xlsx/csv/svg/markdown conversion, bridge, and editor as a scriptable command or a terminal app.",
   "type": "module",
   "repository": {
@@ -88,6 +88,7 @@
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
     "commander": "^15.0.0",
+    "document-outline.js": "^1.0.0",
     "documents.js": "^3.1.2",
     "ink": "^7.1.1",
     "ink-text-input": "^6.0.0",