@fireota/cli 0.1.1 → 0.3.0

package/README.md

@@ -25,53 +25,93 @@
 npm install --save-dev @fireota/cli
 ```
 
-Set two environment variables (create the API key in FireOTA → Settings → API keys):
+Set two environment variables (an admin creates the API key in FireOTA → API keys):
 
 ```sh
 FIREOTA_URL=https://ota.example.com
 FIREOTA_API_KEY=fota_sk_live_...
 ```
 
-Scopes: `release.write` (create, upload), `release.publish` (publish, pause, roll back), `rollout.write` (change rollout).
+Scopes: `release.write` (create, upload), `release.publish` (publish, pause, roll back), `rollout.write` (change rollout). Check a key with `npx fireota whoami`.
+
+Optional defaults: `FIREOTA_APP_ID`, `FIREOTA_CHANNEL`, `FIREOTA_RUNTIME`.
 
 ## Publish in one command
 
 Run from your React Native project root:
 
 ```sh
-npx fireota publish --app YOUR_APP_ID --platform android \
-  --version 1.3.1 --runtime 1.3.0 --channel production --rollout 10 --notes "Fix checkout crash"
+npx fireota publish --app YOUR_APP_ID --platform all --runtime 1.3.0 \
+  --channel production --rollout 10 --message "Fix checkout crash"
 ```
 
-This runs the React Native bundler, compiles Hermes bytecode when Hermes is enabled, packs the images next to the bundle, creates the release, uploads it to your Firebase Storage (checksum verified) and publishes it. Retries are safe: the same inputs never create a duplicate release.
+This runs the React Native bundler, compiles Hermes bytecode when Hermes is enabled, packs the images next to the bundle, creates the update, uploads it to your Firebase Storage (checksum verified) and publishes it. `--platform all` builds Android and iOS and publishes them as one update group.
+
+- **Updates are identified by their ID**, like Expo. `--version` is only an optional label (e.g. `1.3.1-hotfix`).
+- `--runtime` must equal the runtime version of the store build that should receive the update. Bump it whenever native code changes.
+- Retries are safe: the same inputs never create a duplicate update, and finished steps are skipped.
+- `--json` prints a machine-readable result; the exit code is 1 on any error.
+
+## Code signing (optional)
+
+```sh
+npx fireota signing generate --out ./fireota-keys   # fireota-private.pem stays with you
+```
 
-- `--version` must be new for each release on a channel.
-- `--runtime` must equal the runtime version of the store build that should receive it.
+Paste `fireota-public.pem` into the dashboard (app → Code signing), pass the same public key to `FireOTA.configure({ codeSigningCertificate })`, and publish with `--private-key ./fireota-keys/fireota-private.pem` (in CI: the `FIREOTA_SIGNING_KEY` secret holding the PEM text, or `FIREOTA_SIGNING_KEY_PATH`). The signature covers the package's SHA-256 plus runtime and platform; the server and the app both reject updates that don't match.
 
 ## Commands
 
 ```text
+fireota init     [--app <appId>] [--server-url <url>] [--channel production] [--dry-run]
+fireota publish  --app <appId> --platform <android|ios|all> [--runtime <x.y.z>] --message "…"
+                 [--channel production] [--rollout 10] [--version <label>] [--mandatory] [--native ">=1.4.0"]
+                 [--file update.fota] [--private-key key.pem] [--json]
 fireota bundle   --platform <android|ios> [--entry index.js] [--out update.fota] [--hermes auto|on|off]
-fireota publish  --app <appId> --platform <p> --version <x.y.z> --runtime <x.y.z>
-                 [--channel production] [--rollout 10] [--notes "…"] [--mandatory] [--native ">=1.4.0"] [--file update.fota]
-fireota release create   --app <appId> --platform <p> --version <v> --runtime <r> [--channel c]
-fireota release upload   <releaseId> --file update.fota
+fireota whoami
+fireota signing generate [--out ./fireota-keys]
+fireota release create   --app <appId> --platform <p> --runtime <r> [--message m] [--version v] [--channel c]
+fireota release upload   <releaseId> --file update.fota [--private-key key.pem]
 fireota release publish  <releaseId> [--rollout 100]
 fireota release rollout  <releaseId> --percentage <0-100>
 fireota release pause    <releaseId>
 fireota release rollback <releaseId> --reason "…" [--target <releaseId>]
-fireota releases [--app <appId>]
+fireota releases [--app <appId>] [--json]
 ```
 
-## GitHub Actions
+## CI/CD
+
+The same command works on every CI. Commit, branch and build number are detected automatically on GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps, CircleCI, Bitrise, Buildkite, Travis, TeamCity, Codemagic and AWS CodeBuild; anywhere else set `FIREOTA_GIT_SHA`, `FIREOTA_GIT_BRANCH` and `FIREOTA_BUILD_NUMBER`. Ready-made pipeline files for each tool are in the dashboard under **CI/CD**.
+
+GitHub Actions:
 
 ```yaml
-- run: npx fireota publish --app ${{ vars.FIREOTA_APP_ID }} --platform android --version 1.3.${{ github.run_number }} --runtime 1.3.0 --channel beta
+- run: npx fireota publish --app ${{ vars.FIREOTA_APP_ID }} --platform android --runtime 1.3.0 --channel beta --message "${{ github.event.head_commit.message }}"
   env:
     FIREOTA_URL: ${{ vars.FIREOTA_URL }}
     FIREOTA_API_KEY: ${{ secrets.FIREOTA_API_KEY }}
 ```
 
+Jenkins (declarative):
+
+```groovy
+environment {
+  FIREOTA_URL     = 'https://ota.example.com'
+  FIREOTA_API_KEY = credentials('fireota-api-key')
+}
+steps {
+  sh 'npm ci && npx fireota publish --app "$APP_ID" --platform android --runtime 1.3.0 --message "$(git log -1 --pretty=%s)"'
+}
+```
+
+Bitbucket Pipelines:
+
+```yaml
+script:
+  - npm ci
+  - npx fireota publish --app "$FIREOTA_APP_ID" --platform android --runtime 1.3.0 --message "$(git log -1 --pretty=%s)"
+```
+
 ## License
 
 MIT

package/bin/fireota.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 /**
- * FireOTA CLI — build update packages and manage releases from a terminal or CI.
- * Needs Node 18+. Configuration via environment:
- *   FIREOTA_URL      your FireOTA deployment, e.g. https://ota.example.com
- *   FIREOTA_API_KEY  an API key from Settings -> API keys (fota_sk_...)
+ * FireOTA CLI — build update packages and manage releases from a terminal or any CI.
+ * Needs Node 18+. Configuration via environment (flags win over environment):
+ *   FIREOTA_URL       your FireOTA deployment, e.g. https://ota.example.com
+ *   FIREOTA_API_KEY   an API key from Settings -> API keys (fota_sk_...)
+ *   FIREOTA_APP_ID, FIREOTA_CHANNEL, FIREOTA_RUNTIME   defaults for --app, --channel, --runtime
+ *   FIREOTA_SIGNING_KEY (PEM text) or FIREOTA_SIGNING_KEY_PATH   code signing private key
  */
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -11,24 +13,48 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
+import { detectCi } from "../lib/ci.mjs";
+import { runInit } from "../lib/init.mjs";
 import { packDirectory } from "../lib/package.mjs";
+import { storeVersion } from "../lib/project.mjs";
+import { generateKeys, loadPrivateKey, signUpdate } from "../lib/signing.mjs";
 
 const HELP = `FireOTA CLI
 
 Usage:
