openship 0.1.1 → 0.1.7

package/docker-compose.yml

@@ -1,90 +0,0 @@
-# ──────────────────────────────────────────────────────────
-# Openship — Self-Hosted Docker Compose
-#
-# Quick start:
-#   cp .env.example .env
-#   docker compose up -d
-#
-# This spins up the full Openship stack:
-#   • Dashboard (Next.js)  → localhost:3001
-#   • Web / Landing        → localhost:3000
-#   • API (Hono)           → localhost:4000
-#   • PostgreSQL            → localhost:5432
-#   • Redis                 → localhost:6379
-# ──────────────────────────────────────────────────────────
-
-version: "3.9"
-
-services:
-  # ─── Database ─────────────────────────────────────────
-  postgres:
-    image: postgres:16-alpine
-    restart: unless-stopped
-    environment:
-      POSTGRES_USER: openship
-      POSTGRES_PASSWORD: openship
-      POSTGRES_DB: openship
-    ports:
-      - "5432:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-
-  # ─── Cache / Queue ───────────────────────────────────
-  redis:
-    image: redis:7-alpine
-    restart: unless-stopped
-    ports:
-      - "6379:6379"
-    volumes:
-      - redis_data:/data
-
-  # ─── API ──────────────────────────────────────────────
-  api:
-    build:
-      context: .
-      dockerfile: apps/api/Dockerfile
-    restart: unless-stopped
-    ports:
-      - "4000:4000"
-    environment:
-      NODE_ENV: production
-      PORT: 4000
-      CLOUD_MODE: "false"
-      DEPLOY_MODE: docker
-      DATABASE_URL: postgresql://openship:openship@postgres:5432/openship
-      REDIS_URL: redis://redis:6379
-      JWT_SECRET: change-me-in-production
-      BETTER_AUTH_SECRET: change-me-in-production   # used for session signing
-      TRUSTED_ORIGINS: http://localhost:3001,http://localhost:3000
-    depends_on:
-      - postgres
-      - redis
-
-  # ─── Dashboard ────────────────────────────────────────
-  dashboard:
-    build:
-      context: .
-      dockerfile: apps/dashboard/Dockerfile
-    restart: unless-stopped
-    ports:
-      - "3001:3001"
-    environment:
-      NODE_ENV: production
-      NEXT_PUBLIC_API_URL: http://api:4000/api
-    depends_on:
-      - api
-
-  # ─── Web / Landing ───────────────────────────────────
-  web:
-    build:
-      context: .
-      dockerfile: apps/web/Dockerfile
-    restart: unless-stopped
-    ports:
-      - "3000:3000"
-    environment:
-      NODE_ENV: production
-
-volumes:
-  postgres_data:
-  redis_data:

package/openship.code-workspace

@@ -1,7 +0,0 @@
-{
-    "folders": [
-        {
-            "path": "."
-        }
-    ]
-}

package/packages/adapters/docs/ARCHITECTURE.md

