@thegetty/quire-cli 1.0.0-rc.44 → 1.0.0-rc.45

package/man/quire.1

@@ -0,0 +1,341 @@
+.TH "QUIRE" "1" "January 2026" "1.0.0-rc.38"
+.SH "NAME"
+\fBquire\fR \- Quire command\-line interface
+.SH SYNOPSIS
+.P
+\fBquire\fP [options] <command> [command\-options]
+.SH DESCRIPTION
+.P
+Quire is a command\-line tool for creating and publishing digital books\.
+.br
+It generates static websites, PDFs, and EPUBs from a Quire project
+.br
+containing Markdown content and YAML data files\.
+.P
+A typical workflow starts with \fBquire new\fP to scaffold a project, \fBquire preview\fP to develop locally, and \fBquire build\fP, \fBquire pdf\fP, or \fBquire epub\fP to produce publication outputs\.
+.SH COMMANDS
+.SS Project Creation
+
+.RS 1
+.IP \(bu 2
+\fBnew\fP [projectPath] [starter]:
+.br
+Create a new Quire project from a template\. If \fIprojectPath\fR is
+.br
+omitted, the current directory is used\. An optional \fIstarter\fR argument
+.br
+specifies a repository URL or local path for a starter project\.
+.P
+\fB\-\-quire\-version\fP \fIversion\fR pins the quire\-11ty version to install\.
+.br
+\fB\-\-quire\-path\fP \fIpath\fR uses a local quire\-11ty package instead of a
+.br
+published version\.
+
+.RE
+.SS Development
+
+.RS 1
+.IP \(bu 2
+\fBpreview\fP:
+.br
+Start a local development server with live reload\. Changes to source
+.br
+files are rebuilt automatically\.
+.P
+\fB\-p\fP, \fB\-\-port\fP \fIport\fR sets the server port (default: 8080)\.
+.br
+\fB\-\-open\fP opens the browser when the server starts\.
+.IP \(bu 2
+\fBbuild\fP:
+.br
+Run the Eleventy build to generate static HTML output\. Build outputs
+.br
+are written to the project's output directory\.
+.P
+\fB\-d\fP, \fB\-\-dry\-run\fP runs the build without writing files\.
+.IP \(bu 2
+\fBclean\fP:
+.br
+Remove build outputs (HTML, PDF, and EPUB files)\.
+.P
+\fB\-d\fP, \fB\-\-dry\-run\fP shows paths that would be deleted without removing them\.
+.br
+\fB\-\-status\fP also clears stored build status for the project\.
+
+.RE
+.SS Output Generation
+
+.RS 1
+.IP \(bu 2
+\fBpdf\fP:
+.br
+Generate a print\-ready PDF from build output\.
+.P
+\fB\-\-engine\fP \fIname\fR selects the PDF engine (\fBpagedjs\fP or \fBprince\fP; default:
+.br
+from config or \fBpagedjs\fP)\.
+.br
+\fB\-\-build\fP runs the site build first if output is missing\.
+.br
+\fB\-\-open\fP opens the PDF in the default application after generation\.
+.br
+\fB\-o\fP, \fB\-\-output\fP \fIpath\fR sets a custom output file path\.
+.IP \(bu 2
+\fBepub\fP:
+.br
+Generate an EPUB e\-book from build output\.
+.P
+\fB\-\-engine\fP \fIname\fR selects the EPUB engine (\fBepubjs\fP or \fBpandoc\fP; default:
+.br
+from config or \fBepubjs\fP)\.
+.br
+\fB\-\-build\fP runs the site build first if output is missing\.
+.br
+\fB\-\-open\fP opens the EPUB in the default application after generation\.
+.br
+\fB\-o\fP, \fB\-\-output\fP \fIpath\fR sets a custom output file path\.
+
+.RE
+.SS Information and Diagnostics
+
+.RS 1
+.IP \(bu 2
+\fBdoctor\fP [checks\.\.\.]:
+.br
+Run diagnostic checks on the Quire environment and project\. Checks are
+.br
+organized into four sections: Environment (os, cli, node, runtime, npm,
+.br
+git), Tools (prince, pandoc), Project (project, deps, 11ty, data), and
+.br
+Outputs (build, pdf, epub)\.
+.P
+Without arguments, all checks are run\. Pass section names or individual
+.br
+check IDs to run a subset (e\.g\., \fBquire doctor environment\fP or
+.br
+\fBquire doctor node git\fP)\.
+.P
+\fB\-e\fP, \fB\-\-errors\fP shows only failed checks\.
+.br
+\fB\-w\fP, \fB\-\-warnings\fP shows only warnings\.
+.br
+\fB\-\-json\fP [\fIfile\fR] outputs results as JSON to stdout or a file\.
+.br
+\fB\-\-reset\fP clears stored build status for the current project\.
+.P
+Aliases: \fBcheckup\fP, \fBcheck\fP, \fBdiagnostic\fP, \fBhealth\fP\|\.
+.IP \(bu 2
+\fBinfo\fP:
+.br
+Display version information for the current project, including
+.br
+quire\-cli, quire\-11ty, and starter template versions\.
+.P
+\fB\-\-debug\fP includes installation paths\.
+.br
+\fB\-\-json\fP outputs version information as JSON\.
+.IP \(bu 2
+\fBvalidate\fP:
+.br
+Check YAML files in the project's \fBcontent/_data/\fP directory for
+.br
+syntax errors\.
+.P
+\fB\-\-json\fP outputs validation results as JSON\.
+.IP \(bu 2
+\fBsettings\fP [operation] [key] [value]:
+.br
+View and modify CLI settings\. Without arguments, displays all current
+.br
+settings\.
+.P
+Operations: \fBget\fP, \fBset\fP, \fBdelete\fP, \fBreset\fP, \fBpath\fP\|\.
+.P
+\fB\-\-json\fP outputs raw JSON\.
+.br
+\fB\-\-debug\fP enables debug output for troubleshooting\.
+.P
+Aliases: \fBprefs\fP, \fBpreferences\fP, \fBconf\fP, \fBconfig\fP, \fBconfigure\fP\|\.
+.IP \(bu 2
+\fBhelp\fP [topic]:
+.br
+Display help for a topic or list available topics\. Topics include
+.br
+individual commands, workflows, and configuration guides\.
+.P
+\fB\-\-list\fP lists all available topics\.
+.P
+Alias: \fBh\fP\|\.
+
+.RE
+.SH GLOBAL OPTIONS
+
+.RS 1
+.IP \(bu 2
+\fB\-q\fP, \fB\-\-quiet\fP:
+.br
+Suppress progress output\. Hides spinner messages, quire\-11ty log
+.br
+output, Vite log output, and the Eleventy directory listing\. Exit
+.br
+codes still indicate success or failure\. Useful for CI pipelines
+.br
+and scripts\.
+.IP \(bu 2
+\fB\-v\fP, \fB\-\-verbose\fP:
+.br
+Show detailed progress\. Enables quire\-11ty informational log output,
+.br
+the Eleventy directory listing (file\-by\-file build table), and Vite
+.br
+info\-level output in addition to spinner messages\.
+.IP \(bu 2
+\fB\-\-debug\fP:
+.br
+Enable debug output for troubleshooting\. Activates the \fBquire:*\fP debug
+.br
+namespace, Eleventy's \fBDEBUG=Eleventy*\fP tracing, and quire\-11ty debug\-
+.br
+level log output\. Can be combined with \fB\-\-verbose\fP\.
+.IP \(bu 2
+\fB\-\-reduced\-motion\fP:
+.br
+Disable spinner animation and line overwriting\. Each build phase prints
+.br
+on a new line with a static status symbol\. Compatible with screen
+.br
+readers and terminals that do not support ANSI escape sequences\. Can
+.br
+also be enabled via the \fBREDUCED_MOTION\fP environment variable or the
+.br
+\fBreducedMotion\fP config setting\.
+.IP \(bu 2
+\fB\-\-color\fP:
+.br
+Force colored output, overriding the \fBNO_COLOR\fP environment variable\.
+.IP \(bu 2
+\fB\-\-no\-color\fP:
+.br
+Disable colored output\.
+.IP \(bu 2
+\fB\-\-no\-pager\fP:
+.br
+Disable paging for long output (e\.g\., help topics)\.
+.IP \(bu 2
+\fB\-V\fP, \fB\-\-version\fP:
+.br
+Output the quire version number\.
+.IP \(bu 2
+\fB\-h\fP, \fB\-\-help\fP:
+.br
+Display help for quire or a subcommand\.
+
+.RE
+.SH ENVIRONMENT
+
+.RS 1
+.IP \(bu 2
+\fBQUIRE_LOG_LEVEL\fP=\fIlevel\fR:
+.br
+Override the log verbosity for quire\-11ty output\. Valid values are
+.br
+\fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarn\fP, \fBerror\fP, and \fBsilent\fP\. This is
+.br
+normally set automatically by the CLI based on \fB\-\-quiet\fP, \fB\-\-verbose\fP,
+.br
+and \fB\-\-debug\fP flags\. Setting it manually is useful when running
+.br
+quire\-11ty outside the CLI\.
+.IP \(bu 2
+\fBREDUCED_MOTION\fP=\fI1\fR:
+.br
+Disable spinner animation, equivalent to \fB\-\-reduced\-motion\fP\.
+.IP \(bu 2
+\fBNO_COLOR\fP=\fI1\fR:
+.br
+Disable colored output (respected by chalk)\. Overridden by \fB\-\-color\fP\.
+.IP \(bu 2
+\fBNO_PAGER\fP=\fI1\fR:
+.br
+Disable paging for long output, equivalent to \fB\-\-no\-pager\fP\.
+.IP \(bu 2
+\fBPAGER\fP=\fIprogram\fR:
+.br
+Set the pager program for long output (default: \fBless\fP)\.
+.IP \(bu 2
+\fBDEBUG\fP=\fIpattern\fR:
+.br
+Enable debug output for matching namespaces\. Examples:
+.P
+\fBDEBUG=quire:*\fP enables all Quire CLI debug output\.
+.br
+\fBDEBUG=quire:lib:pdf\fP enables only PDF module debug output\.
+.br
+\fBDEBUG=quire:lib:*\fP enables all library module debug output\.
+.br
+\fBDEBUG=Eleventy*\fP enables Eleventy internal debug output\.
+
+.RE
+.SH COMMON WORKFLOWS
+.P
+Start a new project and preview it locally:
+.RS 2
+.nf
+quire new my\-book && cd my\-book && quire preview
+.fi
+.RE
+.P
+Build the site for web deployment:
+.RS 2
+.nf
+quire clean && quire build
+.fi
+.RE
+.P
+Generate all publication formats:
+.RS 2
+.nf
+quire clean && quire build && quire pdf && quire epub
+.fi
+.RE
+.P
+Build and open a PDF in one step:
+.RS 2
+.nf
+quire pdf \-\-build \-\-open
+.fi
+.RE
+.SH CONFIGURATION
+.P
+Persistent settings are managed with the \fBquire settings\fP command\. Common
+.br
+settings include:
+.RS 2
+.nf
+quire settings set verbose true
+quire settings set pdfEngine prince
+quire settings set updateChannel rc
+.fi
+.RE
+.P
+Run \fBquire settings\fP to see all available settings and their current values\.
+.br
+Run \fBquire settings path\fP to show the configuration file location\.
+.SH EXIT STATUS
+
+.RS 1
+.IP \(bu 2
+\fB0\fP: Success
+.IP \(bu 2
+\fB1\fP: Command failed (build error, validation error, missing output, etc\.)
+
+.RE
+.SH SEE ALSO
+.P
+Full documentation: https://quire.getty.edu/docs-v1
+.P
+Report bugs: https://github.com/thegetty/quire/issues
+.P
+Source code: https://github.com/thegetty/quire

package/man/quire.1.md

@@ -0,0 +1,232 @@
+# quire(1) -- Quire command-line interface
+
+## SYNOPSIS
+
+`quire` \[options\] <command> \[command-options\]
+
+## DESCRIPTION
+
+Quire is a command-line tool for creating and publishing digital books.
+It generates static websites, PDFs, and EPUBs from a Quire project
+containing Markdown content and YAML data files.
+
+A typical workflow starts with `quire new` to scaffold a project, `quire
+preview` to develop locally, and `quire build`, `quire pdf`, or `quire
+epub` to produce publication outputs.
+
+## COMMANDS
+
+### Project Creation
+
+* `new` \[projectPath\] \[starter\]:
+  Create a new Quire project from a template. If _projectPath_ is
+  omitted, the current directory is used. An optional _starter_ argument
+  specifies a repository URL or local path for a starter project.
+
+  `--quire-version` _version_ pins the quire-11ty version to install.
+  `--quire-path` _path_ uses a local quire-11ty package instead of a
+  published version.
+
+### Development
+
+* `preview`:
+  Start a local development server with live reload. Changes to source
+  files are rebuilt automatically.
+
+  `-p`, `--port` _port_ sets the server port (default: 8080).
+  `--open` opens the browser when the server starts.
+
+* `build`:
+  Run the Eleventy build to generate static HTML output. Build outputs
+  are written to the project's output directory.
+
+  `-d`, `--dry-run` runs the build without writing files.
+
+* `clean`:
+  Remove build outputs (HTML, PDF, and EPUB files).
+
+  `-d`, `--dry-run` shows paths that would be deleted without removing them.
+  `--status` also clears stored build status for the project.
+
+### Output Generation
+
+* `pdf`:
+  Generate a print-ready PDF from build output.
+
+  `--engine` _name_ selects the PDF engine (`pagedjs` or `prince`; default:
+  from config or `pagedjs`).
+  `--build` runs the site build first if output is missing.
+  `--open` opens the PDF in the default application after generation.
+  `-o`, `--output` _path_ sets a custom output file path.
+
+* `epub`:
+  Generate an EPUB e-book from build output.
+
+  `--engine` _name_ selects the EPUB engine (`epubjs` or `pandoc`; default:
+  from config or `epubjs`).
+  `--build` runs the site build first if output is missing.
+  `--open` opens the EPUB in the default application after generation.
+  `-o`, `--output` _path_ sets a custom output file path.
+
+### Information and Diagnostics
+
+* `doctor` \[checks...\]:
+  Run diagnostic checks on the Quire environment and project. Checks are
+  organized into four sections: Environment (os, cli, node, runtime, npm,
+  git), Tools (prince, pandoc), Project (project, deps, 11ty, data), and
+  Outputs (build, pdf, epub).
+
+  Without arguments, all checks are run. Pass section names or individual
+  check IDs to run a subset (e.g., `quire doctor environment` or
+  `quire doctor node git`).
+
+  `-e`, `--errors` shows only failed checks.
+  `-w`, `--warnings` shows only warnings.
+  `--json` \[_file_\] outputs results as JSON to stdout or a file.
+  `--reset` clears stored build status for the current project.
+
+  Aliases: `checkup`, `check`, `diagnostic`, `health`.
+
+* `info`:
+  Display version information for the current project, including
+  quire-cli, quire-11ty, and starter template versions.
+
+  `--debug` includes installation paths.
+  `--json` outputs version information as JSON.
+
+* `validate`:
+  Check YAML files in the project's `content/_data/` directory for
+  syntax errors.
+
+  `--json` outputs validation results as JSON.
+
+* `settings` \[operation\] \[key\] \[value\]:
+  View and modify CLI settings. Without arguments, displays all current
+  settings.
+
+  Operations: `get`, `set`, `delete`, `reset`, `path`.
+
+  `--json` outputs raw JSON.
+  `--debug` enables debug output for troubleshooting.
+
+  Aliases: `prefs`, `preferences`, `conf`, `config`, `configure`.
+
+* `help` \[topic\]:
+  Display help for a topic or list available topics. Topics include
+  individual commands, workflows, and configuration guides.
+
+  `--list` lists all available topics.
+
+  Alias: `h`.
+
+## GLOBAL OPTIONS
+
+* `-q`, `--quiet`:
+  Suppress progress output. Hides spinner messages, quire-11ty log
+  output, Vite log output, and the Eleventy directory listing. Exit
+  codes still indicate success or failure. Useful for CI pipelines
+  and scripts.
+
+* `-v`, `--verbose`:
+  Show detailed progress. Enables quire-11ty informational log output,
+  the Eleventy directory listing (file-by-file build table), and Vite
+  info-level output in addition to spinner messages.
+
+* `--debug`:
+  Enable debug output for troubleshooting. Activates the `quire:*` debug
+  namespace, Eleventy's `DEBUG=Eleventy*` tracing, and quire-11ty debug-
+  level log output. Can be combined with `--verbose`.
+
+* `--reduced-motion`:
+  Disable spinner animation and line overwriting. Each build phase prints
+  on a new line with a static status symbol. Compatible with screen
+  readers and terminals that do not support ANSI escape sequences. Can
+  also be enabled via the `REDUCED_MOTION` environment variable or the
+  `reducedMotion` config setting.
+
+* `--color`:
+  Force colored output, overriding the `NO_COLOR` environment variable.
+
+* `--no-color`:
+  Disable colored output.
+
+* `--no-pager`:
+  Disable paging for long output (e.g., help topics).
+
+* `-V`, `--version`:
+  Output the quire version number.
+
+* `-h`, `--help`:
+  Display help for quire or a subcommand.
+
+## ENVIRONMENT
+
+* `QUIRE_LOG_LEVEL`=_level_:
+  Override the log verbosity for quire-11ty output. Valid values are
+  `trace`, `debug`, `info`, `warn`, `error`, and `silent`. This is
+  normally set automatically by the CLI based on `--quiet`, `--verbose`,
+  and `--debug` flags. Setting it manually is useful when running
+  quire-11ty outside the CLI.
+
+* `REDUCED_MOTION`=_1_:
+  Disable spinner animation, equivalent to `--reduced-motion`.
+
+* `NO_COLOR`=_1_:
+  Disable colored output (respected by chalk). Overridden by `--color`.
+
+* `NO_PAGER`=_1_:
+  Disable paging for long output, equivalent to `--no-pager`.
+
+* `PAGER`=_program_:
+  Set the pager program for long output (default: `less`).
+
+* `DEBUG`=_pattern_:
+  Enable debug output for matching namespaces. Examples:
+
+  `DEBUG=quire:*` enables all Quire CLI debug output.
+  `DEBUG=quire:lib:pdf` enables only PDF module debug output.
+  `DEBUG=quire:lib:*` enables all library module debug output.
+  `DEBUG=Eleventy*` enables Eleventy internal debug output.
+
+## COMMON WORKFLOWS
+
+Start a new project and preview it locally:
+
+    quire new my-book && cd my-book && quire preview
+
+Build the site for web deployment:
+
+    quire clean && quire build
+
+Generate all publication formats:
+
+    quire clean && quire build && quire pdf && quire epub
+
+Build and open a PDF in one step:
+
+    quire pdf --build --open
+
+## CONFIGURATION
+
+Persistent settings are managed with the `quire settings` command. Common
+settings include:
+
+    quire settings set verbose true
+    quire settings set pdfEngine prince
+    quire settings set updateChannel rc
+
+Run `quire settings` to see all available settings and their current values.
+Run `quire settings path` to show the configuration file location.
+
+## EXIT STATUS
+
+* `0`: Success
+* `1`: Command failed (build error, validation error, missing output, etc.)
+
+## SEE ALSO
+
+Full documentation: <https://quire.getty.edu/docs-v1>
+
+Report bugs: <https://github.com/thegetty/quire/issues>
+
+Source code: <https://github.com/thegetty/quire>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thegetty/quire-cli",
   "description": "Quire command-line interface",
-  "version": "1.0.0-rc.44",
+  "version": "1.0.0-rc.45",
   "author": "Getty Digital",
   "license": "SEE LICENSE IN https://github.com/thegetty/quire/blob/main/LICENSE",
   "bugs": {
@@ -16,9 +16,11 @@
     "quire": "./bin/cli.js"
   },
   "exports": "./bin/cli.js",
+  "man": "./man/quire.1",
   "type": "module",
   "files": [
     "bin/",
+    "man/",
     "patches/",
     "schemas/",
     "scripts/",
@@ -36,7 +38,6 @@
     "directory": "packages/cli"
   },
   "scripts": {
-    "docs": "jsdoc2md --configure jsdoc.json --files src/**/*.js > docs/cli.md",
     "lint": "eslint src --ext .js",
     "lint:fix": "npm run lint -- --fix",
     "test": "ava",
@@ -87,7 +88,7 @@
     "ava": "^6.2.0",
     "eslint": "^8.32.0",
     "esmock": "^2.7.3",
-    "jsdoc-to-markdown": "^9.1.1",
+
     "memfs": "^4.51.1",
     "sinon": "^17.0.1"
   },