beffroi-reporting/docs/operations.md

2.8 KiB

Editing, building, and publishing

Setup and editing

Run ./beffroi.sh bootstrap after cloning to initialize the pinned Reports and Reportist submodules. ./beffroi.sh doctor checks the core tools. Edit source files in reports/reports/ or add a raw capture to reports/diagnostics/; implementation changes belong in Reportist. Consult the report input contract for authored YAML/JSON and the diagnostic plugin for raw capture behavior.

Render one source while editing:

./beffroi.sh report reports/reports/2026-09-04-clevo-handoff.yaml /tmp/report.pdf
./beffroi.sh diagnostic-pdf reports/diagnostics/windows_system_report_DESKTOP-SAU019H_20260915_121057.json /tmp/diagnostic.pdf

capture-pdf is a compatibility alias for diagnostic-pdf. For evidence processing, ./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT NEW_OUTPUT_DIR REFERENCE_TIME [AUTHOR] [THEME] writes both diagnostic.json and report.pdf. The PDF renderer reads the raw capture directly.

Local verification

Run ./beffroi.sh test before publishing. It executes Reportist's report and diagnostic suites, checks the stored source set, builds all PDFs, and compares all seven reports and ten diagnostics to the recorded legacy baseline. The original renderer in legacy/typst_reporter is retained as a read-only local reference. Its ignored build/ PDFs enable raster comparison when available; CI can still check recorded page counts and text hashes without them.

Build the complete publication with:

./beffroi.sh all build/publication --replace
./beffroi.sh all build/publication --replace --include-json

--replace builds beside the existing directory, then swaps it after success. --include-json adds authored report JSON exports and copies raw capture JSON beside the PDFs. Single-document rendering refuses an existing PDF unless --force is supplied.

CI and delivery

On main, the macro Jenkinsfile checks out pinned submodules, runs tests, builds the publication, creates password-protected AES ZIP archives, archives them as CI artifacts, and copies Reports.zip and Diagnostics.zip to its configured deployment directory. Jenkins supplies REPORT_ZIP_PASSWORD from credentials. The password must not be committed or printed. The standalone Reportist Jenkinsfile runs plugin tests. Reports Jenkinsfile checks YAML and JSON syntax only.

./beffroi.sh package BUILD_DIR ARTIFACT_DIR runs the same packaging locally when REPORT_ZIP_PASSWORD is set. It requires uv and pinned pyzipper. Package output is checked by reopening the archives. Publication and deployment are external actions; review generated sources and artifacts before pushing a change that triggers the main-branch pipeline.