@@ -1,160 +0,0 @@
-# Platform Architecture
-
-> `@repo/adapters` — the abstraction layer between Openship's API and the underlying infrastructure.
-
-## Three Deployment Targets
-
-The same codebase runs in three completely different environments. The `createPlatform()` factory resolves the correct combination at startup based on config.
-
-```
-┌────────────────┬──────────────────────┬──────────────────────────┬─────────────────────┐
-│                │  cloud (Oblien)      │  selfhosted              │  desktop            │
-├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
-│  Runtime       │  CloudRuntime        │  DockerRuntime or        │  BareRuntime        │
-│                │  (pure API calls)    │  BareRuntime             │  (local executor)   │
-├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
-│  Routing       │  CloudInfraProvider  │  TraefikProvider         │  NoopInfraProvider  │
-│                │  (pure API calls)    │  (writes YAML via exec)  │  (silent no-op)     │
-├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
-│  SSL           │  CloudInfraProvider  │  TraefikProvider (ACME)  │  NoopInfraProvider  │
-│                │  (pure API calls)    │  (file ops via exec)     │  (no-op)            │
-├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
-│  System        │  null                │  SystemManager           │  null               │
-│                │  (no RCE at all)     │  (checks + installers)   │  (no setup needed)  │
-├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
-│  Executor      │  null                │  LocalExecutor or        │  null               │
-│                │  (nothing executes)  │  SshExecutor (shared)    │  (BareRuntime owns) │
-├────────────────┼──────────────────────┼──────────────────────────┼─────────────────────┤
-│  ssh2 loaded?  │  NO                  │  Only if SSH config set  │  NO                 │
-└────────────────┴──────────────────────┴──────────────────────────┴─────────────────────┘
-```
-
-## Three Layers
-
-Each layer has a single responsibility. They are composed by the Platform, never used directly.
-
-### 1. Runtime — build/deploy/stop lifecycle
-
-| Class | Transport | Use Case |
-|---|---|---|
-| `DockerRuntime` | dockerode (socket / SSH / TLS) | Self-hosted with Docker |
-| `BareRuntime` | `CommandExecutor` (local or SSH) | Self-hosted bare metal, desktop |
-| `CloudRuntime` | HTTP API calls (Oblien SDK) | Oblien cloud |
-
-- Docker has its **own** SSH transport via dockerode — separate from the shared executor
-- Bare uses the **shared** executor for everything (git, npm, nohup, kill, PID files)
-- Cloud makes **zero** local calls — pure API stubs
-
-### 2. Infra — routing + SSL
-
-| Class | Transport | Use Case |
-|---|---|---|
-| `TraefikProvider` | `CommandExecutor` (dual-path) | Self-hosted |
-| `CloudInfraProvider` | HTTP API calls (Oblien SDK) | Oblien cloud |
-| `NoopInfraProvider` | Nothing | Desktop / dev |
-
-- Traefik writes YAML config files to a watched directory via the executor
-- SSL is Traefik's built-in ACME resolver — cert info read via the executor
-- The executor enables Traefik config to be written on the local machine OR a remote server via SSH
-
-### 3. System — prerequisite checks + server setup
-
-| Class | Transport | Use Case |
-|---|---|---|
-| `SystemManager` | `CommandExecutor` | Self-hosted only |
-| _null_ | — | Cloud and Desktop (no setup needed) |
-
-- Checks: docker, traefik, git, node, bun — all via executor
-- Installers: automated install scripts with real-time log streaming
-- State: cached in `SetupStateStore` (file or DB), 24h auto-reverification
-- Feature gating: `requireFeature("deploy")` reads cached state (free on hot paths)
-
-## File Map
-
-```
-src/
-├── types.ts              # Shared types: configs, CommandExecutor, SshConfig
-├── platform.ts           # Factory + singleton (createPlatform, getPlatform)
-├── index.ts              # Barrel exports
-│
-├── runtime/
-│   ├── types.ts          # RuntimeAdapter interface, RuntimeCapability
-│   ├── docker.ts         # DockerRuntime (dockerode)
-│   ├── bare.ts           # BareRuntime (executor-based)
-│   ├── cloud.ts          # CloudRuntime (API stubs)
-│   └── index.ts          # Factory + re-exports
-│
-├── infra/
-│   ├── types.ts          # RoutingProvider, SslProvider interfaces
-│   ├── traefik.ts        # Traefik file provider (dual-path via executor)
-│   ├── cloud.ts          # Cloud infra (API stubs)
-│   └── noop.ts           # No-op (desktop/dev)
-│
-└── system/
-    ├── types.ts          # SystemLog, ComponentStatus, InstallerConfig, etc.
-    ├── executor.ts       # LocalExecutor, SshExecutor, createExecutor()
-    ├── state.ts          # SetupStateStore interface, FileStateStore
-    ├── checks.ts         # Component health checks (all via executor)
-    ├── installer.ts      # Component installers (all via executor)
-    ├── setup.ts          # SystemManager orchestrator
-    └── index.ts          # Barrel exports
-```
-
-## How It's Wired
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  API (apps/api)                                                 │
-│                                                                 │
-│  app.ts:  bootstrapPlatform()                                   │
-│           │                                                     │
-│           ▼                                                     │
-│  controller-helpers.ts:  resolveConfig() → initPlatform()       │
-│                          platform() → getPlatform()             │
-│                                                                 │
-│  service code:  const { runtime, routing, ssl } = platform()    │
-│                 await runtime.build(config, onLog)               │
-│                 await routing.registerRoute({ domain, ... })    │
-│                 await ssl.provisionCert(domain)                 │
-└─────────────────────────────────────────────────────────────────┘
-          │
-          ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  @repo/adapters                                                 │
-│                                                                 │
-│  createPlatform(config) ─┬─ "cloud"      → CloudRuntime        │
-│                          │                + CloudInfraProvider   │
-│                          │                + system: null         │
-│                          │                + executor: null       │
-│                          │                                      │
-│                          ├─ "selfhosted" → Docker/BareRuntime   │
-│                          │                + TraefikProvider      │
-│                          │                + SystemManager        │
-│                          │                + executor ─┐         │
-│                          │                            │         │
-│                          │    ┌───────────────────────┘         │
-│                          │    │ shared across:                  │
-│                          │    │  • BareRuntime (if bare mode)   │
-│                          │    │  • TraefikProvider              │
-│                          │    │  • SystemManager                │
-│                          │    │  • checks.ts + installer.ts     │
-│                          │                                      │
-│                          └─ "desktop"    → BareRuntime (own)    │
-│                                           + NoopInfraProvider   │
-│                                           + system: null        │
-│                                           + executor: null      │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Environment Variables
-
-| Variable | Values | Effect |
-|---|---|---|
-| `CLOUD_MODE` | `true` / `false` | Force cloud target (overrides DEPLOY_MODE) |
-| `DEPLOY_MODE` | `docker` / `bare` / `cloud` / `desktop` | Select runtime + target |
-
-Resolution priority in `resolveConfig()`:
-1. `CLOUD_MODE=true` or `DEPLOY_MODE=cloud` → `target: "cloud"`
-2. `DEPLOY_MODE=desktop` → `target: "desktop"`
-3. Everything else → `target: "selfhosted"` + `runtime: DEPLOY_MODE`
-4. Default (nothing set) → `target: "selfhosted"`, `runtime: "docker"`

