postext-cli 0.0.0-stage → 1.22.3

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# postext-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.
+**The [postext](https://postext.dev/) command line.**
+
+`postext` turns a book written in Markdown into a PDF, HTML, an EPUB, page images or a Word file, from a terminal, a script or an agent. It is one self-contained executable per system: the Bun runtime, the postext engine, the PDF, EPUB, HTML and Word writers, the page painter (Skia), HarfBuzz, the default fonts (EB Garamond, Open Sans) and the ICC print profiles are all inside it. There is nothing to install.
+
+## Get it
+
+Every postext release attaches the executables to its [GitHub Release](https://github.com/drnachio/postext/releases/latest), with `SHA256SUMS` and [`readme.txt`](bin/readme.txt):
+
+| File | System |
+|---|---|
+| `postext-macos-arm64` | macOS, Apple silicon |
+| `postext-macos-x64` | macOS, Intel |
+| `postext-linux-x64` | Linux x86-64 (glibc) |
+| `postext-linux-arm64` | Linux ARM64 (glibc) |
+| `postext-linux-x64-musl` | Linux x86-64, musl (Alpine: `apk add libstdc++ libgcc`) |
+| `postext-windows-x64.exe` | Windows x64 |
+
+```bash
+curl -fL -o postext https://github.com/drnachio/postext/releases/latest/download/postext-linux-x64
+chmod +x postext
+./postext
+```
+
+With Node.js, `npx postext-cli` downloads the executable of your system from npm and runs it.
+
+## Use
+
+```bash
+postext                                        # help
+postext help pdf                               # options of a command
+postext pdf book.postext -o book.pdf
+postext pdf book/ --pdfx x4 --profile fogra51  # print-ready PDF/X-4
+postext html book.postext -o book.html         # one self-contained page
+postext epub book.postext --layout reflowable
+postext image book.postext --page 12 -o p12.png
+postext images book.postext --pages 1-10 -o pages/ --dpi 100 -f webp
+postext docx book.postext -o book.docx
+postext import-docx manuscript.docx -o manuscript/
+postext pack book/ -o book.postext
+postext unpack book.postext -o book/
+postext info book.postext --pages
+postext check book.postext --json
+postext build book/ --pdf out/book.pdf --html out/book.html --watch
+```
+
+A book is any of:
+
+- a `.postext` bundle, the file the [Sandbox](https://postext.dev/en/sandbox) exports and opens;
+- an unpacked book folder, with its `preset.json`, chapters, resources and fonts;
+- loose Markdown files, one chapter each, in the order given (a folder: its `.md` files by name), with an optional `--config` JSON, a `--resources` folder of pictures (each named by its file name, or described in a `resources.json`) and a `--fonts` folder.
+
+`--set path=value` changes one setting without editing the book (`--set page.dpi=150`, `--set bodyText.fontFamily=Lora`), and `--chapters 2-4` lays out part of it.
+
+### Fonts
+
+A family the book does not carry is looked up in the `--font-dir` folders, then among the faces compiled in (EB Garamond, Open Sans), then in the cache, then downloaded once from Google Fonts into `~/.cache/postext` (`%LOCALAPPDATA%\postext\cache` on Windows; `POSTEXT_CACHE_DIR` or `--cache-dir` moves it). `--offline` never downloads. A family found nowhere is set in EB Garamond, with a warning, so the layout and the PDF still agree.
+
+### Scripts and agents
+
+- `--json` prints one JSON object on stdout: the outputs written, the page count, every warning (with the chapter file and line, and the page), and the time each step took. Messages go to stderr.
+- Exit codes: `0` done, `1` failed, `2` wrong usage, `3` `check` found errors (or any warning with `--strict`).
+- `-o -` writes a single output to stdout (`postext image book.postext -p 1 -o - | …`).
+- `postext build` lays the book out once for several outputs, and `--watch` keeps the engine and the fonts loaded: a change is laid out again in a fraction of a second.
+
+## Develop
+
+```bash
+pnpm --filter postext-cli start pdf book.postext      # run from the sources
+pnpm --filter postext-cli test                        # bun test (units and end to end)
+pnpm --filter postext-cli build:bin                   # every executable into bin/
+pnpm --filter postext-cli build:bin --current         # this machine's only
+sh scripts/smoke.sh bin/postext-macos-arm64           # smoke test an executable
+```
+
+`scripts/build-bin.ts` cross-compiles every target from one machine: it fetches Skia's native addon for each platform from npm and embeds it. The release workflow builds them, runs `scripts/smoke.sh` on Linux (glibc and Alpine), macOS and Windows runners, attaches them to the GitHub Release and publishes the npm packages (`scripts/npm-publish.mjs`).
+
+## License
+
+MIT. The embedded EB Garamond and Open Sans are under the SIL Open Font License ([`fonts/`](fonts/)).

package/bin/readme.txt

@@ -0,0 +1,78 @@
+postext command line 1.22.3
+===========================
+
+One self-contained executable per system: no installation, no runtime and
+no libraries. The postext engine, the PDF, EPUB, HTML and Word writers,
+the page painter (Skia), the default fonts (EB Garamond, Open Sans) and the
+print colour profiles are all inside.
+
+Executables (115 to 140 MB each)
+--------------------------------
+
+  postext-macos-arm64          macOS, Apple silicon (M1 and later)
+  postext-macos-x64            macOS, Intel
+  postext-linux-x64            Linux x86-64 (glibc: Debian, Ubuntu, Fedora…)
+  postext-linux-arm64          Linux ARM64 (glibc: Raspberry Pi OS 64-bit, Graviton…)
+  postext-linux-x64-musl       Linux x86-64, musl (Alpine)
+  postext-windows-x64.exe      Windows x64
+
+Download the latest (every release of postext publishes them):
+
+  https://github.com/drnachio/postext/releases/latest/download/<file>
+
+  e.g. https://github.com/drnachio/postext/releases/latest/download/postext-linux-x64
+
+or a given version: https://github.com/drnachio/postext/releases/tag/v1.22.3
+SHA256SUMS lists the checksum of each file.
+
+Install
+-------
+
+Linux and macOS:
+
+  curl -fL -o postext https://github.com/drnachio/postext/releases/latest/download/postext-linux-x64
+  chmod +x postext
+  ./postext                       # prints the help
+  sudo mv postext /usr/local/bin  # optional: run it from anywhere
+
+Linux builds need only the C library every distribution has (glibc 2.27
+or later; musl for Alpine, which also needs `apk add libstdc++ libgcc`).
+
+macOS: a file downloaded with a browser is quarantined; clear the flag once:
+
+  xattr -d com.apple.quarantine postext-macos-arm64
+
+Windows (PowerShell):
+
+  Invoke-WebRequest https://github.com/drnachio/postext/releases/latest/download/postext-windows-x64.exe -OutFile postext.exe
+  .\postext.exe
+
+With Node.js installed, `npx postext-cli` downloads and runs the right one.
+
+Use
+---
+
+  postext                                   help
+  postext help <command>                    options of a command
+  postext pdf book.postext -o book.pdf      PDF
+  postext html book.postext -o book.html    HTML (one self-contained file)
+  postext epub book.postext -o book.epub    EPUB 3
+  postext image book.postext --page 1 -o p1.png        one page as an image
+  postext images book.postext -o pages/ --dpi 100      every page
+  postext docx book.postext -o book.docx    Word
+  postext import-docx draft.docx -o draft/  Word to a postext book
+  postext pack book/ -o book.postext        folder (or Markdown files) to a bundle
+  postext unpack book.postext -o book/      bundle to a folder
+  postext info book.postext                 chapters, fonts, resources
+  postext check book.postext --json         problems, as JSON for scripts and agents
+  postext build book/ --pdf b.pdf --html b.html --watch   several outputs, rebuild on change
+
+A book is a .postext file, an unpacked folder with its preset.json, or loose
+Markdown files (one chapter each) with --config, --resources and --fonts.
+Fonts the book does not carry are looked up in --font-dir folders, then
+downloaded once from Google Fonts into ~/.cache/postext (--offline never
+downloads).
+
+Exit codes: 0 done, 1 failed, 2 wrong usage, 3 check found problems.
+
+Docs: https://postext.dev/docs · Source: https://github.com/drnachio/postext

package/npm/postext.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// `npx postext-cli` / `postext` installed from npm: runs the executable of
+// this platform, which npm installed as one of the optional dependencies
+// (postext-cli-<os>-<arch>). The executable needs no Node.js; this file
+// only finds it.
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const os = { darwin: 'macos', linux: 'linux', win32: 'windows' }[process.platform];
+const arch = { arm64: 'arm64', x64: 'x64' }[process.arch];
+const musl = process.platform === 'linux' && !process.report?.getReport()?.header?.glibcVersionRuntime;
+const name = `postext-cli-${os}-${arch}${musl ? '-musl' : ''}`;
+const exe = `postext${process.platform === 'win32' ? '.exe' : ''}`;
+
+let bin;
+try {
+  bin = require.resolve(`${name}/bin/${exe}`);
+} catch {
+  console.error(`postext: no executable for ${process.platform}-${process.arch}${musl ? ' (musl)' : ''} (package ${name}).`);
+  console.error('Download one from https://github.com/drnachio/postext/releases/latest');
+  process.exit(1);
+}
+const result = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) {
+  console.error(`postext: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "postext-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.22.3",
+  "license": "MIT",
+  "homepage": "https://postext.dev/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/drnachio/postext.git",
+    "directory": "packages/postext-cli"
+  },
+  "description": "The postext command line: PDF, HTML, EPUB, page images and Word files from a .postext book or loose Markdown, in one self-contained executable for Linux, macOS and Windows.",
+  "keywords": [
+    "postext",
+    "cli",
+    "pdf",
+    "epub",
+    "typesetting",
+    "markdown",
+    "book"
+  ],
+  "type": "module",
+  "bin": {
+    "postext": "npm/postext.js"
+  },
+  "files": [
+    "npm/postext.js",
+    "bin/readme.txt"
+  ],
+  "optionalDependencies": {
+    "postext-cli-macos-arm64": "1.22.3",
+    "postext-cli-macos-x64": "1.22.3",
+    "postext-cli-linux-x64": "1.22.3",
+    "postext-cli-linux-arm64": "1.22.3",
+    "postext-cli-linux-x64-musl": "1.22.3",
+    "postext-cli-windows-x64": "1.22.3"
+  }
+}