135 lines
8.2 KiB
Markdown
135 lines
8.2 KiB
Markdown
# 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.
|