@renbostudios/edge-ota 0.4.0 → 0.4.2

package/README.md

@@ -1,112 +1,211 @@
-# @renbostudios/edge-ota CLI
+<p align="center">
+  <img src="https://ota.renbo.site/og.png" alt="Edge OTA" width="100%">
+</p>
 
-Zero-SDK, self-hostable OTA update CLI for Expo React Native. Push signed JavaScript bundles to any EdgeOTA server.
+<h1 align="center">
+  <code>edge-ota</code>
+</h1>
 
-## Install
+<p align="center">
+  <strong>Zero-SDK, self-hostable OTA update CLI for Expo React Native</strong><br>
+  Push signed JavaScript bundles to any EdgeOTA server.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@renbostudios/edge-ota"><img src="https://img.shields.io/npm/v/@renbostudios/edge-ota?style=flat-square&color=81C784" alt="npm version"></a>
+  <a href="https://github.com/renbostudios/edge-ota-cli/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@renbostudios/edge-ota?style=flat-square&color=FFAA00" alt="license"></a>
+  <a href="https://www.npmjs.com/package/@renbostudios/edge-ota"><img src="https://img.shields.io/npm/dm/@renbostudios/edge-ota?style=flat-square&color=81C784" alt="downloads"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/renbostudios/edge-ota-cli">GitHub</a> · <a href="https://ota.renbo.site">Dashboard</a> · <a href="https://ota.renbo.site/docs">Docs</a> · <a href="https://pd1mvpk7lt.ufs.sh/f/6uDGWrRxa3ipmhByNjc2TlHph0oA4dsWRFUuqZMan18Gwb7g">Video Tutorial</a>
+</p>
+
+---
+
+<br>
+
+```
+ ╔══════════════════════════════════════════════════════════════════╗
+ ║                                                                ║
+ ║   ┌─┐┬┌─┬┌┬┐┌─┐┌─┐┬ ┬┌─┐┌┐┌┌┬┐┌─┐                          ║
+ ║   └─┐││ ┤│││├┤ │ ┬├─┤├─┤│││ │ ┤ └─┐                         ║
+ ║   └─┘┴└─┴┴ ┴└  └─┘┴ ┴┴ ┴┘└┘─┴┘└─┘└─┘                         ║
+ ║                                                                ║
+ ║   Push signed OTA bundles to the edge.                         ║
+ ║   Zero SDK. Zero egress. Full control.                         ║
+ ║                                                                ║
+ ╚══════════════════════════════════════════════════════════════════╝
+```
+
+<br>
+
+## ⚡ Quick Start
+
+```
+ ┌──────────────────────────────────────────────────────────────┐
+ │  STEP 01                                                     │
+ │  Install the CLI globally                                    │
+ └──────────────────────────────────────────────────────────────┘
+```
 
 ```bash
 npm install -g @renbostudios/edge-ota
 ```
 
-Requires Node.js 18+ and an Expo project with `expo-updates` installed.
-
-## Quick Start
+```
+ ┌──────────────────────────────────────────────────────────────┐
+ │  STEP 02                                                     │
+ │  Log in to your EdgeOTA account                              │
+ └──────────────────────────────────────────────────────────────┘
+```
 
 ```bash
-# 1. Log in to your EdgeOTA account
 edge-ota login
+```
+
+```
+ ┌──────────────────────────────────────────────────────────────┐
+ │  STEP 03                                                     │
+ │  Register your project & generate signing keys               │
+ └──────────────────────────────────────────────────────────────┘
+```
 
-# 2. Register your project and generate signing keys
+```bash
 edge-ota init
+```
+
+```
+ ┌──────────────────────────────────────────────────────────────┐
+ │  STEP 04                                                     │
+ │  ⚠  REBUILD YOUR NATIVE APP (required!)                     │
+ └──────────────────────────────────────────────────────────────┘
+```
 
-# 3. Rebuild your native app (REQUIRED — see below)
+```bash
 npx expo prebuild --clean
 npx expo run:ios
 npx expo run:android
+```
+
+```
+ ┌──────────────────────────────────────────────────────────────┐
+ │  STEP 05                                                     │
+ │  Push an OTA update 🚀                                       │
+ └──────────────────────────────────────────────────────────────┘
+```
 
-# 4. Push an OTA update
+```bash
 edge-ota push
 ```
 