+  fireota init     [--app <appId>] [--server-url <url>] [--channel production] [--dry-run] [--force]
+                   One-time setup: creates fireota.config.js, wraps your root component with the
+                   built-in update UI, and wires MainApplication / AppDelegate for release builds.
+  fireota publish  --app <appId> --platform <android|ios|all> [--runtime <x.y.z>] --message "What changed"
+                   [--channel production] [--rollout 10] [--version <label>] [--mandatory] [--native ">=1.4.0"]
+                   [--file update.fota] [--private-key fireota-private.pem] [--json]
+                   Builds (unless --file), uploads to your Firebase Storage and publishes.
+                   --platform all publishes Android + iOS as one update group.
   fireota bundle   --platform <android|ios> [--entry index.js] [--out update.fota] [--hermes auto|on|off]
-  fireota publish  --app <appId> --platform <android|ios> --version <x.y.z> --runtime <x.y.z>
-                   [--channel production] [--rollout 10] [--notes "..."] [--mandatory] [--native ">=1.4.0"]
-                   [--file update.fota]          (builds the package first when --file is omitted)
-  fireota release create   --app <appId> --platform <p> --version <v> --runtime <r> [--channel c] [--notes n] [--mandatory] [--native c]
-  fireota release upload   <releaseId> --file update.fota
+  fireota whoami   Shows the workspace, key role and apps behind FIREOTA_API_KEY.
+  fireota signing generate [--out ./fireota-keys]   Creates an RSA key pair for code signing.
+  fireota release create   --app <appId> --platform <p> --runtime <r> [--message m] [--version v] [--channel c]
+  fireota release upload   <releaseId> --file update.fota [--private-key key.pem]
   fireota release publish  <releaseId> [--rollout 100]
   fireota release rollout  <releaseId> --percentage <0-100>
   fireota release pause    <releaseId>
   fireota release rollback <releaseId> --reason "..." [--target <releaseId>]
-  fireota releases [--app <appId>]
+  fireota releases [--app <appId>] [--json]
 
