feat: add bootstrap and workflow commands
This commit is contained in:
parent
a0d11a71f9
commit
f5c2e69ea9
|
|
@ -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
|
||||
|
|
|
|||
25
Makefile
25
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)"
|
||||
|
|
|
|||
40
README.md
40
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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.'
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue