beffroi-tools/AGENTS.md

48 lines
2.3 KiB
Markdown

# beffroi-tools
This repository contains small Python command-line tools for everyday local
document and media workflows. Keep them simple to run and document their usage
in `README.md`.
## Current 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, and PDF. PDF reports compile through
the Typst CLI.
- `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.
- `test_exporter.py` covers exporter validation, no-op behavior, conversion
failures, and overwrite behavior.
## 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.
- Update `README.md` when command-line options or workflows change.
- Run checks appropriate to the change before committing. Exporter regression
tests run with `python -m unittest test_exporter -v`. For rendering changes,
test with the actual external tools when available and inspect visual output.
Report any checks that could not be completed.
## 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.