feat: add bootstrap and workflow commands

This commit is contained in:
Dandaedre 2026-09-15 23:14:19 +02:00
parent a0d11a71f9
commit f5c2e69ea9
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
7 changed files with 241 additions and 31 deletions

View File

@ -125,13 +125,12 @@ machine; automated draft content remains distinct from reviewed analysis.
Depends on a working end-to-end slice from Passes 2–4. Work in beffroi-reporting.
- [ ] P5.1 Align submodule paths with `diagnostics/`, `reports/`, `reporter/`; update `.gitmodules`, documentation, scripts, and CI together, preserving pinned revisions and local work.
- [ ] P5.2 Add bootstrap to initialize pinned submodules, check actual tool/platform dependencies, explain missing requirements, and prepare workspace directories without silent system modifications.
- [ ] P5.3 Add high-level workflow commands based on the component CLIs for collection, offline analysis, draft report generation, rendering, and a complete incident run. Keep implementation in components.
- [x] P5.2 Add bootstrap to initialize pinned submodules, check actual tool/platform dependencies, explain missing requirements, and prepare workspace directories without silent system modifications.
- [x] P5.3 Add high-level workflow commands based on the component CLIs for collection, offline analysis, draft report generation, rendering, and a complete incident run. Keep implementation in components.
- [x] P5.4 Add an integration test: sanitized capture → analysis → diagnostic artifact → report adapter → report input → Reportist → PDF. Validate schemas, expected evidence/findings, and PDF output; use isolated temporary outputs.
- [x] P5.5 Invoke component checks and the integration test from Jenkins; report actual validation coverage, tool versions, and artifacts accurately.
- Component contract suites are wired through `make check` and Jenkins; the
diagnostic-to-report slice is now included, while analysis, PDF rendering,
and the complete end-to-end integration test remain pending.
complete analysis, diagnostic-to-report, and PDF-rendering path is included.
- [ ] P5.6 Pin the tested component commits intentionally and document external dependencies plus clean-checkout reproduction commands; verify `git clone --recursive` followed by bootstrap and integration testing.
Exit: a pinned integration revision runs the sanitized pipeline reproducibly,
@ -153,6 +152,22 @@ reports remain understandable/recreatable and individual tools need no macro rep
## Pass handoff log
### 2026-09-15 — Bootstrap and workflow orchestration
- Completed P5.2–P5.3 with `bootstrap.sh`, explicit `make analyse`, `make draft`,
`make render`, and `make all` entry points. The root only composes the pinned
public component CLIs; component implementation stays in its owning repository.
- Bootstrap initializes recorded submodule revisions, reports missing Git/uv/Typst,
prepares isolated pinned Python environments, and makes no system-package changes.
Its `--check` mode verifies tools, component presence, and exact gitlink revisions.
- The integration suite now exercises `scripts/workflow.sh all` itself, producing
a diagnostic artifact, immutable generation, and PDF in a fresh temporary run.
Explicit reference time and report metadata prevent clock/account defaults.
- Validation: 62 component tests plus the complete workflow pipeline pass.
Native Windows collection remains outside the current Linux validation.
- Next: verify bootstrap from a clean recursive clone and document exact external
dependencies/pins under P5.6, then address remaining component migration work.
### 2026-09-15 — Standalone renderer pass complete
- Completed P3.1–P3.5. Reportist now has the generic schema-first YAML/JSON-to-PDF

View File

@ -1,4 +1,27 @@
.PHONY: check
.PHONY: help bootstrap check analyse draft render all
help:
@echo 'make bootstrap'
@echo 'make check'
@echo 'make analyse CAPTURE=... EVIDENCE_ROOT=... OUTPUT=... REFERENCE_TIME=...'
@echo 'make draft DIAGNOSTIC=... EVIDENCE_ROOT=... OUTPUT_DIR=... TITLE=... AUTHOR=... DATE=...'
@echo 'make render REPORT=... OUTPUT=...'
@echo 'make all CAPTURE=... EVIDENCE_ROOT=... WORK_DIR=... REFERENCE_TIME=... TITLE=... AUTHOR=... DATE=...'
bootstrap:
bash bootstrap.sh
check:
bash scripts/check-components.sh
analyse:
bash scripts/workflow.sh analyse "$(CAPTURE)" "$(EVIDENCE_ROOT)" "$(OUTPUT)" "$(REFERENCE_TIME)"
draft:
bash scripts/workflow.sh draft "$(DIAGNOSTIC)" "$(EVIDENCE_ROOT)" "$(OUTPUT_DIR)" "$(TITLE)" "$(AUTHOR)" "$(DATE)"
render:
bash scripts/workflow.sh render "$(REPORT)" "$(OUTPUT)"
all:
bash scripts/workflow.sh all "$(CAPTURE)" "$(EVIDENCE_ROOT)" "$(WORK_DIR)" "$(REFERENCE_TIME)" "$(TITLE)" "$(AUTHOR)" "$(DATE)"

View File

