@zerodeploy/cli 0.1.0

package/README.md

@@ -0,0 +1,523 @@
+# ZeroDeploy CLI
+
+Command-line interface for deploying static sites to ZeroDeploy.
+
+## Installation
+
+```bash
+# From the monorepo root
+bun install
+
+# Link CLI globally
+cd apps/cli && bun link
+```
+
+After linking, the `zerodeploy` command is available globally.
+
+## Quick Start
+
+```bash
+# 1. Login with GitHub
+zerodeploy login
+
+# 2. Create an organization
+zerodeploy org create "My Company"
+
+# 3. Create a site
+zerodeploy site create my-company "My Website"
+
+# 4. Deploy your site
+zerodeploy deploy my-website --org my-company --dir ./dist
+```
+
+## Commands
+
+### Authentication
+
+#### `zerodeploy login`
+
+Authenticate with GitHub OAuth. Opens browser for authentication and stores JWT token locally.
+
+```bash
+zerodeploy login
+```
+
+Token is stored at `~/.zerodeploy/token`.
+
+#### `zerodeploy logout`
+
+Clear stored authentication token.
+
+```bash
+zerodeploy logout
+```
+
+#### `zerodeploy whoami`
+
+Display current logged-in user information.
+
+```bash
+zerodeploy whoami
+```
+
+Output:
+```
+Logged in as:
+  Username: johndoe
+  User ID:  019b1234-5678-...
+  Admin:    No
+```
+
+### Organizations
+
+#### `zerodeploy org list`
+
+List all organizations you own.
+
+```bash
+zerodeploy org list
+```
+
+Output:
+```
+Organizations:
+- My Company [paid] (id: 019b1234-...)
+- Personal [paid] (id: 019b5678-...)
+```
+
+#### `zerodeploy org create <name>`
+
+Create a new organization. Slug is auto-generated from the name.
+
+```bash
+zerodeploy org create "My Company"
+```
+
+Output:
+```
+Organization created: My Company
+  id: 019b1234-5678-...
+```
+
+### Sites
+
+#### `zerodeploy site list <orgSlug>`
+
+List all sites in an organization. Shows linked GitHub repositories if configured.
+
+```bash
+zerodeploy site list my-company
+```
+
+Output:
+```
+Sites:
+  my-website           My Website -> company/frontend
+  landing-page         Landing Page
+  docs                 Documentation -> company/monorepo
+```
+
+#### `zerodeploy site create <orgSlug> <name> [options]`
+
+Create a new site in an organization. Slug is auto-generated from the name.
+
+**Options:**
+- `--repo <owner/repo>` - Link to a GitHub repository
+
+```bash
+# Create a site
+zerodeploy site create my-company "My Website"
+
+# Create a site linked to a GitHub repo
+zerodeploy site create my-company "Dashboard" --repo company/monorepo
+```
+
+Output:
+```
+Site created: Dashboard
+  ID: 019b1234-5678-...
+  Repo: company/monorepo
+```
+
+#### `zerodeploy site link <orgSlug> <siteSlug> <repo>`
+
+Link an existing site to a GitHub repository. One repository can be linked to multiple sites (monorepo support).
+
+```bash
+zerodeploy site link my-company dashboard company/monorepo
+```
+
+Output:
+```
+Site "Dashboard" linked to company/monorepo
+```
+
+#### `zerodeploy site unlink <orgSlug> <siteSlug>`
+
+Remove the GitHub repository link from a site.
+
+```bash
+zerodeploy site unlink my-company dashboard
+```
+
+Output:
+```
+Site "Dashboard" unlinked from GitHub repository
+```
+
+#### GitHub Repository Linking
+
+Sites can be linked to GitHub repositories to enable:
+- Tracking which repo deploys to which site
+- Future: Automatic PR preview comments
+- Future: GitHub webhook integration
+
+**Monorepo support:** One repository can be linked to multiple sites:
+
+```
+company/monorepo
+├── apps/marketing  → site: marketing
+├── apps/dashboard  → site: dashboard
+└── apps/docs       → site: docs
+```
+
+### Deployment
+
+#### `zerodeploy deploy <siteSlug> [options]`
+
+Deploy a directory to a site. Uploads all files and makes the deployment live.
+
+**Arguments:**
+- `siteSlug` - The site slug to deploy to
+
+**Options:**
+- `--org <orgSlug>` - Organization slug (required)
+- `--dir <directory>` - Directory to deploy (default: auto-detect)
+- `--build` - Run build command before deploying
+- `--no-build` - Skip build step (even if output dir doesn't exist)
+- `--build-command <cmd>` - Override the build command
+- `--install` - Run install command before building
+
+**CI/CD Options:**
+- `--pr <number>` - PR number (for GitHub Actions)
+- `--pr-title <title>` - PR title
+- `--commit <sha>` - Commit SHA
+- `--commit-message <message>` - Commit message
+- `--branch <branch>` - Branch name
+- `--github-output` - Output deployment info in GitHub Actions format
+
+```bash
+# Deploy specific directory
+zerodeploy deploy my-website --org my-company --dir ./dist
+
+# Auto-detect build directory (looks for dist/, build/, out/, public/)
+zerodeploy deploy my-website --org my-company
+
+# Build and deploy (auto-detects framework)
+zerodeploy deploy my-website --org my-company --build
+
+# Install, build, and deploy
+zerodeploy deploy my-website --org my-company --install --build
+
+# Custom build command
+zerodeploy deploy my-website --org my-company --build-command "npm run build:prod"
+```
+
+Output:
+```
+Detected: Vite
+
+Building...
+> npm run build
+
+Deploying: ./dist
+Found 42 files (1.2 MB)
+Created deployment: 019b1234-5678-...
+Uploading files...
+  [100%] 42/42 files
+
+Deployment successful!
+URL:     https://my-website_my-company.zerodeploy.app
+Preview: https://019b1234_my-website_my-company.zerodeploy.app
+```
+
+#### Preview Deployments
+
+Each deployment gets a unique preview URL that remains accessible even after new deployments:
+
+- **Production URL**: `https://site_org.zerodeploy.app` - Always serves the current deployment
+- **Preview URL**: `https://{shortId}_site_org.zerodeploy.app` - Serves a specific deployment
+
+Preview URLs use the first 8 characters of the deployment ID. This is useful for:
+- Reviewing changes before promoting to production
+- Sharing specific versions with stakeholders
+- Rolling back by comparing different deployments
+- PR preview deployments
+
+#### GitHub Actions Integration
+
+ZeroDeploy integrates with GitHub Actions for automated deployments and PR previews.
+
+**Setup:**
+1. Generate a token: Run `zerodeploy login` and copy the token from `~/.zerodeploy/token`
+2. Add the token to your repository secrets as `ZERODEPLOY_TOKEN`
+3. Copy the workflow template to `.github/workflows/deploy.yml`
+
+**Minimal workflow:**
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bun run build
+      - name: Deploy
+        env:
+          ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
+        run: bunx zerodeploy deploy my-site --org my-org
+```
+
+**PR Preview workflow:**
+```yaml
+- name: Deploy PR Preview
+  if: github.event_name == 'pull_request'
+  env:
+    ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
+  run: |
+    zerodeploy deploy my-site \
+      --org my-org \
+      --pr ${{ github.event.pull_request.number }} \
+      --pr-title "${{ github.event.pull_request.title }}" \
+      --commit ${{ github.sha }} \
+      --branch ${{ github.head_ref }} \
+      --github-output
+```
+
+The `--github-output` flag exports deployment info as GitHub Actions outputs:
+- `deployment_id` - The deployment ID
+- `deployment_url` - The production URL
+- `preview_url` - The unique preview URL
+
+See `apps/cli/examples/github-actions/` for full workflow templates including PR comment automation
+
+#### Framework Auto-Detection
+
+The CLI automatically detects your framework from `package.json` and uses the appropriate build command and output directory:
+
+| Framework | Detection | Build Command | Output Dir |
+|-----------|-----------|---------------|------------|
+| Vite | `vite` in deps | `npm run build` | `dist/` |
+| Next.js | `next` in deps | `npm run build` | `out/` |
+| Create React App | `react-scripts` in deps | `npm run build` | `build/` |
+| Vue CLI | `@vue/cli-service` in deps | `npm run build` | `dist/` |
+| Nuxt | `nuxt` in deps | `npm run build` | `dist/` |
+| Astro | `astro` in deps | `npm run build` | `dist/` |
+| SvelteKit | `@sveltejs/kit` in deps | `npm run build` | `build/` |
+| Gatsby | `gatsby` in deps | `npm run build` | `public/` |
+| Remix | `@remix-run/dev` in deps | `npm run build` | `public/build/` |
+| Parcel | `parcel` in deps | `npm run build` | `dist/` |
+
+**Auto-build behavior:**
+- If a framework is detected but the output directory doesn't exist, the CLI automatically runs the build
+- Use `--no-build` to skip the build step
+- Use `--build-command` to override the detected build command
+
+**Auto-detected directories (fallback):**
+If no framework is detected, the CLI looks for common build output directories:
+1. `dist/` (Vite, Rollup)
+2. `build/` (Create React App)
+3. `out/` (Next.js static export)
+4. `public/` (static sites)
+
+**Ignored files:**
+The following are automatically excluded from deployments:
+- `node_modules/`
+- `.git/`
+- `.env`, `.env.*` files
+- Hidden files starting with `.`
+
+#### `zerodeploy deploy list <siteSlug> --org <orgSlug>`
+
+List all deployments for a site.
+
+```bash
+zerodeploy deploy list my-website --org my-company
+```
+
+Output:
+```
+Deployments for my-company/my-website:
+
+  019b1234  ready       12/14/2025, 9:00:00 PM <- current
+  019b1230  ready       12/14/2025, 8:30:00 PM
+  019b1220  ready       12/14/2025, 8:00:00 PM
+```
+
+**Options:**
+- `--org <orgSlug>` - Organization slug (required)
+- `--limit <number>` - Number of deployments to show (default: 10)
+
+#### `zerodeploy deploy rollback <deploymentId>`
+
+Rollback to a previous deployment. Sets the specified deployment as the current live deployment.
+
+```bash
+zerodeploy deploy rollback 019b1230-5678-...
+```
+
+Output:
+```
+Rolled back successfully
+   Deployment: 019b1230-5678-...
+   URL: https://my-website_my-company.zerodeploy.app
+```
+
+### Deploy Tokens
+
+Deploy tokens allow CI/CD systems to authenticate with ZeroDeploy without using your personal JWT.
+
+#### `zerodeploy token create <name> --org <org> --site <site>`
+
+Create a new deploy token for a site.
+
+```bash
+zerodeploy token create "GitHub Actions" --org my-company --site my-website
+```
+
+Output:
+```
+Deploy token created successfully!
+
+Name:  GitHub Actions
+ID:    019b1234-5678-...
+
+Token (save this - it will not be shown again):
+
+  abc123def456...
+
+Usage in GitHub Actions:
+  Add this token as a repository secret named ZERODEPLOY_TOKEN
+```
+
+**Options:**
+- `--org <orgSlug>` - Organization slug (required)
+- `--site <siteSlug>` - Site slug (required)
+
+#### `zerodeploy token list --org <org> --site <site>`
+
+List all deploy tokens for a site.
+
+```bash
+zerodeploy token list --org my-company --site my-website
+```
+
+Output:
+```
+Deploy tokens for my-company/my-website:
+
+  019b1234  GitHub Actions        Created: 12/14/2025  Last used: 12/14/2025
+  019b5678  CircleCI              Created: 12/10/2025  Last used: Never
+```
+
+#### `zerodeploy token delete <tokenId> --org <org> --site <site>`
+
+Delete a deploy token. You can use the full ID or the first 8 characters.
+
+```bash
+zerodeploy token delete 019b1234 --org my-company --site my-website
+```
+
+## Deployment Flow
+
+1. **Create deployment** - API creates a new deployment record with `uploading` status
+2. **Upload files** - CLI scans directory and uploads each file as base64 to R2
+3. **Finalize** - API marks deployment as `ready` and sets it as the current deployment
+4. **Live** - Site is immediately accessible at the deployment URL
+
+## Accessing Deployed Sites
+
+After deployment, sites are accessible at:
+
+**Local development:**
+```
+http://localhost:8787/serve/<orgSlug>/<siteSlug>/
+```
+
+**Production:**
+```
+https://<siteSlug>_<orgSlug>.zerodeploy.app
+```
+
+### SPA Support
+
+ZeroDeploy automatically handles SPA (Single Page Application) routing:
+- Requests without file extensions fall back to `index.html`
+- Enables client-side routing for React, Vue, Angular, etc.
+
+### Caching
+
+Appropriate cache headers are set automatically:
+- **HTML files**: `max-age=0, must-revalidate` (always check for updates)
+- **Hashed assets** (e.g., `main.abc123.js`): `max-age=31536000, immutable` (1 year)
+- **Other assets**: `max-age=3600, stale-while-revalidate=86400` (1 hour)
+
+## Configuration
+
+### Token Storage
+
+Authentication token is stored at `~/.zerodeploy/token`.
+
+For CI/CD, set the `ZERODEPLOY_TOKEN` environment variable instead. The environment variable takes precedence over the file-based token.
+
+### API URL
+
+By default, CLI connects to production (`https://api.zerodeploy.dev`). To use a local development server, set the `ZERODEPLOY_API_URL` environment variable:
+
+```bash
+# Point to local dev server
+export ZERODEPLOY_API_URL=http://localhost:8787
+
+# Or prefix individual commands
+ZERODEPLOY_API_URL=http://localhost:8787 zerodeploy whoami
+```
+
+Make sure your local API is running with `cd apps/api && bun run dev`.
+
+## Development
+
+```bash
+# Run CLI in development
+cd apps/cli
+bun run src/index.ts <command>
+
+# Run tests
+bun test
+
+# Run e2e tests (requires API running)
+bun test test/e2e.test.ts
+```
+
+## Troubleshooting
+
+### "Not logged in"
+
+Run `zerodeploy login` to authenticate.
+
+### "Org not found"
+
+Ensure you're using the correct org slug (lowercase, hyphenated). Use `zerodeploy org list` to see your organizations.
+
+### "Site not found"
+
+Ensure you're using the correct site slug and org slug. Use `zerodeploy site list <orgSlug>` to see sites.
+
+### "No build directory found"
+
+Specify the directory explicitly with `--dir ./path/to/build` or ensure your project has a `dist/`, `build/`, `out/`, or `public/` directory.