# Repository Guidelines

## What is Warelay?
Warelay is a WhatsApp relay CLI tool for sending, receiving, and auto-replying to WhatsApp messages. It supports two provider backends:
- **Twilio**: Enterprise-grade WhatsApp Business API with delivery tracking, webhooks, and polling
- **Web (Baileys)**: Personal WhatsApp Web session via QR code linking (unofficial @whiskeysockets/baileys library)

Primary use case: Running AI assistants (like "Clawd" - Claude-powered) that respond to WhatsApp messages with configurable sessions, transcription, and heartbeats.

## Project Structure & Module Organization

### Core Architecture
```
src/
├── index.ts              # Main entry point + public API exports
├── provider-web.ts       # Barrel exports for Web provider (from src/web/)
├── cli/
│   ├── program.ts        # Commander.js CLI definition (all commands)
│   ├── deps.ts           # Dependency injection via createDefaultDeps()
│   ├── prompt.ts         # Interactive prompts (promptYesNo)
│   └── relay_tmux.ts     # tmux session management
├── commands/
│   ├── send.ts           # warelay send
│   ├── status.ts         # warelay status (Twilio only)
│   ├── webhook.ts        # warelay webhook
│   └── up.ts             # (startup helpers)
├── auto-reply/
│   ├── reply.ts          # getReplyFromConfig() - main reply engine
│   ├── command-reply.ts  # runCommandReply() - external command execution
│   ├── claude.ts         # Claude CLI JSON output parsing
│   ├── templating.ts     # {{Placeholder}} template substitution
│   └── transcription.ts  # Audio-to-text transcription
├── config/
│   ├── config.ts         # ~/.warelay/warelay.json schema + loadConfig()
│   └── sessions.ts       # ~/.warelay/sessions.json (Claude session state)
├── providers/
│   ├── provider.types.ts # Provider = "twilio" | "web"
│   ├── twilio/index.ts   # Twilio re-exports
│   └── web/index.ts      # Web re-exports
├── twilio/
│   ├── client.ts         # createClient() - Twilio SDK init
│   ├── send.ts           # sendMessage(), waitForFinalStatus()
│   ├── messages.ts       # listRecentMessages(), formatMessageLine()
│   ├── monitor.ts        # monitorTwilio() - polling loop
│   ├── webhook.ts        # Express server for Twilio callbacks
│   ├── heartbeat.ts      # runTwilioHeartbeatOnce()
│   ├── typing.ts         # sendTypingIndicator()
│   └── update-webhook.ts # Twilio callback URL management
├── web/
│   ├── session.ts        # createWaSocket(), pickProvider(), webAuthExists()
│   ├── login.ts          # loginWeb() - QR code flow
│   ├── inbound.ts        # monitorWebInbox() - message listener
│   ├── outbound.ts       # sendMessageWeb()
│   ├── auto-reply.ts     # monitorWebProvider() - main relay loop
│   ├── media.ts          # Download/resize helpers
│   └── reconnect.ts      # Exponential backoff math
├── media/
│   ├── store.ts          # saveMediaSource(), saveMediaBuffer(), cleanOldMedia()
│   ├── host.ts           # ensureMediaHosted() - Tailscale Funnel hosting
│   ├── server.ts         # Express routes for serving media
│   └── constants.ts      # MAX_IMAGE_BYTES (6MB), MAX_AUDIO_BYTES (16MB), etc.
├── infra/
│   ├── tailscale.ts      # ensureFunnel(), getTailnetHostname()
│   ├── ports.ts          # ensurePortAvailable(), PortInUseError
│   └── binaries.ts       # ensureBinary() - external tool checks
├── process/
│   ├── exec.ts           # runCommandWithTimeout(), runExec()
│   └── command-queue.ts  # Command queueing
├── webhook/
│   ├── server.ts         # Webhook server setup
│   └── update.ts         # Webhook URL updates
├── env.ts                # Zod schema for TWILIO_* env vars
├── globals.ts            # setVerbose(), isVerbose(), info(), danger()
├── runtime.ts            # RuntimeEnv type for testable I/O
├── logger.ts             # Pino logger setup
├── logging.ts            # getResolvedLoggerSettings()
├── utils.ts              # assertProvider(), normalizeE164(), toWhatsappJid()
└── version.ts            # VERSION constant
```

