iftypeset/app/CLI_SPEC.md

CLI Specification

The CLI is designed for CI use: deterministic outputs, stable exit codes, and JSON artifacts for tooling.

Common flags (all commands)

This is the target contract; v0 currently implements a subset per-command.

Precedence (highest → lowest): CLI flags → iftypeset.yaml → hard defaults.

• --spec <dir>: Spec root directory (default: spec/).
• --input <path>: Markdown file or directory (where applicable).
• --out <dir>: Output directory (default: out/).
• --profile <name>: One of: web_pdf, print_pdf, dense_tech, memo, slide_deck, webtypography_nc (non-commercial).
• --config <path>: Path to iftypeset.yaml (defaults to ./iftypeset.yaml when present).
• --engine <auto|playwright|wkhtmltopdf|weasyprint>: Preferred PDF engine (default: playwright; auto is treated as playwright; Chromium CLI engine is banned).
• --font-dir <dir>: Additional font directory (repeatable) to supply corporate fonts at render time.
• --strict-fonts: Enforce a fonts contract for PDF rendering (fail if primary profile fonts are missing or not embedded in the PDF).
• --strict: Use strict thresholds in spec/quality_gates.yaml (QA/report).
• --format <json|sarif|text>: Lint output format.
• --fail-on <must|should|warn>: Lowest severity that fails lint (default: must).
• --degraded-ok: Allow degraded mode without failing (lint/render-html).
• --fix: Apply safe deterministic fixes (lint/run).
• --fix-mode <suggest|rewrite>: Fix mode for --fix (lint/run).
• --lint-fixed: When rewriting fixes, lint the fixed output instead of the original (lint/run).
• --version: Print tool version and exit.

Command: validate-spec

Purpose:

• Validate YAML/JSON spec files and (when present) rule NDJSON batches.

Outputs:

• out/spec-validation.json

Exit codes:

• 0: ok
• 2: config/schema error

Command: profiles list

Purpose:

• List available profile ids in the current spec.

Outputs:

• JSON to stdout (profiles: [...])

Exit codes:

• 0: ok
• 2: config error

Command: gates show

Purpose:

• Show QA gate thresholds for a profile (--strict selects strict mode).

Outputs:

• JSON to stdout (gates: {...})

Exit codes:

• 0: ok
• 2: config error

Command: rules list / rules show

Purpose:

• List rules with basic filters, or show a full rule record by id.

Outputs:

• JSON to stdout (rules: [...] or rule: {...})

Exit codes:

• 0: ok
• 2: config error / rule not found

Command: report

Purpose:

• Produce a consolidated report (coverage + indexes status).

Outputs:

• out/coverage-report.json
• out/coverage-summary.md
• out/report/index.html

Exit codes:

• 0: report built
• 1: coverage floor violated (only when rule batches exist)
• 2: config/schema error

Command: doctor

Purpose:

• Emit environment and determinism diagnostics (renderer, Poppler, fonts, locale).

Outputs:

• out/doctor.json
• out/doctor.md

Exit codes:

• 0: ok
• 2: config error

Command: bundle

Purpose:

• Create a portable tarball of out/ artifacts with a sha256 manifest for external review.

Outputs:

• out/bundle-manifest.json
• out/iftypeset-bundle.tar.gz (default; override with --bundle)

Exit codes:

• 0: ok

Notes:

• Files larger than --max-size-mb are skipped and recorded in the manifest.
• Bundle entries are sorted and stored with fixed mtimes for deterministic output.

Command: run

Purpose:

• One-shot CI pipeline: validate → lint → render-html → render-pdf (best effort) → qa → report.

Outputs:

• All artifacts from the underlying commands.
• out/run-summary.json
• When --input is a directory or glob, per-doc artifacts are written under out/docs/<relpath>/ and out/report/index.html becomes a multi-doc index.

Exit codes:

• 0: pipeline ok (lint + qa + report passed)
• 1: gate failed (lint/qa/report/degraded render-html)
• 2: config error
• 3: renderer/tool error (only when --require-pdf is set)

Notes:

• PDF rendering failures are recorded as warnings in run-summary.json and do not fail the run unless --require-pdf is set.
• Use --skip-pdf to omit PDF rendering entirely when only HTML QA is desired.
• Use --engine to force a specific renderer (useful for reproducible CI).
• Use --font-dir to mount a corporate fonts directory and avoid fallback fonts.
• Use --strict-fonts (or profile fonts.require_primary: true) to fail fast if font fallback would occur.

Command: lint

Purpose:

• Parse Markdown into a minimal block AST (headings, paragraphs, lists, code fences, tables).
• Emit deterministic diagnostics and a manual checklist derived from the registry.

Outputs:

• out/lint-report.json
• out/manual-checklist.md
• out/manual-checklist.json
• out/degraded-mode-report.json (only when degraded mode triggers)
• out/lint-report.sarif (only when --format sarif)
• out/fix-suggestions.json (only when --fix --fix-mode suggest)
• out/fixed/*.md (only when --fix --fix-mode rewrite)

Notes:

• --lint-fixed re-lints the rewritten output so diagnostics reflect the fixed text.

Exit codes:

• 0: ok
• 1: lint failed (fail-on threshold exceeded, or degraded mode without --degraded-ok)
• 2: config error

Command: render-html

Purpose:

• Render Markdown to deterministic HTML and CSS based on a profile.

Outputs:

• out/render.html
• out/render.css
• out/typeset-report.json
• out/degraded-mode-report.json (only when degraded mode triggers)

Exit codes:

• 0: ok
• 1: degraded mode without --degraded-ok
• 2: config error

Command: render-pdf

Purpose:

• Render Markdown to PDF using the configured engine (default: playwright; --engine auto is treated as playwright; Chromium CLI engine is not supported).

Outputs:

• out/render.html
• out/render.css
• out/typeset-report.json
• out/render-log.json
• out/render.pdf (only when rendering succeeds)

Exit codes:

• 0: ok
• 3: renderer missing or engine error (see out/render-log.json)
• 2: config error

Notes:

• Use --engine to force a specific renderer (e.g., --engine wkhtmltopdf).
• Use --font-dir to supply additional font directories for the renderer (e.g., corporate fonts).
• Use --strict-fonts (or profile fonts.require_primary: true) to prevent silent font fallbacks in shipped PDFs.

Command: qa

Purpose:

• Run deterministic post-render QA checks (HTML analysis v0) and enforce numeric gates from spec/quality_gates.yaml.

Args:

• --out <dir>: output directory containing render.html / render.pdf (default: out/)
• --html <path>: HTML to analyze (default: <out>/render.html)
• --pdf <path>: optional PDF path for reporting (default: <out>/render.pdf)
• --strict: use strict thresholds from spec/quality_gates.yaml
• --format <json|sarif>: optional SARIF output for CI annotations

Outputs:

• out/layout-report.json
• out/qa-report.json
• out/qa-report.sarif (when --format sarif)

Exit codes:

• 0: gates pass
• 1: gates fail
• 2: config error / missing HTML input