package/packages/adapters/docs/BUILD-PIPELINE.md

@@ -1,171 +0,0 @@
-# Build Pipeline & Process Management
-
-> How builds run, how processes are tracked, and how cleanup works across all runtimes.
-
-## Build Flow
-
-All three runtimes implement `build()` but with completely different transports:
-
-```
-build.service.ts
-    │
-    │  Creates BuildLogger (single source of truth for all log emission)
-    │  Creates logCallback → pushes to logs[] + SSE broadcast
-    │
-    ▼
-runtime.build(config, logger)
-    │
-    ├─ CloudRuntime   → Oblien API: workspace.build() + execAndStream()
-    ├─ BareRuntime    → executor.streamExec() through runBuildPipeline()
-    └─ DockerRuntime  → (stub — Docker builds via Dockerfile)
-```
-
-## BuildLogger — Single Source of Truth
-
-Every log emission goes through `BuildLogger`. No adapter creates `LogEntry` objects with step metadata directly.
-
-```typescript
-class BuildLogger {
-  log(message: string, level?)       // Plain log line
-  step(step, status, message)        // Step lifecycle event (stepper UI)
-  runStep(step, label, fn)           // Run a step: emit running → execute → completed/failed
-  get callback(): LogCallback        // Pass to exec functions for raw output streaming
-}
-```
-
-### Who calls what
-
-| Caller | Method | Purpose |
-|---|---|---|
-| `runBuildPipeline()` | `logger.runStep("clone", ...)` | Step events for clone/install/build |
-| `runBuildPipeline()` | `logger.log(...)` | Pipeline status messages |
-| `build.service.ts` | `logger.step("deploy", ...)` | Deploy phase step events |
-| `build.service.ts` | `logger.log(...)` | Deploy status messages |
-| `executor.streamExec()` | `logger.callback` (raw `LogCallback`) | stdout/stderr lines from shell commands |
-| `cloud.ts execAndStream()` | raw `LogCallback` | Oblien exec output chunks |
-
-## Shared Build Pipeline
-
-`runBuildPipeline()` is used by `BareRuntime` and would be used by `DockerRuntime` when it supports builds. `CloudRuntime` has its own build flow via the Oblien API.
-
-```
-runBuildPipeline(env, config, logger)
-    │
-    ├─ Step: clone
-    │    env.exec(`git clone --branch ${branch} --depth 1 ${repo} .`, logger.callback)
-    │
-    ├─ Step: install
-    │    env.exec(`npm install` / `yarn` / `pnpm install`, logger.callback)
-    │
-    ├─ Step: build (if buildCommand configured)
-    │    env.exec(buildCommand, logger.callback)
-    │
-    └─ Returns { status: "deploying" | "failed", durationMs }
-```
-
-The `BuildEnvironment` abstraction decouples the pipeline from the executor:
-
-```typescript
-interface BuildEnvironment {
-  projectDir: string;
-  exec(command: string, onLog: LogCallback): Promise<void>;
-}
-```
-
-BareRuntime wires it to `this.executor.streamExec()`. A future Docker build could wire it to `docker exec`.
-
-## Process Management (Bare Runtime)
-
-### Deploy — setsid for proper process groups
-
-```
-deploy(config)
-    │
-    │  setsid nohup npm start >> logfile 2>&1 &
-    │  echo $!
-    │         │
-    │         └─ PID captured → written to .pids/{deploymentId}.pid
-    │
-    └─ setsid makes npm the process group leader
-       so all child processes belong to the same PGID
-```
-
-### Stop — kill the entire tree
-
-```
-stop(containerId)
-    │
-    │  1. Read PID from .pids/{containerId}.pid
-    │  2. kill -- -${pid}        ← SIGTERM the entire process group
-    │     (fallback: kill ${pid}   if group kill not supported)
-    │  3. Wait up to 10s for graceful shutdown
-    │  4. kill -9 -- -${pid}     ← SIGKILL the group if still alive
-    │
-    └─ This ensures child processes (e.g., node spawned by npm)
-       are cleaned up too — no orphans
-```
-
-### PID Tracking
-
-```
-${workDir}/
-  .pids/
-    {deploymentId}.pid    ← contains the PID as plain text
-  .logs/
-    {deploymentId}.log    ← stdout + stderr from the process
-```
-
-All PID operations go through the executor:
-- `readPid()` → `executor.readFile(pidFile)`
-- `writePid()` → `executor.writeFile(pidFile, pid)`
-- `isAlive()` → `executor.exec("kill -0 ${pid}")`
-
-This means PID management works identically on local and remote (SSH) servers.
-
-### Build Cancellation
-
-```
-cancelBuild(sessionId)
-    │
-    │  Read PID from .pids/build-{sessionId}.pid
-    │  kill -- -${pid}   ← kill entire build process group
-    │
-    └─ Kills git clone, npm install, or whatever is running
-```
-
-## Resource Configuration
-
-```typescript
-interface ResourceConfig {
-  cpuCores: number;   // Fractional cores (e.g., 0.5, 1, 2)
-  memoryMb: number;   // Memory in megabytes
-}
-
-// Defaults
-DEFAULT_RESOURCE_CONFIG  = { cpuCores: 0.5, memoryMb: 512 }   // runtime
-DEFAULT_BUILD_RESOURCE_CONFIG = { cpuCores: 2, memoryMb: 4096 } // build
-```
-
-- Cloud: `cpuCores` passed directly to Oblien SDK (fractional, e.g., 0.5)
-- Docker: used for container resource limits
-- Bare: informational only (OS manages resources)
-
-## Error Handling
-
-Build failures cascade cleanly:
-
-```
-Pipeline step fails (e.g., npm install exits non-zero)
-    │
-    ├─ executor.streamExec returns { code: non-zero }
-    ├─ BuildEnvironment.exec throws Error
-    ├─ runBuildPipeline catches → logger.step(step, "failed", message)
-    ├─ Returns { status: "failed" }
-    │
-    ▼
-build.service.ts
-    ├─ Updates deployment status to "failed"
-    ├─ Persists logs to DB via finishBuildSession()
-    ├─ Broadcasts failure via SSE
-    └─ Sends failure notification email
-```

