document-cli 3.1.10 → 3.1.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -16
- package/dist/cli.js +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.js +1 -1
- package/package.json +8 -7
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# document-cli
|
|
2
2
|
|
|
3
|
-
[](https://github.com/ExaDev/document-cli) [](https://www.npmjs.com/package/document-cli) [](https://github.com/ExaDev/documents.js/tree/main/packages/document-cli) [](https://www.npmjs.com/package/document-cli) [](https://www.npmjs.com/package/document-cli) [](https://github.com/ExaDev/documents.js/actions)
|
|
4
4
|
|
|
5
|
-
> 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`](
|
|
5
|
+
> 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`](../document-outline.js/README.md) builds over any readable document, wired up as a scriptable subcommand or a full-screen terminal editor. Installs as either `document-cli` or `doculi`.
|
|
6
6
|
|
|
7
7
|
`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.
|
|
8
8
|
|
|
@@ -38,16 +38,16 @@ graph TD
|
|
|
38
38
|
odf --> cli
|
|
39
39
|
pdfcodec --> cli
|
|
40
40
|
|
|
41
|
-
click schema "https://github.com/ExaDev/document-schema.js" "document-schema.js"
|
|
42
|
-
click ooxml "https://github.com/ExaDev/ooxml.js" "ooxml.js"
|
|
43
|
-
click odf "https://github.com/ExaDev/odf.js" "odf.js"
|
|
44
|
-
click pdfcodec "https://github.com/ExaDev/pdf-codec" "pdf-codec"
|
|
45
|
-
click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec"
|
|
46
|
-
click bytecodec "https://github.com/ExaDev/byte-codec" "byte-codec"
|
|
41
|
+
click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
|
|
42
|
+
click ooxml "https://github.com/ExaDev/documents.js/tree/main/packages/ooxml.js" "ooxml.js"
|
|
43
|
+
click odf "https://github.com/ExaDev/documents.js/tree/main/packages/odf.js" "odf.js"
|
|
44
|
+
click pdfcodec "https://github.com/ExaDev/documents.js/tree/main/packages/pdf-codec" "pdf-codec"
|
|
45
|
+
click mdcodec "https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec" "markdown-codec"
|
|
46
|
+
click bytecodec "https://github.com/ExaDev/documents.js/tree/main/packages/byte-codec" "byte-codec"
|
|
47
47
|
click documents "https://github.com/ExaDev/documents.js" "documents.js"
|
|
48
|
-
click outline "https://github.com/ExaDev/document-outline.js" "document-outline.js"
|
|
49
|
-
click mcp "https://github.com/ExaDev/document-mcp" "document-mcp"
|
|
50
|
-
click cli "https://github.com/ExaDev/document-cli" "document-cli"
|
|
48
|
+
click outline "https://github.com/ExaDev/documents.js/tree/main/packages/document-outline.js" "document-outline.js"
|
|
49
|
+
click mcp "https://github.com/ExaDev/documents.js/tree/main/packages/document-mcp" "document-mcp"
|
|
50
|
+
click cli "https://github.com/ExaDev/documents.js/tree/main/packages/document-cli" "document-cli"
|
|
51
51
|
|
|
52
52
|
style cli fill:#f9a825,stroke:#333,stroke-width:3px
|
|
53
53
|
```
|
|
@@ -56,9 +56,9 @@ graph TD
|
|
|
56
56
|
|
|
57
57
|
`documents.js` is a library, not a tool — everything it does happens through function calls from TypeScript/JavaScript. Most people who want to convert a docx to a PDF, extract an `.odb` table to CSV, or poke at a PDF's structure from a terminal don't want to write a script to do it. `document-cli` is that missing entry point: every one of documents.js's direct conversion pairs, its generic converter, its `.odm`/`.odb` extraction functions (including a bounded SQL engine over an `.odb`'s own tables and full report rendering), its PDF inspector, and its document metadata/source-font introspection become a single command-line invocation, and its seven live-view editors (docx/pptx/odt/odp/ods/odg/markdown) become a keyboard-driven terminal app that never needs a code editor open at all.
|
|
58
58
|
|
|
59
|
-
[`document-mcp`](
|
|
59
|
+
[`document-mcp`](../document-mcp/README.md) is the sibling frontend over the identical `documents.js` library — an MCP server rather than a terminal CLI/TUI — so the two are independent consumers of one shared implementation, each exposing whatever subset of it suits a human at a terminal versus an MCP-speaking agent.
|
|
60
60
|
|
|
61
|
-
The CLI and the TUI are deliberately not two separate implementations of the same logic. The TUI's own document-opening, saving, and PDF-export code (`src/tui/format/`) calls the identical `documents.js` functions the CLI commands call — `openDocx`/`createDocx`/`docxToPdf` and their five siblings per format, plus `readOdbTables`/`readPdf` for the two read-only sources — so there is exactly one place either surface can drift from what documents.js itself does: nowhere. This CLI adds no conversion logic of its own, so a conversion's fidelity — which pairs round-trip losslessly, which are a best-effort reconstruction, and why — is exactly what [`documents.js`'s own Fidelity section](
|
|
61
|
+
The CLI and the TUI are deliberately not two separate implementations of the same logic. The TUI's own document-opening, saving, and PDF-export code (`src/tui/format/`) calls the identical `documents.js` functions the CLI commands call — `openDocx`/`createDocx`/`docxToPdf` and their five siblings per format, plus `readOdbTables`/`readPdf` for the two read-only sources — so there is exactly one place either surface can drift from what documents.js itself does: nowhere. This CLI adds no conversion logic of its own, so a conversion's fidelity — which pairs round-trip losslessly, which are a best-effort reconstruction, and why — is exactly what [`documents.js`'s own Fidelity section](../documents.js/README.md#fidelity) documents, table included; it is not restated here.
|
|
62
62
|
|
|
63
63
|
## Getting started
|
|
64
64
|
|
|
@@ -70,7 +70,7 @@ npm i -g document-cli
|
|
|
70
70
|
npm i -g doculi
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
-
Both names install the exact same package and the exact same binary — `package.json`'s `bin` field declares both `document-cli` and `doculi` pointing at the one built entry point unconditionally, so there is no "real" name and an alias; pick whichever you find easier to type.
|
|
73
|
+
Both names install the exact same package and the exact same binary — `package.json`'s `bin` field declares both `document-cli` and `doculi` pointing at the one built entry point unconditionally, so there is no "real" name and an alias; pick whichever you find easier to type. Unlike a sibling's second *npm package name* (`documents.js`'s own `js.documents` — see that package's README, and note the older per-repo pipeline's GitHub Packages republish this pattern used to mirror is no longer running, per [ExaDev/documents.js#732](https://github.com/ExaDev/documents.js/issues/732)), this is one package with two `bin` entries: a second name for the same build, not a second build, and unaffected by that gap.
|
|
74
74
|
|
|
75
75
|
## Usage
|
|
76
76
|
|
|
@@ -168,7 +168,7 @@ document-cli set-metadata report.docx report.docx --set-title "Q3 Report" --set-
|
|
|
168
168
|
document-cli set-metadata report.docx report.odt --set-keywords "draft,internal"
|
|
169
169
|
```
|
|
170
170
|
|
|
171
|
-
**`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`](
|
|
171
|
+
**`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`](../document-outline.js/README.md)'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):
|
|
172
172
|
|
|
173
173
|
```sh
|
|
174
174
|
document-cli outline report.docx
|
|
@@ -286,7 +286,11 @@ pnpm test:workers # turbo run _test:workers -> vitest run --config vitest.worke
|
|
|
286
286
|
- **`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.
|
|
287
287
|
- **`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.
|
|
288
288
|
- **A TUI screen must call an editor's own accessors fresh on every render, never cache them.** documents.js's live-view editors (`DocxRun`, `OdtParagraph`, `OdsCell`, ...) mutate the real XML tree in place — `editor.paragraphs()`/`slide.shapes()`/`sheet.cell(r, c)` called once and stored in `useState`/`useMemo` goes stale the instant any screen mutates the underlying document, with nothing in the type system or in React to catch it (see `src/tui/state/types.ts`'s own doc comment on `Screen`).
|
|
289
|
-
- **The conversions this CLI runs carry the same fidelity limits documents.js itself documents** — most notably that PDF-pivot conversions are not round-trip-lossless (line wrapping drifts under standard-14 font substitution, justified text renders left-aligned, tables and vector shapes don't reconstruct from a PDF), and that `pdf-to-ods` recovers only what a spreadsheet printed, never a real number/date/formula. None of that is specific to this CLI or the TUI; see documents.js's own README, particularly its [Fidelity](
|
|
289
|
+
- **The conversions this CLI runs carry the same fidelity limits documents.js itself documents** — most notably that PDF-pivot conversions are not round-trip-lossless (line wrapping drifts under standard-14 font substitution, justified text renders left-aligned, tables and vector shapes don't reconstruct from a PDF), and that `pdf-to-ods` recovers only what a spreadsheet printed, never a real number/date/formula. None of that is specific to this CLI or the TUI; see documents.js's own README, particularly its [Fidelity](../documents.js/README.md#fidelity) section, for the full, format-by-format account.
|
|
290
|
+
|
|
291
|
+
## Contributing
|
|
292
|
+
|
|
293
|
+
Release, CI, and commit-message conventions are all workspace-wide, not package-local — see the [monorepo root README](../../README.md#releases) for the release mechanism and [CONTRIBUTING.md](../../CONTRIBUTING.md) for the shared git hooks and history conventions. Work inside `packages/document-cli/`.
|
|
290
294
|
|
|
291
295
|
## License
|
|
292
296
|
|
package/dist/cli.js
CHANGED
package/dist/index.cjs
CHANGED
package/dist/index.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "document-cli",
|
|
3
|
-
"version": "3.1.
|
|
3
|
+
"version": "3.1.12",
|
|
4
4
|
"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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
@@ -55,8 +55,9 @@
|
|
|
55
55
|
"prepublishOnly": "pnpm run lint && pnpm run typecheck && tsdown && publint && attw --pack",
|
|
56
56
|
"lint": "turbo run _lint",
|
|
57
57
|
"_lint": "eslint . --fix --cache --max-warnings 0",
|
|
58
|
-
"typecheck": "turbo run _typecheck",
|
|
58
|
+
"typecheck": "turbo run _typecheck _typecheck:attw",
|
|
59
59
|
"_typecheck": "tsc --noEmit",
|
|
60
|
+
"_typecheck:attw": "attw --pack",
|
|
60
61
|
"test": "turbo run _test",
|
|
61
62
|
"_test": "vitest run --project unit",
|
|
62
63
|
"test:watch": "vitest --project unit",
|
|
@@ -89,9 +90,9 @@
|
|
|
89
90
|
"packageManager": "pnpm@11.6.0",
|
|
90
91
|
"dependencies": {
|
|
91
92
|
"commander": "^15.0.0",
|
|
92
|
-
"document-outline.js": "^1.0.
|
|
93
|
-
"document-schema.js": "^4.3.
|
|
94
|
-
"documents.js": "^4.0.
|
|
93
|
+
"document-outline.js": "^1.0.4",
|
|
94
|
+
"document-schema.js": "^4.3.7",
|
|
95
|
+
"documents.js": "^4.0.24",
|
|
95
96
|
"ink": "^7.1.1",
|
|
96
97
|
"ink-text-input": "^6.0.0",
|
|
97
98
|
"react": "^19.2.8"
|
|
@@ -113,8 +114,8 @@
|
|
|
113
114
|
"husky": "^9.1.7",
|
|
114
115
|
"ink-testing-library": "^4.0.0",
|
|
115
116
|
"lint-staged": "^17.3.0",
|
|
116
|
-
"odf.js": "^5.0.
|
|
117
|
-
"pdf-codec": "^3.0.
|
|
117
|
+
"odf.js": "^5.0.7",
|
|
118
|
+
"pdf-codec": "^3.0.12",
|
|
118
119
|
"publint": "^0.3.22",
|
|
119
120
|
"semantic-release": "^25.0.8",
|
|
120
121
|
"tsdown": "^0.22.14",
|