beffroi-tools/AGENTS.md

5.8 KiB

beffroi-tools

This repository contains Rust reporting/conversion apps 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

  • crates/pptx-reporter/ 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. It is the sole PPTX video reporter; the Python implementation and cross-language parity harness are retired. Preserve the established report/JSON/Ontime behavior with Rust regression tests in crates/pptx-reporter/tests/. Apply trims, retain looping/unsupported timing in reports, and omit those cases from Ontime and playback totals. The document exporter remains Python.

  • crates/rundown-converter/ is the spreadsheet rundown converter: shared Rust core, CLI and egui interface. Keep inference, untimed-gap identification, IR construction, consistency validation and Ontime export separate. A timing column must have a consistent meaning across all relevant rows. Ambiguities block export; explicit starts and untimed gaps must survive conversion. Private examples in rundowns/ and public downloads stay untracked; tests use synthetic fixtures. PDF, XLS/ODS readers and buffer correction remain future work.

  • 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.

  • Jenkinsfile runs Python/Rust tests, 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.

  • rust-release.toml builds Windows/Linux with Cross and Apple Silicon/Intel macOS 13+ with a pinned cargo-zigbuild container. Portable bundles include FFprobe on every platform; canonical cargo-binstall archives require external FFprobe.

  • scripts/fetch_ffprobe.py fetches checksum-verified target FFprobe builds into ignored downloads/. Named release bundles use scripts/prepare-release.py with per-target pins in crates/pptx-reporter/ffprobe-pins.json; the standalone packager retains --fetch-ffprobe. scripts/build_macos_ffprobe.py builds the macOS dependency from pinned FFmpeg source, with source, LGPL notices and the recipe bundled. Include upstream notices/provenance, never commit binaries.

Repository layout

  • tools/ and tests/: Python prototypes and their regression tests.
  • crates/<tool>/: each Rust port owns its source, assets, build script and tests.
  • Root Cargo workspace: shared version/metadata, lockfile, profiles and target directory.
  • Retire Python prototypes once their Rust replacements are validated. Add future Rust tools as workspace members and include every member in CI checks and coverage.

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. Python exporter, CI and packaging 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 --all --check, cargo clippy --locked --workspace --all-targets --all-features -- -D warnings, cargo test --locked --workspace --all-features, and RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --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.