beffroi-tools/AGENTS.md

84 lines
4.9 KiB
Markdown

# beffroi-tools
This repository contains a Rust PPTX reporter trial and Python command-line tools
for everyday local document and media workflows. Keep them simple to run. Keep `README.md` minimal,
with quick-start examples and links to detailed documentation in `docs/`.
## Current tools
- `src/` is the Rust reporter: shared core, CLI and egui desktop interface.
PDF compilation and DejaVu fonts are embedded. Discover FFprobe beside the app,
under `bin/`, or on PATH. Keep report/JSON/Ontime behavior compatible with the
Python reference; `scripts/parity.py` verifies real-media parity.
The document exporter is outside the Rust migration scope.
- `tools/pptx_videos.py` discovers and extracts embedded PPTX videos, maps them to
slides, probes metadata with FFmpeg's `ffprobe`, and generates timing reports
in Markdown, plain text, JSON, HTML, Typst, PDF, and Ontime 4 JSON. Markdown
and Ontime are the defaults. PDF reports compile through the Typst CLI.
Its output root contains `videos/` for media and `reports/` for reports and
Typst sources; report media links are relative to `reports/`.
- `tools/ontime.py` maps video references into an importable Ontime rundown.
- `tools/playback.py` reads per-shape trims and flags looping/unsupported timing.
Keep these cases in reports but omit them from Ontime and playback totals.
`tests/test_playback.py` covers the XML and effective-duration behavior.
- `tools/progress.py` provides shared transient terminal progress and plain logs
for redirected output; `tests/test_progress.py` checks display cleanup.
- `tools/exporter.py` uses DeckCraft to export PPTX presentations to PDF or PNG slides,
and PdfCraft to render PDF pages as PNGs. It discovers CLI executables or
locally installed AppImages. PDF-to-PDF is a successful no-op unless compression
is requested. Ghostscript powers `--pdf-quality` and bounded `--target-size`
attempts; `--pdf-dpi` reuses an exact selected resolution. Report selected
PDF and PNG resolutions in terminal output. An unmet target must not publish
output or replace existing files.
- `tests/test_exporter.py` covers exporter validation, no-op behavior, conversion
failures, and overwrite behavior.
- `tests/test_pptx_videos.py` covers slide discovery, extraction, temporary probing,
report formatting, and error handling.
- `Jenkinsfile` runs Python/Rust tests, parity, lint, docs and coverage on
`rust_no_docker`. The explicitly requested badge workflow archives exactly
three SVGs and publishes them only from main during cleanup. CI never creates
releases or uploads release binaries. Cross and `rust_realease` are separate,
manually invoked build/release preparation tools.
- `scripts/fetch_ffprobe.py` fetches checksum-verified target FFprobe builds into
ignored `downloads/`. Portable release packaging calls it with
`--fetch-ffprobe`; include upstream notices/provenance, never commit binaries.
## Working conventions
- Prefer Python's standard library and existing external CLI tools over adding
dependencies.
- Preserve source documents. Keep temporary files temporary and require an
explicit overwrite option when replacing existing exports.
- Provide useful progress and actionable errors. Terminal colors should respect
`NO_COLOR` and disappear when output is redirected.
- Preserve slide order, readable aligned text reports, and consistent styling
in visual reports.
- Keep tools in `tools/`, tests in `tests/`, and specialized documentation in
`docs/`. Update the relevant docs when options or workflows change; keep the
README's examples and links current.
- Run checks appropriate to the change before committing. Exporter regression
tests and video-report tests run with
`python3 -m unittest discover -s tests -v`. For rendering changes,
test with the actual external tools when available and inspect visual output.
Report any checks that could not be completed.
- Rust gates: `cargo fmt --check`, `cargo clippy --locked --all-targets
--all-features -- -D warnings`, `cargo test --locked --all-features`, and
`RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps`.
Run `python3 scripts/ci.py coverage` for the whole Rust application; do not
exclude production GUI/PDF code to raise the reported percentage.
## Commit every task
- Every completed task that changes repository files must end with a Git commit.
Committing the task is part of completing it; do not wait for a separate user
request to commit.
- Inspect the working tree first. Stage only changes belonging to the task;
preserve unrelated or pre-existing changes.
- Use a concise, descriptive commit message explaining the change.
- Do not commit generated exports, temporary files, credentials, or caches.
- Include the commit hash and validation summary in the final response.
- If committing is blocked, explain why and identify the uncommitted changes.
Do not claim the task was committed.
- Read-only tasks need no empty commit. Do not push commits unless requested.