@beamdeploy/cli 0.2.0-preview.1

package/README.md

@@ -0,0 +1,22 @@
+# @beamdeploy/cli
+
+BeamDeploy's Node.js 20+ command-line client for validating and uploading immutable OTA bundles,
+uploading React Native platform bundles, and promoting a tested version between channels.
+
+```bash
+npm install --save-dev @beamdeploy/cli
+npx beamdeploy --help
+```
+
+Set the control-plane origin and an app-scoped deploy key through CI secrets:
+
+```bash
+export BEAMDEPLOY_SERVER="https://beamdeploy.example.com"
+export BEAMDEPLOY_TOKEN="<app-scoped deploy key>"
+npx beamdeploy doctor --server "$BEAMDEPLOY_SERVER"
+npx beamdeploy auth context
+```
+
+Never commit the deploy key or ship it in a mobile application. Use `rn upload --dry-run` to
+validate a React Native artifact locally before the authenticated staging upload. Inspect
+`npx beamdeploy --help` before using optional preflight or channel commands.

package/dist/cli.cjs

@@ -0,0 +1,922 @@
+#!/usr/bin/env node
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// ../../scripts/beamdeploy-cli.mjs
+var import_promises2 = require("node:fs/promises");
+var import_node_os = require("node:os");
+var import_node_path2 = __toESM(require("node:path"), 1);
+
+// ../../src/bundle-delta.js
+var import_yauzl = __toESM(require("yauzl"), 1);
+
+// ../../src/zip-pack.js
+function crc32(buffer) {
+  let crc = 4294967295;
+  for (let i = 0; i < buffer.length; i += 1) {
+    crc ^= buffer[i];
+    for (let j = 0; j < 8; j += 1) {
+      crc = crc >>> 1 ^ (crc & 1 ? 3988292384 : 0);
+    }
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function zipEntry(fileName, body) {
+  const name = Buffer.from(fileName);
+  const checksum = crc32(body);
+  const localHeader = Buffer.alloc(30);
+  localHeader.writeUInt32LE(67324752, 0);
+  localHeader.writeUInt16LE(20, 4);
+  localHeader.writeUInt16LE(0, 6);
+  localHeader.writeUInt16LE(0, 8);
+  localHeader.writeUInt16LE(0, 10);
+  localHeader.writeUInt16LE(0, 12);
+  localHeader.writeUInt32LE(checksum, 14);
+  localHeader.writeUInt32LE(body.length, 18);
+  localHeader.writeUInt32LE(body.length, 22);
+  localHeader.writeUInt16LE(name.length, 26);
+  localHeader.writeUInt16LE(0, 28);
+  const centralHeader = Buffer.alloc(46);
+  centralHeader.writeUInt32LE(33639248, 0);
+  centralHeader.writeUInt16LE(20, 4);
+  centralHeader.writeUInt16LE(20, 6);
+  centralHeader.writeUInt16LE(0, 8);
+  centralHeader.writeUInt16LE(0, 10);
+  centralHeader.writeUInt16LE(0, 12);
+  centralHeader.writeUInt16LE(0, 14);
+  centralHeader.writeUInt32LE(checksum, 16);
+  centralHeader.writeUInt32LE(body.length, 20);
+  centralHeader.writeUInt32LE(body.length, 24);
+  centralHeader.writeUInt16LE(name.length, 28);
+  centralHeader.writeUInt16LE(0, 30);
+  centralHeader.writeUInt16LE(0, 32);
+  centralHeader.writeUInt16LE(0, 34);
+  centralHeader.writeUInt16LE(0, 36);
+  centralHeader.writeUInt32LE(0, 38);
+  centralHeader.writeUInt32LE(0, 42);
+  const centralOffset = localHeader.length + name.length + body.length;
+  const centralSize = centralHeader.length + name.length;
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(101010256, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(1, 8);
+  end.writeUInt16LE(1, 10);
+  end.writeUInt32LE(centralSize, 12);
+  end.writeUInt32LE(centralOffset, 16);
+  end.writeUInt16LE(0, 20);
+  return {
+    local: Buffer.concat([localHeader, name, body]),
+    central: Buffer.concat([centralHeader, name]),
+    centralSize,
+    centralOffset
+  };
+}
+function packZip(entries) {
+  if (!entries.length) {
+    throw new Error("packZip requires at least one entry.");
+  }
+  const parts = [];
+  const centrals = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const zipped = zipEntry(entry.name, entry.data);
+    parts.push(zipped.local);
+    centrals.push({ ...zipped, offset });
+    offset += zipped.local.length;
+  }
+  let centralSize = 0;
+  for (const central of centrals) {
+    const patched = Buffer.from(central.central);
+    patched.writeUInt32LE(central.offset, 42);
+    parts.push(patched);
+    centralSize += patched.length;
+  }
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(101010256, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(centrals.length, 8);
+  end.writeUInt16LE(centrals.length, 10);
+  end.writeUInt32LE(centralSize, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+  parts.push(end);
+  return Buffer.concat(parts);
+}
+
+// ../../src/bundle-delta.js
+var DELTA_MANIFEST_PATH = "_beamdeploy/delta.json";
+var DELTA_FORMAT = "beamdeploy-delta-v1";
+var DELTA_UPLOAD_RATIO_THRESHOLD = 0.9;
+function unsafeZipPath(fileName) {
+  return fileName.startsWith("/") || fileName.includes("\\") || fileName.split("/").filter(Boolean).some((part) => part === "..");
+}
+function normalizePath(fileName) {
+  return fileName.replace(/\\/g, "/");
+}
+function readZipFileMap(buffer) {
+  return new Promise((resolve, reject) => {
+    const files = /* @__PURE__ */ new Map();
+    import_yauzl.default.fromBuffer(buffer, { lazyEntries: true, validateEntrySizes: true }, (error, zipfile) => {
+      if (error || !zipfile) {
+        reject(new Error("Unable to read bundle zip."));
+        return;
+      }
+      const pending = [];
+      zipfile.on("entry", (entry) => {
+        if (unsafeZipPath(entry.fileName) || /\/$/.test(entry.fileName)) {
+          zipfile.readEntry();
+          return;
+        }
+        pending.push(
+          new Promise((entryResolve, entryReject) => {
+            zipfile.openReadStream(entry, (streamError, readStream) => {
+              if (streamError || !readStream) {
+                entryReject(streamError || new Error("Unable to read zip entry."));
+                return;
+              }
+              const chunks = [];
+              readStream.on("data", (chunk) => chunks.push(chunk));
+              readStream.on("end", () => {
+                files.set(normalizePath(entry.fileName), Buffer.concat(chunks));
+                entryResolve();
+              });
+              readStream.on("error", entryReject);
+            });
+          })
+        );
+        zipfile.readEntry();
+      });
+      zipfile.on("end", async () => {
+        zipfile.close();
+        try {
+          await Promise.all(pending);
+          resolve(files);
+        } catch (entryError) {
+          reject(entryError);
+        }
+      });
+      zipfile.on("error", reject);
+      zipfile.readEntry();
+    });
+  });
+}
+function computeDeltaFromFileMaps(baseFiles, newFiles, baseVersion) {
+  const deleted = [];
+  const changed = /* @__PURE__ */ new Map();
+  for (const [path3] of baseFiles) {
+    if (path3 === DELTA_MANIFEST_PATH) {
+      continue;
+    }
+    if (!newFiles.has(path3)) {
+      deleted.push(path3);
+    }
+  }
+  for (const [path3, body] of newFiles) {
+    if (path3 === DELTA_MANIFEST_PATH) {
+      continue;
+    }
+    const previous = baseFiles.get(path3);
+    if (!previous || !previous.equals(body)) {
+      changed.set(path3, body);
+    }
+  }
+  if (!changed.size && !deleted.length) {
+    throw new Error("No file changes detected between base and new bundle.");
+  }
+  const manifest = {
+    format: DELTA_FORMAT,
+    baseVersion,
+    delete: deleted
+  };
+  const entries = [{ name: DELTA_MANIFEST_PATH, data: Buffer.from(JSON.stringify(manifest), "utf8") }];
+  for (const [path3, body] of [...changed.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    entries.push({ name: path3, data: body });
+  }
+  const deltaZip = packZip(entries);
+  return {
+    deltaZip,
+    deleted,
+    changedCount: changed.size,
+    deletedCount: deleted.length
+  };
+}
+async function buildDeltaZipFromBundles(baseBuffer, newBuffer, baseVersion) {
+  const baseFiles = await readZipFileMap(baseBuffer);
+  const newFiles = await readZipFileMap(newBuffer);
+  return computeDeltaFromFileMaps(baseFiles, newFiles, baseVersion);
+}
+function shouldPreferFullUpload(deltaSize, fullSize, threshold = DELTA_UPLOAD_RATIO_THRESHOLD) {
+  if (!fullSize || fullSize <= 0) {
+    return true;
+  }
+  return deltaSize >= fullSize * threshold;
+}
+
+// ../../src/rn-upload.js
+var import_node_crypto = require("node:crypto");
+var import_promises = require("node:fs/promises");
+var import_node_path = __toESM(require("node:path"), 1);
+
+// ../../src/bundle-platform.js
+var MOBILE_PLATFORMS = /* @__PURE__ */ new Set(["ios", "android"]);
+var BUNDLE_PLATFORMS = /* @__PURE__ */ new Set([...MOBILE_PLATFORMS, "electron"]);
+function normalizeBundlePlatform(value) {
+  const platform = String(value || "").trim().toLowerCase();
+  return BUNDLE_PLATFORMS.has(platform) ? platform : null;
+}
+
+// ../../src/rn-upload.js
+var IOS_BUNDLE_NAMES = ["bundle/main.jsbundle", "main.jsbundle"];
+var ANDROID_BUNDLE_NAMES = ["bundle/index.android.bundle", "index.android.bundle"];
+function normalizeRnVersionSlug(rnVersion) {
+  const match = String(rnVersion || "").trim().match(/(\d+)\.(\d+)/);
+  if (!match) {
+    return "unknown";
+  }
+  return `${match[1]}${match[2]}`;
+}
+function slugAbi(value) {
+  return String(value || "default").trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "default";
+}
+function deriveNativeBuildId({
+  rnVersion,
+  hermesEnabled = true,
+  nativeModulesAbi = "default",
+  nativeBuildId
+} = {}) {
+  const override = String(nativeBuildId || "").trim();
+  if (override) {
+    return override;
+  }
+  const rnSlug = normalizeRnVersionSlug(rnVersion);
+  const engine = hermesEnabled ? "hermes" : "jsc";
+  const abi = slugAbi(nativeModulesAbi);
+  const fingerprint = `${rnVersion}|${hermesEnabled}|${abi}`;
+  const digest = (0, import_node_crypto.createHash)("sha256").update(fingerprint).digest("hex").slice(0, 8);
+  return `rn${rnSlug}-${engine}-${abi}-${digest}`;
+}
+function sha256Hex(buffer) {
+  return (0, import_node_crypto.createHash)("sha256").update(buffer).digest("hex");
+}
+function rnBundleZipEntryName(platform) {
+  return platform === "ios" ? "bundle/main.jsbundle" : "bundle/index.android.bundle";
+}
+function rnSourcemapZipEntryName(platform) {
+  return platform === "ios" ? "bundle/main.jsbundle.map" : "bundle/index.android.bundle.map";
+}
+async function fileExists(filePath) {
+  try {
+    const info = await (0, import_promises.stat)(filePath);
+    return info.isFile();
+  } catch {
+    return false;
+  }
+}
+async function findRnBundleSource(bundleDir, platform) {
+  const names = platform === "ios" ? IOS_BUNDLE_NAMES : ANDROID_BUNDLE_NAMES;
+  for (const rel of names) {
+    const candidate = import_node_path.default.join(bundleDir, rel);
+    if (await fileExists(candidate)) {
+      return { sourcePath: candidate, zipPath: rnBundleZipEntryName(platform) };
+    }
+  }
+  throw new Error(
+    `Could not find ${platform === "ios" ? "main.jsbundle" : "index.android.bundle"} under ${bundleDir}. Expected one of: ${names.join(", ")}`
+  );
+}
+async function collectAssetEntries(assetsDir) {
+  const entries = [];
+  async function walk(dir, prefix) {
+    const names = await (0, import_promises.readdir)(dir);
+    for (const name of names) {
+      const full = import_node_path.default.join(dir, name);
+      const rel = prefix ? `${prefix}/${name}` : name;
+      const info = await (0, import_promises.stat)(full);
+      if (info.isDirectory()) {
+        await walk(full, rel);
+      } else {
+        entries.push({
+          name: `assets/${rel}`,
+          data: await (0, import_promises.readFile)(full)
+        });
+      }
+    }
+  }
+  await walk(assetsDir, "");
+  return entries;
+}
+async function readReactNativeVersion(projectDir) {
+  try {
+    const raw = await (0, import_promises.readFile)(import_node_path.default.join(projectDir, "package.json"), "utf8");
+    const pkg = JSON.parse(raw);
+    const value = pkg.dependencies?.["react-native"] || pkg.devDependencies?.["react-native"] || pkg.peerDependencies?.["react-native"] || "";
+    return String(value).replace(/^[\^~>=<]+/, "").trim();
+  } catch {
+    return "";
+  }
+}
+function buildRnCompatibility({ rnVersion, hermesEnabled, nativeBuildId }) {
+  return {
+    runtime: "react-native",
+    rnVersion: String(rnVersion || "").trim(),
+    hermesEnabled: Boolean(hermesEnabled),
+    nativeBuildId: String(nativeBuildId || "").trim()
+  };
+}
+function buildRnUploadQuery({ channel, platform, compatibility }) {
+  const params = new URLSearchParams();
+  if (channel) {
+    params.set("channel", channel);
+  }
+  const normalizedPlatform = normalizeBundlePlatform(platform);
+  if (normalizedPlatform) {
+    params.set("platform", normalizedPlatform);
+  }
+  if (compatibility?.runtime) {
+    params.set("runtime", compatibility.runtime);
+  }
+  if (compatibility?.nativeBuildId) {
+    params.set("nativeBuildId", compatibility.nativeBuildId);
+  }
+  if (compatibility?.rnVersion) {
+    params.set("rnVersion", compatibility.rnVersion);
+  }
+  if (compatibility?.hermesEnabled !== void 0) {
+    params.set("hermesEnabled", compatibility.hermesEnabled ? "true" : "false");
+  }
+  return params.toString();
+}
+async function packRnOtaZip({
+  bundleDir,
+  bundlePath,
+  sourcemapPath,
+  platform,
+  rnVersion,
+  hermesEnabled = true,
+  nativeModulesAbi = "default",
+  nativeBuildId: nativeBuildIdOverride
+}) {
+  const normalizedPlatform = normalizeBundlePlatform(platform);
+  if (!normalizedPlatform) {
+    throw new Error("platform must be ios or android");
+  }
+  const zipPath = rnBundleZipEntryName(normalizedPlatform);
+  let bundleData;
+  if (bundlePath) {
+    const resolvedBundle = import_node_path.default.resolve(bundlePath);
+    if (!await fileExists(resolvedBundle)) {
+      throw new Error(`Bundle file not found: ${resolvedBundle}`);
+    }
+    bundleData = await (0, import_promises.readFile)(resolvedBundle);
+  } else {
+    if (!bundleDir) {
+      throw new Error("bundleDir or bundlePath is required");
+    }
+    const found = await findRnBundleSource(bundleDir, normalizedPlatform);
+    bundleData = await (0, import_promises.readFile)(found.sourcePath);
+  }
+  const derivedBuildId = deriveNativeBuildId({
+    rnVersion,
+    hermesEnabled,
+    nativeModulesAbi,
+    nativeBuildId: nativeBuildIdOverride
+  });
+  const compatibility = buildRnCompatibility({
+    rnVersion,
+    hermesEnabled,
+    nativeBuildId: derivedBuildId
+  });
+  const fileChecksums = {
+    [zipPath]: sha256Hex(bundleData)
+  };
+  const zipEntries = [{ name: zipPath, data: bundleData }];
+  if (sourcemapPath) {
+    const resolvedMap = import_node_path.default.resolve(sourcemapPath);
+    if (!await fileExists(resolvedMap)) {
+      throw new Error(`Source map not found: ${resolvedMap}`);
+    }
+    const mapData = await (0, import_promises.readFile)(resolvedMap);
+    const mapZipPath = rnSourcemapZipEntryName(normalizedPlatform);
+    fileChecksums[mapZipPath] = sha256Hex(mapData);
+    zipEntries.push({ name: mapZipPath, data: mapData });
+  }
+  const assetsDir = import_node_path.default.join(bundleDir || ".", "assets");
+  try {
+    const assetInfo = await (0, import_promises.stat)(assetsDir);
+    if (assetInfo.isDirectory()) {
+      const assetEntries = await collectAssetEntries(assetsDir);
+      for (const entry of assetEntries) {
+        fileChecksums[entry.name] = sha256Hex(entry.data);
+        zipEntries.push(entry);
+      }
+    }
+  } catch {
+  }
+  const manifest = {
+    rnVersion: compatibility.rnVersion,
+    hermesEnabled: compatibility.hermesEnabled,
+    nativeBuildId: compatibility.nativeBuildId,
+    platform: normalizedPlatform,
+    fileChecksums
+  };
+  const manifestBody = Buffer.from(JSON.stringify(manifest, null, 2));
+  zipEntries.push({ name: "manifest.json", data: manifestBody });
+  return {
+    zip: packZip(zipEntries),
+    manifest,
+    nativeBuildId: derivedBuildId,
+    compatibility
+  };
+}
+
+// ../../scripts/beamdeploy-cli.mjs
+var configDir = import_node_path2.default.join((0, import_node_os.homedir)(), ".beamdeploy");
+var configPath = import_node_path2.default.join(configDir, "config.json");
+function usage() {
+  console.log(`BeamDeploy CLI
+
+Usage:
+  beamdeploy init [apiKey]
+  beamdeploy login <apiKey>
+  beamdeploy auth context
+  beamdeploy doctor [--server http://localhost:8787]
+  beamdeploy app create <appId> [name]
+  beamdeploy bundle upload <appId> <version> <zipPath> [--channel production] [--platform electron] [--delta] [--delta-base <version>] [--preflight]
+  beamdeploy bundle patch <appId> <version> [--display-name NAME] [--description TEXT] [--notes TEXT]
+      [--min-native V] [--max-native V] [--breaking]
+  beamdeploy bundle trash <appId> <version>
+  beamdeploy bundle restore <appId> <version>
+  beamdeploy channel trash <appId> <channel>
+  beamdeploy channel restore <appId> <channel>
+  beamdeploy rn upload <appId> <version> [bundleDir] --platform ios|android
+      [--bundle <jsbundle>] [--sourcemap <map>] [--deploy-key <token>]
+      [--channel production] [--rn-version 0.74.0] [--no-hermes] [--abi arm64-v8a]
+      [--native-build-id ID] [--project .] [--dry-run] [--preflight]
+  beamdeploy channel promote <appId> <channel> <version> [--preflight]
+  beamdeploy channel set <appId> <channel> --bundle <version> [--preflight]
+  beamdeploy channel ensure <appId> <channel> [--self-assign] [--preflight]
+  beamdeploy stats <appId> [--preflight]
+
+Environment:
+  BEAMDEPLOY_SERVER   API server URL, defaults to http://localhost:8787
+  BEAMDEPLOY_TOKEN    Admin API key or app deploy key (overridden by --deploy-key)
+`);
+}
+function argValue(args, name, fallback = "") {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : args[index + 1] || fallback;
+}
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+async function loadConfig() {
+  try {
+    return JSON.parse(await (0, import_promises2.readFile)(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function saveConfig(config) {
+  await (0, import_promises2.mkdir)(configDir, { recursive: true });
+  await (0, import_promises2.writeFile)(configPath, JSON.stringify(config, null, 2));
+}
+async function request(pathname, options = {}) {
+  const config = await loadConfig();
+  const server = process.env.BEAMDEPLOY_SERVER || config.server || "http://localhost:8787";
+  const token = options.token || process.env.BEAMDEPLOY_TOKEN || config.token || "";
+  const headers = {
+    ...options.body instanceof Buffer ? {} : { "content-type": "application/json" },
+    ...options.headers
+  };
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+  const response = await fetch(`${server}${pathname}`, {
+    ...options,
+    headers
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const detail = payload.message ? `${payload.error || response.status}: ${payload.message}` : payload.error || "request failed";
+    throw new Error(`${response.status}: ${detail}`);
+  }
+  return payload;
+}
+var DEPLOY_SCOPE_REQUIREMENTS = {
+  upload: "bundle:upload",
+  promote: "channel:promote",
+  stats: "read:stats"
+};
+function deployKeyAllowsChannelScope(context, channel) {
+  if (!context?.channels?.length || context.channelAccess?.includes("*")) {
+    return true;
+  }
+  const normalized = String(channel || "").trim().toLowerCase();
+  if (!normalized) {
+    return true;
+  }
+  return context.channels.includes(normalized);
+}
+function assertDeployKeyPreflight(context, { appId, channel, action }) {
+  if (!context || context.kind !== "deploy_key") {
+    return;
+  }
+  if (context.appId !== appId) {
+    throw new Error(`Deploy key is scoped to app ${context.appId}, not ${appId}.`);
+  }
+  const requiredScope = DEPLOY_SCOPE_REQUIREMENTS[action];
+  if (requiredScope && !(context.scopes || []).includes(requiredScope) && !(context.scopes || []).includes("deploy:admin")) {
+    throw new Error(`Deploy key lacks ${requiredScope} scope required for ${action}. Current scopes: ${(context.scopes || []).join(", ") || "none"}.`);
+  }
+  if (channel && !deployKeyAllowsChannelScope(context, channel)) {
+    const allowed = context.channels?.length ? context.channels.join(", ") : "all channels";
+    throw new Error(`Deploy key is not allowed for channel "${channel}". Allowed channels: ${allowed}.`);
+  }
+}
+async function loadAuthContext(tokenOverride) {
+  return request("/v1/auth/context", { token: tokenOverride || void 0 });
+}
+async function resolveDeltaBaseVersion(appId, channel, explicitBase, token) {
+  if (explicitBase) {
+    return explicitBase;
+  }
+  const payload = await request(`/v1/apps/${encodeURIComponent(appId)}/channels`, {
+    token: token || void 0
+  });
+  const match = (payload.channels || []).find((row) => row.name === channel);
+  if (!match?.bundleVersion) {
+    throw new Error(
+      `Channel "${channel}" has no bundle to diff against. Upload a full bundle first or pass --delta-base <version>.`
+    );
+  }
+  return match.bundleVersion;
+}
+async function downloadBundleZip(appId, version, token) {
+  const config = await loadConfig();
+  const server = process.env.BEAMDEPLOY_SERVER || config.server || "http://localhost:8787";
+  const authToken = token || process.env.BEAMDEPLOY_TOKEN || config.token || "";
+  const headers = {};
+  if (authToken) {
+    headers.authorization = `Bearer ${authToken}`;
+  }
+  const response = await fetch(
+    `${server}/updates/${encodeURIComponent(appId)}/${encodeURIComponent(version)}.zip`,
+    { headers }
+  );
+  if (!response.ok) {
+    throw new Error(`Unable to download base bundle ${version}: HTTP ${response.status}`);
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+async function main() {
+  const [command, subcommand, ...args] = process.argv.slice(2);
+  if (!command || command === "--help" || command === "-h") {
+    usage();
+    return;
+  }
+  if (command === "init") {
+    const apiKey = subcommand || process.env.BEAMDEPLOY_TOKEN || "";
+    const server = process.env.BEAMDEPLOY_SERVER || "http://localhost:8787";
+    await (0, import_promises2.writeFile)(
+      "beamdeploy.config.json",
+      JSON.stringify(
+        {
+          server,
+          appId: "com.example.app",
+          channel: "production",
+          tokenEnv: "BEAMDEPLOY_TOKEN"
+        },
+        null,
+        2
+      )
+    );
+    if (apiKey) {
+      await saveConfig({ server, token: apiKey });
+    }
+    console.log("Created beamdeploy.config.json");
+    return;
+  }
+  if (command === "auth" && subcommand === "context") {
+    const deployKey = argValue(args, "--deploy-key", "");
+    const payload = await loadAuthContext(deployKey || void 0);
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (command === "login") {
+    const token = subcommand;
+    if (!token) throw new Error("Usage: beamdeploy login <apiKey>");
+    await saveConfig({
+      server: process.env.BEAMDEPLOY_SERVER || "http://localhost:8787",
+      token
+    });
+    console.log("Saved BeamDeploy API token.");
+    return;
+  }
+  if (command === "doctor") {
+    const server = argValue([subcommand, ...args].filter(Boolean), "--server", process.env.BEAMDEPLOY_SERVER || "http://localhost:8787");
+    const health = await fetch(`${server}/v1/health`).then((response) => response.json());
+    console.log(JSON.stringify(health, null, 2));
+    return;
+  }
+  if (command === "app" && subcommand === "create") {
+    const [appId, ...nameParts] = args;
+    if (!appId) throw new Error("Usage: beamdeploy app create <appId> [name]");
+    const payload = await request("/v1/apps", {
+      method: "POST",
+      body: JSON.stringify({ appId, name: nameParts.join(" ") || appId })
+    });
+    console.log(JSON.stringify(payload.app, null, 2));
+    return;
+  }
+  if (command === "rn" && subcommand === "upload") {
+    const [appId, version, bundleDirArg, ...rest] = args;
+    if (!appId || !version) {
+      throw new Error(
+        "Usage: beamdeploy rn upload <appId> <version> [bundleDir] --platform ios|android [--bundle <file>] [--sourcemap <file>] [--deploy-key <token>] [--channel production] [--rn-version 0.74.0] [--no-hermes] [--abi arm64-v8a] [--native-build-id ID] [--project .] [--dry-run]"
+      );
+    }
+    const platform = argValue(rest, "--platform", "");
+    if (!platform) {
+      throw new Error("beamdeploy rn upload requires --platform ios or --platform android");
+    }
+    const bundlePath = argValue(rest, "--bundle", "");
+    const sourcemapPath = argValue(rest, "--sourcemap", "");
+    const deployKey = argValue(rest, "--deploy-key", "");
+    const channel = argValue(rest, "--channel", "production");
+    const bundleDir = bundleDirArg ? import_node_path2.default.resolve(bundleDirArg) : bundlePath ? import_node_path2.default.dirname(import_node_path2.default.resolve(bundlePath)) : process.cwd();
+    const projectDir = import_node_path2.default.resolve(argValue(rest, "--project", bundleDir));
+    const rnVersion = argValue(rest, "--rn-version", "") || await readReactNativeVersion(projectDir);
+    if (!rnVersion) {
+      throw new Error("Set --rn-version or add react-native to package.json dependencies.");
+    }
+    const packed = await packRnOtaZip({
+      bundleDir: bundlePath ? bundleDir : import_node_path2.default.resolve(bundleDir),
+      bundlePath: bundlePath || void 0,
+      sourcemapPath: sourcemapPath || void 0,
+      platform,
+      rnVersion,
+      hermesEnabled: !hasFlag(rest, "--no-hermes"),
+      nativeModulesAbi: argValue(rest, "--abi", "default"),
+      nativeBuildId: argValue(rest, "--native-build-id", "")
+    });
+    const query = buildRnUploadQuery({ channel, platform, compatibility: packed.compatibility });
+    const uploadPath = `/v1/apps/${encodeURIComponent(appId)}/bundles/${encodeURIComponent(version)}?${query}`;
+    const summary = {
+      appId,
+      version,
+      platform,
+      channel,
+      nativeBuildId: packed.nativeBuildId,
+      compatibility: packed.compatibility,
+      manifest: packed.manifest,
+      zipBytes: packed.zip.length,
+      uploadPath
+    };
+    if (hasFlag(rest, "--dry-run")) {
+      console.log(JSON.stringify({ dryRun: true, ...summary }, null, 2));
+      return;
+    }
+    if (hasFlag(rest, "--preflight")) {
+      const context = await loadAuthContext(deployKey || void 0);
+      assertDeployKeyPreflight(context, { appId, channel, action: "upload" });
+      if (channel) {
+        assertDeployKeyPreflight(context, { appId, channel, action: "promote" });
+      }
+    }
+    const payload = await request(uploadPath, {
+      method: "POST",
+      headers: { "content-type": "application/zip" },
+      body: packed.zip,
+      token: deployKey || void 0
+    });
+    console.log(JSON.stringify({ ...payload, ...summary }, null, 2));
+    return;
+  }
+  if (command === "bundle" && subcommand === "upload") {
+    const [appId, version, zipPath, ...rest] = args;
+    if (!appId || !version || !zipPath) {
+      throw new Error(
+        "Usage: beamdeploy bundle upload <appId> <version> <zipPath> [--channel production] [--platform electron] [--delta] [--delta-base <version>]"
+      );
+    }
+    const channel = argValue(rest, "--channel", "production");
+    const uploadPlatform = argValue(rest, "--platform", "").toLowerCase();
+    const deployKey = argValue(rest, "--deploy-key", "");
+    const useDelta = hasFlag(rest, "--delta");
+    const deltaBaseExplicit = argValue(rest, "--delta-base", "");
+    const fullBody = await (0, import_promises2.readFile)(zipPath);
+    let uploadBody = fullBody;
+    let uploadQuery = `channel=${encodeURIComponent(channel)}`;
+    if (uploadPlatform === "electron") {
+      uploadQuery += "&platform=electron&runtime=electron";
+    } else if (uploadPlatform) {
+      throw new Error('bundle upload --platform supports only "electron" (Capacitor/RN use default or rn upload).');
+    }
+    if (hasFlag(rest, "--preflight")) {
+      const context = await loadAuthContext(deployKey || void 0);
+      assertDeployKeyPreflight(context, { appId, channel, action: "upload" });
+      assertDeployKeyPreflight(context, { appId, channel, action: "promote" });
+    }
+    if (useDelta) {
+      const baseVersion = await resolveDeltaBaseVersion(appId, channel, deltaBaseExplicit, deployKey || void 0);
+      if (baseVersion === version) {
+        throw new Error("Delta base version must differ from the version being uploaded.");
+      }
+      const baseBody = await downloadBundleZip(appId, baseVersion, deployKey || void 0);
+      const { deltaZip, changedCount, deletedCount } = await buildDeltaZipFromBundles(baseBody, fullBody, baseVersion);
+      if (shouldPreferFullUpload(deltaZip.length, fullBody.length)) {
+        console.error(
+          `Delta (${deltaZip.length} bytes) is not smaller than full bundle (${fullBody.length} bytes); uploading full zip.`
+        );
+      } else {
+        uploadBody = deltaZip;
+        uploadQuery += "&delta=1";
+        console.error(
+          `Uploading delta against ${baseVersion}: ${changedCount} changed, ${deletedCount} deleted (${deltaZip.length} bytes vs ${fullBody.length} full).`
+        );
+      }
+    }
+    const payload = await request(
+      `/v1/apps/${encodeURIComponent(appId)}/bundles/${encodeURIComponent(version)}?${uploadQuery}`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/zip" },
+        body: uploadBody,
+        token: deployKey || void 0
+      }
+    );
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (command === "bundle" && subcommand === "patch") {
+    const [appId, version, ...rest] = args;
+    if (!appId || !version) {
+      throw new Error(
+        "Usage: beamdeploy bundle patch <appId> <version> [--display-name NAME] [--description TEXT] [--notes TEXT] [--min-native V] [--max-native V] [--breaking]"
+      );
+    }
+    const body = {};
+    const displayName = argValue(rest, "--display-name", "");
+    const description = argValue(rest, "--description", "");
+    const notes = argValue(rest, "--notes", "");
+    const minNative = argValue(rest, "--min-native", "");
+    const maxNative = argValue(rest, "--max-native", "");
+    if (displayName) body.displayName = displayName;
+    if (description) body.description = description;
+    if (notes) body.notes = notes;
+    if (minNative) body.minNativeVersion = minNative;
+    if (maxNative) body.maxNativeVersion = maxNative;
+    if (hasFlag(rest, "--breaking")) body.breaking = true;
+    const payload = await request(`/v1/apps/${encodeURIComponent(appId)}/bundles/${encodeURIComponent(version)}`, {
+      method: "PATCH",
+      body: JSON.stringify(body)
+    });
+    console.log(JSON.stringify(payload.bundle, null, 2));
+    return;
+  }
+  if (command === "bundle" && subcommand === "trash") {
+    const [appId, version] = args;
+    if (!appId || !version) throw new Error("Usage: beamdeploy bundle trash <appId> <version>");
+    const payload = await request(`/v1/apps/${encodeURIComponent(appId)}/bundles/${encodeURIComponent(version)}`, {
+      method: "DELETE"
+    });
+    console.log(JSON.stringify(payload.bundle, null, 2));
+    return;
+  }
+  if (command === "bundle" && subcommand === "restore") {
+    const [appId, version] = args;
+    if (!appId || !version) throw new Error("Usage: beamdeploy bundle restore <appId> <version>");
+    const payload = await request(
+      `/v1/apps/${encodeURIComponent(appId)}/bundles/${encodeURIComponent(version)}/restore`,
+      { method: "POST" }
+    );
+    console.log(JSON.stringify(payload.bundle, null, 2));
+    return;
+  }
+  if (command === "channel" && subcommand === "trash") {
+    const [appId, channel] = args;
+    if (!appId || !channel) throw new Error("Usage: beamdeploy channel trash <appId> <channel>");
+    const payload = await request(`/v1/apps/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}`, {
+      method: "DELETE"
+    });
+    console.log(JSON.stringify(payload.channel, null, 2));
+    return;
+  }
+  if (command === "channel" && subcommand === "restore") {
+    const [appId, channel] = args;
+    if (!appId || !channel) throw new Error("Usage: beamdeploy channel restore <appId> <channel>");
+    const payload = await request(
+      `/v1/apps/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}/restore`,
+      { method: "POST" }
+    );
+    console.log(JSON.stringify(payload.channel, null, 2));
+    return;
+  }
+  if (command === "channel" && subcommand === "promote") {
+    const [appId, channel, version] = args;
+    if (!appId || !channel || !version) {
+      throw new Error("Usage: beamdeploy channel promote <appId> <channel> <version> [--preflight]");
+    }
+    const deployKey = argValue(args, "--deploy-key", "");
+    if (hasFlag(args, "--preflight")) {
+      const context = await loadAuthContext(deployKey || void 0);
+      assertDeployKeyPreflight(context, { appId, channel, action: "promote" });
+    }
+    const payload = await request(`/v1/apps/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}`, {
+      method: "PATCH",
+      body: JSON.stringify({ bundleVersion: version }),
+      token: deployKey || void 0
+    });
+    console.log(JSON.stringify(payload.channel, null, 2));
+    return;
+  }
+  if (command === "channel" && subcommand === "set") {
+    const [appId, channel, ...rest] = args;
+    const version = argValue(rest, "--bundle", "") || rest[0];
+    if (!appId || !channel || !version) {
+      throw new Error("Usage: beamdeploy channel set <appId> <channel> --bundle <version> [--preflight]");
+    }
+    const deployKey = argValue(rest, "--deploy-key", "");
+    if (hasFlag(rest, "--preflight")) {
+      const context = await loadAuthContext(deployKey || void 0);
+      assertDeployKeyPreflight(context, { appId, channel, action: "promote" });
+    }
+    const payload = await request(`/v1/apps/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}`, {
+      method: "PATCH",
+      body: JSON.stringify({ bundleVersion: version }),
+      token: deployKey || void 0
+    });
+    console.log(JSON.stringify(payload.channel, null, 2));
+    return;
+  }
+  if (command === "channel" && subcommand === "ensure") {
+    const [appId, channel, ...rest] = args;
+    if (!appId || !channel) {
+      throw new Error("Usage: beamdeploy channel ensure <appId> <channel> [--self-assign] [--preflight]");
+    }
+    const deployKey = argValue(rest, "--deploy-key", "");
+    const allowSelfAssign = hasFlag(rest, "--self-assign") || channel.startsWith("pr-");
+    if (hasFlag(rest, "--preflight")) {
+      const context = await loadAuthContext(deployKey || void 0);
+      assertDeployKeyPreflight(context, { appId, channel, action: "promote" });
+    }
+    const payload = await request(`/v1/apps/${encodeURIComponent(appId)}/channels`, {
+      method: "POST",
+      body: JSON.stringify({ name: channel, allowSelfAssign }),
+      token: deployKey || void 0
+    }).catch(async (error) => {
+      if (!String(error.message).startsWith("409:") && !String(error.message).includes("already")) {
+        throw error;
+      }
+      return request(`/v1/apps/${encodeURIComponent(appId)}/channels/${encodeURIComponent(channel)}`, {
+        method: "PATCH",
+        body: JSON.stringify({}),
+        token: deployKey || void 0
+      });
+    });
+    console.log(JSON.stringify(payload.channel, null, 2));
+    return;
+  }
+  if (command === "stats") {
+    const appId = subcommand;
+    if (!appId) throw new Error("Usage: beamdeploy stats <appId> [--preflight]");
+    const deployKey = argValue(args, "--deploy-key", "");
+    if (hasFlag(args, "--preflight")) {
+      const context = await loadAuthContext(deployKey || void 0);
+      assertDeployKeyPreflight(context, { appId, action: "stats" });
+    }
+    const payload = await request(`/v1/statistics/app/${encodeURIComponent(appId)}`, {
+      token: deployKey || void 0
+    });
+    console.log(JSON.stringify(payload.statistics, null, 2));
+    return;
+  }
+  usage();
+  process.exitCode = 1;
+}
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@beamdeploy/cli",
+  "version": "0.2.0-preview.1",
+  "description": "BeamDeploy CLI — push OTA bundles and React Native updates from CI/CD pipelines",
+  "type": "module",
+  "bin": {
+    "beamdeploy": "./dist/cli.cjs"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "esbuild src/cli.mjs --bundle --platform=node --target=node20 --format=cjs --banner:js='#!/usr/bin/env node' --external:yauzl --outfile=dist/cli.cjs",
+    "pack:check": "node ../../scripts/beamdeploy-cli-pack-check.mjs",
+    "prepack": "npm run build && npm run pack:check",
+    "prepublishOnly": "npm run build && npm run pack:check"
+  },
+  "dependencies": {
+    "yauzl": "^3.3.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "beamdeploy",
+    "ota",
+    "live-update",
+    "react-native",
+    "capacitor",
+    "ci",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beamdeploy/beamdeploy.git",
+    "directory": "packages/beamdeploy-cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}