beffroi-tools/AGENTS.md

2.8 KiB

beffroi-tools

This repository contains small 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

  • 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.
  • 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.
  • tests/test_exporter.py covers exporter validation, no-op behavior, conversion failures, and overwrite behavior.
  • tests/test_pptx_videos.py covers slide discovery, extraction, temporary probing, report formatting, and error handling.
  • Jenkinsfile runs the Python unit tests on rust_no_docker. CI is test-only: no publishing, badges, or archived artifacts.

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. Exporter regression tests and video-report 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.

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.