From d047b35fbfc183feccfc7ff7555c4d9375ec0226 Mon Sep 17 00:00:00 2001 From: Justin Beckwith Date: Thu, 2 Apr 2026 10:52:09 -0700 Subject: [PATCH] docs: add AGENTS guide Co-authored-by: Codex --- AGENTS.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 5 +++++ 2 files changed, 67 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7a2901a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# AGENTS.md + +Guidance for AI agents and developers working on `promptfoo/example-app`. + +## Repository Purpose + +This is a TypeScript/Express example API gateway for AI chat. It exposes public and authenticated chat endpoints, maps fish-named path levels (`minnow`, `shark`) to internal prompt-safety levels, issues RS256 JWTs through OAuth-style token endpoints, and forwards chat completions to LiteLLM. + +This repo is intentionally useful as a security-scanning example, so preserve clear auth, prompt, and model-routing boundaries when making changes. + +## Common Commands + +```bash +# Install dependencies +npm install + +# Compile TypeScript to dist/ +npm run build + +# Start the compiled server +npm start + +# Run the development server with ts-node +npm run dev + +# Start LiteLLM from the local compose file +docker compose up -d +``` + +There is no local test script in `package.json` today, so use `npm run build` as the minimum validation command for code changes. + +## Code Layout + +- `src/server.ts`: Express app startup, middleware registration, route wiring, and in-memory RSA key generation. +- `src/routes/chat.ts`: request validation, fish-level to prompt-level mapping, model allowlist enforcement, and LiteLLM request forwarding. +- `src/routes/oauth.ts`: OAuth token and JWKS handlers for client credentials and password grants. +- `src/middleware/auth.ts`: JWT Bearer-token verification middleware. +- `src/domains/`: per-domain prompt text and prompt loaders for `general`, `finance`, `medicine`, `taxes`, and `vacation-rental`. +- `src/utils/jwt-keys.ts`: in-memory RSA key generation plus public/private key accessors and JWKS export. +- `src/utils/litellm-config.ts`: reads `litellm_config.yaml` and caches allowed model names. +- `litellm_config.yaml` and `docker-compose.yml`: local LiteLLM runtime configuration. + +## Implementation Rules + +- Load environment variables before modules that depend on them; `src/server.ts` intentionally calls `dotenv.config()` first. +- Preserve the `minnow`/`shark` API contract even though the implementation maps those names to `insecure`/`secure` prompt files internally. +- Keep Zod validation and explicit JSON error responses when changing route handlers. +- Do not commit real `.env` files, client secrets, user passwords, private keys, or API keys. +- Be careful with domain prompt edits: `secure.txt` files encode the safety/compliance behavior this app is meant to demonstrate. +- `src/utils/litellm-config.ts` currently fails open when the model config cannot be read; do not silently change that behavior without calling it out in the PR. + +## Validation + +- Run `npm run build` after TypeScript changes. +- Run `npm run dev` with `docker compose up -d` when you need to manually verify chat/OAuth flows against LiteLLM. +- CI currently runs the Promptfoo Code Scan workflow and requires the aggregate `CI Success` check. + +## Git Workflow + +- Do not push directly to `main`; create a branch and open a PR. +- Use Conventional Commit subjects (`feat:`, `fix:`, `docs:`, `refactor:`, `build:`, `ci:`, `chore:`) to match current repo history. +- Keep PR descriptions specific about API behavior, auth/prompt-safety impact, and manual validation performed. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..29b1801 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# Compatibility Note + +The canonical repository guide is [AGENTS.md](./AGENTS.md). + +This file remains as a compatibility shim for tools that still auto-load `CLAUDE.md`.