From 102735d483ec4486ba44b73637eb655dde254d2f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 25 Nov 2025 12:44:31 +0100 Subject: [PATCH] Docs: add repository guidelines to AGENTS.md --- AGENTS.md | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7ca325d8d..706099640 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,36 @@ -# Agent Notes +# Repository Guidelines -- Whenever you make code changes, if the relay is running (check tmux), restart it so the new code is loaded. For this repo the session is `warelay-relay`; kill and start `pnpm warelay relay --verbose` in tmux. +## Project Structure & Module Organization +- Source code: `src/` (CLI wiring in `src/cli`, commands in `src/commands`, Twilio in `src/twilio`, Web provider in `src/provider-web.ts`, infra in `src/infra`, media pipeline in `src/media`). +- Tests: colocated `*.test.ts` plus e2e in `src/cli/relay.e2e.test.ts`. +- Docs: `docs/` (images, queue, Claude config). Built output lives in `dist/`. + +## Build, Test, and Development Commands +- Install deps: `pnpm install` +- Run CLI in dev: `pnpm warelay ...` (tsx entry) or `pnpm dev` for `src/index.ts`. +- Type-check/build: `pnpm build` (tsc) +- Lint/format: `pnpm lint` (biome check), `pnpm format` (biome format) +- Tests: `pnpm test` (vitest); coverage: `pnpm test:coverage` + +## Coding Style & Naming Conventions +- Language: TypeScript (ESM). Prefer strict typing; avoid `any`. +- Formatting/linting via Biome; run `pnpm lint` before commits. +- Keep files concise; extract helpers instead of “V2” copies. Use existing patterns for CLI options and dependency injection via `createDefaultDeps`. + +## Testing Guidelines +- Framework: Vitest with V8 coverage thresholds (70% lines/branches/functions/statements). +- Naming: match source names with `*.test.ts`; e2e in `*.e2e.test.ts`. +- Run `pnpm test` (or `pnpm test:coverage`) before pushing when you touch logic. + +## Commit & Pull Request Guidelines +- Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`). +- Group related changes; avoid bundling unrelated refactors. +- PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags. + +## Security & Configuration Tips +- Environment: copy `.env.example`; set Twilio creds and WhatsApp sender (`TWILIO_WHATSAPP_FROM`). +- Web provider stores creds at `~/.warelay/credentials/`; rerun `warelay login` if logged out. +- Media hosting relies on Tailscale Funnel when using Twilio; use `warelay webhook --ingress tailscale` or `--serve-media` for local hosting. + +## Agent-Specific Notes +- If the relay is running in tmux (`warelay-relay`), restart it after code changes: kill pane/session and run `pnpm warelay relay --verbose` inside tmux. Check tmux before editing; keep the watcher healthy if you start it.