open-ota 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo E. Dominguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# expo-ota-cli
+
+Publishes an Expo app's JS bundle to a self-hosted [Expo OTA](https://github.com/focux/expo-ota)
+server. Run it from the app directory after deploying the server.
+
+```sh
+npx expo-ota-cli publish --branch staging --message "Fix payment sheet"
+```
+
+It runs `expo export` for both platforms, resolves each platform's runtime version, uploads only the
+assets the server does not already have, publishes the update group, then builds bsdiff patches
+against the newest three bundles on the branch and uploads them (`bsdiff` must be on the PATH,
+otherwise patches are skipped with a warning).
+
+## Credentials
+
+| Setting | Env var | Flag | Value |
+| --- | --- | --- | --- |
+| Server origin | `OTA_URL` | `--server` | The `updatesUrl` printed by the server deploy, for example `https://u.example.com` |
+| Publish token | `OTA_PUBLISH_TOKEN` | `--token` | The `OTA_PUBLISH_TOKEN` the server was deployed with |
+| Actor | `OTA_ACTOR` | | Optional. Who the publish is credited to; defaults to the commit author |
+
+Flags win over environment variables. In CI, store the token as a secret and the origin as a
+variable. Locally, export them in your shell or put them in a `.env` your shell loads; the CLI does
+not read `.env` files itself.
+
+## Commands
+
+```
+expo-ota publish --branch <name> [--message <text>] [--rollout <0-100>]
+                 [--platform ios] [--platform android] [--skip-export] [--dist <dir>]
+                 [--no-patches] [--project <dir>] [--server <url>] [--token <token>]
+expo-ota rollback-to-embedded --branch <name> [--platform ios|android] [--message <text>]
+expo-ota --help
+```
+
+`--rollout` starts the group as a canary; the remaining devices keep the previous update until the
+rollout is widened in the dashboard. `rollback-to-embedded` publishes a group that sends every
+device on the branch back to the JS baked into its build.
+
+Requires Node 20 or newer and the Expo CLI of the app it runs in.

