@playcademy/sandbox 0.1.0-beta.11 → 0.1.0-beta.13

package/README.md

@@ -1,15 +1,344 @@
-# sandbox
+# @playcademy/sandbox
 
-To install dependencies:
+**Local development server for isolated Playcademy game development**
+
+The sandbox provides a complete, isolated development environment for building games on the Playcademy platform. It runs entirely locally with a PostgreSQL database (PGLite) that can be configured for either persistent storage or in-memory operation, and serves all Playcademy APIs without requiring external services or authentication.
+
+## Overview
+
+The sandbox is designed to solve the key challenge of game development: providing a local environment that accurately mirrors the production Playcademy platform while remaining completely isolated and easy to set up.
+
+### Key Benefits
+
+- **Isolated Environment**: Completely local execution with no external dependencies
+- **Zero Configuration**: Automatic database setup and seeding
+- **Full API Compatibility**: All Playcademy APIs available locally
+- **Fast Development Cycle**: Quick startup with configurable database storage (persistent or in-memory)
+- **Production Parity**: Same business logic as production platform
+- **Game-Specific Seeding**: Automatically seeds your game's data for development
+
+### Use Cases
+
+- **Game Development**: Local testing of Playcademy API integration
+- **Template Development**: Building new game templates
+- **SDK Testing**: Validating Playcademy SDK functionality
+- **API Exploration**: Understanding available platform features
+- **Rapid Prototyping**: Quick game concept validation
+
+## Architecture
+
+The sandbox is built on a lightweight stack optimized for development speed:
+
+- **Hono**: Fast, lightweight web framework
+- **PGLite**: PostgreSQL database (WebAssembly) - configurable for persistent or in-memory storage
+- **Drizzle ORM**: Type-safe database operations
+- **@playcademy/api-core**: Production API handlers
+- **@playcademy/data**: Database schema and types
+
+### Directory Structure
+
+```
+packages/sandbox/src/
+├── cli.ts              # Command-line interface
+├── server.ts           # HTTP server setup
+├── constants.ts        # Configuration and defaults
+├── types.ts            # TypeScript definitions
+├── database/           # Database setup and seeding
+│   ├── index.ts        # Database initialization
+│   ├── path-manager.ts # Database file management
+│   └── seed.ts         # Demo data and game seeding
+├── lib/                # Core functionality
+│   └── auth.ts         # Authentication middleware
+├── routes/             # API route handlers
+└── utils/              # Utility functions
+    └── port.ts         # Port availability checking
+```
+
+## Installation & Usage
+
+### Global Installation
+
+```bash
+# Install globally for use anywhere
+bun install -g @playcademy/sandbox
+
+# Start sandbox in any project
+playcademy-sandbox
+```
+
+### Local Installation
+
+```bash
+# Install in your project
+bun add -D @playcademy/sandbox
+
+# Use via package.json script
+{
+  "scripts": {
+    "sandbox": "playcademy-sandbox"
+  }
+}
+```
+
+### Command Line Interface
 
 ```bash
-bun install
+# Basic usage
+playcademy-sandbox
+
+# Custom port
+playcademy-sandbox --port 3000
+
+# With project information (enables game-specific seeding)
+playcademy-sandbox --project-name "My Game" --project-slug "my-game"
+
+# Verbose logging
+playcademy-sandbox --verbose
 ```
 
-To run:
+### CLI Options
+
+| Option           | Description                 | Default |
+| ---------------- | --------------------------- | ------- |
+| `--port, -p`     | Server port                 | `4321`  |
+| `--verbose, -v`  | Enable verbose logging      | `true`  |
+| `--project-name` | Display name for your game  | -       |
+| `--project-slug` | URL-safe slug for your game | -       |
+
+## Server Endpoints
+
+Once running, the sandbox provides several key endpoints:
+
+### Health & Status
+
+- **GET `/health`** - Server health check and status information
+
+### API Base
+
+- **GET `/api`** - API manifest and available endpoints
+
+### Playcademy APIs
+
+All production Playcademy APIs are available locally:
+
+- **`/api/users`** - User management and profiles
+- **`/api/games`** - Game sessions, state, and uploads
+- **`/api/inventory`** - User inventory management
+- **`/api/items`** - Item definitions and operations
+- **`/api/shop`** - In-game shop functionality
+- **`/api/shop-listings`** - Marketplace listings
+- **`/api/currencies`** - Virtual currency systems
+- **`/api/levels`** - User progression and XP
+- **`/api/maps`** - Game world data and elements
+- **`/api/dev`** - Developer tools and utilities
+
+### Example URLs
+
+```
+# Server status
+http://localhost:4321/health
+
+# API manifest
+http://localhost:4321/api
+
+# User profile
+http://localhost:4321/api/users/me
+
+# Game sessions
+http://localhost:4321/api/games/{gameId}/sessions
+```
+
+## Database Management
+
+### Automatic Setup
+
+The sandbox automatically:
+
+1. **Creates Database Schema** - Uses programmatic schema creation from TypeScript definitions
+2. **Seeds Demo Data** - Provides realistic test data for development
+3. **Seeds Game Data** - Creates your specific game when project options are provided
+
+### Demo Data Includes
+
+- **Users**: Test user accounts with different roles
+- **Games**: Sample games for testing
+- **Items**: Various item types and categories
+- **Currencies**: Virtual currency systems
+- **Maps**: Basic world/map structures
+
+### Database Storage Options
+
+The sandbox supports two database storage modes:
+
+- **Persistent Storage** (default): Database file stored in project's `node_modules` directory
+- **In-Memory**: No persistent storage, fastest startup, data lost on restart
 
 ```bash
-bun run index.ts
+# Default persistent storage location:
+# ./node_modules/@playcademy/vite-plugin/node_modules/.playcademy/sandbox.db
+
+# In-memory mode can be enabled via:
+# - memoryOnly: true in programmatic usage
+# - setupDatabase(':memory:') for custom path
 ```
 
