beffroi-tools/AGENTS.md

8.4 KiB
Raw Permalink Blame History

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/ascii-names/ is the sequential ASCII filename cleaner: one Rust binary with egui drag-and-drop and CLI modes. Keep renames paced and single-threaded, preserve file contents, never overwrite collision targets, and skip symlinks. The selected root stays unchanged; descendants are processed inside out.

  • 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. The five user-approved XLSX fixtures listed in rundowns/sources.json are tracked and exercised by tests/supplied_corpus.rs; other local examples, generated exports and public downloads stay untracked. Keep synthetic tests for isolated cases. 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 in a FreeBSD jail. ASCII cleaner tests must verify safe refusal when the jail lacks the native no-overwrite API; exercise successful renames on supported hosts as well. 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.

  • companion-modules/media-player-classic/ is the local MPC-HC module for Companion 5.1. Prefer JSON status with HTML fallback; drive feedback from player state, clear stale state on failures, and keep polling serialized and cancellable. Preserve numeric action IDs and upstream MIT attribution. Use Node.js 22.20+ (22.x); run npm test, npm run check, and npm run package in the module. setup.py installs locked dependencies and can back up/configure the launcher. Keep dependencies, packages, and caches untracked; real-player playback checks are separate from automated mock HTTP tests.

  • PDF Presenter is a standalone sibling at ../pdf-presenter, Gitea idle-org/pdf-presenter. This repository links to it; do not add it as a workspace member or publish its badges. It is currently a foundation, not a working presenter.

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.
  • For each tool change, add a succinct entry to its changelog linked from docs/changelogs.md: what changed and any useful testing note or limitation. Use Unreleased until tagged; add new tools to the index. Keep shared changes in affected tools’ logs, without duplicating implementation details.
  • 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.

Save/export interfaces

  • Document every persistent save and export format under docs/interfaces/, including field names, units, precision, versioning, validation, omissions, import/round-trip behavior, and compatibility expectations.
  • Whenever a save-file schema or export representation changes, update the corresponding interface documentation, examples, and regression tests in the same task. Do not leave interfaces out of a schema change.
  • Version breaking changes explicitly; provide a tested migration or a clear unsupported-version error rather than silently interpreting incompatible data.
  • Canvas Pilot has moved to ../canvas-pilot and its own Gitea repository, idle-org/canvas-pilot. Its code, contracts, fixtures, probe and book belong there. This repository links to its manual but never publishes or deletes that book.

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.