@fireota/cli 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sujay-Dynamisch/FireOTA/main/public/logo-mark.png" alt="FireOTA" width="96" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">FireOTA CLI</h1>
+
+<p align="center">
+  Build FireOTA update packages and publish React Native over-the-air releases from a terminal or CI.<br />
+  Works with <a href="https://www.npmjs.com/package/@fireota/react-native"><code>@fireota/react-native</code></a>.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@fireota/cli"><img alt="@fireota/cli" src="https://img.shields.io/npm/v/@fireota/cli?label=%40fireota%2Fcli" /></a>
+  <a href="https://www.npmjs.com/package/@fireota/react-native"><img alt="@fireota/react-native" src="https://img.shields.io/npm/v/@fireota/react-native?label=%40fireota%2Freact-native" /></a>
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue" />
+</p>
+
+---
+
+> **Beta (0.x).** Requires Node.js 18.17+.
+
+## Setup
+
+```sh
+npm install --save-dev @fireota/cli
+```
+
+Set two environment variables (create the API key in FireOTA → Settings → 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).
+
+## 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"
+```
+
+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.
+
+- `--version` must be new for each release on a channel.
+- `--runtime` must equal the runtime version of the store build that should receive it.
+
+## Commands
+
+```text
+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 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>]
+```
+
+## 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
+  env:
+    FIREOTA_URL: ${{ vars.FIREOTA_URL }}
+    FIREOTA_API_KEY: ${{ secrets.FIREOTA_API_KEY }}
+```
+
+## License
+
+MIT

package/bin/fireota.mjs

