petdex: Instructions file for Codex

Petdex Agent Notes

Commands

• Use Bun for repo work: bun install, not npm install. Published CLI docs mention npm/npx for end users only.
• Recommended local app dev is bun run dev:docker; it boots local Postgres and Redis with shared Clerk dev defaults from .env.dev.
• Maintainer dev is bun dev with .env.local copied from .env.example; this path expects Clerk, Postgres/Neon, R2, Upstash, Resend, OpenAI, and ElevenLabs credentials.
• bun run dev:mock is deprecated and intentionally exits. Keep .env.mock only for targeted mock-backed tests or build checks.
• Root checks: bun run check for Biome, bun run format to write Biome fixes, bun run build for the Next app, bun run test for the full Bun suite, and bun run i18n:check after editing translation messages. There is no root typecheck script. Use bun run test rather than a bare bun test: the raise lives in that script's --timeout, and a bare bun test never reads it, so it still aborts the specs that need more than Bun's 5s default. bunfig.toml cannot carry the raise instead: there is no [test] timeout key, and a preload calling setDefaultTimeout does not reach every file — measured at one of five.
• Focused tests use bun run test path/to/file.test.ts, which forwards the path and keeps the suite timeout. Tests that import src/lib/db/client.ts directly or indirectly, including src/lib/pet-search.test.ts and src/lib/security.test.ts, need a usable DATABASE_URL or mock env: bun run test --env-file=.env.mock src/lib/security.test.ts.
• mock.module is process-wide, so a suite that stubs a module before importing anything that pulls it in is the only kind that runs correctly on its own. The four collection route suites under src/app/api/{cli,profile} run in isolated processes through src/lib/collection-routes.test.ts and stub @/lib/db/client ahead of their @/lib/collection-access import for that reason — a stubbing suite that loads first in a root run masks the ordering, so run one alone (bun run test 'src/app/api/profile/collections/[id]/route.integration.ts') after touching it, and remember they stub runCollectionMutation, so their assertions never execute the collection SQL. When the point is to execute real SQL, use a suite that owns its PGlite connection (src/lib/collection-empty-list.test.ts).
• Do not run the whole root suite with --env-file=.env.mock: PETDEX_MOCK=1 makes packages/petdex-cli's asset-hosts.test.ts fail, because mock mode injects mock.invalid into the server-side asset allowlist the CLI pins against. Keep the env flag on focused root runs only.
• packages/petdex-cli and packages/discord-bot are independent packages, not root workspaces; run their own bun install and package scripts from inside each directory. Root tsconfig.json excludes packages.
• CLI package verification, run from packages/petdex-cli, is bun run build && bun run typecheck, plus bun run test for its suite. The build emits ignored dist/petdex.js and prepends the node shebang in postbuild. Use bun run test there for the same reason as the root: the --timeout lives in that script, and its spawn-a-CLI specs are slow enough to brush Bun's 5s default on a loaded machine. CI runs a bare bun test and has not tripped it.
• Discord bot work stays in packages/discord-bot; use bun run register, bun run dev, or bun run start there with env from packages/discord-bot/.env.example.