package/dist/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { run } from "./expo.js";
+import { publish, rollbackToEmbedded } from "./publish.js";
+const usage = `expo-ota - publish Expo updates to a self-hosted Expo OTA server
+
+Usage:
+  expo-ota publish --branch <name> [options]
+  expo-ota rollback-to-embedded --branch <name> [options]
+
+Commands:
+  publish                Export the project and publish an update group.
+  rollback-to-embedded   Publish a group that sends clients back to their embedded update.
+
+Options:
+  --branch <name>        Branch to publish to. Required.
+  --message <text>       Message stored with the group.
+  --rollout <0-100>      Percent of clients that get the update. Publish only.
+  --platform <name>      ios or android. Repeatable. Defaults to both.
+  --dist <dir>           Export output directory, relative to the project. Publish only. Defaults to dist.
+  --skip-export          Reuse an existing export instead of running expo export. Publish only.
+  --no-patches           Skip the bsdiff delta patches built after publishing. Publish only.
+  --project <dir>        Expo project directory. Defaults to the working directory.
+  --server <url>         Server origin. Overrides OTA_URL.
+  --token <token>        Publish token. Overrides OTA_PUBLISH_TOKEN.
+  -h, --help             Show this help.
+
+Environment:
+  OTA_URL                Server origin, for example https://u.example.com
+  OTA_PUBLISH_TOKEN      Bearer token for the publish endpoints, the OTA_PUBLISH_TOKEN the server was deployed with.
+  OTA_ACTOR              Who to credit the publish to. Defaults to the commit author.
+`;
+const main = async () => {
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(2),
+        allowPositionals: true,
+        options: {
+            branch: { type: "string" },
+            message: { type: "string" },
+            rollout: { type: "string" },
+            platform: { type: "string", multiple: true },
+            dist: { type: "string" },
+            "skip-export": { type: "boolean" },
+            "no-patches": { type: "boolean" },
+            project: { type: "string" },
+            server: { type: "string" },
+            token: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    const command = positionals[0];
+    if (values.help === true || command === undefined) {
+        process.stdout.write(usage);
+        return;
+    }
+    if (command !== "publish" && command !== "rollback-to-embedded") {
+        throw new Error(`Unknown command "${command}". Run expo-ota --help.`);
+    }
+    if (values.branch === undefined || values.branch === "") {
+        throw new Error("--branch is required.");
+    }
+    const platforms = [];
+    for (const platform of values.platform ?? []) {
+        if (platform !== "ios" && platform !== "android") {
+            throw new Error(`--platform must be ios or android, got "${platform}".`);
+        }
+        if (!platforms.includes(platform)) {
+            platforms.push(platform);
+        }
+    }
+    if (platforms.length === 0) {
+        platforms.push("ios", "android");
+    }
+    let rolloutPercent;
+    if (values.rollout !== undefined) {
+        rolloutPercent = Number(values.rollout);
+        if (!Number.isInteger(rolloutPercent) || rolloutPercent < 0 || rolloutPercent > 100) {
+            throw new Error(`--rollout must be a whole number between 0 and 100, got "${values.rollout}".`);
+        }
+    }
+    const url = values.server ?? process.env["OTA_URL"];
+    const token = values.token ?? process.env["OTA_PUBLISH_TOKEN"];
+    if (url === undefined || url === "" || token === undefined || token === "") {
+        throw new Error("Set OTA_URL and OTA_PUBLISH_TOKEN, or pass --server and --token. Run expo-ota --help.");
+    }
+    const server = { url: url.replace(/\/+$/, ""), token, fetch };
+    const projectDir = path.resolve(values.project ?? process.cwd());
+    const common = {
+        branch: values.branch,
+        message: values.message,
+        platforms,
+        projectDir,
+        server,
+        run,
+        log: (message) => process.stdout.write(`${message}\n`),
+    };
+    if (command === "rollback-to-embedded") {
+        await rollbackToEmbedded(common);
+        return;
+    }
+    await publish({
+        ...common,
+        rolloutPercent,
+        distDir: path.resolve(projectDir, values.dist ?? "dist"),
+        skipExport: values["skip-export"] === true,
+        noPatches: values["no-patches"] === true,
+    });
+};
+try {
+    await main();
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+}

package/dist/expo.js

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export const run = async (command, args, cwd) => {
+    const { stdout } = await execFileAsync(command, [...args], { cwd, maxBuffer: 64 * 1024 * 1024 });
+    return stdout;
+};
+export const exportProject = (run, projectDir, distDir, platforms) => run("npx", ["expo", "export", ...platforms.flatMap((platform) => ["--platform", platform]), "--output-dir", distDir], projectDir);
+export const publicConfig = async (run, projectDir) => {
+    const stdout = await run("npx", ["expo", "config", "--type", "public", "--json"], projectDir);
+    // The Expo CLI prints progress lines around the JSON document.
+    const json = stdout.slice(stdout.indexOf("{"), stdout.lastIndexOf("}") + 1);
+    if (json === "") {
+        throw new Error("expo config --type public --json printed no JSON.");
+    }
+    return JSON.parse(json);
+};
+export const resolveRuntimeVersion = async (run, projectDir, platform) => {
+    const stdout = await run("npx", ["expo-updates", "runtimeversion:resolve", "--platform", platform], projectDir);
+    const lines = stdout.split("\n").filter((line) => line.trim() !== "");
+    const last = lines.at(-1) ?? "";
+    const parsed = JSON.parse(last);
+    if (typeof parsed.runtimeVersion !== "string") {
+        throw new Error(`Could not resolve the ${platform} runtime version from: ${last}`);
+    }
+    return parsed.runtimeVersion;
+};
+export const gitCommit = async (run, projectDir) => {
+    try {
+        return (await run("git", ["rev-parse", "HEAD"], projectDir)).trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+// Who to credit the publish to: OTA_ACTOR wins, else the commit author.
+export const actor = async (run, projectDir) => {
+    const fromEnv = process.env["OTA_ACTOR"];
+    if (fromEnv !== undefined && fromEnv !== "")
+        return fromEnv;
+    try {
+        return (await run("git", ["log", "-1", "--format=%ae"], projectDir)).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/patches.js

@@ -0,0 +1,43 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { branchBundles, downloadAsset, uploadPatch } from "./server.js";
+const reason = (error) => (error instanceof Error ? error.message : String(error));
+// bsdiff needs about 17x the bundle in memory, so patches are built here on the
+// runner and uploaded. A patch that fails to build is skipped, never fatal.
+export const generatePatches = async (options) => {
+    const { branch, server, run, log } = options;
+    for (const target of options.targets) {
+        try {
+            const bundles = await branchBundles(server, branch, target.platform, target.runtimeVersion, 3);
+            const bases = bundles.filter((bundle) => bundle.hash !== target.hash);
+            if (bases.length === 0)
+                continue;
+            const dir = await mkdtemp(path.join(tmpdir(), "ota-patch-"));
+            try {
+                const targetFile = path.join(dir, "target.bundle");
+                await writeFile(targetFile, target.bytes);
+                for (const base of bases) {
+                    try {
+                        const baseFile = path.join(dir, `${base.hash}.bundle`);
+                        const patchFile = path.join(dir, `${base.hash}.patch`);
+                        await writeFile(baseFile, await downloadAsset(server, base.hash));
+                        await run("bsdiff", [baseFile, targetFile, patchFile], dir);
+                        const patch = await readFile(patchFile);
+                        await uploadPatch(server, base.hash, target.hash, patch);
+                        log(`patch ${base.hash.slice(0, 7)}..${target.hash.slice(0, 7)} ${patch.length}`);
+                    }
+                    catch (error) {
+                        log(`warning: no patch from ${base.hash.slice(0, 7)}: ${reason(error)}`);
+                    }
+                }
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+        }
+        catch (error) {
+            log(`warning: no patches for ${target.platform}: ${reason(error)}`);
+        }
+    }
+};

package/dist/publish.js

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { actor, exportProject, gitCommit, publicConfig, resolveRuntimeVersion, } from "./expo.js";
+import { generatePatches } from "./patches.js";
+import { missingAssets, publishGroup, uploadAsset } from "./server.js";
+const contentTypes = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    json: "application/json",
+    mp3: "audio/mpeg",
+    mp4: "video/mp4",
+    wav: "audio/wav",
+    txt: "text/plain",
+};
+// Matches Expo's reference server: base64url sha256 addresses the bytes, md5 hex is the client-side key.
+const storeAsset = async (file, contentType, fileExtension, uploads) => {
+    const bytes = await readFile(file);
+    const hash = createHash("sha256").update(bytes).digest("base64url");
+    uploads.set(hash, { bytes, contentType });
+    return { hash, key: createHash("md5").update(bytes).digest("hex"), contentType, fileExtension };
+};
+const uploadMissing = async (server, hashes, uploads) => {
+    let next = 0;
+    const worker = async () => {
+        for (let index = next++; index < hashes.length; index = next++) {
+            const hash = hashes[index];
+            const upload = uploads.get(hash);
+            if (upload === undefined) {
+                throw new Error(`The server asked for an asset this export does not contain: ${hash}`);
+            }
+            await uploadAsset(server, hash, upload.bytes, upload.contentType);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(4, hashes.length) }, worker));
+};
+const submit = async (server, group, log) => {
+    const published = await publishGroup(server, group);
+    log(`Published group ${published.groupId}`);
+    for (const update of published.updates) {
+        log(`  ${update.platform} ${update.runtimeVersion} -> ${update.id}`);
+    }
+    return published;
+};
+export const publish = async (options) => {
+    const { run, projectDir, distDir, platforms, server, log } = options;
+    if (!options.skipExport) {
+        log(`Exporting ${platforms.join(" and ")} to ${distDir}`);
+        await exportProject(run, projectDir, distDir, platforms);
+    }
+    const metadata = JSON.parse(await readFile(path.join(distDir, "metadata.json"), "utf8"));
+    const expoConfig = await publicConfig(run, projectDir);
+    const uploads = new Map();
+    const updates = {};
+    const targets = [];
+    for (const platform of platforms) {
+        const files = metadata.fileMetadata[platform];
+        if (files === undefined) {
+            throw new Error(`${path.join(distDir, "metadata.json")} has no ${platform} export.`);
+        }
+        const runtimeVersion = await resolveRuntimeVersion(run, projectDir, platform);
+        const launchAsset = await storeAsset(path.join(distDir, files.bundle), "application/javascript", ".bundle", uploads);
+        const assets = [];
+        for (const asset of files.assets) {
+            assets.push(await storeAsset(path.join(distDir, asset.path), contentTypes[asset.ext.toLowerCase()] ?? "application/octet-stream", `.${asset.ext}`, uploads));
+        }
+        updates[platform] = { runtimeVersion, launchAsset, assets };
+        targets.push({ platform, runtimeVersion, hash: launchAsset.hash, bytes: uploads.get(launchAsset.hash).bytes });
+        log(`${platform}: runtime ${runtimeVersion}, ${assets.length} assets`);
+    }
+    const hashes = [...uploads.keys()];
+    const missing = await missingAssets(server, hashes);
+    log(`Uploading ${missing.length} of ${hashes.length} assets`);
+    await uploadMissing(server, missing, uploads);
+    const commit = await gitCommit(run, projectDir);
+    const who = await actor(run, projectDir);
+    const published = await submit(server, {
+        branch: options.branch,
+        ...(options.message !== undefined && { message: options.message }),
+        ...(commit !== undefined && { gitCommit: commit }),
+        ...(who !== undefined && { actor: who }),
+        ...(options.rolloutPercent !== undefined && { rolloutPercent: options.rolloutPercent }),
+        expoConfig,
+        updates,
+    }, log);
+    if (!options.noPatches) {
+        await generatePatches({ branch: options.branch, targets, server, run, log });
+    }
+    return published;
+};
+export const rollbackToEmbedded = async (options) => {
+    const updates = {};
+    for (const platform of options.platforms) {
+        const runtimeVersion = await resolveRuntimeVersion(options.run, options.projectDir, platform);
+        updates[platform] = { runtimeVersion, rollbackToEmbedded: true };
+    }
+    const commit = await gitCommit(options.run, options.projectDir);
+    const who = await actor(options.run, options.projectDir);
+    return submit(options.server, {
+        branch: options.branch,
+        ...(options.message !== undefined && { message: options.message }),
+        ...(commit !== undefined && { gitCommit: commit }),
+        ...(who !== undefined && { actor: who }),
+        updates,
+    }, options.log);
+};

package/dist/server.js

@@ -0,0 +1,56 @@
+const check = async (response, what) => {
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`${what} failed: ${response.status} ${response.statusText} ${body}`.trim());
+    }
+};
+export const missingAssets = async (server, hashes) => {
+    const response = await server.fetch(`${server.url}/publish/assets/missing`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${server.token}`, "content-type": "application/json" },
+        body: JSON.stringify({ hashes }),
+    });
+    await check(response, "POST /publish/assets/missing");
+    const body = (await response.json());
+    return [...(body.missing ?? [])];
+};
+export const uploadAsset = async (server, hash, bytes, contentType) => {
+    const response = await server.fetch(`${server.url}/publish/assets/${hash}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${server.token}`, "content-type": contentType },
+        body: bytes,
+    });
+    await check(response, `PUT /publish/assets/${hash}`);
+};
+export const publishGroup = async (server, group) => {
+    const response = await server.fetch(`${server.url}/publish/groups`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${server.token}`, "content-type": "application/json" },
+        body: JSON.stringify(group),
+    });
+    await check(response, "POST /publish/groups");
+    return (await response.json());
+};
+export const branchBundles = async (server, branch, platform, runtimeVersion, limit) => {
+    const query = new URLSearchParams({ platform, runtime: runtimeVersion, limit: String(limit) });
+    const path = `/publish/branches/${encodeURIComponent(branch)}/bundles`;
+    const response = await server.fetch(`${server.url}${path}?${query}`, {
+        headers: { authorization: `Bearer ${server.token}` },
+    });
+    await check(response, `GET ${path}`);
+    const body = (await response.json());
+    return [...(body.bundles ?? [])];
+};
+export const downloadAsset = async (server, hash) => {
+    const response = await server.fetch(`${server.url}/assets/${hash}`);
+    await check(response, `GET /assets/${hash}`);
+    return new Uint8Array(await response.arrayBuffer());
+};
+export const uploadPatch = async (server, baseHash, targetHash, bytes) => {
+    const response = await server.fetch(`${server.url}/publish/patches/${baseHash}/${targetHash}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${server.token}`, "content-type": "application/octet-stream" },
+        body: bytes,
+    });
+    await check(response, `PUT /publish/patches/${baseHash}/${targetHash}`);
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "open-ota",
+  "version": "0.1.0",
+  "description": "Publish Expo updates to a self-hosted Expo OTA server",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/focux/expo-ota",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "expo",
+    "expo-updates",
+    "ota",
+    "cloudflare"
+  ],
+  "type": "module",
+  "bin": {
+    "expo-ota": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}