hackerrun 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:uncloud.run)",
+      "WebFetch(domain:www.ubicloud.com)",
+      "Bash(grep:*)",
+      "Bash(ssh root@46.4.244.246 \"jool -i hackerrun pool4 add 46.4.244.246 0-65535 --icmp\")",
+      "Bash(ssh root@46.4.244.246 \"jool -i hackerrun stats display\")",
+      "Bash(ssh root@46.4.244.246 \"ip -6 route show | grep 64:ff9b\")",
+      "Bash(ssh root@46.4.244.246 \"ip6tables -L -v -n\")",
+      "Bash(ssh:*)",
+      "Bash(find:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run build:*)",
+      "Bash(node dist/index.js:*)",
+      "Bash(npx prisma migrate:*)",
+      "Bash(ls:*)",
+      "Bash(npm ls:*)",
+      "Bash(npx prisma generate:*)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,9 @@
+# Ubicloud API Configuration
+UBICLOUD_API_TOKEN=your_api_token_here
+UBICLOUD_PROJECT_ID=your_project_id_here
+
+# Optional: Default values
+# Available locations: eu-central-h1, eu-north-h1, us-east-a2
+UBICLOUD_DEFAULT_LOCATION=us-east-a2
+UBICLOUD_DEFAULT_SIZE=standard-2
+UBICLOUD_DEFAULT_IMAGE=ubuntu-noble

package/CLAUDE.md