+> **📹 Prefer video?** Watch the full setup tutorial below:
+
+<p align="center">
+  <video src="https://pd1mvpk7lt.ufs.sh/f/6uDGWrRxa3ipmhByNjc2TlHph0oA4dsWRFUuqZMan18Gwb7g" controls width="100%" style="max-width: 640px; border: 1px solid #333; border-radius: 4px; background: #000;">
+    Your browser does not support the video tag.
+  </video>
+</p>
+
+<br>
+
 ---
 
-## Commands
+<br>
+
+## 📦 Commands
 
 ### `edge-ota login`
 
-Authenticate with your EdgeOTA account. Credentials are stored globally at `~/.config/edge-ota/config.json`.
+Authenticate with your EdgeOTA account. Credentials are stored globally — no per-project `.env` files needed.
 
 ```bash
-edge-ota login
-edge-ota login --server https://my-server.com   # custom server
+edge-ota login                                    # default server
+edge-ota login --server https://my-server.com     # custom server
 ```
 
-You'll be prompted for your email and password. The session token is saved globally — no per-project `.env` files needed.
+```
+ ┌──────────────────────────────────────────────┐
+ │  📁 Stored at:                               │
+ │  ~/.config/edge-ota/config.json              │
+ │                                              │
+ │  Contains: auth token, email, server URL     │
+ └──────────────────────────────────────────────┘
+```
+
+---
 
 ### `edge-ota logout`
 
-Remove stored credentials.
+Remove stored credentials from this machine.
 
 ```bash
 edge-ota logout
 ```
 
+---
+
 ### `edge-ota init`
 
-Register your project on the EdgeOTA server, generate an ECDSA P-256 signing key pair, and configure `app.json` with the correct update URL.
+The all-in-one setup command. Registers your project, generates ECDSA P-256 signing keys, and configures `app.json`.
 
 ```bash
-edge-ota init
-edge-ota init --server https://my-server.com   # override server
+edge-ota init                                    # interactive setup
+edge-ota init --server https://my-server.com     # override server
 ```
 
-**What it does:**
+**What happens under the hood:**
+
+```
+  ① Fetches your existing projects from the server
+  ② Lets you select an existing project or create a new one
+  ③ Generates an ECDSA P-256 key pair
+  ④ Registers the project with your public key
+  ⑤ Saves private key → ~/.config/edge-ota/keys/<projectId>.key
+  ⑥ Updates app.json with server URL, public key, and headers
+```
 
