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.