diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 8ef806e..495b02e 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -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 diff --git a/Makefile b/Makefile index 8878272..7e72d94 100644 --- a/Makefile +++ b/Makefile @@ -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)" diff --git a/README.md b/README.md index 6fbfe1d..84e0513 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/bootstrap.sh b/bootstrap.sh new file mode 100755 index 0000000..8286eeb --- /dev/null +++ b/bootstrap.sh @@ -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.' diff --git a/reportist b/reportist index d628673..b4472e9 160000 --- a/reportist +++ b/reportist @@ -1 +1 @@ -Subproject commit d6286735e93b24745afdbd6fec8e65034128b192 +Subproject commit b4472e9055fc86045e1eec53100154d89a618035 diff --git a/scripts/check-components.sh b/scripts/check-components.sh index 7ecb012..48a4dfd 100644 --- a/scripts/check-components.sh +++ b/scripts/check-components.sh @@ -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.' diff --git a/scripts/workflow.sh b/scripts/workflow.sh new file mode 100755 index 0000000..3d0df48 --- /dev/null +++ b/scripts/workflow.sh @@ -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