107 lines
5.1 KiB
Markdown
107 lines
5.1 KiB
Markdown
# 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.
|