diff --git a/Jenkinsfile b/Jenkinsfile index 569619a..a6506c3 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -35,7 +35,7 @@ pipeline { stage('Test Components and Integration') { steps { - sh 'scripts/check-components.sh' + sh './beffroi.sh test' } } @@ -44,7 +44,7 @@ pipeline { sh ''' set -eu rm -rf "${CI_REPORT_DIR}" "${CI_ARTIFACT_DIR}" - scripts/build-publication.sh "${CI_REPORT_DIR}" + ./beffroi.sh all "${CI_REPORT_DIR}" ''' } } @@ -57,7 +57,7 @@ pipeline { sh ''' set +x set -eu - scripts/package-reports.sh "${CI_REPORT_DIR}" "${CI_ARTIFACT_DIR}" + ./beffroi.sh package "${CI_REPORT_DIR}" "${CI_ARTIFACT_DIR}" ''' archiveArtifacts artifacts: '.ci-artifacts/*.zip.enc', fingerprint: true } diff --git a/README.md b/README.md index cee33be..b84d7bc 100644 --- a/README.md +++ b/README.md @@ -1,133 +1,55 @@ # Beffroi Reporting -Beffroi Reporting is a reproducible workspace for turning Windows diagnostic -captures into structured findings and PDF reports. It pins compatible revisions -of three independent tools: +Beffroi Reporting turns structured reports and Windows diagnostic captures into +PDFs. The root `beffroi.sh` command is the main entry point. -| Directory | Component | Responsibility | -| --- | --- | --- | -| `diagnostics/` | Win Diagnostics | Normalizes captures and produces traceable diagnostic findings | -| `reports/` | Beffroi Reports | Creates immutable report drafts with evidence and provenance | -| `reporter/` | Reportist | Validates YAML or JSON report definitions and renders PDFs with Typst | +## Generate one personal report + +Write a Reportist YAML or JSON file, then run: + +```bash +./beffroi.sh report my-report.yaml my-report.pdf +``` + +See [`reporter/examples`](reporter/examples) for complete inputs. + +## Generate one diagnostic report + +```bash +./beffroi.sh diagnostic \ + capture.json /path/to/evidence /path/to/new-output \ + 2026-09-15T12:00:00Z 'Diagnostic review' 'Reviewer Name' 2026-09-15 +``` + +The output contains the normalized diagnostic, evidence-backed draft generation, +and rendered PDF. + +## Generate every stored PDF + +Add report YAML files under +[`reports/reports`](reports/reports) +or diagnostic JSON captures under +[`reports/diagnostics`](reports/diagnostics), +commit them with the reports submodule update, and run: + +```bash +./beffroi.sh all build/publication +``` + +Jenkins runs the same build and publishes encrypted report archives from `main`. + +## Commands ```text -Windows capture - ↓ -diagnostic.json - ↓ -reviewable report draft - ↓ -report.pdf +./beffroi.sh report INPUT OUTPUT.pdf +./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT OUTPUT_DIR REFERENCE_TIME TITLE AUTHOR DATE +./beffroi.sh all NEW_OUTPUT_DIR +./beffroi.sh package BUILD_DIR ARTIFACT_DIR +./beffroi.sh test +./beffroi.sh bootstrap +./beffroi.sh doctor ``` -Each component can be used separately. This repository supplies the pinned -versions and high-level commands for the complete workflow. - -## Requirements - -The runtime uses Bash, Git, and Typst 0.15 or newer. -Selected report fonts must also be installed; the examples use DejaVu Sans and -DejaVu Sans Mono. - -## Installation - -Clone the workspace with its pinned submodules and run bootstrap: - -```bash -git clone --recursive -cd beffroi-reporting -./bootstrap.sh -``` - -Bootstrap checks runtime dependencies, initializes the recorded submodule -revisions, and builds the publication helper. It does not install system -packages. For an existing checkout, the same command initializes any missing -submodules. Use `./bootstrap.sh --check` to verify dependencies and pins without -changing the checkout. - -## Create a report - -Run the complete workflow with an explicit capture, evidence root, and new work -directory: - -```bash -scripts/workflow.sh all \ - /path/to/evidence/capture.json \ - /path/to/evidence \ - /path/to/new-run \ - 2026-09-15T12:00:00Z \ - 'Diagnostic review' \ - 'Reviewer Name' \ - 2026-09-15 -``` - -The work directory must not already exist. A successful run creates: - -```text -new-run/ -├── diagnostic.json -├── generation/ -│ ├── diagnostic.json -│ ├── evidence/ -│ ├── generation.json -│ └── report.draft.json -└── report.pdf -``` - -The generation directory is immutable and records source hashes, tool versions, -options, and evidence. Existing destinations are never overwritten. - -Use the individual stages when a report needs review or editing between steps: - -```bash -scripts/workflow.sh analyse CAPTURE EVIDENCE_ROOT OUTPUT REFERENCE_TIME -scripts/workflow.sh draft DIAGNOSTIC EVIDENCE_ROOT OUTPUT_DIR TITLE AUTHOR DATE -scripts/workflow.sh render REPORT OUTPUT -``` - -Process every JSON capture in a directory tree through all stages with: - -```bash -scripts/workflow-all.sh CAPTURE_DIR EVIDENCE_ROOT OUTPUT_ROOT REFERENCE_TIME TITLE AUTHOR DATE -``` - -This creates parallel `diagnostics`, `generations`, and `pdfs` trees beneath a -new output root. - -## Build publication archives - -Build the preserved authored reports and diagnostic reports with: - -```bash -scripts/build-publication.sh /path/to/new-publication-directory -``` - -Create password-encrypted publication artifacts with: - -```bash -REPORT_ZIP_PASSWORD='...' scripts/package-reports.sh \ - /path/to/publication-directory /path/to/artifacts -``` - -The result contains `Reports.zip.enc` and `Diagnostics.zip.enc`, encrypted with -AES-256-CBC and PBKDF2. Jenkins archives both files and publishes main-branch -builds to `/mnt/books/Reports` using the -`typst-reporter-publish-password` credential. - -## Reproducibility - -Git submodules pin exact component commits instead of following branch heads. -`git submodule status` shows the selected revisions. Record the root commit, -Typst version, and installed font files when reproducing a historical report. -PDF bytes can vary across Typst and font versions even when content and layout -remain equivalent. - -## Contributing - -See the [contributor guide](docs/development.md). - -## License - -Root-level orchestration software is licensed under the MIT License. Diagnostic -evidence, report content, and branding may have separate terms; see -[LICENSE.md](LICENSE.md). +The command reports missing tools for the requested operation. See +[`docs/development.md`](docs/development.md) for repository structure, testing, +publication details, and component development. diff --git a/beffroi.sh b/beffroi.sh new file mode 100755 index 0000000..39b5a08 --- /dev/null +++ b/beffroi.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "${BASH_SOURCE[0]}")" + +usage() { + cat <<'EOF' +Usage: + ./beffroi.sh report INPUT OUTPUT.pdf + ./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT OUTPUT_DIR REFERENCE_TIME TITLE AUTHOR DATE + ./beffroi.sh all NEW_OUTPUT_DIR + ./beffroi.sh package BUILD_DIR ARTIFACT_DIR + ./beffroi.sh test + ./beffroi.sh bootstrap + ./beffroi.sh doctor +EOF + exit "${1:-0}" +} + +require() { + local missing=() command + for command in "$@"; do command -v "$command" >/dev/null 2>&1 || missing+=("$command"); done + ((${#missing[@]} == 0)) || { echo "Missing tools: ${missing[*]}" >&2; exit 1; } +} + +command_name=${1:-help}; shift || true +case "$command_name" in + report) + [[ $# -eq 2 ]]||usage 2; require typst + reporter/tools/render.sh "$1" --output "$2" + ;; + diagnostic) + [[ $# -eq 7 ]]||usage 2; require git typst + scripts/workflow.sh all "$@" + ;; + all) + [[ $# -eq 1 ]]||usage 2; require git typst + scripts/build-publication.sh "$1" + ;; + package) + [[ $# -eq 2 ]]||usage 2; require zip unzip openssl + scripts/package-reports.sh "$1" "$2" + ;; + test) + [[ $# -eq 0 ]]||usage 2; require git typst uv + scripts/check-components.sh + ;; + bootstrap) + [[ $# -eq 0 ]]||usage 2; require git typst + ./bootstrap.sh + ;; + doctor) + [[ $# -eq 0 ]]||usage 2 + require git typst + echo "Core tools are available." + for optional in uv zip unzip openssl; do + if command -v "$optional" >/dev/null 2>&1; then "$optional" --version 2>/dev/null | head -n 1 || true; else echo "Optional tool missing: $optional"; fi + done + ;; + help|-h|--help) usage 0;; + *) usage 2;; +esac diff --git a/diagnostics b/diagnostics index 5770b61..bf331f6 160000 --- a/diagnostics +++ b/diagnostics @@ -1 +1 @@ -Subproject commit 5770b61460ed69a095331916d6b5febcfc465182 +Subproject commit bf331f6bdb34ee0056816dd12527ccb0f7b3a30b diff --git a/reporter b/reporter index 7a7ba72..79179b2 160000 --- a/reporter +++ b/reporter @@ -1 +1 @@ -Subproject commit 7a7ba72524a30ece719f7ec4ab0209701d40ff92 +Subproject commit 79179b2f6844bc76ee062d18a6b4cc4c9a736121 diff --git a/reports b/reports index 11cd0f6..5cf1945 160000 --- a/reports +++ b/reports @@ -1 +1 @@ -Subproject commit 11cd0f615bddb13bc5eb34287fc431509d981f5f +Subproject commit 5cf1945f56b30e2bcc4d6221ff07a2b1bfe616c0 diff --git a/scripts/build-publication.sh b/scripts/build-publication.sh index 4f481b7..25c60a2 100755 --- a/scripts/build-publication.sh +++ b/scripts/build-publication.sh @@ -5,11 +5,11 @@ output_root=${1:-} [[ -n "$output_root" && $# -eq 1 ]]||{ echo "Usage: $0 NEW_OUTPUT_ROOT" >&2; exit 2; } [[ ! -e "$output_root" ]]||{ echo "$output_root: output root already exists" >&2; exit 1; } mkdir -p "$output_root/reports" "$output_root/diagnostics" -reports/tools/convert-legacy-reports.sh reports/archive/typst_reporter/reports "$output_root/reports/sources" +reports/tools/convert-legacy-reports.sh reports/reports "$output_root/reports/sources" reporter/tools/validate-all.sh "$output_root/reports/sources" reporter/tools/render-all.sh "$output_root/reports/sources" --output-dir "$output_root/reports/pdfs" -scripts/workflow-all.sh reports/archive/typst_reporter/diagnostics \ - reports/archive/typst_reporter/diagnostics "$output_root/diagnostic-work" \ +scripts/workflow-all.sh reports/diagnostics \ + reports/diagnostics "$output_root/diagnostic-work" \ 2026-09-15T12:15:00Z 'Diagnostic report' "${DIAGNOSTICS_AUTHOR:-Beffroi}" 2026-09-15 cp -R "$output_root/diagnostic-work/pdfs/." "$output_root/diagnostics/" echo "Built publishable reports under $output_root"