jfl 0.0.0

package/template/.claude/skills/fly-deploy/SKILL.md

@@ -0,0 +1,676 @@
+---
+name: fly-deploy
+description: Complete Fly.io deployment management - deploy, scale, logs, secrets, database, and more
+---
+
+# Fly Deployment Manager
+
+Comprehensive Fly.io deployment management through conversation.
+
+## Core Principle
+
+**Deployments should be simple and observable.**
+
+Guide users through Fly.io operations with clear feedback, helpful context, and actionable next steps. Abstract away complexity while maintaining full control.
+
+## Usage
+
+```
+/fly-deploy                      # Show deployment status
+/fly-deploy status               # Detailed app and database status
+/fly-deploy deploy               # Deploy the app
+/fly-deploy logs                 # Stream recent logs
+/fly-deploy secrets              # Manage environment secrets
+/fly-deploy scale                # Scale machines and resources
+/fly-deploy db                   # Database management
+/fly-deploy ssh                  # SSH into a machine
+/fly-deploy health               # Check health status
+/fly-deploy restart              # Restart all machines
+/fly-deploy destroy              # Destroy app (with confirmation)
+```
+
+## Commands
+
+### /fly-deploy (default: status)
+
+Shows current deployment status:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JFL PLATFORM - FLY.IO STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+App: jfl-platform
+Region: sjc (San Jose)
+URL: https://jfl-platform.fly.dev
+
+MACHINES
+  ✓ 78d40e1a - running (sjc)
+  ✓ 90e3f7a4 - running (sjc)
+
+DATABASE
+  ✓ jfl-platform-db - running
+  Postgres 15
+  Primary: sjc
+
+HEALTH
+  ✓ All checks passing
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+QUICK ACTIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/fly-deploy deploy    Deploy latest changes
+/fly-deploy logs      View recent logs
+/fly-deploy ssh       SSH into machine
+```
+
+**Implementation:**
+```bash
+flyctl status --json
+flyctl info --json
+flyctl machines list --json
+```
+
+### /fly-deploy deploy
+
+Deploys the application:
+
+**Steps:**
+1. Check if there are uncommitted changes (warn if so)
+2. Show what will be deployed (git commit hash/message)
+3. Run deployment
+4. Stream build/deploy logs
+5. Show final status with URL
+6. Suggest next action (view logs, test URL, etc.)
+
+**Implementation:**
+```bash
+# Check for uncommitted changes
+git status --porcelain
+
+# Get current commit
+git log -1 --oneline
+
+# Deploy
+flyctl deploy
+
+# Check health after deploy
+flyctl status --json
+```
+
+**Example output:**
+```
+Deploying jfl-platform...
+
+Commit: a4a4dfd "auto: session save"
+Branch: main
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Building...
+✓ Docker build complete (2m 15s)
+
+Deploying...
+✓ Machines updated (45s)
+
+Health checks...
+✓ All checks passing
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+DEPLOYED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+https://jfl-platform.fly.dev
+
+Want me to:
+- Open the URL in your browser?
+- Stream logs?
+- Check health?
+```
+
+### /fly-deploy logs [--follow] [--machine=ID]
+
+Shows recent application logs:
+
+**Options:**
+- `--follow` / `-f` - Stream logs in real-time
+- `--machine=ID` - Logs from specific machine
+- `--lines=N` - Number of recent lines (default: 100)
+
+**Implementation:**
+```bash
+# Recent logs
+flyctl logs --lines 100
+
+# Follow logs
+flyctl logs --follow
+
+# Specific machine
+flyctl logs --machine 78d40e1a
+```
+
+**Example output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LOGS - jfl-platform
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+2026-01-19T18:45:23Z [info] ✓ Ready in 1204ms
+2026-01-19T18:45:45Z [info] GET /api/auth/session 200 in 45ms
+2026-01-19T18:46:12Z [info] POST /api/projects 201 in 123ms
+2026-01-19T18:46:15Z [error] Database connection timeout
+
+Last 4 lines. Use /fly-deploy logs --follow to stream.
+```
+
+### /fly-deploy secrets
+
+Manage environment secrets:
+
+**Subcommands:**
+- `list` - Show all secret names (not values)
+- `set <KEY>=<VALUE>` - Set/update a secret
+- `unset <KEY>` - Remove a secret
+- `sync` - Sync from local .env file
+
+**Implementation:**
+```bash
+# List secrets
+flyctl secrets list
+
+# Set secret
+flyctl secrets set KEY="value"
+
+# Unset secret
+flyctl secrets unset KEY
+
+# Bulk set from .env (with confirmation)
+flyctl secrets import < .env
+```
+
+**Example output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SECRETS - jfl-platform
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+AUTH_SECRET                     Set 2d ago
+DATABASE_URL                    Set 5d ago (from Fly Postgres)
+GITHUB_CLIENT_ID                Set 5d ago
+GITHUB_CLIENT_SECRET            Set 5d ago
+NODE_ENV                        Set 5d ago
+
+5 secrets total
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ACTIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/fly-deploy secrets set KEY=value    Add/update secret
+/fly-deploy secrets sync             Sync from .env
+```
+
+**For sync command, confirm with user:**
+```
+This will sync all secrets from your local .env file:
+
+Will set/update:
+  - AUTH_SECRET
+  - GITHUB_CLIENT_ID
+  - GITHUB_CLIENT_SECRET
+  - STRIPE_SECRET_KEY
+
+Continue? (yes/no)
+```
+
+### /fly-deploy scale
+
+Scale machines and resources:
+
+**Options:**
+- `machines <count>` - Scale to N machines
+- `memory <size>` - Change memory (256mb, 512mb, 1gb, 2gb)
+- `cpu <count>` - Change CPU count (1, 2, 4, 8)
+- `regions <list>` - Add/remove regions
+
+**Implementation:**
+```bash
+# Scale machines
+flyctl scale count 3
+
+# Scale memory
+flyctl scale memory 1gb
+
+# Scale CPU
+flyctl scale cpu 2
+
+# Scale to regions
+flyctl regions add lax iad
+```
+
+**Example output:**
+```
+Current scale:
+  Machines: 2
+  Memory: 256mb
+  CPU: 1 shared
+  Regions: sjc
+
+What would you like to change?
+1. Scale to 3 machines (faster, costs ~$15/mo more)
+2. Increase memory to 512mb (better performance)
+3. Add regions (lax, iad - lower latency)
+4. Custom configuration
+```
+
+### /fly-deploy db
+
+Database management:
+
+**Subcommands:**
+- `status` - Database status and connection info
+- `connect` - Open psql connection
+- `migrate` - Run Prisma migrations
+- `backup` - Create manual backup
+- `restore <snapshot>` - Restore from backup
+
+**Implementation:**
+```bash
+# Database status
+flyctl postgres db show jfl-platform-db
+
+# Connect via psql
+flyctl postgres connect -a jfl-platform-db
+
+# List backups
+flyctl volumes list -a jfl-platform-db
+```
+
+**For migrations, use the app context:**
+```bash
+# SSH into app machine and run migrations
+flyctl ssh console -a jfl-platform -C "npx prisma migrate deploy"
+```
+
+**Example output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+DATABASE - jfl-platform-db
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Type: Postgres 15
+Region: sjc (primary)
+Storage: 10GB (2.3GB used)
+
+CONNECTION
+  Internal: jfl-platform-db.flycast
+  Port: 5432
+
+BACKUPS
+  Last backup: 2h ago (automatic)
+  Retention: 7 days
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ACTIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/fly-deploy db connect     Open psql console
+/fly-deploy db migrate     Run Prisma migrations
+```
+
+### /fly-deploy ssh [machine-id]
+
+SSH into a machine:
+
+**Options:**
+- No args - Pick from list of running machines
+- `machine-id` - Connect to specific machine
+
+**Implementation:**
+```bash
+# Interactive select
+flyctl ssh console
+
+# Specific machine
+flyctl ssh console --machine 78d40e1a
+
+# Run command
+flyctl ssh console -C "ls -la"
+```
+
+**Example:**
+```
+Available machines:
+1. 78d40e1a (sjc) - primary
+2. 90e3f7a4 (sjc) - secondary
+
+Which machine? (1-2, or 'all' to run command on all)
+
+> 1
+
+Connecting to 78d40e1a...
+
+You're now in the machine. Type 'exit' to disconnect.
+
+Common commands:
+  ls /app              # App directory
+  cat /app/package.json
+  ps aux               # Running processes
+  df -h                # Disk usage
+```
+
+### /fly-deploy health
+
+Check application health:
+
+**Checks:**
+- HTTP health endpoint
+- All machines responsive
+- Database connectivity
+- Recent errors in logs
+
+**Implementation:**
+```bash
+# Machine status
+flyctl status --json
+
+# Check health endpoint
+curl https://jfl-platform.fly.dev/api/health
+
+# Recent errors
+flyctl logs --lines 100 | grep -i error
+```
+
+**Example output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+HEALTH CHECK - jfl-platform
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ HTTP health endpoint    200 OK (45ms)
+✓ All machines running    2/2 healthy
+✓ Database connected      Latency 12ms
+⚠ Recent errors          3 errors in last hour
+
+Recent issues:
+  - 3x "Database connection timeout" at /api/projects
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Want me to:
+- Show full error logs?
+- Check database connection pool settings?
+```
+
+### /fly-deploy restart
+
+Restart all machines:
+
+**Behavior:**
+1. Show current machine status
+2. Confirm restart action
+3. Rolling restart (one at a time for zero downtime)
+4. Show new machine status
+
+**Implementation:**
+```bash
+# Rolling restart
+flyctl machines restart --force
+
+# Or restart specific machine
+flyctl machines restart 78d40e1a
+```
+
+**Example:**
+```
+This will restart all machines in a rolling fashion.
+
+Current uptime: 3d 14h 22m
+
+Continue? (yes/no)
+
+> yes
+
+Restarting machines...
+  ✓ 78d40e1a restarted (15s)
+  ✓ 90e3f7a4 restarted (12s)
+
+All machines restarted. Health checks passing.
+```
+
+### /fly-deploy destroy
+
+Destroy the application and database:
+
+**DANGER ZONE**
+
+**Behavior:**
+1. Explain what will be destroyed
+2. Require explicit confirmation with app name
+3. Optionally backup database first
+4. Destroy resources
+5. Update local files (remove fly.toml reference)
+
+**Implementation:**
+```bash
+# List resources
+flyctl apps list
+flyctl postgres list
+
+# Destroy app (requires confirmation)
+flyctl apps destroy jfl-platform
+
+# Destroy database (requires confirmation)
+flyctl postgres destroy jfl-platform-db
+```
+
+**Example:**
+```
+⚠️  DANGER ZONE
+
+This will permanently destroy:
+  - App: jfl-platform (2 machines)
+  - Database: jfl-platform-db (Postgres 15, 10GB)
+  - All data (Users, Projects, Deployments, etc.)
+
+This cannot be undone.
+
+Create a database backup first? (yes/no)
+
+> yes
+
+Creating backup... ✓
+
+To confirm, type the app name: jfl-platform
+
+> jfl-platform
+
+Destroying resources...
+  ✓ App destroyed
+  ✓ Database destroyed
+
+Deployment removed from Fly.io.
+```
+
+## Error Handling
+
+### Not Authenticated
+
+If `flyctl auth token` fails:
+
+```
+You're not authenticated with Fly.io.
+
+Run this to login:
+  flyctl auth login
+
+This will open your browser to authenticate.
+```
+
+### App Not Found
+
+If app doesn't exist on Fly:
+
+```
+No Fly.io app found.
+
+Options:
+1. Deploy new app: /fly-deploy init
+2. Link existing app: flyctl config show [app-name]
+```
+
+### Build Failures
+
+If deployment build fails, parse logs and suggest fixes:
+
+```
+Build failed: Docker error
+
+Error: "npm ERR! missing: typescript@^5.0.0"
+
+Suggested fix:
+  npm install --save-dev typescript@^5.0.0
+
+Want me to:
+- Install the missing dependency?
+- Show full build logs?
+- Cancel deployment?
+```
+
+## Configuration Detection
+
+### Auto-detect from fly.toml
+
+```toml
+app = 'jfl-platform'
+primary_region = 'sjc'
+```
+
+**Read this to:**
+- Get app name
+- Get primary region
+- Get configuration
+
+### Auto-detect Database
+
+```bash
+# Check for attached Postgres
+flyctl postgres list
+flyctl postgres db show -a jfl-platform-db
+```
+
+### Multi-App Detection
+
+If multiple fly.toml files exist (monorepo):
+
+```
+Multiple Fly apps detected:
+
+1. jfl-platform (./platform)
+2. jfl-api (./api)
+3. jfl-worker (./worker)
+
+Which app? (1-3, or 'all')
+```
+
+## Dependencies
+
+- `flyctl` CLI installed and authenticated
+- `fly.toml` in project directory
+- Docker (for local builds)
+- `git` (for commit detection)
+
+## Tips and Best Practices
+
+### Always show context
+
+Don't just execute commands. Show what's happening:
+
+```
+Deploying changes from commit a4a4dfd...
+```
+
+### Suggest next actions
+
+After any operation, guide the user:
+
+```
+Deployed successfully!
+
+Next steps:
+- Test the deployment: https://jfl-platform.fly.dev
+- Watch logs: /fly-deploy logs --follow
+- Check health: /fly-deploy health
+```
+
+### Warn on destructive actions
+
+```
+⚠️  This will restart all machines (brief downtime possible)
+```
+
+### Parse errors helpfully
+
+If something fails, explain what went wrong and how to fix it:
+
+```
+Deployment failed: Health check timeout
+
+The app deployed but isn't responding to health checks.
+
+Common causes:
+1. Database connection issues (check DATABASE_URL secret)
+2. Port mismatch (app listening on wrong port)
+3. Startup errors (check logs)
+
+Want me to:
+- Check the logs?
+- Verify database connection?
+- Rollback to previous version?
+```
+
+### Show costs when scaling
+
+```
+Scaling to 3 machines:
+  Current cost: ~$5/mo
+  New cost: ~$15/mo (+$10/mo)
+
+Continue? (yes/no)
+```
+
+## Integration with Other Skills
+
+### Works with /hud
+
+Add deployment status to HUD:
+
+```
+Deployment: ✓ Production running (2 machines)
+Last deploy: 2h ago
+```
+
+### Works with project specs
+
+Check `product/platform/fly.toml` for configuration.
+
+### Works with git
+
+Detect uncommitted changes before deploy.
+Show commit info in deploy logs.
+
+## Quick Reference
+
+```
+/fly-deploy               # Status dashboard
+/fly-deploy deploy        # Deploy latest changes
+/fly-deploy logs -f       # Stream logs
+/fly-deploy secrets list  # List secrets
+/fly-deploy scale         # Scale resources
+/fly-deploy db status     # Database info
+/fly-deploy ssh           # SSH into machine
+/fly-deploy health        # Health check
+/fly-deploy restart       # Restart machines
+```
+
+---
+
+**Remember:** Keep it conversational. Guide users through operations with clear feedback and helpful suggestions. Make Fly.io deployments feel simple and observable.