# AGENTS.md

## Project

Wrenn JavaScript SDK — a client library for the Wrenn microVM platform. e2b drop-in replacement.
Package name: `@wrenn/sdk`. Node.js 18+, TypeScript 5.5+, managed with [pnpm](https://pnpm.io/).

## Commands

```bash
pnpm install                          # install deps
make lint                             # biome check + format check (no auto-fix)
make test                             # unit tests only (vitest)
make test-integration                 # all tests including integration (needs live server)
make generate                         # regenerate types from OpenAPI spec (openapi-typescript)
make check                            # lint + unit test
make build                            # tsup build (CJS + ESM + DTS)
```

- `make test` runs all non-integration tests. To run a specific test file: `pnpm vitest run tests/commands.test.ts`
- No separate typecheck step — `vitest` and `tsup` handle type checking during test/build. `tsc --noEmit` is available but not wired up in CI.

## Architecture

- `src/` — the library package
  - `capsule.ts` — high-level `Capsule` class (main user-facing class)
  - `client.ts` — low-level `WrennClient` with `CapsulesResource` and `SnapshotsResource`
  - `commands.ts` — command execution, streaming, and background process management
  - `files.ts` — filesystem operations
  - `pty.ts` — interactive terminal (PTY) over WebSocket
  - `exceptions.ts` — typed error hierarchy (`WrennError` base)
  - `models/generated.ts` — **auto-generated** from OpenAPI spec via `openapi-typescript` (never edit directly; run `make generate`)
  - `git/` — git operations inside capsules (clone, push, pull, status, branches, etc.)
  - `code-interpreter/` — specialized capsule for stateful Jupyter kernel execution
  - `_shared/http.ts` — thin `fetch` wrapper with auth headers, base URL, and error mapping
  - `_shared/websocket.ts` — WebSocket helper wrapping `ws`
  - `config.ts` — constants (`DEFAULT_BASE_URL`, env var names)
- `tests/` — unit tests use `msw` to mock HTTP; integration tests are in `tests/integration/`
- `api/openapi.yaml` — OpenAPI spec used for type generation

## Key Conventions

- Generated types live in `src/models/generated.ts`. Never edit them. Run `make generate` to update.
- No sync/async split — JS is naturally async. One `Capsule` class, all methods return `Promise`.
- `Sandbox` is a deprecated alias for `Capsule`. New code should use `Capsule`.
- Uses native `fetch` for HTTP (Node 18+), `ws` for WebSockets, `zod` for runtime validation.
- Resource disposal via `Symbol.asyncDispose` (`await using`). Also supports manual `.close()`.
- Streaming methods return `AsyncGenerator` (e.g. `commands.stream()`, `files.downloadStream()`).
- Static + instance method pattern: `capsule.destroy()` (instance) and `Capsule.destroy(id, opts)` (static).

## Testing

- Unit tests mock HTTP via `msw` (Mock Service Worker for Node).
- Integration tests require env vars: `WRENN_API_KEY` (or `WRENN_TOKEN`), optionally `WRENN_BASE_URL`.
- Integration test fixtures in `tests/integration/setup.ts` create real capsules and clean them up.
- Tests use `vitest` — no `@jest` globals. Use `import { describe, it, expect } from 'vitest'`.

## CI

Woodpecker CI (`.woodpecker/check.yml`) runs on push to `main` and `dev`:
1. `make lint`
2. `make test`
3. `make test-integration`

## Dependencies

Runtime: `ws` (WebSocket), `zod` (validation). Everything else is dev-only.

<!-- code-review-graph MCP tools -->
## MCP Tools: code-review-graph

**IMPORTANT: This project has a knowledge graph. ALWAYS use the
code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
the codebase.** The graph is faster, cheaper (fewer tokens), and gives
you structural context (callers, dependents, test coverage) that file
scanning cannot.

### When to use graph tools FIRST

- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
- **Architecture questions**: `get_architecture_overview` + `list_communities`

Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.

### Key Tools

| Tool | Use when |
| ------ | ---------- |
| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
| `get_review_context` | Need source snippets for review — token-efficient |
| `get_impact_radius` | Understanding blast radius of a change |
| `get_affected_flows` | Finding which execution paths are impacted |
| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
| `semantic_search_nodes` | Finding functions/classes by name or keyword |
| `get_architecture_overview` | Understanding high-level codebase structure |
| `refactor_tool` | Planning renames, finding dead code |

### Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use `detect_changes` for code review.
3. Use `get_affected_flows` to understand impact.
4. Use `query_graph` pattern="tests_for" to check coverage.