@fireota/cli 0.1.1 → 0.2.0

package/README.md

@@ -25,53 +25,92 @@
 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 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,41 @@ 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 { packDirectory } from "../lib/package.mjs";
+import { generateKeys, loadPrivateKey, signUpdate } from "../lib/signing.mjs";
 
 const HELP = `FireOTA CLI
 
 Usage:
+  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.
+
+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 +68,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 +83,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 +114,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 +126,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 +160,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 +182,44 @@ async function api(method, path, body, extraHeaders = {}) {
   return json.data;
 }
 
-async function createRelease(flags) {
+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: need(flags, "runtime", "FIREOTA_RUNTIME"),
+    ...(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 +227,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: need(flags, "runtime", "FIREOTA_RUNTIME"), 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 +258,116 @@ async function main() {
     bundle(parseArgs(process.argv.slice(3)).flags);
     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]))).join(":") + String(all.runtime ?? process.env.FIREOTA_RUNTIME)) }
+        : {};
+    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/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.2.0",
   "description": "Build FireOTA update packages and publish React Native OTA releases from a terminal or CI.",
   "license": "MIT",
   "type": "module",