astro-loader-pocketbase: Instructions file for Codex

AGENTS.md

Compact ramp-up guide for AI agents. Each item exists because an agent would likely miss it.

Project

An Astro content loader package that integrates PocketBase as a data source, using Astro's Content Loader API. Key capabilities: loading PocketBase collections, real-time updates (via astro-integration-pocketbase), incremental builds, schema generation/validation, and file handling.

Relevant upstream documentation:

• Astro Content Loader API
• PocketBase Documentation

Environment

• Node >= 22.12.0 required; .nvmrc specifies node version. Use nvm use before anything.
• Package manager: npm (version enforced via packageManager field). Do not use pnpm or yarn.

Essential commands

npm run format       # oxfmt — format all files
npm run lint:fix     # oxlint --fix — lint + auto-fix
npm run typecheck    # tsc --noEmit on src/ and test/
npm test             # vitest run (unit + e2e, needs PocketBase for e2e)
npm run test:unit    # unit tests only — no PocketBase needed
npm run test:e2e     # e2e tests only — PocketBase must be running first
npm run build        # tsdown → dist/

Run a single test file:

npx vitest run test/path/to/file.spec.ts

Pre-commit order (husky enforces this)

All three must pass before committing, in this order:

1. npm run format
2. npm run lint:fix
3. npm run typecheck

lint-staged runs oxfmt + oxlint on staged files automatically. The pre-commit hook also runs npm run typecheck if any .ts files are staged.

E2E test setup

E2E tests require a PocketBase instance at http://localhost:8090.

# One-time: download PocketBase binary to .pocketbase/ (gitignored)
npm run test:e2e:setup

# Start PocketBase (blocks terminal — use a separate terminal)
./.pocketbase/pocketbase serve

# Then run e2e tests
npm run test:e2e

Hardcoded test credentials: [email protected] / test1234 (created by the setup script).