-Environment: FIREOTA_URL, FIREOTA_API_KEY. Run from your React Native project root.`;
+Updates are identified by their ID (like Expo): --version is only an optional label, and
+--runtime must equal the runtime version of the store build the update is for. Without
+--runtime, the app's store version is used (android/app/build.gradle versionName, iOS
+MARKETING_VERSION) — the same default the SDK uses.
+
+Environment: FIREOTA_URL, FIREOTA_API_KEY (required); FIREOTA_APP_ID, FIREOTA_CHANNEL,
+FIREOTA_RUNTIME, FIREOTA_SIGNING_KEY / FIREOTA_SIGNING_KEY_PATH (optional).
+Works on GitHub Actions, GitLab, Bitbucket, Jenkins, Azure DevOps, CircleCI, Bitrise and any
+other CI: commit, branch and build number are detected automatically.
+Exit codes: 0 success, 1 error.`;
+
+let jsonMode = false;
+/** Human progress goes to stderr in --json mode so stdout stays machine-readable. */
+const log = (...args) => (jsonMode ? console.error(...args) : console.log(...args));
 
 function parseArgs(argv) {
   const positional = [];
@@ -49,13 +75,14 @@ function parseArgs(argv) {
 }
 
 function fail(message) {
+  if (jsonMode) console.log(JSON.stringify({ ok: false, error: message }));
   console.error(`fireota: ${message}`);
   process.exit(1);
 }
 
-function need(flags, key) {
-  const value = flags[key];
-  if (value === undefined || value === true) fail(`--${key} is required`);
+function need(flags, key, envName) {
+  const value = flags[key] ?? (envName ? process.env[envName] : undefined);
+  if (value === undefined || value === true || value === "") fail(`--${key} is required${envName ? ` (or set ${envName})` : ""}`);
   return String(value);
 }
 
@@ -63,6 +90,12 @@ function sha256(buffer) {
   return createHash("sha256").update(buffer).digest("hex");
 }
 
+/** Deterministic RFC-4122-shaped id, so a retried CI job reuses the same update group. */
+function groupIdFrom(seed) {
+  const h = sha256(Buffer.from(seed));
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
 // ---------- packaging ----------
 
 function hermesEnabled(platform, mode) {
@@ -88,8 +121,8 @@ function hermesc() {
 }
 
 /** Runs the React Native bundler (+ Hermes) and packs bundle and assets into one update file. */
-function bundle(flags) {
-  const platform = need(flags, "platform");
+function bundle(flags, platformOverride) {
+  const platform = platformOverride ?? need(flags, "platform");
   if (!["android", "ios"].includes(platform)) fail("--platform must be android or ios");
   if (!existsSync("package.json") || !existsSync(join("node_modules", "react-native"))) {
     fail("Run this from your React Native project root (react-native must be installed).");
@@ -100,25 +133,27 @@ function bundle(flags) {
   const out = join(work, "package");
   try {
     const jsOut = join(work, "bundle.js");
-    console.log(`Bundling ${entry} for ${platform}…`);
+    log(`Bundling ${entry} for ${platform}…`);
     // Run the project's own React Native CLI through Node: no shell, same on every OS.
     execFileSync(
       process.execPath,
       [join("node_modules", "react-native", "cli.js"), "bundle", "--platform", platform, "--dev", "false", "--minify", "false", "--entry-file", entry, "--bundle-output", jsOut, "--assets-dest", out],
-      { stdio: "inherit" },
+      { stdio: jsonMode ? ["ignore", "ignore", "inherit"] : "inherit" },
     );
     // The bundler only creates the assets folder when the app has images.
     mkdirSync(out, { recursive: true });
     if (hermesEnabled(platform, String(flags.hermes ?? "auto"))) {
-      console.log("Compiling to Hermes bytecode…");
-      execFileSync(hermesc(), ["-O", "-w", "-emit-binary", "-out", join(out, bundleName), jsOut], { stdio: "inherit" });
+      log("Compiling to Hermes bytecode…");
+      execFileSync(hermesc(), ["-O", "-w", "-emit-binary", "-out", join(out, bundleName), jsOut], {
+        stdio: jsonMode ? ["ignore", "ignore", "inherit"] : "inherit",
+      });
     } else {
       writeFileSync(join(out, bundleName), readFileSync(jsOut));
     }
     const packed = packDirectory(out);
-    const target = resolve(String(flags.out ?? `fireota-${platform}.fota`));
+    const target = resolve(String(flags.out && !platformOverride ? flags.out : `fireota-${platform}.fota`));
     writeFileSync(target, packed);
-    console.log(`Package: ${target}\nSize:    ${(packed.length / 1024 / 1024).toFixed(2)} MB\nSHA-256: ${sha256(packed)}`);
+    log(`Package: ${target}\nSize:    ${(packed.length / 1024 / 1024).toFixed(2)} MB\nSHA-256: ${sha256(packed)}`);
     return target;
   } finally {
     rmSync(work, { recursive: true, force: true });
@@ -132,13 +167,18 @@ async function api(method, path, body, extraHeaders = {}) {
   const key = process.env.FIREOTA_API_KEY;
   if (!base) fail("Set FIREOTA_URL to your FireOTA deployment URL.");
   if (!key) fail("Set FIREOTA_API_KEY (Settings -> API keys).");
-  const headers = { authorization: `Bearer ${key}`, ...extraHeaders };
+  const headers = { authorization: `Bearer ${key}`, "user-agent": "fireota-cli", ...extraHeaders };
   let payload = body;
   if (body && !(body instanceof FormData)) {
     headers["content-type"] = "application/json";
     payload = JSON.stringify(body);
   }
-  const response = await fetch(`${base.replace(/\/+$/, "")}/api/public/v1${path}`, { method, headers, body: payload });
+  let response;
+  try {
+    response = await fetch(`${base.replace(/\/+$/, "")}/api/public/v1${path}`, { method, headers, body: payload });
+  } catch (error) {
+    fail(`Could not reach ${base}: ${error instanceof Error ? error.message : error}`);
+  }
   let json;
   try {
     json = await response.json();
@@ -149,34 +189,53 @@ async function api(method, path, body, extraHeaders = {}) {
   return json.data;
 }
 
-async function createRelease(flags) {
+/** --runtime / FIREOTA_RUNTIME, else the app's store version for that platform. */
+function runtimeFor(flags, platform) {
+  const explicit = flags.runtime ?? process.env.FIREOTA_RUNTIME;
+  if (explicit && explicit !== true) return String(explicit);
+  const detected = storeVersion(platform);
+  if (!detected) fail(`Could not read the ${platform} app version; pass --runtime <x.y.z>.`);
+  return detected;
+}
+
+async function createRelease(flags, platform, extra = {}) {
+  const ci = detectCi();
+  const message = flags.message ?? flags.notes;
   const body = {
-    appId: need(flags, "app"),
-    channel: String(flags.channel ?? "production"),
-    platform: need(flags, "platform"),
-    version: need(flags, "version"),
-    runtimeVersion: need(flags, "runtime"),
-    ...(flags.notes ? { releaseNotes: String(flags.notes) } : {}),
+    appId: need(flags, "app", "FIREOTA_APP_ID"),
+    channel: String(flags.channel ?? process.env.FIREOTA_CHANNEL ?? "production"),
+    platform,
+    runtimeVersion: runtimeFor(flags, platform),
+    ...(flags.version && flags.version !== true ? { version: String(flags.version) } : {}),
+    ...(message && message !== true ? { releaseNotes: String(message) } : {}),
     ...(flags.mandatory ? { mandatory: true } : {}),
     ...(flags.native ? { nativeVersionConstraint: String(flags.native) } : {}),
-    ...(process.env.GITHUB_SHA ? { gitCommitSha: process.env.GITHUB_SHA } : {}),
-    ...(process.env.GITHUB_REF_NAME ? { gitBranch: process.env.GITHUB_REF_NAME } : {}),
+    ...(ci.gitCommitSha ? { gitCommitSha: ci.gitCommitSha.slice(0, 64) } : {}),
+    ...(ci.gitBranch ? { gitBranch: ci.gitBranch.slice(0, 120) } : {}),
+    ...(ci.buildNumber ? { buildNumber: String(ci.buildNumber).slice(0, 40) } : {}),
+    ...extra,
   };
   // Same inputs -> same release, so a retried CI job never creates duplicates.
   const idempotencyKey = sha256(Buffer.from(JSON.stringify(body)));
   const release = await api("POST", "/releases", body, { "idempotency-key": idempotencyKey });
-  console.log(`Release #${release.number} (${release.id}) — ${release.status}`);
+  log(`Update #${release.number} (${release.id}) — ${release.status} [${platform}, ${ci.provider}]`);
   return release;
 }
 
-async function uploadRelease(releaseId, file) {
+async function uploadRelease(releaseId, file, signing) {
   if (!existsSync(file)) fail(`File not found: ${file}`);
   const bytes = readFileSync(file);
+  const hash = sha256(bytes);
   const form = new FormData();
   form.append("bundle", new Blob([bytes], { type: "application/octet-stream" }), "update.fota");
-  console.log(`Uploading ${(bytes.length / 1024 / 1024).toFixed(2)} MB…`);
-  const result = await api("POST", `/releases/${releaseId}/bundle`, form, { "x-bundle-sha256": sha256(bytes) });
-  console.log(`Verified in your Firebase Storage. SHA-256 ${result.checksum}`);
+  const headers = { "x-bundle-sha256": hash };
+  if (signing?.key) {
+    headers["x-fireota-signature"] = signUpdate(signing.key, { runtimeVersion: signing.runtimeVersion, platform: signing.platform, sha256: hash });
+    log("Signed with your code signing key.");
+  }
+  log(`Uploading ${(bytes.length / 1024 / 1024).toFixed(2)} MB…`);
+  const result = await api("POST", `/releases/${releaseId}/bundle`, form, headers);
+  log(`Verified in your Firebase Storage. SHA-256 ${result.checksum}`);
   return result;
 }
 
@@ -184,9 +243,28 @@ async function releaseAction(releaseId, body) {
   return api("POST", `/releases/${releaseId}/publish`, body);
 }
 
+/** Create → upload → publish, skipping steps a retried CI job already completed. */
+async function publishOne(flags, platform, file, extra, privateKey) {
+  const release = await createRelease(flags, platform, extra);
+  if (["draft", "failed", "uploading"].includes(release.status)) {
+    await uploadRelease(release.id, file, privateKey ? { key: privateKey, runtimeVersion: runtimeFor(flags, platform), platform } : null);
+  } else {
+    log(`Bundle already uploaded (status ${release.status}); skipping upload.`);
+  }
+  const rollout = Number(flags.rollout ?? 100);
+  if (release.status === "published") {
+    log("Already published; nothing to do.");
+    return { id: release.id, number: release.number, platform, rollout: null, status: "published" };
+  }
+  const result = await releaseAction(release.id, { action: "publish", rolloutPercentage: rollout });
+  log(`Published update #${release.number} (${platform}) at ${result.rollout}%.`);
+  return { id: release.id, number: release.number, platform, rollout: result.rollout, status: "published" };
+}
+
 async function main() {
   const [command, sub, ...rest] = process.argv.slice(2);
   const { positional, flags } = parseArgs([sub, ...rest].filter((v) => v !== undefined));
+  jsonMode = Boolean(flags.json);
 
   if (!command || command === "help" || command === "--help" || flags.help) {
     console.log(HELP);
@@ -196,53 +274,135 @@ async function main() {
     bundle(parseArgs(process.argv.slice(3)).flags);
     return;
   }
+  if (command === "init") {
+    const all = parseArgs(process.argv.slice(3)).flags;
+    const result = await runInit(all, { api, log, fail });
+    console.log(result.dry ? "\nFireOTA init (dry run — nothing written):\n" : "\nFireOTA is set up:\n");
+    for (const [mark, text] of result.results) console.log(`  ${mark} ${text}`);
+    const versions = [
+      result.runtime.android ? `Android ${result.runtime.android}` : null,
+      result.runtime.ios ? `iOS ${result.runtime.ios}` : null,
+    ].filter(Boolean);
+    console.log(`
+Runtime version: ${versions.join(", ") || "unknown"} (your store version — bump it when native code changes).
+
+Next:
+  1. Rebuild the app once (release build / store build): npx react-native run-android --mode release${result.runtime.ios ? "\n     iOS: cd ios && pod install" : ""}
+  2. Publish an update:  FIREOTA_URL=${result.serverUrl} FIREOTA_API_KEY=… npm run ota:publish -- --message "What changed"
+  3. Optional: show <UpdateScreen /> from '@fireota/react-native' in your settings.`);
+    if (result.results.some(([mark]) => mark === "!")) console.log("\nSteps marked ! need a manual change — see https://github.com/Sujay-Dynamisch/FireOTA#readme");
+    return;
+  }
+  if (command === "whoami") {
+    const me = await api("GET", "/me");
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, ...me }));
+      return;
+    }
+    console.log(`Workspace: ${me.organization.name} (${me.organization.slug})\nKey:       ${me.key.label} — acts as ${me.key.role}\nApps:`);
+    for (const app of me.apps) {
+      console.log(`  ${app.name}\t${app.id}\truntime ${app.runtimeVersion}${app.requiresSignedUpdates ? "\tsigned updates required" : ""}`);
+    }
+    return;
+  }
+  if (command === "signing") {
+    if (positional[0] !== "generate") fail("usage: fireota signing generate [--out ./fireota-keys]");
+    const keys = generateKeys(flags.out && flags.out !== true ? String(flags.out) : undefined);
+    console.log(`Created ${keys.privatePath} (keep secret — never commit it)\nCreated ${keys.publicPath}
+
+Next:
+  1. Dashboard → Applications → your app → Code signing: paste ${keys.publicPath}
+  2. In the app: FireOTA.configure({ …, codeSigningCertificate: <contents of fireota-public.pem> })
+  3. Publish with --private-key ${keys.privatePath}  (in CI: store the file as the FIREOTA_SIGNING_KEY secret)`);
+    return;
+  }
   if (command === "releases") {
-    const query = flags.app ? `?appId=${encodeURIComponent(String(flags.app))}` : "";
+    const app = flags.app ?? process.env.FIREOTA_APP_ID;
+    const query = app ? `?appId=${encodeURIComponent(String(app))}` : "";
     const rows = await api("GET", `/releases${query}`);
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, releases: rows }));
+      return;
+    }
     for (const r of rows) {
-      console.log(`#${r.number}\t${r.platform}\t${r.version}\t${r.status}\t${r.rollout_percentage}%\t${r.id}`);
+      console.log(`#${r.number}\t${r.id.slice(0, 8)}\t${r.platform}\truntime ${r.runtime_version}\t${r.status}\t${r.rollout_percentage}%\t${r.version || "-"}\t${(r.release_notes || "").split("\n")[0]}`);
     }
     return;
   }
   if (command === "publish") {
     const all = parseArgs(process.argv.slice(3)).flags;
-    const file = all.file ? String(all.file) : bundle(all);
-    const release = await createRelease(all);
-    await uploadRelease(release.id, file);
-    const result = await releaseAction(release.id, { action: "publish", rolloutPercentage: Number(all.rollout ?? 100) });
-    console.log(`Published #${release.number} at ${result.rollout}%.`);
+    jsonMode = Boolean(all.json);
+    const platform = need(all, "platform");
+    if (!["android", "ios", "all"].includes(platform)) fail("--platform must be android, ios or all");
+    if (platform === "all" && all.file) fail("--file cannot be combined with --platform all (each platform needs its own package).");
+    let privateKey = null;
+    try {
+      privateKey = loadPrivateKey(all["private-key"] && all["private-key"] !== true ? String(all["private-key"]) : undefined);
+    } catch (error) {
+      fail(`Could not read the signing key: ${error instanceof Error ? error.message : error}`);
+    }
+
+    const platforms = platform === "all" ? ["android", "ios"] : [platform];
+    const files = Object.fromEntries(platforms.map((p) => [p, all.file ? String(all.file) : bundle(all, p)]));
+    // Android + iOS built from the same commit form one update group (Expo-style).
+    const extra =
+      platform === "all"
+        ? { groupId: groupIdFrom(platforms.map((p) => `${sha256(readFileSync(files[p]))}@${runtimeFor(all, p)}`).join(":")) }
+        : {};
+    const results = [];
+    for (const p of platforms) results.push(await publishOne(all, p, files[p], extra, privateKey));
+    if (jsonMode) console.log(JSON.stringify({ ok: true, groupId: extra.groupId ?? null, updates: results }));
     return;
   }
   if (command === "release") {
     const id = positional[1];
     switch (positional[0]) {
-      case "create":
-        await createRelease(flags);
+      case "create": {
+        const r = await createRelease(flags, need(flags, "platform"));
+        if (jsonMode) console.log(JSON.stringify({ ok: true, ...r }));
         return;
-      case "upload":
-        await uploadRelease(id ?? fail("release id required"), need(flags, "file"));
+      }
+      case "upload": {
+        let privateKey = null;
+        try {
+          privateKey = loadPrivateKey(flags["private-key"] && flags["private-key"] !== true ? String(flags["private-key"]) : undefined);
+        } catch (error) {
+          fail(`Could not read the signing key: ${error instanceof Error ? error.message : error}`);
+        }
+        let signing = null;
+        if (privateKey) {
+          const list = await api("GET", "/releases?limit=200");
+          const target = list.find((r) => r.id === id);
+          if (!target) fail("Release not found (needed to sign it).");
+          signing = { key: privateKey, runtimeVersion: target.runtime_version, platform: target.platform };
+        }
+        const r = await uploadRelease(id ?? fail("release id required"), need(flags, "file"), signing);
+        if (jsonMode) console.log(JSON.stringify({ ok: true, ...r }));
         return;
+      }
       case "publish": {
         const r = await releaseAction(id ?? fail("release id required"), { action: "publish", rolloutPercentage: Number(flags.rollout ?? 100) });
-        console.log(`Published at ${r.rollout}%.`);
+        jsonMode ? console.log(JSON.stringify({ ok: true, ...r })) : console.log(`Published at ${r.rollout}%.`);
         return;
       }
       case "rollout": {
         const r = await releaseAction(id ?? fail("release id required"), { action: "rollout", rolloutPercentage: Number(need(flags, "percentage")) });
-        console.log(`Rollout set to ${r.rollout}%.`);
+        jsonMode ? console.log(JSON.stringify({ ok: true, ...r })) : console.log(`Rollout set to ${r.rollout}%.`);
         return;
       }
-      case "pause":
-        await releaseAction(id ?? fail("release id required"), { action: "pause" });
-        console.log("Paused.");
+      case "pause": {
+        const r = await releaseAction(id ?? fail("release id required"), { action: "pause" });
+        jsonMode ? console.log(JSON.stringify({ ok: true, ...r })) : console.log("Paused.");
         return;
+      }
       case "rollback": {
         const r = await releaseAction(id ?? fail("release id required"), {
           action: "rollback",
           reason: need(flags, "reason"),
           ...(flags.target ? { targetReleaseId: String(flags.target) } : {}),
         });
-        console.log(r.restoredReleaseId ? `Rolled back; now serving ${r.restoredReleaseId}.` : "Rolled back; channel has no active release.");
+        if (jsonMode) console.log(JSON.stringify({ ok: true, ...r }));
+        else console.log(r.restoredReleaseId ? `Rolled back; now serving ${r.restoredReleaseId}.` : "Rolled back; channel has no active release.");
         return;
       }
       default:

package/lib/ci.mjs

@@ -0,0 +1,53 @@
+/**
+ * Detects the CI provider and the commit/branch/build being released, so `fireota publish`
+ * records the same metadata on GitHub Actions, GitLab, Bitbucket, Jenkins, Azure DevOps,
+ * CircleCI, Bitrise, Buildkite, Travis, TeamCity, Codemagic, AWS CodeBuild — or any other
+ * tool through the FIREOTA_GIT_SHA / FIREOTA_GIT_BRANCH / FIREOTA_BUILD_NUMBER variables.
+ */
+import { execFileSync } from "node:child_process";
+
+const env = process.env;
+
+const PROVIDERS = [
+  { name: "GitHub Actions", when: () => env.GITHUB_ACTIONS === "true", sha: "GITHUB_SHA", branch: "GITHUB_REF_NAME", build: "GITHUB_RUN_NUMBER" },
+  { name: "GitLab CI", when: () => env.GITLAB_CI === "true", sha: "CI_COMMIT_SHA", branch: "CI_COMMIT_REF_NAME", build: "CI_PIPELINE_IID" },
+  { name: "Bitbucket Pipelines", when: () => Boolean(env.BITBUCKET_BUILD_NUMBER), sha: "BITBUCKET_COMMIT", branch: "BITBUCKET_BRANCH", build: "BITBUCKET_BUILD_NUMBER" },
+  { name: "Jenkins", when: () => Boolean(env.JENKINS_URL), sha: "GIT_COMMIT", branch: ["BRANCH_NAME", "GIT_BRANCH"], build: "BUILD_NUMBER" },
+  { name: "Azure Pipelines", when: () => env.TF_BUILD === "True", sha: "BUILD_SOURCEVERSION", branch: "BUILD_SOURCEBRANCHNAME", build: "BUILD_BUILDNUMBER" },
+  { name: "CircleCI", when: () => env.CIRCLECI === "true", sha: "CIRCLE_SHA1", branch: "CIRCLE_BRANCH", build: "CIRCLE_BUILD_NUM" },
+  { name: "Bitrise", when: () => env.BITRISE_IO === "true", sha: "BITRISE_GIT_COMMIT", branch: "BITRISE_GIT_BRANCH", build: "BITRISE_BUILD_NUMBER" },
+  { name: "Buildkite", when: () => env.BUILDKITE === "true", sha: "BUILDKITE_COMMIT", branch: "BUILDKITE_BRANCH", build: "BUILDKITE_BUILD_NUMBER" },
+  { name: "Travis CI", when: () => env.TRAVIS === "true", sha: "TRAVIS_COMMIT", branch: "TRAVIS_BRANCH", build: "TRAVIS_BUILD_NUMBER" },
+  { name: "TeamCity", when: () => Boolean(env.TEAMCITY_VERSION), sha: "BUILD_VCS_NUMBER", branch: "TEAMCITY_BUILD_BRANCH", build: "BUILD_NUMBER" },
+  { name: "Codemagic", when: () => env.CM_BUILD_ID !== undefined, sha: "CM_COMMIT", branch: "CM_BRANCH", build: "BUILD_NUMBER" },
+  { name: "AWS CodeBuild", when: () => Boolean(env.CODEBUILD_BUILD_ID), sha: "CODEBUILD_RESOLVED_SOURCE_VERSION", branch: "CODEBUILD_WEBHOOK_HEAD_REF", build: "CODEBUILD_BUILD_NUMBER" },
+];
+
+function pick(keys) {
+  for (const key of [keys].flat()) if (env[key]) return env[key];
+  return undefined;
+}
+
+function git(args) {
+  try {
+    return execFileSync("git", args, { stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function detectCi() {
+  const provider = PROVIDERS.find((p) => p.when());
+  const ci = Boolean(provider) || env.CI === "true" || env.CI === "1";
+  const branch = (env.FIREOTA_GIT_BRANCH ?? (provider ? pick(provider.branch) : undefined) ?? git(["rev-parse", "--abbrev-ref", "HEAD"]))?.replace(
+    /^(refs\/heads\/|origin\/)/,
+    "",
+  );
+  return {
+    ci,
+    provider: provider?.name ?? (ci ? "CI" : "local"),
+    gitCommitSha: env.FIREOTA_GIT_SHA ?? (provider ? pick(provider.sha) : undefined) ?? git(["rev-parse", "HEAD"]),
+    gitBranch: branch && branch !== "HEAD" ? branch : undefined,
+    buildNumber: env.FIREOTA_BUILD_NUMBER ?? (provider ? pick(provider.build) : undefined),
+  };
+}

package/lib/init.mjs

@@ -0,0 +1,238 @@
+/**
+ * `npx fireota init` — wires FireOTA into a React Native project in one step:
+ *   fireota.config.js   app ID, server URL, channel (no secrets; safe to commit)
+ *   index.js            wraps the root component with withFireOTA(App, config)
+ *   MainApplication     release builds load the latest verified OTA bundle (Android)
+ *   AppDelegate         release builds load the latest verified OTA bundle (iOS)
+ *   package.json        "ota:publish" script
+ *   .gitignore          update packages and the code signing private key
+ * Every step is idempotent and skipped when already done; nothing is overwritten.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { androidVersionName, findFile, iosMarketingVersion } from "./project.mjs";
+
+const IMPORT_SDK = "dev.fireota.reactnative.FireOTA";
+
+/** Finds the ")" that closes the "(" at `open`. */
+function closingParen(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i += 1) {
+    if (text[i] === "(") depth += 1;
+    else if (text[i] === ")") {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function addKotlinImport(source) {
+  if (source.includes(`import ${IMPORT_SDK}`)) return source;
+  const imports = [...source.matchAll(/^import .+$/gm)];
+  const last = imports.at(-1);
+  if (!last) return source.replace(/^(package .+)$/m, `$1\n\nimport ${IMPORT_SDK}`);
+  const at = last.index + last[0].length;
+  return `${source.slice(0, at)}\nimport ${IMPORT_SDK}${source.slice(at)}`;
+}
+
+/** Returns the patched MainApplication source, or null when no known template matched. */
+export function patchMainApplication(source, isKotlin) {
+  if (source.includes("FireOTA.getJSBundleFile")) return { source, status: "already" };
+  if (isKotlin) {
+    // React Native 0.76+: getDefaultReactHost(context = …, packageList = …)
+    const call = source.indexOf("getDefaultReactHost(");
+    if (call !== -1) {
+      const open = call + "getDefaultReactHost".length;
+      const close = closingParen(source, open);
+      if (close !== -1) {
+        let head = source.slice(0, close).replace(/\s+$/, "");
+        if (!head.endsWith(",") && !head.endsWith("(")) head += ",";
+        const patched =
+          `${head}\n      // FireOTA: release builds load the latest verified OTA bundle (null = bundle in the APK).\n` +
+          `      jsBundleFilePath = if (BuildConfig.DEBUG) null else FireOTA.getJSBundleFile(applicationContext),\n    ` +
+          source.slice(close);
+        return { source: addKotlinImport(patched), status: "patched" };
+      }
+    }
+    // Older templates: object : DefaultReactNativeHost(this) { … }
+    const host = /object\s*:\s*DefaultReactNativeHost\(this\)\s*\{/.exec(source);
+    if (host) {
+      const at = host.index + host[0].length;
+      const method =
+        "\n        // FireOTA: release builds load the latest verified OTA bundle.\n" +
+        "        override fun getJSBundleFile(): String? =\n" +
+        "          if (BuildConfig.DEBUG) super.getJSBundleFile()\n" +
+        "          else FireOTA.getJSBundleFile(applicationContext) ?: super.getJSBundleFile()\n";
+      return { source: addKotlinImport(source.slice(0, at) + method + source.slice(at)), status: "patched" };
+    }
+    return { source, status: "unknown" };
+  }
+  const host = /new\s+DefaultReactNativeHost\(this\)\s*\{/.exec(source);
+  if (!host) return { source, status: "unknown" };
+  const at = host.index + host[0].length;
+  const method =
+    "\n        // FireOTA: release builds load the latest verified OTA bundle.\n" +
+    "        @Override\n        protected String getJSBundleFile() {\n" +
+    "          if (BuildConfig.DEBUG) return super.getJSBundleFile();\n" +
+    "          String ota = FireOTA.getJSBundleFile(getApplicationContext());\n" +
+    "          return ota != null ? ota : super.getJSBundleFile();\n        }\n";
+  let patched = source.slice(0, at) + method + source.slice(at);
+  if (!patched.includes(`import ${IMPORT_SDK};`)) patched = patched.replace(/^(package .+;)$/m, `$1\n\nimport ${IMPORT_SDK};`);
+  return { source: patched, status: "patched" };
+}
+
+const SWIFT_HELPER = `
+
+/// FireOTA: the latest verified OTA bundle, or nil to use the one in the app binary.
+/// Looked up at runtime, so no bridging header is needed.
+private func fireOTABundleURL() -> URL? {
+  guard let fireOTA: AnyClass = NSClassFromString("FireOTA") else { return nil }
+  return (fireOTA as AnyObject).perform(NSSelectorFromString("bundleURL"))?.takeUnretainedValue() as? URL
+}
+`;
+
+export function patchAppDelegate(source, isSwift) {
+  if (source.includes("fireOTABundleURL") || source.includes("[FireOTA bundleURL]")) return { source, status: "already" };
+  if (isSwift) {
+    const target = 'Bundle.main.url(forResource: "main", withExtension: "jsbundle")';
+    if (!source.includes(target)) return { source, status: "unknown" };
+    return { source: source.replace(target, `fireOTABundleURL() ?? ${target}`) + SWIFT_HELPER, status: "patched" };
+  }
+  const target = '[[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"]';
+  if (!source.includes(target)) return { source, status: "unknown" };
+  let patched = source.replace(target, `[FireOTA bundleURL] ?: ${target}`);
+  patched = patched.replace(/^(#import .+)$/m, `$1\n#import <FireOTA.h>`);
+  return { source: patched, status: "patched" };
+}
+
+/** Wraps AppRegistry.registerComponent(name, () => App) with withFireOTA(App, fireotaConfig). */
+export function patchEntry(source, configImport) {
+  if (source.includes("withFireOTA")) return { source, status: "already" };
+  if (source.includes("FireOTA.configure")) return { source, status: "manual-configure" };
+  const re = /AppRegistry\.registerComponent\(\s*([^,]+?)\s*,\s*\(\)\s*=>\s*([A-Za-z_$][\w$]*)\s*\)/;
+  if (!re.test(source)) return { source, status: "unknown" };
+  let patched = source.replace(re, "AppRegistry.registerComponent($1, () => withFireOTA($2, fireotaConfig))");
+  const imports = [...patched.matchAll(/^import .+$/gm)];
+  const last = imports.at(-1);
+  const lines = `import { withFireOTA } from '@fireota/react-native';\nimport fireotaConfig from '${configImport}';`;
+  patched = last ? `${patched.slice(0, last.index + last[0].length)}\n${lines}${patched.slice(last.index + last[0].length)}` : `${lines}\n${patched}`;
+  return { source: patched, status: "patched" };
+}
+
+function configFile({ appId, serverUrl, channel, certificate }) {
+  return `// FireOTA settings — created by \`npx fireota init\`. No secrets here; safe to commit.
+// runtimeVersion defaults to the app's store version (Android versionName / iOS
+// CFBundleShortVersionString): bump that version whenever native code changes.
+
+/** @type {import('@fireota/react-native').FireOTAConfig} */
+const fireotaConfig = {
+  appId: '${appId}',
+  serverUrl: '${serverUrl}',
+  channel: __DEV__ ? 'development' : '${channel}',
+  checkOnAppStart: true,
+  installMode: 'nextRestart', // normal updates apply on the next launch (with a "Restart" prompt)
+  mandatoryInstallMode: 'immediate',${certificate ? `\n  codeSigningCertificate: \`${certificate.trim()}\`,` : ""}
+};
+
+export default fireotaConfig;
+`;
+}
+
+async function ask(question) {
+  if (!process.stdin.isTTY) return "";
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runInit(flags, { api, log, fail }) {
+  if (!existsSync("package.json") || !existsSync(join("node_modules", "react-native"))) {
+    fail("Run this from your React Native project root (react-native must be installed).");
+  }
+  if (!existsSync(join("node_modules", "@fireota", "react-native"))) {
+    fail("Install the SDK first: npm install @fireota/react-native");
+  }
+  const dry = Boolean(flags["dry-run"]);
+  const results = [];
+  const write = (path, content, label) => {
+    if (!dry) writeFileSync(path, content);
+    results.push(["✓", label]);
+  };
+
+  // 1. Settings ------------------------------------------------------------
+  let serverUrl = String(flags["server-url"] ?? process.env.FIREOTA_URL ?? "").replace(/\/+$/, "");
+  let appId = String(flags.app ?? process.env.FIREOTA_APP_ID ?? "");
+  if (!appId && process.env.FIREOTA_API_KEY && serverUrl) {
+    const me = await api("GET", "/me");
+    if (me.apps.length === 1) appId = me.apps[0].id;
+    else if (me.apps.length > 1) {
+      log("Applications in this workspace:");
+      for (const app of me.apps) log(`  ${app.id}  ${app.name}`);
+    }
+  }
+  if (!serverUrl) serverUrl = (await ask("FireOTA URL (e.g. https://fireota.example.com): ")).replace(/\/+$/, "");
+  if (!appId) appId = await ask("App ID (Dashboard → Applications → your app): ");
+  if (!serverUrl || !appId) fail("Pass --server-url and --app (or set FIREOTA_URL and FIREOTA_APP_ID).");
+  const channel = String(flags.channel ?? "production");
+
+  const configPath = "fireota.config.js";
+  const certificatePath = join("fireota-keys", "fireota-public.pem");
+  const certificate = existsSync(certificatePath) ? readFileSync(certificatePath, "utf8") : null;
+  if (existsSync(configPath) && !flags.force) results.push(["–", `${configPath} exists (kept; --force to rewrite)`]);
+  else write(configPath, configFile({ appId, serverUrl, channel, certificate }), `${configPath} created${certificate ? " (with code signing certificate)" : ""}`);
+
+  // 2. JS entry ------------------------------------------------------------
+  const entry = ["index.js", "index.ts", "index.tsx"].find((f) => existsSync(f));
+  if (!entry) results.push(["!", "No index.js found — wrap your root component: withFireOTA(App, fireotaConfig)"]);
+  else {
+    const res = patchEntry(readFileSync(entry, "utf8"), "./fireota.config");
+    if (res.status === "patched") write(entry, res.source, `${entry}: root component wrapped with withFireOTA()`);
+    else if (res.status === "already") results.push(["–", `${entry} already uses withFireOTA`]);
+    else if (res.status === "manual-configure") results.push(["–", `${entry} already calls FireOTA.configure() (left as is)`]);
+    else results.push(["!", `${entry}: wrap your root component manually: withFireOTA(App, fireotaConfig)`]);
+  }
+
+  // 3. Android -------------------------------------------------------------
+  const mainApp = findFile(join("android", "app", "src", "main"), (n) => n === "MainApplication.kt" || n === "MainApplication.java");
+  if (!mainApp) results.push(["!", "Android: MainApplication not found — see the Android setup docs"]);
+  else {
+    const res = patchMainApplication(readFileSync(mainApp, "utf8"), mainApp.endsWith(".kt"));
+    const rel = relative(".", mainApp);
+    if (res.status === "patched") write(mainApp, res.source, `${rel}: loads the OTA bundle in release builds`);
+    else if (res.status === "already") results.push(["–", `${rel} already loads FireOTA`]);
+    else results.push(["!", `${rel}: unknown template — add FireOTA.getJSBundleFile() as in the Android setup docs`]);
+  }
+
+  // 4. iOS -----------------------------------------------------------------
+  const delegate = findFile("ios", (n) => n === "AppDelegate.swift" || n === "AppDelegate.mm" || n === "AppDelegate.m", 3);
+  if (!delegate) results.push(["–", "iOS: no AppDelegate found (skipped)"]);
+  else {
+    const res = patchAppDelegate(readFileSync(delegate, "utf8"), delegate.endsWith(".swift"));
+    const rel = relative(".", delegate);
+    if (res.status === "patched") write(delegate, res.source, `${rel}: loads the OTA bundle in release builds (run pod install)`);
+    else if (res.status === "already") results.push(["–", `${rel} already loads FireOTA`]);
+    else results.push(["!", `${rel}: unknown template — return [FireOTA bundleURL] in bundleURL (see iOS setup docs)`]);
+  }
+
+  // 5. package.json script + .gitignore ------------------------------------
+  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+  pkg.scripts ??= {};
+  if (pkg.scripts["ota:publish"]) results.push(["–", 'package.json already has "ota:publish"']);
+  else {
+    pkg.scripts["ota:publish"] = "fireota publish --platform all";
+    write("package.json", `${JSON.stringify(pkg, null, 2)}\n`, 'package.json: added "ota:publish" script');
+  }
+  const ignore = existsSync(".gitignore") ? readFileSync(".gitignore", "utf8") : "";
+  const missing = ["*.fota", "fireota-keys/fireota-private.pem"].filter((line) => !ignore.split(/\r?\n/).includes(line));
+  if (missing.length === 0) results.push(["–", ".gitignore already covers FireOTA files"]);
+  else write(".gitignore", `${ignore.replace(/\s*$/, "\n")}\n# FireOTA\n${missing.join("\n")}\n`, `.gitignore: ignores ${missing.join(", ")}`);
+
+  const runtime = { android: androidVersionName(), ios: iosMarketingVersion() };
+  return { results, dry, appId, serverUrl, channel, runtime };
+}

package/lib/project.mjs

@@ -0,0 +1,54 @@
+/** Reads facts about the React Native project the CLI runs in. */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** android/app/build.gradle(.kts): versionName "1.3.3" / versionName = "1.3.3" */
+export function androidVersionName(root = ".") {
+  for (const file of ["android/app/build.gradle", "android/app/build.gradle.kts"]) {
+    const path = join(root, file);
+    if (!existsSync(path)) continue;
+    const match = /versionName\s*=?\s*["']([^"']+)["']/.exec(readFileSync(path, "utf8"));
+    if (match) return match[1];
+  }
+  return undefined;
+}
+
+/** ios/<App>.xcodeproj/project.pbxproj MARKETING_VERSION, or a literal CFBundleShortVersionString. */
+export function iosMarketingVersion(root = ".") {
+  const ios = join(root, "ios");
+  if (!existsSync(ios)) return undefined;
+  for (const entry of readdirSync(ios)) {
+    if (!entry.endsWith(".xcodeproj")) continue;
+    const pbx = join(ios, entry, "project.pbxproj");
+    if (!existsSync(pbx)) continue;
+    const match = /MARKETING_VERSION\s*=\s*"?([0-9][^";]*)"?;/.exec(readFileSync(pbx, "utf8"));
+    if (match) return match[1].trim();
+  }
+  for (const entry of readdirSync(ios)) {
+    const plist = join(ios, entry, "Info.plist");
+    if (!existsSync(plist)) continue;
+    const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<$]+)<\/string>/.exec(readFileSync(plist, "utf8"));
+    if (match) return match[1].trim();
+  }
+  return undefined;
+}
+
+/** The app's store version for a platform — FireOTA's default runtime version. */
+export function storeVersion(platform, root = ".") {
+  return platform === "ios" ? iosMarketingVersion(root) : androidVersionName(root);
+}
+
+/** Recursively finds the first file matching a name test below a directory. */
+export function findFile(dir, test, depth = 6) {
+  if (!existsSync(dir) || depth < 0) return undefined;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "build" || entry.name === "Pods" || entry.name.startsWith(".")) continue;
+    const path = join(dir, entry.name);
+    if (entry.isFile() && test(entry.name)) return path;
+    if (entry.isDirectory()) {
+      const found = findFile(path, test, depth - 1);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}

package/lib/signing.mjs

@@ -0,0 +1,48 @@
+/**
+ * Code signing (optional, per app). The private key stays on this machine or in your CI's
+ * secret store; FireOTA and the app only ever see the public key.
+ *
+ * Signed message — identical in the server and the SDK:
+ *   fireota-update-v1\n<runtimeVersion>\n<platform>\n<sha256 of the .fota package, hex>
+ */
+import { createPrivateKey, generateKeyPairSync, sign } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export function signatureMessage({ runtimeVersion, platform, sha256 }) {
+  return `fireota-update-v1\n${runtimeVersion}\n${platform}\n${sha256.toLowerCase()}`;
+}
+
+/** --private-key <file>, or FIREOTA_SIGNING_KEY (PEM text) / FIREOTA_SIGNING_KEY_PATH in CI. */
+export function loadPrivateKey(flagPath) {
+  const path = flagPath ?? process.env.FIREOTA_SIGNING_KEY_PATH;
+  const pem = path ? readFileSync(resolve(String(path)), "utf8") : process.env.FIREOTA_SIGNING_KEY;
+  if (!pem) return null;
+  // CI secret stores often turn newlines into literal "\n".
+  const key = createPrivateKey(pem.includes("\\n") ? pem.replace(/\\n/g, "\n") : pem);
+  if (key.asymmetricKeyType !== "rsa") throw new Error("The signing key must be an RSA private key.");
+  return key;
+}
+
+export function signUpdate(privateKey, input) {
+  return sign("sha256", Buffer.from(signatureMessage(input), "utf8"), privateKey).toString("base64");
+}
+
+export function generateKeys(outDir) {
+  const dir = resolve(outDir ?? "fireota-keys");
+  const privatePath = join(dir, "fireota-private.pem");
+  const publicPath = join(dir, "fireota-public.pem");
+  if (existsSync(privatePath) || existsSync(publicPath)) {
+    throw new Error(`${dir} already contains FireOTA keys. Refusing to overwrite them.`);
+  }
+  const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  });
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(privatePath, privateKey, { mode: 0o600 });
+  writeFileSync(publicPath, publicKey);
+  writeFileSync(join(dir, ".gitignore"), "fireota-private.pem\n");
+  return { dir, privatePath, publicPath, publicKey };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fireota/cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Build FireOTA update packages and publish React Native OTA releases from a terminal or CI.",
   "license": "MIT",
   "type": "module",