beffroi-tools/AGENTS.md

2.3 KiB

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.