js-sdk/AGENTS.md

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.

Commands

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.