AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Extract PDF Pages Agent Guide

Agent guide for extracting selected page ranges from a PDF with sorted deduped page parsing.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Extract PDF Pages in the alexandrai-tools project.

Project overview

This guide covers src/tools/extract-pages-pdf. The parser accepts one-based singles and ranges, sorts and dedupes output, clamps ranges to total pages, rejects invalid tokens, and returns an empty array for blank specs. Body.astro defaults blank UI input to the full document, copies selected pages into a fresh PDF, and downloads extracted.pdf.

Primary source files

  • src/tools/extract-pages-pdf/index.ts defines meta, PageRangeError, and parsePageRanges.
  • src/tools/extract-pages-pdf/index.test.ts covers range parsing, dedupe, clamping, beyond-total pages, blank specs, reversed ranges, zero pages, garbage input, and multiple ranges.
  • src/tools/extract-pages-pdf/Body.astro owns input loading, range defaulting, page copy, save, download, and clear actions.
  • src/tools/extract-pages-pdf/i18n.ts owns localized labels.
  • src/lib/tools.ts registers the tool metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Keep extract behavior focused on selected pages, not deletion semantics.
  • Return sorted deduped page numbers from parsePageRanges.
  • Use one-based page numbers in UI and docs.
  • Convert to zero-based page indices only for pdf-lib copyPages.
  • Default blank UI ranges to all pages.
  • Reject empty final selections with PageRangeError.
  • Maintain copied page order as the sorted parsed order.

Testing

Test parsePageRanges thoroughly, blank UI defaulting, empty final selection errors, multi-range extraction, out-of-range ranges, copied page order, output page count, invalid input messages, and download-state reset.

PR checklist

  • npm test passes for extract-pages-pdf.
  • PDF and binary file processing remain browser-local.
  • Pure helper behavior, UI state, and i18n labels stay aligned.
  • Invalid input, empty output, and download behavior are covered by tests.