AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools PDF Utilities Agent Guide

Project-specific AGENTS.md guidance for AlexandrAI Tools PDF utilities, browser-only PDF handling, pure helper tests, page ranges, rotation normalization, and static build checks.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools PDF utilities.

Project Overview

PDF utilities process user-selected files in the browser and should avoid server upload paths. The category includes page rotation, page splitting, deletion, page numbering, and image-to-PDF workflows. Pure helper logic should live in index.ts and be covered by focused tests.

Project Map

  • src/tools/rotate-pdf/index.ts defines rotate-pdf metadata and normalizeAngle().
  • src/tools/split-pdf/index.ts and delete-pages-pdf/index.ts own page selection helpers.
  • src/tools/add-page-numbers-pdf/index.ts owns page numbering metadata and logic.
  • src/tools/images-to-pdf/index.ts bridges images into PDF generation.
  • src/tools/pdf-lazy-loading.test.ts covers lazy loading expectations.
  • package.json includes pdf-lib as the PDF manipulation dependency.

Setup Commands

bashnpm test -- src/tools/rotate-pdf/index.test.ts src/tools/split-pdf/index.test.ts src/tools/delete-pages-pdf/index.test.ts
npm test -- src/tools/pdf-lazy-loading.test.ts
npm run typecheck
npm run build

Change Rules For Agents

  • Keep file bytes in the browser.
  • Keep page range parsing and rotation normalization as pure tested helpers.
  • Lazy-load heavy PDF code when practical.
  • Validate user page selections before creating output.
  • Do not mutate the original File object.
  • Keep output download explicit.
  • Keep metadata descriptions honest about browser-only processing.
  • Avoid cross-tool shared state for selected files.

Verification

bashnpm test -- src/tools/rotate-pdf/index.test.ts src/tools/split-pdf/index.test.ts src/tools/delete-pages-pdf/index.test.ts
npm test -- src/tools/pdf-lazy-loading.test.ts
npm run build

Manual checks should cover encrypted or invalid PDFs, empty selections, large files within browser limits, and page-order preservation.

Security Notes

PDF tools handle sensitive documents. Do not add upload, remote conversion, persistent storage, hidden logging, or preview content in URL parameters.

PR Checklist

  • Pure helpers have focused tests.
  • Browser-only claim remains true.
  • Lazy loading still works.
  • Invalid page selections show errors.
  • Build succeeds.