### Key Files by Function
| Function | Primary Files |
|----------|---------------|
| CLI entry | `src/index.ts`, `src/cli/program.ts` |
| Twilio send | `src/twilio/send.ts`, `src/commands/send.ts` |
| Web send | `src/web/outbound.ts` |
| Auto-reply | `src/auto-reply/reply.ts`, `src/auto-reply/command-reply.ts` |
| Claude integration | `src/auto-reply/claude.ts` |
| Config | `src/config/config.ts` (schema), `src/config/sessions.ts` (state) |
| Web relay loop | `src/web/auto-reply.ts` (monitorWebProvider) |
| Media pipeline | `src/media/store.ts`, `src/media/host.ts` |

## CLI Commands Reference
| Command | Description | Key Options |
|---------|-------------|-------------|
| `login` | Link WhatsApp via QR | `--verbose` |
| `logout` | Clear web credentials | |
| `send` | Send message | `--to`, `--message`, `--media`, `--provider`, `--wait`, `--poll`, `--json` |
| `relay` | Auto-reply loop | `--provider auto\|web\|twilio`, `--interval`, `--lookback`, `--heartbeat-now` |
| `relay:heartbeat` | Relay + immediate heartbeat | `--provider auto\|web`, `--verbose` |
| `relay:tmux` | Relay in tmux session | |
| `relay:heartbeat:tmux` | Relay + heartbeat in tmux | |
| `status` | Show recent messages | `--limit`, `--lookback`, `--json` |
| `webhook` | Run inbound webhook | `--ingress tailscale\|none`, `--port`, `--path` |
| `heartbeat` | Trigger one heartbeat | `--to`, `--session-id`, `--all`, `--message` |

## 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)
- Fix lint/format: `pnpm lint:fix`, `pnpm format:fix`
- Tests: `pnpm test` (vitest); coverage: `pnpm test:coverage`
- Node requirement: >=22.0.0

## Key Dependencies
| Package | Purpose |
|---------|---------|
| `@whiskeysockets/baileys` | WhatsApp Web protocol (unofficial) |
| `twilio` | Twilio SDK for WhatsApp Business API |
| `commander` | CLI argument parsing |
| `express` | Webhook server |
| `zod` | Schema validation (config, env) |
| `json5` | Config file parsing (allows comments) |
| `pino` | Structured logging |
| `sharp` | Image resizing for media limits |
| `qrcode-terminal` | QR code display for login |
| `chalk` | CLI colorization |

## 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()`.

## Architectural Patterns

### Dependency Injection
Commands use `CliDeps` from `src/cli/deps.ts` for testability:
```typescript
export type CliDeps = {
  sendMessage: typeof sendMessage;
  sendMessageWeb: typeof sendMessageWeb;
  waitForFinalStatus: typeof waitForFinalStatus;
  monitorTwilio: typeof monitorTwilio;
  // ...
};
export function createDefaultDeps(): CliDeps { /* ... */ }
```

### Runtime Abstraction
`RuntimeEnv` from `src/runtime.ts` abstracts I/O for testing:
```typescript
export type RuntimeEnv = {
  log: (msg: string) => void;
  error: (msg: string) => void;
  exit: (code: number) => never;
};
```

### Provider Selection
`pickProvider()` in `src/web/session.ts`:
- `"auto"` → web if `~/.warelay/credentials/` exists, else twilio
- Web sessions don't fall back to Twilio on disconnect (exits instead)

### Templating
`src/auto-reply/templating.ts` supports `{{Placeholder}}` tokens:
- `{{Body}}`, `{{BodyStripped}}` (with reset trigger removed)
- `{{From}}`, `{{To}}`, `{{MessageSid}}`
- `{{SessionId}}`, `{{IsNewSession}}`
- `{{MediaPath}}`, `{{MediaUrl}}`, `{{MediaType}}`

### Session Management
Sessions in `~/.warelay/sessions.json`:
```typescript
type SessionEntry = {
  sessionId: string;      // UUID for Claude --session-id
  updatedAt: number;      // Timestamp for idle expiration
  systemSent?: boolean;   // For sendSystemOnce feature
};
```
- Per-sender or global scope
- Idle expiration (default 60 minutes)
- Reset triggers (`/new` by default)

