feat: refactor client + containers to be testable, and add tests

[ghostwriternr]

Summary

This PR implements a complete 3-layer SDK architecture with a new container runtime implementation and comprehensive testing infrastructure.

Complete Architecture Implementation

3-Layer SDK Architecture

• Client SDK Layer (src/clients/): Domain-specific clients (Command, File, Process, Port, Git, Utility) with direct response interfaces
• Durable Object Layer (src/sandbox.ts): Persistent sandbox instances with request routing and session management
• Container Runtime Layer (container_src/): Complete Bun-based execution environment with services, handlers, and middleware

Container Runtime Implementation

• Service Layer: Business logic with ServiceResult<T> pattern (ProcessService, FileService, GitService, PortService, SessionService)
• Handler Layer: HTTP endpoint implementations with proper validation
• Middleware Pipeline: CORS, logging, validation, and security
• Security Service: Comprehensive input validation, path security, and command sanitization

Comprehensive Testing Strategy

Multi-tier testing approach (Node.js with intelligent mocking due to vitest + Workers + Containers compatibility issues)

• Unit Tests: Client SDK testing with HTTP mocking and error validation
• Container Tests: Service and handler testing with dependency mocking
• Contract Tests: HTTP API and streaming format validation

Testing Approach

• No Docker required - comprehensive Node.js mocking
• ServiceResult<T> pattern testing for container services
• Direct response interface testing for client SDK
• Fresh stream generation for ReadableStream handling

Security & Reliability Improvements

• Port Access Control: Fixed critical vulnerability with proper token validation for unexposed ports
• Preview URL Security: Replaced guessable URLs with cryptographic tokens
• Input Validation: Comprehensive SecurityService with Zod schema validation
• Path Security: Sandbox traversal prevention and command sanitization
• Resource Management: Automatic cleanup and lifecycle management

Internal Architecture Improvements

• Refactored from monolithic client to domain-specific client architecture (no user-facing API changes)
• Implemented ServiceResult<T> pattern for all container business logic
• Complete container runtime rewrite with structured service layer
• Removed integration and E2E tests in favor of comprehensive mocked testing

Developer Experience & Documentation

Complete Contributor Documentation

• CLAUDE.md: AI agent instructions with architectural patterns and development commands
• docs/ARCHITECTURE.md: Detailed 3-layer system design and implementation patterns
• docs/DEVELOPER_GUIDE.md: Step-by-step contribution workflows and feature development
• docs/TESTING.md: Comprehensive testing strategy with service patterns
• CONTRIBUTING.md: Contribution guidelines and code standards

CI/CD & Development

• Streamlined GitHub Actions with environment-appropriate test coverage
• Enhanced development workflow with watch mode and coverage reporting
• Build optimization and quality checks integration

[changeset-bot]

🦋 Changeset detected

Latest commit: ae7dda6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/sandbox	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[threepointone]

jesus take the wheel