PDF Guard

Overview

A command-line utility for working with PDF documents in bulk: inspecting their structure, validating that they are well-formed, and applying document-level protection settings consistently across a whole directory.

Problem

Applying the same handling to a folder of PDFs through a desktop application is slow, inconsistent and easy to get wrong halfway through. It is also not something you can put in a pipeline — which is exactly where this kind of work belongs.

Goals

• One command that processes a directory rather than one document.
• Deterministic, inspectable behaviour: the same input always produces the same output.
• Clear failure. A malformed source document should stop with a useful message, not silently emit a damaged file.

Approach

The tool is structured as a small pipeline: discover input files, parse and validate each document, apply the requested operation, then write output to a separate location so the source is never modified in place. Each stage is independent, which keeps the failure modes local and the code testable.

The command-line interface is intentionally thin — it parses arguments and delegates. That keeps the underlying operations importable as a library rather than locked inside the CLI.

Key implementation details

• Non-destructive by default. Sources are never overwritten; output is written to a separate target.
• Validation before mutation. A document is checked for structural integrity before anything is applied to it.
• Per-file error isolation. One unreadable document reports and is skipped rather than aborting an entire batch.
• Library-first design, with the CLI as a thin wrapper over it.

Challenges

PDF is a forgiving format in practice and files in the wild frequently deviate from the specification. A meaningful share of the work was deciding which deviations to tolerate and which to reject, and making sure the tool never turned a slightly unusual file into a definitively broken one.

What I learned

Batch tools live or die by their failure behaviour. Getting the error handling and reporting right mattered considerably more to the tool’s usefulness than any of the features did.