-This project was created using `bun init` in bun v1.2.10. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+## Authentication
+
+The sandbox includes simplified authentication for development:
+
+- **No Real Authentication Required**: Automatically provides a test user context
+- **JWT Token Support**: Compatible with real Playcademy authentication flows
+- **Developer Keys**: Supports development API keys for testing
+
+## Integration with Game Development
+
+### Basic Integration
+
+```javascript
+// Your game code
+const API_BASE = 'http://localhost:4321/api'
+
+// Fetch user inventory
+const inventory = await fetch(`${API_BASE}/inventory`)
+const items = await inventory.json()
+
+// Add item to user inventory
+await fetch(`${API_BASE}/inventory/add`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ itemId: 'sword-001', quantity: 1 }),
+})
+```
+
+### With Playcademy SDK
+
+```javascript
+import { PlaycademySDK } from '@playcademy/sdk'
+
+// Initialize SDK with sandbox
+const sdk = new PlaycademySDK({
+    apiUrl: 'http://localhost:4321/api',
+})
+
+// Use SDK methods normally
+const user = await sdk.users.getProfile()
+const inventory = await sdk.inventory.getItems()
+```
+
+## Development
+
+### Building the Sandbox
+
+```bash
+# Build for distribution
+bun run build
+
+# Development with auto-reload
+bun run dev
+
+# Start without building
+bun run start
+```
+
+### Custom Build Process
+
+The build process includes:
+
+1. **TypeScript Compilation**: Builds CLI and server entry points
+2. **Type Generation**: Creates `.d.ts` files for type safety
+3. **PGlite Binary Bundling**: Includes WebAssembly binaries for distribution
+
+### Project-Specific Development
+
+When developing a specific game, provide project information for enhanced development experience:
+
+```bash
+playcademy-sandbox \
+  --project-name "Equation Arena" \
+  --project-slug "equation-arena"
+```
+
+This enables:
+
+- **Automatic Game Registration**: Your game appears in the games API
+- **Custom Seeding**: Game-specific items and configuration
+
+## Advanced Configuration
+
+### Programmatic Usage
+
+```typescript
+import { startServer } from '@playcademy/sandbox'
+
+const server = await startServer({
+    port: 4321,
+    verbose: true,
+    memoryOnly: true,
+    seed: true,
+    project: {
+        slug: 'my-game',
+        displayName: 'My Game',
+        version: '1.0.0',
+    },
+})
+```
+
+### Custom Database Configuration
+
+```typescript
+// Use in-memory database (no persistence)
+const server = await startServer({
+    port: 4321,
+    memoryOnly: true, // Use in-memory database
+})
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Port Already in Use**
+
+```bash
+# Sandbox automatically finds available port
+playcademy-sandbox --port 4321
+# Will use 4322, 4323, etc. if 4321 is taken
+```
+
+**API Not Responding**
+
+- Check that server started successfully (look for green startup messages)
+- Verify the port isn't blocked by firewall
+- Try accessing `/health` endpoint first
+
+### Debug Mode
+
+```bash
+# Enable verbose logging
+playcademy-sandbox --verbose
+
+# Check server health
+curl http://localhost:4321/health
+```
+
+## Contributing
+
+The sandbox is a crucial development tool for the Playcademy ecosystem. When contributing:
+
+1. **Maintain API Parity**: Ensure sandbox APIs match production behavior
+2. **Keep It Fast**: Optimize for quick development iteration
+3. **Update Documentation**: Keep examples current with API changes
+4. **Test Thoroughly**: Validate with real game development scenarios
+
+For general contribution guidelines, see the [monorepo CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+## Related Packages
+
+- [`@playcademy/api-core`](../api-core/): API handlers used by sandbox
+- [`@playcademy/data`](../data/): Database schema and types
+- [`@playcademy/sdk`](../sdk/): JavaScript SDK for game development
+- **Game Templates**: See `/templates` for example integrations
+
+## Distribution
+
+The sandbox is distributed as a standalone npm package for use in game development. It can be installed globally or as a development dependency in game projects.