# 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.