@@ -0,0 +1,532 @@
+# Hackerrun CLI
+
+CLI tool for deploying apps using Ubicloud VMs + Uncloud container orchestration.
+
+## Related Projects
+
+- `../hackerrun-platform` - Platform API (Next.js)
+- `../uncloud` - Container orchestration (not our code)
+
+## Domains
+
+| Domain | Purpose |
+|--------|---------|
+| `hackerrun.com` | Platform website, docs, dashboard |
+| `hackerrun.app` | User deployed applications |
+
+## User Experience
+
+```bash
+$ hackerrun login              # One-time GitHub OAuth
+$ cd myapp
+$ hackerrun deploy             # App live at https://laughing-buddha.hackerrun.app
+```
+
+### App Naming
+
+| Identifier | Scope | Example |
+|------------|-------|---------|
+| **App Name** | Per user | `myapp` |
+| **Domain Name** | Global | `laughing-buddha` (Railway-style random) |
+
+### Domain Format
+
+- Single service: `{domain}.hackerrun.app`
+- Multi-service: `{domain}-{service}.hackerrun.app` (flattened for Cloudflare wildcard SSL)
+
+### Config Files
+
+- **`.hackerrun`** - Links folder to app (contains app name)
+- **`hackerrun.yml`** - Production compose with `x-ports` for public exposure
+- **`docker-compose.yml`** - Local dev (ignored by hackerrun)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `hackerrun login` | Auth via GitHub |
+| `hackerrun deploy` | Deploy app |
+| `hackerrun apps` | List apps |
+| `hackerrun logs <app>` | View logs |
+| `hackerrun ssh <app>` | SSH into VM |
+| `hackerrun destroy <app>` | Delete app |
+| `hackerrun link <app>` | Link folder to existing app |
+| `hackerrun unlink` | Remove `.hackerrun` |
+| `hackerrun rename --app <old> <new>` | Rename app |
+| `hackerrun domain --app <app> <new>` | Change domain |
+
+## Architecture: IPv4 Cost Optimization
+
+**Problem:** Ubicloud charges $3/mo per public IPv4.
+
+**Solution:** Single Gateway ($3/mo fixed) handles all traffic:
+
+```
+INBOUND: User → Cloudflare → Tunnel → Gateway (Caddy) → App VMs (IPv6-only)
+OUTBOUND: Container → DNS64 → NAT64 → IPv4 Internet
+```
+
+### Gateway Components
+
+| Component | Purpose |
+|-----------|---------|
+| cloudflared | Tunnel endpoint (no inbound ports exposed) |
+| Caddy | Routes by hostname to App VMs |
+| BIND9 | DNS64 (synthesizes AAAA for IPv4 hosts) |
+| Jool | NAT64 (translates 64:ff9b::/96 to IPv4) |
+| WireGuard | NAT64 tunnel from App VMs |
+
+### Gateway Details
+
+```
+IPv4: 46.4.244.246 | IPv6: 2a01:4f8:2b01:1317:e830::2
+Location: eu-central-h1 | SSH: ssh root@46.4.244.246
+Tunnel: 29a25987-06a5-425e-bbed-b090492a4e71
+```
+
+### x-ports Protocol
+
+Use `/http` (Cloudflare terminates external HTTPS):
+
+```yaml
+services:
+  app:
+    x-ports:
+      - "3000/http"  # Single service
+      - "laughing-buddha-api.hackerrun.app:8080/http"  # Multi-service
+```
+
+## SSH Authentication: Temporary Certificates
+
+Users don't manage SSH keys. Instead, CLI gets short-lived certificates signed by platform CA.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         PLATFORM API                            │
+│                                                                 │
+│  SSH CA Private Key (signs certificates)                        │
+│  Platform SSH Key (for VM creation + admin access)              │
+│                                                                 │
+│  POST /api/apps/:appName/ssh-certificate                        │
+│    → Signs short-lived cert (5 min TTL)                         │
+│    → Returns certificate to CLI                                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                           CLI                                    │
+│                                                                 │
+│  1. Generate ephemeral keypair                                  │
+│  2. Request cert from platform                                  │
+│  3. Load key+cert into temp SSH agent                           │
+│  4. Run uc --connect ssh+cli://root@[vm-ip] <command>           │
+│  5. Cleanup (kill agent, delete temp files)                     │
+└─────────────────────────────────────────────────────────────────┘
+         │                                    │
+         │ IPv6 (direct)                      │ IPv4 (tunnel via gateway)
+         ▼                                    ▼
+┌─────────────────┐                  ┌─────────────────┐
+│    App VM       │                  │    Gateway      │
+│  Trusts CA      │                  │  Trusts CA      │
+│                 │                  │        │        │
+│  TrustedUserCA  │                  │        ▼        │
+│  Keys = ca.pub  │                  │    App VM       │
+└─────────────────┘                  └─────────────────┘
+```
+
+### VM Authentication Setup
+
+When creating app VMs via Ubicloud:
+
+| Key | Location on VM | Purpose |
+|-----|----------------|---------|
+| Platform SSH public key | `/root/.ssh/authorized_keys` | Ubicloud requirement + admin access |
+| CA public key | `/etc/ssh/hackerrun-ca.pub` | User certificate validation |
+
+```bash
+# /etc/ssh/sshd_config.d/hackerrun-ca.conf
+TrustedUserCAKeys /etc/ssh/hackerrun-ca.pub
+```
+
+### IPv6 vs IPv4 Connectivity
+
+CLI detects network and handles automatically (same logic as current `hackerrun ssh`):
+
+```typescript
+// Test IPv6 connectivity (3s timeout)
+let useProxy = false;
+try {
+  execSync(`ssh -o ConnectTimeout=3 root@${vmIpv6} exit`, { timeout: 5000 });
+} catch {
+  useProxy = true;
+}
+
+if (useProxy) {
+  // Tunnel through gateway, then connect
+  ssh -L localPort:[vm-ipv6]:22 root@gateway-ipv4 &
+  uc --connect "ssh+cli://root@localhost:localPort" deploy
+} else {
+  // Direct connection
+  uc --connect "ssh+cli://root@[vm-ipv6]" deploy
+}
+```
+
+### Why `ssh+cli://` (not `ssh://`)
+
+| Connector | SSH Config | ProxyCommand | SSH Agent |
+|-----------|------------|--------------|-----------|
+| `ssh://` | No | No | Yes |
+| `ssh+cli://` | Yes | Yes | Yes |
+
+`ssh+cli://` uses system ssh binary which respects SSH agent where we load our temp cert.
+
+## Deploy Flow (No Local Config)
+
+### Current (Being Replaced)
+
+```
+.hackerrun → app name → sync uncloud config → uc -c <context> deploy
+                              │
+                              └── Local ~/.config/uncloud/config.yaml
+```
+
+### New (Direct Connection)
+
+```
+.hackerrun → app name → platform API → VM IP → uc --connect ssh+cli://root@[vm-ip] deploy
+                              │
+                              └── No local config, platform is source of truth
+```
+
+### Command Execution Flow
+
+```typescript
+async function runUncloudCommand(command: string) {
+  // 1. Read app name from .hackerrun
+  const appName = (await readFile('.hackerrun', 'utf-8')).trim();
+
+  // 2. Get app details from platform API
+  const app = await platformClient.getApp(appName);
+  const vmIpv6 = app.nodes[0].ipv6;
+
+  // 3. Get temp SSH certificate
+  const { keyPath, certPath } = await getTempSSHCertificate(app);
+
+  // 4. Start temp SSH agent, add key+cert
+  const { authSock, agentPid } = await startTempAgent(keyPath);
+
+  // 5. Test IPv6, connect directly or via tunnel
+  // 6. Run: uc --connect "ssh+cli://root@[vm-ip]" <command>
+
+  // 7. Cleanup
+  process.kill(agentPid);
+  await rm(keyPath);
+  await rm(certPath);
+}
+```
+
+### What Gets Removed
+
+| File/Logic | Purpose | Status |
+|------------|---------|--------|
+| `src/lib/uncloud-sync.ts` | Syncs uncloud config locally | **Remove** |
+| `src/lib/ssh.ts` (SSHKeyManager) | Manages user SSH keys | **Remove** |
+| `~/.config/uncloud/` | Local uncloud contexts | **Not needed** |
+| Context switching (`uc -c`) | Selects cluster | **Not needed** |
+
+## Platform DB Schema
+
+```prisma
+model App {
+  id             Int       @id @default(autoincrement())
+  userId         Int       @map("user_id")
+  appName        String    @map("app_name")
+  domainName     String    @unique @map("domain_name")
+  location       String
+  createdAt      DateTime  @default(now()) @map("created_at")
+  lastDeployedAt DateTime? @map("last_deployed_at")
+  user   User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  nodes  AppNode[]
+  routes AppRoute[]
+  @@unique([userId, appName])
+  @@map("apps")
+}
+
+model Gateway {
+  id        Int      @id @default(autoincrement())
+  vmId      String   @unique @map("vm_id")
+  ipv4      String
+  ipv6      String
+  tunnelId  String   @map("tunnel_id")
+  location  String
+  @@map("gateways")
+}
+
+model AppRoute {
+  id          Int    @id @default(autoincrement())
+  appId       Int    @map("app_id")
+  hostname    String @unique
+  backendIpv6 String @map("backend_ipv6")
+  backendPort Int    @default(443)
+  @@map("app_routes")
+}
+
+# New models for SSH auth
+model SSHCertificateAuthority {
+  id                   Int      @id @default(autoincrement())
+  publicKey            String   @map("public_key") @db.Text
+  privateKeyEncrypted  String   @map("private_key_encrypted") @db.Text
+  createdAt            DateTime @default(now()) @map("created_at")
+  @@map("ssh_ca")
+}
+
+model PlatformSSHKey {
+  id                   Int      @id @default(autoincrement())
+  publicKey            String   @map("public_key") @db.Text
+  privateKeyEncrypted  String   @map("private_key_encrypted") @db.Text
+  createdAt            DateTime @default(now()) @map("created_at")
+  @@map("platform_ssh_key")
+}
+```
+
+## App VM Setup (cluster.ts)
+
+1. Create IPv6-only VM with **platform SSH key** (not user key)
+2. Configure CA for user certificates:
+   ```bash
+   echo "$CA_PUBLIC_KEY" > /etc/ssh/hackerrun-ca.pub
+   echo "TrustedUserCAKeys /etc/ssh/hackerrun-ca.pub" > /etc/ssh/sshd_config.d/hackerrun-ca.conf
+   systemctl reload sshd
+   ```
+3. Configure DNS64 via systemd-resolved
+4. Set up WireGuard for NAT64
+5. Run `uc machine init --no-dns`
+
+## Implementation Status
+
+### Completed
+
+- [x] Gateway/AppRoute models, random name generator
+- [x] IPv6-only VM creation, SSH with gateway fallback
+- [x] Deploy with route registration, gateway sync
+- [x] WireGuard/NAT64/Docker IPv6 config
+- [x] Cloudflare Tunnel + wildcard DNS
+- [x] SSH Certificates + Remove Local Config (temp certs, SSH agent, `uc --connect ssh+cli://`, removed uncloud-sync.ts and ssh.ts)
+
+## Docker Container NAT64
+
+Containers need config to reach IPv4 APIs via NAT64:
+
+1. Enable IPv6 in Docker daemon
+2. Recreate `uncloud` network with IPv6
+3. Block IPv4 forwarding (iptables REJECT) so apps fall back to IPv6 quickly
+
+## Gateway Caddyfile
+
+Auto-generated by `gateway-sync.ts`:
+
+```caddyfile
+{
+    http_port 80
+    auto_https off
+}
+
+:80 {
+    @bright_ocean host bright-ocean.hackerrun.app *.bright-ocean.hackerrun.app
+    handle @bright_ocean {
+        reverse_proxy http://[2a01:4f8:2b01:131a:244c::2]:80
+    }
+    handle {
+        respond "App not found" 404
+    }
+}
+```
+
+## Future: Scalability
+
+### Multi-Gateway HA
+- Multiple cloudflared connect to same tunnel
+- App VMs use multiple DNS64/NAT64 gateways
+
+### Scale-to-Zero
+- Gateway detects idle → Platform stops VM → Traffic arrives → Gateway wakes VM
+- Requires Ubicloud Stop/Resume feature
+
+## CI/CD: Integrated Build & Deploy
+
+Railway/Render-style CI/CD without GitHub Actions. User connects their GitHub repo, pushes trigger automatic builds and deploys.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. User pushes to GitHub                                        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  2. GitHub webhook (push event) → hackerrun-platform             │
+│     - Lookup app by repo URL                                     │
+│     - Generate build token (scoped to app, 15 min TTL)          │
+│     - Create ephemeral build VM via Ubicloud API                │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  3. Ephemeral Build VM                                           │
+│     Pre-installed: git, docker, hackerrun CLI, uc CLI           │
+│     Receives: REPO_URL, COMMIT_SHA, BUILD_TOKEN, APP_NAME       │
+│                                                                  │
+│     Build script:                                                │
+│       git clone $REPO_URL /build                                │
+│       cd /build && git checkout $COMMIT_SHA                     │
+│       hackerrun deploy --build-token $BUILD_TOKEN --app $APP    │
+│                                                                  │
+│     hackerrun deploy internally:                                 │
+│       1. Auth via build token (not user's CLI token)            │
+│       2. docker build (on build VM, with cache)                 │
+│       3. SSH to app cluster VM                                   │
+│       4. Transfer image via unregistry (direct, no registry)    │
+│       5. Deploy containers                                       │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  4. Build complete → VM destroyed                                │
+│     - Build logs stored in platform DB                          │
+│     - Status webhook to GitHub (optional)                       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **Reuse `hackerrun deploy`** | Same deploy path for local and CI, no separate build system |
+| **No container registry** | unregistry transfers images directly to cluster |
+| **Ephemeral build VMs** | Clean environment, no multi-tenant security concerns |
+| **Build tokens** | Scoped, short-lived auth for build VM to act on user's behalf |
+
+### CLI Changes
+
+```bash
+# Local deploy (unchanged)
+hackerrun deploy
+  └── Uses ~/.hackerrun/token
+  └── Reads app name from .hackerrun or hackerrun.yaml
+
+# CI/CD deploy (new flags)
+hackerrun deploy --build-token $TOKEN --app myapp
+  └── Uses provided token (no file lookup)
+  └── Uses provided app name (no file lookup)
+  └── Non-interactive, suitable for automation
+```
+
+### Docker Build Caching
+
+Ephemeral VMs need external cache storage for fast rebuilds.
+
+**Option 1: BuildKit with S3/R2 Remote Cache (Recommended)**
+
+```bash
+docker buildx build \
+  --cache-from=type=s3,bucket=hackerrun-cache,region=auto,name=${userId}/${app} \
+  --cache-to=type=s3,bucket=hackerrun-cache,region=auto,name=${userId}/${app},mode=max \
+  -t image:tag .
+```
+
+- Cache persists in Cloudflare R2 (no egress fees)
+- Per-user/app cache isolation
+- First build slow, subsequent builds fast
+
+**Option 2: Pre-baked Build VM Image**
+
+- Custom Ubicloud boot image with common base images pre-pulled
+- `node:20`, `python:3.12`, `golang:1.22`, etc. already cached
+- Reduces cold-start time for first builds
+
+### New Platform Models
+
+```prisma
+model BuildToken {
+  id         Int      @id @default(autoincrement())
+  userId     Int      @map("user_id")
+  appName    String   @map("app_name")
+  token      String   @unique
+  expiresAt  DateTime @map("expires_at")
+  createdAt  DateTime @default(now()) @map("created_at")
+  user       User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  @@map("build_tokens")
+}
+
+model Build {
+  id          Int       @id @default(autoincrement())
+  appId       Int       @map("app_id")
+  commitSha   String    @map("commit_sha")
+  commitMsg   String?   @map("commit_msg")
+  branch      String
+  status      String    @default("pending")  // pending, building, success, failed
+  logs        String?   @db.Text
+  vmId        String?   @map("vm_id")  // Ephemeral build VM
+  startedAt   DateTime? @map("started_at")
+  completedAt DateTime? @map("completed_at")
+  createdAt   DateTime  @default(now()) @map("created_at")
+  app         App       @relation(fields: [appId], references: [id], onDelete: Cascade)
+  @@map("builds")
+}
+
+model GithubRepo {
+  id             Int      @id @default(autoincrement())
+  appId          Int      @unique @map("app_id")
+  installationId BigInt   @map("installation_id")  // GitHub App installation
+  repoFullName   String   @map("repo_full_name")   // owner/repo
+  branch         String   @default("main")         // Branch to deploy
+  createdAt      DateTime @default(now()) @map("created_at")
+  app            App      @relation(fields: [appId], references: [id], onDelete: Cascade)
+  @@map("github_repos")
+}
+```
+
+### New Platform Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /api/webhooks/github` | Receive push events, trigger builds |
+| `POST /api/builds/token` | Generate short-lived build token |
+| `GET /api/apps/:app/builds` | List builds for an app |
+| `GET /api/apps/:app/builds/:id` | Get build details + logs |
+| `POST /api/apps/:app/connect-repo` | Link GitHub repo to app |
+
+### GitHub App Requirements
+
+Need a GitHub App (separate from OAuth) for:
+- Receiving webhooks (push events)
+- Cloning private repos on build VM
+- Setting commit status (optional)
+
+Permissions needed:
+- Contents: read (clone repos)
+- Webhooks: receive push events
+- Commit statuses: write (optional, for status checks)
+
+### Implementation Status
+
+- [ ] BuildToken model + API endpoint
+- [ ] CLI `--build-token` and `--app` flags
+- [ ] GitHub App setup + webhook handler
+- [ ] Build model + status tracking
+- [ ] Ephemeral build VM provisioning
+- [ ] Build log streaming/storage
+- [ ] S3/R2 cache bucket setup
+- [ ] BuildKit cache integration
+- [ ] Pre-baked build VM image (optional)
+
+## Development
+
+```bash
+npm run build
+npm run dev -- <command>
+npm link  # Global testing
+```

package/README.md

@@ -0,0 +1,94 @@
+# Hackerrun CLI
+
+Deploy apps with full control over your infrastructure. Hackerrun provides a Railway/Render-like experience on top of [Ubicloud](https://ubicloud.com) VMs with [Uncloud](https://github.com/psviderski/uncloud) container orchestration.
+
+## Quick Start
+
+```bash
+# Install
+npm install -g hackerrun
+
+# Login (one-time GitHub OAuth)
+hackerrun login
+
+# Deploy your app
+cd myapp
+hackerrun deploy
+# => App live at https://laughing-buddha.hackerrun.app
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `hackerrun login` | Authenticate via GitHub |
+| `hackerrun deploy` | Deploy your application |
+| `hackerrun apps` | List all your apps |
+| `hackerrun logs <app>` | View application logs |
+| `hackerrun ssh <app>` | SSH into app's VM |
+| `hackerrun destroy <app>` | Delete app and infrastructure |
+| `hackerrun link <app>` | Link current directory to an existing app |
+| `hackerrun rename --app <old> <new>` | Rename an app |
+| `hackerrun domain --app <app> <new>` | Change app's domain |
+
+## How It Works
+
+1. **First deploy** creates an IPv6-only VM on Ubicloud
+2. Your app is containerized and deployed via Uncloud
+3. Traffic flows through our gateway: `User → Cloudflare → Gateway → Your App`
+4. Apps get a random domain like `laughing-buddha.hackerrun.app`
+
+## App Naming
+
+| Identifier | Scope | Example |
+|------------|-------|---------|
+| **App Name** | Per user | `myapp` (you choose) |
+| **Domain** | Global | `laughing-buddha` (auto-generated) |
+
+You can change the domain anytime with `hackerrun domain`.
+
+## Configuration Files
+
+- **`hackerrun.yml`** - Docker Compose file for production with `x-ports` for public exposure
+- **`docker-compose.yml`** - Local development (ignored by hackerrun)
+
+### Example hackerrun.yml
+
+```yaml
+services:
+  web:
+    build: .
+    x-ports:
+      - "3000/http"
+```
+
+The `x-ports` extension exposes your service publicly through the gateway.
+
+## Domains
+
+| Domain | Purpose |
+|--------|---------|
+| `hackerrun.com` | Platform website & dashboard |
+| `hackerrun.app` | Your deployed applications |
+
+### Domain Format
+
+- Single service: `{domain}.hackerrun.app`
+- Multi-service: `{domain}-{service}.hackerrun.app`
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Run in development
+npm run dev -- <command>
+
+# Link globally for testing
+npm link
+```
+
+## License
+
+MIT