ts/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

CoreTS (`forge.lthn.ai/core/ts`) is a Go package that manages a Deno 2.x TypeScript runtime as a sandboxed sidecar process. It provides bidirectional communication between Go and Deno over Unix sockets using gRPC (Go→Deno calls) and JSON-RPC (Deno→Go calls), with fine-grained permission gating for filesystem, key-value store, and process operations.

This is a **library package** — no standalone binary. It compiles as part of applications that import it.

## Build & Test Commands

```bash
go build ./...                                # Build
go test ./...                                 # Unit tests (no Deno needed)
go test -tags integration -timeout 60s ./...  # Integration tests (requires Deno 2.x)
go test -run TestName ./...                   # Single test
go test -race ./...                           # Race detector
go test -cover ./...                          # Coverage

go fmt ./...                                  # Format
go vet ./...                                  # Vet

# Proto regeneration
protoc --go_out=. --go-grpc_out=. proto/coredeno.proto
```

## Architecture

All Go code lives in a single `ts` package (no subpackages).

**Two communication channels over Unix sockets:**
- **CoreService (gRPC)** — Go implements, Deno calls. Handles: FileRead/Write/List/Delete, StoreGet/Set, ProcessStart/Stop. Every call is permission-gated against the module's manifest.
- **DenoService (JSON-RPC)** — Deno implements, Go calls. Handles: LoadModule, UnloadModule, ModuleStatus. Newline-delimited JSON over raw Unix socket.

**Startup sequence:** Create sandboxed Medium → Open SQLite store → Start gRPC listener on Unix socket → Launch Deno sidecar (passes CORE_SOCKET/DENO_SOCKET env vars) → Connect DenoClient → Auto-load installed modules.

**Module isolation:** Each module runs in a Deno Worker. The I/O bridge pattern is: module calls core API → worker-entry intercepts via postMessage RPC → ModuleRegistry relays to CoreClient gRPC → Go Server checks permissions with injected module code → result returns through same chain.

### Key Go types
- `Options` — Configuration (DenoPath, SocketPath, AppRoot, etc.)
- `Sidecar` — Manages Deno child process lifecycle
- `Server` — CoreService gRPC implementation with permission gating
- `DenoClient` — JSON-RPC client for module lifecycle
- `Service` — Framework integration (Startable/Stoppable lifecycle)

### Key TypeScript files (runtime/)
- `main.ts` — Entry point, boots gRPC client + JSON-RPC server
- `modules.ts` — ModuleRegistry, Worker lifecycle management
- `client.ts` — CoreService gRPC client wrapper
- `server.ts` — DenoService JSON-RPC server
- `worker-entry.ts` — Worker bootstrap, I/O bridge to parent
- `polyfill.ts` — Deno 2.x http2/grpc-js compatibility fixes (must import before @grpc/grpc-js)

## Code Conventions

- **UK English** in docs and comments (colour, organisation)
- **Error wrapping:** `fmt.Errorf("coredeno: <context>: %w", err)`
- **Test naming:** `_Good`, `_Bad`, `_Ugly` suffixes for test functions
- **Thread safety:** `Sidecar` uses `sync.RWMutex`; `DenoClient` uses `sync.Mutex`
- **Security model:** Empty permission lists deny all access; reserved store namespaces (prefixed `_`) blocked from modules; path matching uses boundary checks to prevent `"data"` matching `"data-secrets"`

## Testing

- **Unit tests** run without Deno — use `MockMedium` and `mockProcessRunner`
- **Integration tests** require `//go:build integration` tag and Deno 2.x installed; tests skip gracefully via `findDeno()` if Deno is absent
- Integration tests are tiered: Tier 1 (boot), Tier 2 (bidirectional comms), Tier 3 (Worker isolation + I/O bridge), Tier 4 (marketplace install)

## Dependencies

- `forge.lthn.ai/core/go` — Core framework (DI, ServiceRuntime)
- `forge.lthn.ai/core/go-io` — Sandboxed filesystem Medium
- `forge.lthn.ai/core/go-io/store` — SQLite key-value store
- `forge.lthn.ai/core/go-scm` — Manifest loading + marketplace installer
- `google.golang.org/grpc` — gRPC transport
- Deno side uses `@grpc/grpc-js` and `@grpc/proto-loader` (npm imports via deno.json, no codegen needed)

## Proto

Source: `proto/coredeno.proto` defines both `CoreService` and `DenoService`. Go stubs are generated; Deno loads the `.proto` dynamically at runtime via `@grpc/proto-loader`.