@ -46,9 +46,36 @@ cd beffroi-reporting
For an existing checkout:
```bash id="ihk4op"
git submodule update --init --recursive
./bootstrap.sh
```
Bootstrap initializes the exact submodule revisions recorded by this repository,
checks Git, uv, and Typst, and prepares isolated Python 3.11 environments under
`.venv/component-checks/`. It may download submodules, Python, or pinned Python
packages, but it does not install system packages. Use `./bootstrap.sh --check`
for a read-only dependency and pinned-revision check.
## Run the workflow
`make help` lists the high-level commands. Each delegates to the pinned component
CLI and requires explicit paths and report metadata. For example:
```bash
make all \
CAPTURE=/path/to/evidence/capture.json \
EVIDENCE_ROOT=/path/to/evidence \
WORK_DIR=/path/to/new-run \
REFERENCE_TIME=2026-09-15T12:00:00Z \
TITLE='Diagnostic review' \
AUTHOR='Reviewer Name' \
DATE=2026-09-15
```
The work directory must not exist. A successful run contains `diagnostic.json`,
an immutable `generation/`, and `report.pdf`. The individual `make analyse`,
`make draft`, and `make render` commands expose the same stages when review or
human editing is needed between them. Run `make help` for their variables.
## Run component checks
On Linux/macOS with Bash, Git, Make, and `uv` available, run:
@ -65,8 +92,9 @@ The runner prints tool versions and component revisions and stops on any failure
Current coverage includes the diagnostic and report contract suites, Reportist
rendering tests, adapter preservation tests, and a branded synthetic
raw-capture-to-diagnostic-to-report-to-PDF path. The analyser currently covers
one reviewed event rule; the remaining rule catalog and native collection are pending.
raw-capture-to-diagnostic-to-report-to-PDF path. The analyser covers all 53
reviewed event rules and seven advisory watchlist entries. Native Windows
collection and broader non-event health checks remain.
Submodules must already be initialized with the command above.
## Push component commits and the workspace together
@ -104,8 +132,10 @@ The first executable migration check is the [synthetic legacy baseline](docs/mig
It records diagnostic behavior and renders example PDFs before extraction.
Version-1 [diagnostic validation](win-diagnostics/docs/diagnostic-contract.md) and
[report validation](reportist/docs/report-contract.md) are now available independently
in their component repositories. The new end-to-end pipeline remains in progress.
[report validation](reportist/docs/report-contract.md) are available independently
in their component repositories. The pinned components now run the sanitized
end-to-end pipeline through the root workflow; native collection and historical
incident migration remain in progress.
## License

65
bootstrap.sh Executable file
View File

@ -0,0 +1,65 @@
#!/usr/bin/env bash
# Initialize pinned components and prepare isolated Python environments.
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"
check_only=false
if [[ "${1:-}" == "--check" ]]; then
check_only=true
elif [[ $# -ne 0 ]]; then
echo "Usage: $0 [--check]" >&2
exit 2
fi
missing=()
for command in git uv typst; do
command -v "$command" >/dev/null 2>&1 || missing+=("$command")
done
if ((${#missing[@]})); then
echo "Missing required tools: ${missing[*]}" >&2
echo 'Install Git, uv, and Typst, then rerun bootstrap.' >&2
exit 1
fi
if ! $check_only; then
git submodule update --init --recursive
fi
for component in win-diagnostics reportist beffroi-reports; do
if [[ ! -e "$component/.git" ]]; then
echo "Missing component checkout: $component" >&2
echo 'Run ./bootstrap.sh with network access to initialize pinned submodules.' >&2
exit 1
fi
done
while IFS= read -r status; do
if [[ "$status" == -* || "$status" == +* ]]; then
echo "Submodule is not at its pinned revision: $status" >&2
echo 'Run ./bootstrap.sh to restore the recorded component revisions.' >&2
exit 1
fi
done < <(git submodule status --recursive)
for component in win-diagnostics reportist; do
if [[ ! -f "$component/requirements.txt" ]]; then
echo "Missing dependency lock: $component/requirements.txt" >&2
exit 1
fi
done
git --version
uv --version
typst --version
if $check_only; then
echo 'Pinned components and required tools are available.'
exit 0
fi
for component in win-diagnostics reportist; do
environment=".venv/component-checks/$component"
uv venv --python 3.11 --allow-existing "$environment"
uv pip sync --python "$environment/bin/python" "$component/requirements.txt"
done
echo 'Bootstrap complete. Run make check or make help.'

@ -1 +1 @@
Subproject commit d6286735e93b24745afdbd6fec8e65034128b192
Subproject commit b4472e9055fc86045e1eec53100154d89a618035

View File

@ -40,30 +40,18 @@ BRANDING_DIRECTORY="$(pwd)/beffroi-reports/config/branding" \
.venv/component-checks/reportist/bin/python -m unittest discover \
-s beffroi-reports/tests -p 'test_*.py' -v
pipeline_check_root="$(mktemp -d "${TMPDIR:-/tmp}/beffroi-pipeline-check.XXXXXX")"
trap 'rm -rf -- "$pipeline_check_root"' EXIT
.venv/component-checks/win-diagnostics/bin/python win-diagnostics/tools/analyse.py \
pipeline_check_parent="$(mktemp -d "${TMPDIR:-/tmp}/beffroi-pipeline-check.XXXXXX")"
trap 'rm -rf -- "$pipeline_check_parent"' EXIT
pipeline_check_root="$pipeline_check_parent/run"
bash scripts/workflow.sh all \
win-diagnostics/tests/fixtures/legacy/windiagnostics-v1.json \
--evidence-root win-diagnostics/tests/fixtures/legacy \
--output "$pipeline_check_root/diagnostic.json" \
--reference-time 2026-09-15T12:00:00Z \
--producer-version "$(git -C win-diagnostics rev-parse HEAD)"
win-diagnostics/tests/fixtures/legacy \
"$pipeline_check_root" \
2026-09-15T12:00:00Z \
'Synthetic diagnostic draft' 'CI Test' 2026-09-15
.venv/component-checks/win-diagnostics/bin/python -c \
'import json,sys; d=json.load(open(sys.argv[1], encoding="utf-8")); assert d["findings"][0]["id"] == "event-service-control-manager-7000"; assert d["findings"][0]["evidence"] == ["event-recent_system_errors-1"]' \
"$pipeline_check_root/diagnostic.json"
.venv/component-checks/reportist/bin/python beffroi-reports/tools/diagnostic-to-report.py \
--diagnostic "$pipeline_check_root/diagnostic.json" \
--evidence-root win-diagnostics/tests/fixtures/legacy \
--output-dir "$pipeline_check_root/generation" \
--title 'Synthetic diagnostic draft' --author 'CI Test' --date 2026-09-15 \
--generator-version "$(git -C beffroi-reports rev-parse HEAD)" \
--diagnostic-validator win-diagnostics/tools/validate.py \
--report-validator reportist/tools/validate.py \
--branding beffroi-reports/config/branding/default.json \
--branding-root beffroi-reports
.venv/component-checks/reportist/bin/python reportist/tools/render.py \
"$pipeline_check_root/generation/report.draft.json" \
--output "$pipeline_check_root/report.pdf"
test "$(head -c 5 "$pipeline_check_root/report.pdf")" = '%PDF-'
echo 'Raw-capture analysis, adapter, and PDF pipeline passed. Native collection and non-event health checks remain.'

89
scripts/workflow.sh Executable file
View File

@ -0,0 +1,89 @@
#!/usr/bin/env bash
# Compose the pinned component CLIs without owning their implementation.
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")/.."
usage() {
cat >&2 <<'EOF'
Usage:
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
scripts/workflow.sh all CAPTURE EVIDENCE_ROOT WORK_DIR REFERENCE_TIME TITLE AUTHOR DATE
EOF
exit 2
}
require_values() {
for value in "$@"; do
[[ -n "$value" ]] || usage
done
}
diagnostic_python=.venv/component-checks/win-diagnostics/bin/python
report_python=.venv/component-checks/reportist/bin/python
for executable in "$diagnostic_python" "$report_python"; do
[[ -x "$executable" ]] || {
echo "Missing prepared environment: $executable" >&2
echo 'Run ./bootstrap.sh first.' >&2
exit 1
}
done
analyse() {
[[ $# -eq 4 ]] || usage
require_values "$@"
"$diagnostic_python" win-diagnostics/tools/analyse.py "$1" \
--evidence-root "$2" --output "$3" --reference-time "$4" \
--producer-version "$(git -C win-diagnostics rev-parse HEAD)"
}
draft() {
[[ $# -eq 6 ]] || usage
require_values "$@"
"$report_python" beffroi-reports/tools/diagnostic-to-report.py \
--diagnostic "$1" --evidence-root "$2" --output-dir "$3" \
--title "$4" --author "$5" --date "$6" \
--generator-version "$(git -C beffroi-reports rev-parse HEAD)" \
--diagnostic-validator win-diagnostics/tools/validate.py \
--report-validator reportist/tools/validate.py \
--branding beffroi-reports/config/branding/default.json \
--branding-root beffroi-reports
}
render() {
[[ $# -eq 2 ]] || usage
require_values "$@"
"$report_python" reportist/tools/render.py "$1" --output "$2"
}
command_name="${1:-}"
[[ -n "$command_name" ]] || usage
shift
case "$command_name" in
analyse) analyse "$@" ;;
draft) draft "$@" ;;
render) render "$@" ;;
all)
[[ $# -eq 7 ]] || usage
require_values "$@"
capture=$1
evidence_root=$2
work_dir=$3
reference_time=$4
title=$5
author=$6
report_date=$7
[[ ! -e "$work_dir" ]] || {
echo "$work_dir: work directory already exists" >&2
exit 1
}
mkdir -p "$work_dir"
analyse "$capture" "$evidence_root" "$work_dir/diagnostic.json" "$reference_time"
draft "$work_dir/diagnostic.json" "$evidence_root" "$work_dir/generation" \
"$title" "$author" "$report_date"
render "$work_dir/generation/report.draft.json" "$work_dir/report.pdf"
;;
*) usage ;;
esac