@@ -0,0 +1,255 @@
+#!/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_...)
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { packDirectory } from "../lib/package.mjs";
+
+const HELP = `FireOTA CLI
+
+Usage:
+  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 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>]
+
+Environment: FIREOTA_URL, FIREOTA_API_KEY. Run from your React Native project root.`;
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) flags[key] = true;
+      else {
+        flags[key] = next;
+        i += 1;
+      }
+    } else positional.push(arg);
+  }
+  return { positional, flags };
+}
+
+function fail(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`);
+  return String(value);
+}
+
+function sha256(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+// ---------- packaging ----------
+
+function hermesEnabled(platform, mode) {
+  if (mode === "on") return true;
+  if (mode === "off") return false;
+  if (platform === "android") {
+    const props = existsSync("android/gradle.properties") ? readFileSync("android/gradle.properties", "utf8") : "";
+    return !/^\s*hermesEnabled\s*=\s*false/m.test(props);
+  }
+  const podfile = existsSync("ios/Podfile") ? readFileSync("ios/Podfile", "utf8") : "";
+  return !/:hermes_enabled\s*=>\s*false/.test(podfile);
+}
+
+function hermesc() {
+  const dir = { win32: "win64-bin", darwin: "osx-bin", linux: "linux64-bin" }[process.platform];
+  const candidates = [
+    join("node_modules", "react-native", "sdks", "hermesc", dir ?? "", process.platform === "win32" ? "hermesc.exe" : "hermesc"),
+    join("node_modules", "hermes-compiler", "hermesc", dir ?? "", process.platform === "win32" ? "hermesc.exe" : "hermesc"),
+  ];
+  const found = candidates.find((c) => existsSync(c));
+  if (!found) fail("Hermes is enabled but hermesc was not found in node_modules. Run npm install, or pass --hermes off.");
+  return found;
+}
+
+/** Runs the React Native bundler (+ Hermes) and packs bundle and assets into one update file. */
+function bundle(flags) {
+  const platform = 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).");
+  }
+  const entry = flags.entry ? String(flags.entry) : existsSync("index.js") ? "index.js" : "index.ts";
+  const bundleName = platform === "android" ? "index.android.bundle" : "main.jsbundle";
+  const work = mkdtempSync(join(tmpdir(), "fireota-"));
+  const out = join(work, "package");
+  try {
+    const jsOut = join(work, "bundle.js");
+    console.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" },
+    );
+    // 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" });
+    } else {
+      writeFileSync(join(out, bundleName), readFileSync(jsOut));
+    }
+    const packed = packDirectory(out);
+    const target = resolve(String(flags.out ?? `fireota-${platform}.fota`));
+    writeFileSync(target, packed);
+    console.log(`Package: ${target}\nSize:    ${(packed.length / 1024 / 1024).toFixed(2)} MB\nSHA-256: ${sha256(packed)}`);
+    return target;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+// ---------- API ----------
+
+async function api(method, path, body, extraHeaders = {}) {
+  const base = process.env.FIREOTA_URL;
+  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 };
+  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 json;
+  try {
+    json = await response.json();
+  } catch {
+    fail(`Unexpected response from FireOTA (HTTP ${response.status}).`);
+  }
+  if (!json.success) fail(`${json.error?.code ?? "ERROR"}: ${json.error?.message ?? "request failed"}`);
+  return json.data;
+}
+
+async function createRelease(flags) {
+  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) } : {}),
+    ...(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 } : {}),
+  };
+  // 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}`);
+  return release;
+}
+
+async function uploadRelease(releaseId, file) {
+  if (!existsSync(file)) fail(`File not found: ${file}`);
+  const bytes = readFileSync(file);
+  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}`);
+  return result;
+}
+
+async function releaseAction(releaseId, body) {
+  return api("POST", `/releases/${releaseId}/publish`, body);
+}
+
+async function main() {
+  const [command, sub, ...rest] = process.argv.slice(2);
+  const { positional, flags } = parseArgs([sub, ...rest].filter((v) => v !== undefined));
+
+  if (!command || command === "help" || command === "--help" || flags.help) {
+    console.log(HELP);
+    return;
+  }
+  if (command === "bundle") {
+    bundle(parseArgs(process.argv.slice(3)).flags);
+    return;
+  }
+  if (command === "releases") {
+    const query = flags.app ? `?appId=${encodeURIComponent(String(flags.app))}` : "";
+    const rows = await api("GET", `/releases${query}`);
+    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}`);
+    }
+    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}%.`);
+    return;
+  }
+  if (command === "release") {
+    const id = positional[1];
+    switch (positional[0]) {
+      case "create":
+        await createRelease(flags);
+        return;
+      case "upload":
+        await uploadRelease(id ?? fail("release id required"), need(flags, "file"));
+        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}%.`);
+        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}%.`);
+        return;
+      }
+      case "pause":
+        await releaseAction(id ?? fail("release id required"), { action: "pause" });
+        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.");
+        return;
+      }
+      default:
+        fail(`unknown release command: ${positional[0] ?? ""}\n\n${HELP}`);
+    }
+  }
+  fail(`unknown command: ${command}\n\n${HELP}`);
+}
+
+main().catch((error) => fail(error instanceof Error ? error.message : String(error)));

package/lib/package.mjs

@@ -0,0 +1,26 @@
+/**
+ * FireOTA update package: gzip( "FOTA1\n" | u32 big-endian header length | JSON {files:[{path,size}]} | file bytes ).
+ * The native SDK unpacks exactly this format (FireOTAStore.kt / FireOTA.m).
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { gzipSync } from "node:zlib";
+
+function walk(dir, root = dir) {
+  return readdirSync(dir).flatMap((name) => {
+    const full = join(dir, name);
+    return statSync(full).isDirectory() ? walk(full, root) : [relative(root, full).split(sep).join("/")];
+  });
+}
+
+/** gzip( "FOTA1\n" | u32 header length | JSON {files:[{path,size}]} | file bytes ) */
+export function packDirectory(dir) {
+  const paths = walk(dir).sort();
+  const files = paths.map((path) => ({ path, size: statSync(join(dir, path)).size }));
+  const header = Buffer.from(JSON.stringify({ version: 1, files }), "utf8");
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(header.length);
+  const parts = [Buffer.from("FOTA1\n", "ascii"), length, header, ...paths.map((p) => readFileSync(join(dir, p)))];
+  return gzipSync(Buffer.concat(parts), { level: 9 });
+}
+

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@fireota/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Build FireOTA update packages and publish React Native OTA releases from a terminal or CI.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "fireota": "bin/fireota.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "react-native",
+    "ota",
+    "over-the-air",
+    "fireota",
+    "cli",
+    "ci"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "FireOTA",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sujay-Dynamisch/FireOTA.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Sujay-Dynamisch/FireOTA/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Sujay-Dynamisch/FireOTA/issues"
+  }
+}