|
|
||
|---|---|---|
| assets | ||
| diagnostics | ||
| docs | ||
| reports | ||
| tools | ||
| .gitignore | ||
| Jenkinsfile | ||
| LICENSE | ||
| README.md | ||
| diagnostics-model.typ | ||
| diagnostics-normalize.typ | ||
| diagnostics-rules.yaml | ||
| diagnostics.typ | ||
| model.typ | ||
| render-diagnostics.sh | ||
| render.sh | ||
| report.typ | ||
| themes.yaml | ||
README.md
Beffroi Reports
Create consistent technical PDF reports from readable, version-controlled YAML. Typst handles the layout, while each report remains easy to edit, review, and diff in Git.
Quick overview
Requirements
- Typst available as
typst - Bash and standard Unix command-line utilities
No additional Typst packages are required.
Create and render a report
- Copy an existing file in
reports/, or start with the minimal boilerplate. - Edit the YAML content.
- Render it:
./render.sh reports/my-report.yaml
The PDF is written to build/my-report.pdf. To render every report recursively:
./render.sh --all
Set the report's purpose explicitly:
report_type: technical # Investigation, engineering review, or handoff
# report_type: briefing # Concise findings for stakeholders
See Report types for the distinction.
Every report must include an author and date, and may select a theme:
theme: default # Also available: cic, eridani
metadata:
Date: "2026-09-05"
Author: "Your Name"
Compilation stops with an actionable error if metadata.Date or
metadata.Author is absent or empty.
Generate a Windows diagnostics assessment
Convert a Full WinDiagnostics text dump into a concise, exception-focused PDF:
./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name" cic
The theme argument is optional and defaults to default. Render every .json
dump under diagnostics/ recursively with:
./render-diagnostics.sh --all "Your Name"
The result is written under build/diagnostics/. Its first page is a short
health summary; later pages deduplicate errors, retain useful evidence, and
record how every collected section was treated without reproducing large lists
of healthy inventory. See Diagnostics reports, including
the safe finding-closure guide.
You can also invoke Typst directly:
typst compile \
--input report=reports/my-report.yaml \
report.typ \
build/my-report.pdf
Project layout
report.typ Typst entry point
model.typ Shared layout and YAML renderer
render.sh Convenience build script
assets/ Logos and other static assets
reports/ Authoritative YAML report sources
build/ Generated PDFs
docs/ Detailed documentation and examples
Detailed guides
- Writing reports — field reference, content blocks, report types, status values, and authoring guidance.
- Examples and boilerplate — complete minimal and full reports ready to copy and adapt.
- Advanced setup — nested archives, customization, YAML themes, automation, and Git policy.
- Diagnostics reports — WinDiagnostics synthesis, filtering policy, usage, safe finding closure, and limitations.
Core principle
YAML files are the authoritative report sources. Keep content and report state
in YAML, and keep visual presentation in model.typ. For example, prefer
severity: high over fields that specify colors or fonts.
Generated PDFs are reproducible artifacts suitable for email, handoff, printing, tickets, and archival. Whether they are committed to Git is a project policy; see Generated PDF policy.
License
See LICENSE.
Jenkins publication
Jenkins renders YAML reports and JSON diagnostics, validates the PDFs, and
publishes encrypted archives to the same /mnt/books mount used by the books:
/mnt/books/Reports/Reports.zip: YAML report PDFs./mnt/books/Reports/diagnostics.zip: diagnostic PDFs, preserving subfolders.
Only the ZIPs are archived as Jenkins artifacts. The agent needs zip, Python 3,
and write access to /mnt/books/Reports. DIAGNOSTICS_AUTHOR defaults to Beffroi.
Packaging uses standard ZIP password encryption (ZipCrypto, not AES).
The temporary password is CHANGE_ME; it is a public placeholder, not a secret.
Later create a Jenkins Secret text credential and replace the Jenkinsfile
assignment with REPORT_ZIP_PASSWORD = credentials('reports-zip-password').
The packaging script reads that environment variable with shell tracing disabled.
To package an existing local build:
REPORT_ZIP_PASSWORD=CHANGE_ME ./tools/package-reports.sh