package/packages/adapters/docs/CLOUD.md

@@ -1,239 +0,0 @@
-# Cloud Architecture
-
-> How Openship connects to Oblien cloud infrastructure — same pipeline, two auth paths.
-
-## Overview
-
-Openship runs in two modes. Both use the **exact same** `CloudRuntime` and build/deploy pipeline. The only difference is how the Oblien SDK client gets authenticated:
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         CloudRuntime(client)                           │
-│                                                                        │
-│   build() → provisionBuildWorkspace → runBuildPipeline → deploy()     │
-│   stop() / start() / restart() / destroy()                            │
-│   logs / metrics / domain management                                   │
-│                                                                        │
-│   Doesn't know or care HOW the Oblien client was authenticated.       │
-└────────────────────────────┬────────────────────────────────────────────┘
-                             │
-              ┌──────────────┴──────────────┐
-              │                             │
-   ┌──────────▼──────────┐      ┌───────────▼───────────┐
-   │  SaaS (CLOUD_MODE)  │      │  Local (!CLOUD_MODE)  │
-   │                     │      │                        │
-   │  Master credentials │      │  Namespace token       │
-   │  clientId + secret  │      │  from stored session   │
-   │                     │      │                        │
-   │  new Oblien({       │      │  new Oblien({          │
-   │    clientId,        │      │    token               │
-   │    clientSecret     │      │  })                    │
-   │  })                 │      │                        │
-   │                     │      │  Scoped to user's      │
-   │  Full platform      │      │  namespace (os-{uid})  │
-   │  access             │      │  30min TTL             │
-   └─────────────────────┘      └────────────────────────┘
-```
-
-## Mode 1: SaaS (`CLOUD_MODE=true`)
-
-When Openship runs as the hosted SaaS platform (api.openship.io):
-
-```
-Server startup
-  → initPlatform({ target: "cloud", cloudClientId, cloudClientSecret })
-  → new Oblien({ clientId, clientSecret })       ← master creds from env
-  → CloudRuntime(client)                          ← singleton, stays for process lifetime
-  → build.service.ts uses platform().runtime directly
-```
-
-The SaaS also exposes a token endpoint for local instances:
-
-```
-POST /api/cloud/token  (requires auth)
-  → ensureNamespace(userId)    ← creates os-{userId} namespace if needed
-  → client.tokens.create({ scope: "namespace", namespace, ttl: 1800 })
-  → { token, namespace, expiresAt }
-```
-
-### Key files
-
-| File | Purpose |
-|---|---|
-| `apps/api/src/lib/openship-cloud.ts` | `ensureNamespace()` + `issueNamespaceToken()` |
-| `apps/api/src/modules/cloud/cloud.controller.ts` | `getToken()` handler |
-| `apps/api/src/modules/cloud/cloud.routes.ts` | `cloudSaasRoutes` → `POST /token` |
-
-## Mode 2: Local (`CLOUD_MODE=false`)
-
-When Openship runs locally (desktop app, self-hosted, CLI):
-
-### Step 1: User connects their Openship Cloud account
-
-```
-Dashboard Settings page
-  → user enters email + password
-  → POST /api/cloud/connect
-  → Local API proxies login to api.openship.io/api/auth/sign-in/email
-  → Receives session token
-  → Encrypts + stores in user_settings.cloud_session_token
-```
-
-### Step 2: Deploy to cloud
-
-```
-build.service.ts → executeBuildAndDeploy()
-  → detects !CLOUD_MODE && target === "cloud"
-  → getCloudToken(userId)
-      → reads encrypted session from DB
-      → POST api.openship.io/api/cloud/token (with Bearer session)
-      → receives namespace-scoped Oblien token (cached in memory, 30min TTL)
-  → createPlatform({ target: "cloud", cloudToken: result.token })
-      → new Oblien({ token })                  ← namespace-scoped
-      → CloudRuntime(client)                    ← per-deploy instance
-  → same build() → same deploy() → same everything
-```
-
-### Key files
-
-| File | Purpose |
-|---|---|
-| `apps/api/src/lib/cloud-client.ts` | `connectCloud()`, `disconnectCloud()`, `isCloudConnected()`, `getCloudToken()` |
-| `apps/api/src/modules/cloud/cloud.controller.ts` | `connect()`, `disconnect()`, `status()` handlers |
-| `apps/api/src/modules/cloud/cloud.routes.ts` | `cloudLocalRoutes` → `POST /connect`, `POST /disconnect`, `GET /status` |
-| `apps/dashboard/src/app/(dashboard)/settings/page.tsx` | Cloud connection UI |
-| `apps/dashboard/src/lib/api/cloud.ts` | `cloudApi` client-side helpers |
-
-## Auth Flow Diagram
-
-```
-LOCAL MODE — full round trip:
-
-┌──────────────┐     POST /api/cloud/connect
-│  Dashboard   │ ──────────────────────────────▶ ┌──────────────┐
-│  Settings    │     { email, password }          │  Local API   │
-│              │                                  │              │
-│              │     { connected: true }           │  cloud       │
-│              │ ◀────────────────────────────────│  controller  │
-└──────────────┘                                  └──────┬───────┘
-                                                         │
-                               POST /api/auth/sign-in    │
-                               { email, password }       │
-                                                         ▼
-                                                  ┌──────────────┐
-                                                  │ Openship     │
-                                                  │ Cloud SaaS   │
-                                                  │              │
-                                                  │ Returns      │
-                                                  │ session token│
-                                                  └──────────────┘
-                                                         │
-                                          encrypt(token) │
-                                          store in DB    │
-                                                         ▼
-                                                  ┌──────────────┐
-                                                  │ user_settings│
-                                                  │ cloud_session│
-                                                  │ _token (enc) │
-                                                  └──────────────┘
-
-
-DEPLOY TIME:
-
-┌──────────────┐                                  ┌──────────────┐
-│ build.service│ ── getCloudToken(userId) ──────▶ │ cloud-client │
-│              │                                  │              │
-│              │                                  │ 1. read DB   │
-│              │                                  │ 2. decrypt   │
-│              │     { token, namespace }          │ 3. POST /api │
-│              │ ◀────────────────────────────────│    /cloud    │
-└──────┬───────┘                                  │    /token    │
-       │                                          └──────┬───────┘
-       │  createPlatform({                               │
-       │    target: "cloud",                              ▼
-       │    cloudToken: token             ┌──────────────────────────┐
-       │  })                              │ Openship Cloud SaaS      │
-       │                                  │                          │
-       ▼                                  │ ensureNamespace(userId)  │
-┌──────────────┐                          │ issueNamespaceToken()    │
-│ CloudRuntime │                          │                          │
-│              │                          │ Returns Oblien namespace │
-│ new Oblien({ │                          │ token (30min TTL)        │
-│   token      │                          └──────────────────────────┘
-│ })           │
-│              │
-│ build()      │──────▶ Oblien API (workspaces, runtime, deploy...)
-│ deploy()     │
-└──────────────┘
-```
-
-## Namespace Model
-
-Each user gets an isolated Oblien namespace:
-
-- **Slug**: `os-{userId}`
-- **Creation**: Idempotent — 409 on duplicate is caught, existing namespace fetched
-- **Cached**: In-memory `Map<userId, slug>` on SaaS server
-
-The namespace token gives full access to everything in that namespace:
-- Create/manage workspaces
-- Build & deploy
-- Domain management
-- Logs & metrics
-
-## Security
-
-| Concern | Approach |
-|---|---|
-| Cloud session at rest | AES-256 encrypted via `encrypt()`/`decrypt()` in `encryption.ts` |
-| Session in transit | HTTPS only (api.openship.io) |
-| Expired sessions | Auto-cleared on 401 from SaaS API |
-| Namespace tokens | 30min TTL, 5min refresh buffer, in-memory cache only |
-| Token scope | Namespace-scoped — user can only access their own resources |
-| No browser cookies | Session lives server-side in DB, never exposed to dashboard |
-
-## API Endpoints
-
-### SaaS routes (`CLOUD_MODE=true`, mounted at `/api/cloud`)
-
-| Method | Path | Handler | Purpose |
-|---|---|---|---|
-| POST | `/token` | `getToken` | Mint namespace-scoped Oblien token |
-
-### Local routes (`CLOUD_MODE=false`, mounted at `/api/cloud`)
-
-| Method | Path | Handler | Purpose |
-|---|---|---|---|
-| POST | `/connect` | `connect` | Proxy login → store encrypted session |
-| POST | `/disconnect` | `disconnect` | Clear stored session |
-| GET | `/status` | `status` | Check connection state |
-
-### Dashboard API (`apps/dashboard/src/lib/api/cloud.ts`)
-
-```typescript
-cloudApi.connect(email, password)  // POST /api/cloud/connect
-cloudApi.disconnect()              // POST /api/cloud/disconnect
-cloudApi.status()                  // GET  /api/cloud/status
-```
-
-## Route Mounting (`app.ts`)
-
-```typescript
-if (env.CLOUD_MODE) {
-  // SaaS: mint tokens for local instances
-  app.route("/api/cloud", cloudSaasRoutes);
-} else {
-  // Local: manage connection to Openship Cloud
-  app.route("/api/cloud", cloudLocalRoutes);
-}
-```
-
-Dynamic imports ensure zero code bleed between modes.
-
-## Database
-
-| Table | Column | Type | Purpose |
-|---|---|---|---|
-| `user_settings` | `cloud_session_token` | `text` (nullable) | Encrypted Openship Cloud session |
-
-Migration: `packages/db/drizzle/0004_add_cloud_session_token.sql`