Skip to content

AGENTS.md

Latest commit

 

History

History
53 lines (46 loc) · 2.86 KB

AGENTS.md

File metadata and controls

53 lines (46 loc) · 2.86 KB

Repository Guidelines

Project Structure & Module Organization

  • Monorepo managed by Yarn workspaces (Node >= 20).
  • Apps: web/ (Next.js app), valhalla/jawn/ (TypeScript API), worker/ (Cloudflare Worker), bifrost/ (site/docs).
  • Shared code: packages/* (cost, filters, llm-mapper, prompts), shared/, sdk/.
  • Infra & data: supabase/, clickhouse/, docker/, env/, examples/.
  • Tests: packages/**/__tests__/, worker (Vitest), valhalla/jawn (Jest), Python integration in tests/.
  • Autogenerated types (do not manually edit these files):
    • valhalla/jawn/src/tsoa-build/
    • web/lib/clients/jawnTypes/
    • bifrost/lib/clients/jawnTypes/
    • worker/supabase/database.types.ts
    • web/db/database.types.ts
    • helicone-cron/src/db/database.types.ts
    • valhalla/jawn/src/lib/db/database.types.ts

Build, Test, and Development Commands

  • Install deps: yarn
  • Lint all: yarn lint • Fix: yarn lint:fix
  • Web app: yarn workspace helicone dev:local | build: yarn workspace helicone build
  • Bifrost: yarn workspace bifrost dev
  • API (Valhalla/Jawn): yarn workspace helicone-api dev | build: yarn workspace helicone-api build
  • Worker: yarn workspace helicone-worker dev | test: yarn workspace helicone-worker test
  • Packages tests: run Jest in packages/ (e.g., npx jest or npx jest __tests__/cost/registrySnapshots.test.ts)
  • Python integration: python tests/python_integration_tests.py

Coding Style & Naming Conventions

  • TypeScript/React, 2‑space indent, semicolons default; format with Prettier.
  • ESLint required; fix warnings before PRs.
  • React components PascalCase.tsx; utilities camelCase.ts; tests *.test.ts in __tests__/.
  • TailwindCSS in web/; rely on prettier-plugin-tailwindcss for class ordering.

Testing Guidelines

  • Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.
  • Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).
  • Run affected workspace tests locally before opening a PR.

Commit & Pull Request Guidelines

  • Use Conventional Commits where possible: feat:, fix:, chore:, refactor:, docs:. Example: feat(web): add usage chart (#1234).
  • PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.
  • Checks must pass: lint, build for touched workspaces, and relevant tests.

Security & Configuration Tips

  • Never commit secrets. Use .env.example as a template.
  • Web envs: vercel env pull or maintain .env.local locally.
  • Worker secrets: wrangler secret put <NAME>.
  • Database/config: see supabase/, clickhouse/, and docker/ for local setup.

Agent-Specific Notes

  • Scope changes to the smallest relevant workspace.
  • Prefer yarn workspace <name> <cmd>; avoid modifying unrelated packages.
  • Keep code style consistent; run yarn lint and add targeted tests.