playcademy 0.1.0

package/README.md

@@ -0,0 +1,293 @@
+# playcademy
+
+The official command-line interface for Playcademy - deploy and share your educational games with ease.
+
+## Installation
+
+```bash
+bun add -g playcademy
+```
+
+Or run directly with bunx:
+
+```bash
+bunx playcademy <command>
+```
+
+## Quick Start
+
+```bash
+# Authenticate with Playcademy
+playcademy login
+
+# Initialize configuration
+playcademy init
+
+# Deploy your game
+playcademy deploy
+```
+
+## Commands
+
+### Authentication
+
+#### `login`
+
+Authenticate with your Playcademy account via SSO or email/password.
+
+```bash
+playcademy login
+playcademy login --sso              # Browser-based SSO
+playcademy login --profile work     # Save to named profile
+```
+
+#### `logout`
+
+Remove stored credentials.
+
+```bash
+playcademy logout
+playcademy logout --profile work
+```
+
+#### `me`
+
+Display current user information.
+
+```bash
+playcademy me
+```
+
+#### `profiles`
+
+Manage authentication profiles.
+
+```bash
+playcademy profiles list    # List all profiles
+playcademy profiles remove <name>
+playcademy profiles reset   # Remove all profiles
+```
+
+### Developer Access
+
+#### `dev apply`
+
+Apply for developer status to create and deploy games.
+
+```bash
+playcademy dev apply
+```
+
+#### `dev status`
+
+Check your current developer status.
+
+```bash
+playcademy dev status
+```
+
+### Games
+
+#### `games list`
+
+List all your games.
+
+```bash
+playcademy games list
+```
+
+#### `games delete`
+
+Delete a game.
+
+```bash
+playcademy games delete <slug>
+playcademy games delete              # Interactive selection
+playcademy games delete my-game -f   # Skip confirmation
+```
+
+### Deployment
+
+#### `init`
+
+Initialize a configuration file in your project.
+
+```bash
+playcademy init
+```
+
+Creates `playcademy.config.js` (or `.json`) with your game settings.
+
+#### `deploy`
+
+Deploy your game to Playcademy.
+
+```bash
+playcademy deploy
+playcademy deploy --env staging        # Deploy to staging
+playcademy deploy --backend            # Include API routes
+playcademy deploy --no-backend         # Skip API routes
+playcademy deploy --dry-run            # Validate without deploying
+playcademy deploy --debug              # Show debug info
+```
+
+**Options:**
+
+- `-c, --config <path>` - Configuration file (`playcademy.config.js` or `.json`)
+- `-n, --name <name>` - Display name
+- `-d, --description <desc>` - Description
+- `-e, --emoji <emoji>` - Emoji icon
+- `-b, --build <path>` - Path to frontend zip file
+- `-u, --external-url <url>` - External URL for external games
+- `--env <env>` - Environment (`production` or `staging`)
+- `--backend` - Deploy API routes
+- `--no-backend` - Skip API routes
+- `--dry-run` - Validate only
+- `--verbose` - Show detailed output
+- `--debug` - Show debug information
+
+**Configuration:**
+
+Create `playcademy.config.js`:
+
+```js
+export default {
+    name: 'My Awesome Game',
+    description: 'A fun puzzle game',
+    emoji: '🎮',
+    buildPath: './dist/game.zip',
+}
+```
+
+Or `playcademy.config.json`:
+
+```json
+{
+    "name": "My Awesome Game",
+    "description": "A fun puzzle game",
+    "emoji": "🎮",
+    "buildPath": "./dist/game.zip"
+}
+```
+
+**Backend API Routes:**
+
+Add custom API routes by creating an `api/` directory:
+
+```
+my-game/
+├── playcademy.config.js
+├── dist/
+│   └── game.zip
+└── api/
+    └── hello.ts        # GET /api/hello
+```
+
+Backend routes are:
+
+- ✅ Automatically deployed for hosted games
+- ⊘ Opt-in for external games (use `--backend` flag)
+
+## Authentication
+
+Credentials are stored in `~/.playcademy/auth.json`:
+
+```json
+{
+    "default": {
+        "token": "YOUR_TOKEN",
+        "userId": "user_123",
+        "email": "user@example.com",
+        "expiresAt": "2024-12-31T23:59:59Z"
+    },
+    "profiles": {
+        "work": {
+            "token": "WORK_TOKEN",
+            "userId": "user_123",
+            "email": "user@example.com",
+            "expiresAt": "2024-12-31T23:59:59Z"
+        }
+    }
+}
+```
+
+### TimeBack Integration
+
+#### `timeback setup`
+
+Set up TimeBack LTI integration for your game.
+
+```bash
+playcademy timeback setup
+playcademy timeback setup --dry-run
+```
+
+#### `timeback verify`
+
+Verify TimeBack resources are correctly configured.
+
+```bash
+playcademy timeback verify
+```
+
+#### `timeback update`
+
+Update TimeBack integration configuration.
+
+```bash
+playcademy timeback update
+```
+
+#### `timeback cleanup`
+
+Remove TimeBack integration (keeps game metadata).
+
+```bash
+playcademy timeback cleanup
+```
+
+## Environment Variables
+
+- `PLAYCADEMY_ENV` - Environment: `staging` or `production` (default: `production`)
+- `PLAYCADEMY_BASE_URL` - Override API endpoint (default: based on `PLAYCADEMY_ENV`)
+- `PLAYCADEMY_PROFILE` - Authentication profile to use (default: `default`)
+
+**Example:**
+
+```bash
+# Deploy to staging
+PLAYCADEMY_ENV=staging playcademy deploy
+
+# Use specific profile
+PLAYCADEMY_PROFILE=work playcademy deploy
+
+# Custom environment
+PLAYCADEMY_BASE_URL=http://localhost:5174 playcademy deploy
+```
+
+## Configuration Files
+
+The CLI supports multiple configuration formats:
+
+- `playcademy.config.js` (ES modules)
+- `playcademy.config.json` (JSON)
+- `playcademy.config.mjs` (ES modules)
+
+Priority: CLI flags > config file > interactive prompts
+
+## Architecture
+
+Built with:
+
+- **Commander.js** - Command parsing
+- **@inquirer/prompts** - Interactive prompts
+- **Colorette** - Terminal styling
+- **esbuild** - Bundling (for encoding compatibility)
+
+## Contributing
+
+See the main [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT