Skip to content

Latest commit

 

History

History
177 lines (124 loc) · 6.14 KB

CLAUDE.md

File metadata and controls

177 lines (124 loc) · 6.14 KB

opencode-fork

OpenCode executor fork for the Pistachiorama sandbox (Spec 131/132)

Rules

bun-patterns

Priority: high

This repo uses Bun as the runtime, package manager, and test runner.

Core Conventions (from upstream AGENTS.md)

  • Use Bun-native APIs: Bun.file(), Bun.serve(), etc.
  • Prefer const over let; use ternaries over reassignment
  • Avoid try/catch, any, else, unnecessary destructuring
  • Rely on type inference; avoid explicit annotations unless needed
  • Use tsgo --noEmit for type checking (not tsc)

Testing

  • Run tests from package directory, not repo root: cd packages/opencode && bun test
  • Root package.json test script intentionally errors — run per-package
  • No mocks — test actual implementation against real behavior
  • Test timeout: --timeout 30000 (30 seconds)
  • Coverage: bun test --coverage generates LCOV at coverage/lcov.info

Package Management

  • Bun workspace monorepo — bun install installs all packages
  • Use bun add <pkg> to add dependencies (not npm/pnpm)
  • bun.lock is the lockfile — commit it

Commands

bun run dev                   # From packages/opencode/

cd packages/opencode && bun test --timeout 30000
cd packages/opencode && bun test --coverage

bun turbo typecheck           # All packages
cd packages/opencode && bunx tsgo --noEmit  # Single package

bunx prettier --check .       # Check
bunx prettier --write .       # Fix

no-any-types

Priority: high

Never use any in TypeScript. Use specific types or unknown with type guards. Prefer type inference over explicit annotations unless ambiguity would arise.

security-no-secrets

Priority: critical

  • NEVER output API keys or secrets
  • NEVER read or output .env file contents
  • Reference secrets by env var name only (e.g., process.env.AXIOM_TOKEN)
  • Use .env.example for documentation
  • Fly.io secrets are set via fly secrets set — never committed

server-architecture

Priority: high

This fork adds a production HTTP server that Pistachiorama's sandbox uses for tool execution.

Key Entry Points

File Purpose
packages/opencode/src/server/server.ts Hono app, CORS, auth, request logging
packages/opencode/src/server/routes/tool-call.ts POST /session/:id/tool/call — direct tool execution
packages/opencode/src/server/routes/session.ts Session CRUD, chat, abort
packages/opencode/src/util/log.ts Custom logger (writes to stderr/file)
packages/opencode/src/util/axiom.ts Axiom telemetry singleton (graceful no-op without AXIOM_TOKEN)

Deployment

  • Runtime: Docker (multi-stage Bun build → Alpine)
  • Platform: Fly.io app pistachiorama-opencode, region sjc, performance-2x VM
  • Port: 8080 (opencode serve --port 8080 --hostname 0.0.0.0)
  • Registry: registry.fly.io/pistachiorama-opencode
  • Auto-stop/start: Enabled — min 1 machine running (avoids cold starts)

CI/CD

  • Docker build+push: On v* tag push via .github/workflows/build-push.yml
  • Tests: .github/workflows/test.yml on PR/push to dev
  • Type check: .github/workflows/typecheck.yml on PR/push to dev
  • Lint: .github/workflows/ci.yml on PR/push to dev (also has ci-pass aggregation job)

Connection Context

The Pistachiorama Rust Durable Object connects server-to-server via fetch() — no browser in the loop. CORS is therefore irrelevant for the sandbox→OpenCode connection. The existing CORS config (localhost + opencode.ai domains) is correct and intentional.

Git Workflow

  • Default branch: dev
  • All PRs target dev
  • Never commit directly to dev
  • Create worktrees for feature branches

ubicloud-runners

Priority: high

Use Ubicloud runners for GitHub Actions, never ubuntu-latest for new workflows.

Default: ubicloud-standard-2 for most jobs. Allowed variants:

  • ubicloud-standard-{2,4,8} — Standard x86
  • ubicloud-standard-{4,8}-arm — ARM64 for cost savings
jobs:
  example:
    runs-on: ubicloud-standard-2 # NOT ubuntu-latest

Note: No Windows or macOS Ubicloud runners — remove upstream Windows/macOS jobs when migrating workflows.