beffroi-tools/AGENTS.md

135 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.
## 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's JSON project and SVG geometry contracts are in
`docs/interfaces/canvas-pilot.md`; per-user application settings are in
`docs/interfaces/canvas-pilot-settings.md`. Reviewed device writes and crop
conversion are documented in `docs/interfaces/midra-device-send.md`; hardware
write/restore diagnostics are explicit examples, never automated CI tests.
## 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.