## 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.
- Pure test additions/fixes generally do **not** need a changelog entry unless they alter user-facing behavior or the user asks for one.

### Test Patterns
```typescript
import { describe, expect, it, vi } from "vitest";

const runtime: RuntimeEnv = {
  log: vi.fn(),
  error: vi.fn(),
  exit: vi.fn(() => { throw new Error("exit"); }),
};

const baseDeps = {
  assertProvider: vi.fn(),
  sendMessageWeb: vi.fn(),
  // ... mock dependencies
} as unknown as CliDeps;
```

## Configuration Files

### Environment (.env)
Required for Twilio provider:
```
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...          # OR
TWILIO_API_KEY=SK...
TWILIO_API_SECRET=...
TWILIO_WHATSAPP_FROM=whatsapp:+19995550123
TWILIO_SENDER_SID=...          # optional
```

### Config (~/.warelay/warelay.json)
JSON5 format with Zod validation:
```json5
{
  logging: { level: "debug", file: "/tmp/warelay/warelay.log" },
  inbound: {
    allowFrom: ["+12345550000"],  // E.164, or "*" for all
    messagePrefix: "",
    responsePrefix: "",
    timestampPrefix: true,       // or IANA timezone string
    transcribeAudio: { command: ["openai", "..."], timeoutSeconds: 45 },
    reply: {
      mode: "command",           // or "text"
      command: ["claude", "--dangerously-skip-permissions", "{{BodyStripped}}"],
      bodyPrefix: "You are a concise assistant.\n\n",
      claudeOutputFormat: "text", // or "json" / "stream-json"
      timeoutSeconds: 600,
      session: {
        scope: "per-sender",     // or "global"
        resetTriggers: ["/new"],
        idleMinutes: 60,
        sendSystemOnce: true,
        sessionIntro: "New conversation started."
      },
      heartbeatMinutes: 10
    }
  },
  web: {
    heartbeatSeconds: 120,
    reconnect: { initialMs: 1000, maxMs: 30000, factor: 2, jitter: 0.2, maxAttempts: 10 }
  }
}
```

## 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.
- Media limits: images ≤6MB, audio/video ≤16MB, documents ≤100MB.

## Agent-Specific Notes
- If the relay is running in tmux (`warelay-relay`), restart it after code changes: kill pane/session and run `warelay relay --provider twilio --verbose` inside tmux. Check tmux before editing; keep the watcher healthy if you start it.
- Always use `--provider twilio` when starting the relay (not `auto` or `web`).
- warelay is installed globally, so use `warelay` directly instead of `pnpm warelay`.
- Also read the shared guardrails at `~/Projects/oracle/AGENTS.md` and `~/Projects/agent-scripts/AGENTS.MD` before making changes; align with any cross-repo rules noted there.

### Common Development Tasks
1. **Adding a new CLI command**: Add to `src/cli/program.ts`, implement in `src/commands/`, add deps to `src/cli/deps.ts`
2. **Modifying auto-reply logic**: `src/auto-reply/reply.ts` is the entry point; `command-reply.ts` handles external commands
3. **Changing config schema**: Update `src/config/config.ts` (Zod schema + WarelayConfig type)
4. **Web provider changes**: Files under `src/web/`; barrel exports via `src/provider-web.ts`
5. **Twilio provider changes**: Files under `src/twilio/`; barrel exports via `src/providers/twilio/index.ts`

### Debugging Tips
- Enable verbose logging: `--verbose` flag or `logging.level: "debug"` in config
- Check logs at `/tmp/warelay/warelay.log` (or configured path)
- Web relay health logs show heartbeat intervals and reconnect policy
- Use `warelay status --json` to inspect recent Twilio traffic
- Session state in `~/.warelay/sessions.json` for Claude session debugging

## Exclamation Mark Escaping Workaround
The Claude Code Bash tool escapes `!` to `\!` in command arguments. When using `warelay send` with messages containing exclamation marks, use heredoc syntax:

```bash
# WRONG - will send "Hello\!" with backslash
warelay send --provider web --to "+1234" --message 'Hello!'

# CORRECT - use heredoc to avoid escaping
warelay send --provider web --to "+1234" --message "$(cat <<'EOF'
Hello!
EOF
)"
```

This is a Claude Code quirk, not a warelay bug.