-1. Fetches your existing projects from the server (if any)
-2. Lets you select an existing project or create a new one
-3. Generates an ECDSA P-256 key pair
-4. Registers the project on the server with your public key
-5. Saves the private key to `~/.config/edge-ota/keys/<projectId>.key`
-6. Updates your `app.json` with:
-   - `expo.updates.url` — points to your EdgeOTA server
-   - `expo.updates.checkAutomatically` — set to `"ON_LOAD"`
-   - `expo.updates.fallbackToCacheTimeout` — set to `30000`
-   - `expo.updates.requestHeaders` — sets `expo-channel-name` to `"production"`
-   - `expo.extra.edgeOtaServer` — the server URL for manual override
-   - `expo.extra.edgeOtaPublicKey` — the generated public key
+> ⚠ **After `init`, you MUST rebuild your native app.** See [Rebuild Required](#-rebuild-required) below.
 
-**After init, you MUST rebuild your native app.** The CLI will print a prominent warning with instructions. See the [Rebuild Required](#rebuild-required) section below.
+---
 
 ### `edge-ota push`
 
-Export your Expo bundle and publish an OTA update to the server.
+Export your Expo bundle and publish an OTA update.
 
 ```bash
-edge-ota push                                      # default: all platforms, production channel
-edge-ota push --channel staging                    # deploy to staging
-edge-ota push --platform ios                       # iOS only
-edge-ota push --platform android                   # Android only
-edge-ota push --skip-export                        # skip expo export, use existing ./dist
-edge-ota push --dry-run                            # build and sign, but don't upload
+edge-ota push                                     # all platforms, production channel
+edge-ota push --channel staging                   # deploy to staging
+edge-ota push --runtime 1.0.0                     # target specific runtime version
+edge-ota push --runtime 1.0.5,1.0.6,1.0.7         # target multiple runtime versions (matrix deployment)
+edge-ota push --platform ios                      # iOS only
+edge-ota push --platform android                  # Android only
+edge-ota push --skip-export                       # use existing ./dist
+edge-ota push --dry-run                           # build & sign, don't upload
 ```
 
-**What it does:**
+**What happens under the hood:**
 
-1. Runs `npx expo export` to create the JavaScript bundle (unless `--skip-export`)
-2. Collects all assets from `./dist`
-3. For each target platform (ios/android):
-   - Locates the platform-specific bundle
-   - Signs the payload with your ECDSA private key
-   - Uploads the bundle + signature to the server
-4. The server verifies the signature before storing the update
+```
+  ① Runs `npx expo export` to create the JS bundle
+  ② Collects all assets from ./dist
+  ③ For each platform (ios/android):
+       → Locates the platform-specific bundle
+       → Signs the payload with your ECDSA private key
+       → Uploads bundle + signature to the server
+  ④ Server verifies the signature before storing
+```
 
 **How it reads your config:**
 
-The CLI reads everything from `app.json` — no flags required for standard deploys:
-- **Server URL** — from `expo.updates.url` (or `expo.extra.edgeOtaServer`)
-- **Project ID** — parsed from the updates URL
-- **Runtime version** — from `expo.runtimeVersion` (string or policy object)
-- **Private key** — from `~/.config/edge-ota/keys/<projectId>.key`
+| Source | What it reads |
+|---|---|
+| `expo.updates.url` | Server URL + Project ID |
+| `expo.runtimeVersion` | Runtime version (string or policy) |
+| `~/.config/edge-ota/keys/<id>.key` | ECDSA private key |
+| `expo.extra.edgeOtaServer` | Server URL override |
+
+---
 
 ### `edge-ota status`
 
@@ -114,9 +213,11 @@ List recent deployments for the current project.
 
 ```bash
 edge-ota status
-edge-ota status --limit 20    # show more releases
+edge-ota status --limit 20                       # show more releases
 ```
 
+---
+
 ### `edge-ota keygen`
 
 Generate a new ECDSA P-256 key pair and print it to stdout. Does not write any files.
@@ -127,63 +228,74 @@ edge-ota keygen
 
 Useful for manual key rotation or generating keys for server-side signing.
 
+<br>
+
 ---
 
-## Rebuild Required
+<br>
 
-After running `edge-ota init`, you **must** rebuild your native app. The `expo-updates` native module reads its configuration (server URL, runtime version) from the **native binary**, not from `app.json` at runtime.
+## 🔄 Rebuild Required
+
+After running `edge-ota init`, you **must** rebuild your native app. The `expo-updates` native module reads its config from the **native binary**, not from `app.json` at runtime.
 
 ```bash
-# Regenerate native projects with fresh config
 npx expo prebuild --clean
-
-# Rebuild
 npx expo run:ios
 npx expo run:android
 
-# Or via EAS
+# or via EAS
 eas build --profile production
 ```
 
-**If you skip this step**, the app will fail with:
-
 ```
-Failed to check for update
+ ╔══════════════════════════════════════════════════════════════════╗
+ ║  ⚠  SKIP THIS STEP AND YOU'LL SEE:                            ║
+ ║                                                                ║
+ ║  "Failed to check for update"                                  ║
+ ║                                                                ║
+ ║  The native module has no valid server URL to reach because    ║
+ ║  it was never embedded in the binary.                          ║
+ ╚══════════════════════════════════════════════════════════════════╝
 ```
 
-The native module has no valid server URL to reach because it was never embedded in the binary.
-
 You must also rebuild after any change to `expo.updates.url` or `expo.runtimeVersion` in `app.json`.
 
+<br>
+
 ---
 
-## How It Works
+<br>
+
+## 🔁 How It Works
 
 ```
-Developer Machine              EdgeOTA Server               User's Phone
-─────────────────              ──────────────               ────────────
-edge-ota push ─────────────►   POST /api/updates
-                               (ECDSA verified)
-                               stores bundle
-                                              ◄──────────── GET /api/updates
-                                                            (expo-updates SDK)
-                                              ────────────► multipart manifest
-                                              ◄──────────── GET /api/assets/:hash
-                                                            download bundle
-                                                            reload app ✓
+  Developer Machine                EdgeOTA Server                User's Phone
+  ─────────────────                ──────────────                ────────────
+
+  edge-ota push ──────────────►   POST /api/updates
+                                   (ECDSA verified ✓)
+                                   (stores bundle)
+                                                   ◄──────────── GET /api/updates
+                                                                 (expo-updates SDK)
+                                                   ────────────► signed manifest
+                                                   ◄──────────── GET /api/assets/:hash
+                                                                 (downloads bundle)
+                                                                 (reloads app ✓)
 ```
 
-1. `edge-ota push` runs `expo export` and uploads the Hermes bundle + ECDSA signature to your server
-2. The server verifies the ECDSA P-256 signature before storing anything
-3. When users open the app, `expo-updates` checks your server for a new manifest
+1. `edge-ota push` runs `expo export` and uploads the Hermes bundle + ECDSA signature
+2. The server **verifies** the ECDSA P-256 signature before storing anything
+3. When users open the app, `expo-updates` checks for a new manifest
 4. The server responds with a signed multipart manifest (Expo Updates Protocol v1)
 5. `expo-updates` downloads and applies the update automatically
 
+<br>
+
 ---
 
-## What `init` Writes to `app.json`
+<br>
 
-After running `edge-ota init`, your `app.json` will contain:
+## ⚙ What `init` Writes to `app.json`
 
 ```json
 {
@@ -205,68 +317,99 @@ After running `edge-ota init`, your `app.json` will contain:
 }
 ```
 
-The `runtimeVersion` field is **not modified** by the CLI — it must already exist in your `app.json`. It supports both static strings and policy objects:
+> `runtimeVersion` is **not modified** by the CLI — it must already exist in your `app.json`. Supports both static strings and policy objects:
 
 ```json
-// Static (recommended)
 "runtimeVersion": "1.0.0"
-
-// Policy-based (auto-increments with expo.version)
+```
+```json
 "runtimeVersion": { "policy": "appVersion" }
 ```
 
+<br>
+
 ---
 
-## Global Storage
+<br>
 
-All credentials and keys are stored outside your project directory:
+## 🗂 Global Storage
 
-| File | Contents |
-|---|---|
-| `~/.config/edge-ota/config.json` | Auth token, email, default server URL |
-| `~/.config/edge-ota/keys/<projectId>.key` | Private ECDSA signing key (per-project) |
-| `~/.config/edge-ota/update-check.json` | Auto-update check timestamp |
+All credentials and keys are stored **outside** your project directory:
+
+```
+ ~/.config/edge-ota/
+ ├── config.json                    ← auth token, email, server URL
+ ├── keys/
+ │   └── <projectId>.key            ← ECDSA private key (per-project)
+ └── update-check.json              ← auto-update check timestamp
+```
 
-Nothing sensitive is ever stored in your project repository.
+```
+ ┌──────────────────────────────────────────────────────────────┐
+ │  🔒 Nothing sensitive is ever stored in your project repo.   │
+ └──────────────────────────────────────────────────────────────┘
+```
+
+<br>
 
 ---
 
-## Environment Variables
+<br>
+
+## 🧪 Environment Variables
 
 | Variable | Purpose |
 |---|---|
-| `EDGE_OTA_TOKEN` | Override the auth token (useful for CI/CD) |
+| `EDGE_OTA_TOKEN` | Override the auth token (for CI/CD pipelines) |
 | `EDGE_OTA_UPDATING` | Internal — prevents recursive auto-updates |
 
+<br>
+
 ---
 
-## Auto-Update
+<br>
+
+## 🔄 Auto-Update
 
-The CLI checks for newer versions on npm every 15 minutes. If a newer version is found, it auto-installs globally. This check happens silently in the background and never blocks command execution.
+The CLI checks for newer versions on npm every 15 minutes. If a newer version is found, it auto-installs globally. This happens silently in the background and never blocks command execution.
 
 To disable: set `EDGE_OTA_UPDATING=true` in your environment.
 
+<br>
+
 ---
 
-## Security
+<br>
+
+## 🔐 Security
 
-- All bundles are signed with ECDSA P-256 before upload
-- The server rejects any bundle with an invalid or missing signature
-- Private keys are stored with `0600` permissions (owner read/write only)
-- Session tokens expire after 24 hours
-- Private keys never leave your machine
+```
+ ┌──────────────────────────────────────────────────────────────┐
+ │                                                              │
+ │  ✅  ECDSA P-256 signing on every bundle upload             │
+ │  ✅  Server rejects invalid or missing signatures            │
+ │  ✅  Private keys stored with 0600 permissions               │
+ │  ✅  Session tokens expire after 24 hours                    │
+ │  ✅  Private keys never leave your machine                   │
+ │                                                              │
+ └──────────────────────────────────────────────────────────────┘
+```
+
+<br>
 
 ---
 
-## Server Setup
+<br>
+
+## 🖥 Server Setup
 
-The EdgeOTA server is a standard Node.js/Express app. You can self-host it or use the managed cloud service.
+The EdgeOTA server is a standard Node.js/Express app. Self-host it or use the managed cloud service at [ota.renbo.site](https://ota.renbo.site).
 
 ### Docker
 
 ```bash
-docker pull renbostudios/edge-ota-server:latest
-docker run -p 3000:3000 -e DATABASE_URL=... renbostudios/edge-ota-server
+docker pull ghcr.io/itskodaaa/edge-ota-backend:latest
+docker run -p 3000:3000 -e DATABASE_URL=... ghcr.io/itskodaaa/edge-ota-backend
 ```
 
 ### Docker Compose
@@ -286,13 +429,20 @@ pnpm install
 pnpm --filter @renbostudios/edge-ota-server-node dev
 ```
 
+<br>
+
 ---
 
-## Troubleshooting
+<br>
 
-### "Failed to check for update" on app launch
+## 🐛 Troubleshooting
 
-The `expo-updates` native module can't reach your server because the URL was never embedded in the binary. Fix: rebuild the native app after `edge-ota init`.
+<details>
+<summary><strong>"Failed to check for update" on app launch</strong></summary>
+
+<br>
+
+The `expo-updates` native module can't reach your server because the URL was never embedded in the binary.
 
 ```bash
 npx expo prebuild --clean
@@ -300,29 +450,73 @@ npx expo run:ios
 npx expo run:android
 ```
 
-### Updates work on iOS but not Android
+</details>
+
+<details>
+<summary><strong>Updates work on iOS but not Android</strong></summary>
 
-The Android native project may still have the default Expo Updates URL. Fix: regenerate and rebuild.
+<br>
+
+The Android native project may still have the default Expo Updates URL. Regenerate and rebuild:
 
 ```bash
 npx expo prebuild --clean
 npx expo run:android
 ```
 
-Verify by checking `android/app/src/main/AndroidManifest.xml` for the `EXPO_UPDATE_URL` meta-data entry — it should point to your EdgeOTA server.
+Verify by checking `android/app/src/main/AndroidManifest.xml` for the `EXPO_UPDATE_URL` meta-data entry.
+
+</details>
+
+<details>
+<summary><strong>Updates stopped working after a version bump</strong></summary>
 
-### Updates stopped working after a version bump
+<br>
 
 If `runtimeVersion` uses the `appVersion` policy, every version bump changes the runtime version. Push a new update after bumping, or switch to a static string.
 
-### "No signing key found" error on push
+</details>
+
+<details>
+<summary><strong>"No signing key found" error on push</strong></summary>
+
+<br>
 
 Run `edge-ota init` to generate keys, or use `edge-ota keygen` to generate a new pair and register it manually.
 
+</details>
+
+<br>
+
+---
+
+<br>
+
+## 📂 Project Structure
+
+```
+ edge-ota-cli/
+ ├── apps/
+ │   ├── cli/            ← CLI tool (you are here)
+ │   ├── server-node/    ← Express + TypeScript API
+ │   ├── worker-oss/     ← Cloudflare Worker (open source)
+ │   ├── dashboard/      ← SvelteKit frontend
+ │   └── core/           ← Shared crypto/manifest logic
+ └── packages/
+     └── core/           ← @renbostudios/edge-ota-core
+```
+
+<br>
+
 ---
 
-## Built by Renbo Studios
+<br>
 
-[renbostudios.com](https://renbostudios.com) — Mobile App Development Studio
+<p align="center">
+  <strong>Built by</strong><br>
+  <a href="https://renbostudios.com">Renbo Studios</a> — Mobile App Development Studio
+</p>
 
-MIT License
+<p align="center">
+  <sub>MIT License · <code>@renbostudios/edge-ota</code></sub>
+</p>