AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repository.

Purpose

This project is a NestJS + Fastify API that normalizes responses across multiple Booru providers using @alejandroakbal/universal-booru-wrapper.

For product/context details, read:

• README.md
• DOCUMENTATION.md

Setup And Commands

Prerequisites:

• Node 24 (see package.json engines)
• Access to GitHub Packages for private dependency installation (see DOCUMENTATION.md)

Install and run:

• corepack enable
• pnpm install
• pnpm dev (watch mode)
• pnpm build
• pnpm start (runs compiled dist/main)

Quality checks:

• pnpm lint
• pnpm format
• pnpm test

Architecture Map

Key files:

• App bootstrap: src/main.ts
• Root module/providers: src/app.module.ts
• API root controller: src/app.controller.ts
• Booru module wiring: src/booru/booru.module.ts
• Booru endpoints: src/booru/booru.controller.ts
• Booru API construction: src/booru/booru.service.ts
• Error mapping/sanitization: src/booru/interceptors/booru-exception.interceptor.ts
• Auth credential management: src/booru/services/booru-auth-manager.service.ts
• Response envelope and links: src/lib/dto/response.dto.ts
• Validation pipe defaults: src/common/validation.ts

High-level flow:

1. Controller validates params/query DTOs and builds a provider API instance via BooruService.
2. Service maps endpoint/query/auth options into the wrapper API constructor.
3. Controller calls wrapper methods (getPosts, getRandomPosts, getSinglePost, getTags).
4. Interceptor converts wrapper errors into Nest HTTP exceptions and sanitizes sensitive URL params.
5. ResponseDto shapes payload, pagination metadata, and navigation links.

Project Conventions

• Keep request contracts in DTO classes under src/booru/dto/ with class-validator + class-transformer.
• Respect global validation behavior from createAppValidationPipe():
  • transform: true
  • whitelist: true
  • forbidNonWhitelisted: true
• Prefer adding behavior in services/interceptors over bloating controllers.
• Preserve response shape generated by ResponseDto unless API contract changes are explicitly requested.
• For booru auth data, keep sanitization behavior aligned with:
  • SENSITIVE_AUTH_PARAMS
  • URL/key-value redaction in auth/interceptor services.

Testing Patterns

• Unit tests use Jest + @nestjs/testing.
• Keep test files as *.spec.ts near the implementation (existing repo pattern).
• Update/add tests when modifying:
  • DTO validation behavior
  • Error mapping/sanitization
  • Response structure (meta, links)

Reference tests:

• src/booru/booru.service.spec.ts
• src/booru/dto/booru-queries.dto.spec.ts
• src/booru/interceptors/booru-exception.interceptor.spec.ts
• src/booru/services/booru-auth-manager.service.spec.ts
• src/lib/dto/response.dto.spec.ts

Pitfalls To Avoid

• Do not assume private package install works without GitHub Packages login.
• Do not leak auth_user, auth_pass, API keys, or equivalent credentials in errors/logs.
• Be careful when refactoring pageID handling in booru.controller.ts and ResponseDto; existing code uses @ts-ignore in several places.
• Keep Fastify/Nest bootstrap behavior intact unless requested (Sentry init, CORS policy, static serving, global validation pipe, clustering).

Change Checklist For Agents

Before finishing a change:

1. Run pnpm lint and pnpm test if dependencies are installed.
2. If DTOs changed, verify validation and query transforms with tests.
3. If error/auth logic changed, verify sanitization and auth failure handling paths.
4. If response generation changed, validate meta and links outputs.