@novacraft-engineering/pulsar-cli 1.0.0 → 1.1.1

package/hash.js

@@ -23,6 +23,17 @@ function walk(dir) {
   return files;
 }
 
+// Per-file sha256 map (relativePath -> hash), used to compute differential packages.
+export function fileHashes(contentsDir) {
+  const map = {};
+  for (const file of walk(contentsDir)) {
+    const relativePath = path.relative(contentsDir, file).split(path.sep).join('/');
+    if (isIgnored(relativePath)) continue;
+    map[relativePath] = sha256(fs.readFileSync(file));
+  }
+  return map;
+}
+
 // Matches @revopush/react-native-code-push CodePushUpdateUtils.computeFinalHashFromManifest:
 // build "relPath:sha256(file)" entries, sort, JSON.stringify the array, sha256 that string.
 export function computePackageHash(contentsDir) {

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@novacraft-engineering/pulsar-cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Pulsar OTA release CLI — bundle, hash, and ship React Native updates over-the-air.",
   "type": "module",
-  "bin": {"pulsar": "./pulsar.js"},
-  "files": ["pulsar.js", "hash.js", "README.md", "LICENSE"],
+  "bin": {
+    "pulsar": "./pulsar.js"
+  },
+  "files": [
+    "pulsar.js",
+    "hash.js",
+    "README.md",
+    "LICENSE"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Novacraft-Africa/pulsar-cli.git"
@@ -12,8 +19,22 @@
   "homepage": "https://pulsar.novacraft.africa",
   "license": "MIT",
   "author": "Novacraft Engineering",
-  "publishConfig": {"access": "public"},
-  "engines": {"node": ">=18"},
-  "scripts": {"test": "node test/hash.test.js"},
-  "keywords": ["react-native", "ota", "code-push", "pulsar", "cli", "release", "hot-update"]
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/hash.test.js"
+  },
+  "keywords": [
+    "react-native",
+    "ota",
+    "code-push",
+    "pulsar",
+    "cli",
+    "release",
+    "hot-update"
+  ]
 }

package/pulsar.js

@@ -4,7 +4,29 @@ import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline';
 import {execFileSync} from 'node:child_process';
-import {computePackageHash} from './hash.js';
+import crypto from 'node:crypto';
+import {computePackageHash, fileHashes} from './hash.js';
+
+// Code signing: sign the package hash into an RS256 JWT the client verifies against its
+// CodePushPublicKey (Info.plist). Written to `.codepushrelease` inside the bundle.
+function signCodePushJWT(privateKeyPem, contentHash) {
+  const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+  const signingInput = `${encode({alg: 'RS256', typ: 'JWT'})}.${encode({contentHash})}`;
+  const signature = crypto.createSign('RSA-SHA256').update(signingInput).sign(privateKeyPem).toString('base64url');
+  return `${signingInput}.${signature}`;
+}
+
+function cmdKeygen() {
+  const {publicKey, privateKey} = crypto.generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    publicKeyEncoding: {type: 'spki', format: 'pem'},
+    privateKeyEncoding: {type: 'pkcs8', format: 'pem'},
+  });
+  fs.writeFileSync('pulsar-private.pem', privateKey);
+  fs.writeFileSync('pulsar-public.pem', publicKey);
+  console.log('✓ wrote pulsar-private.pem (keep secret, use with --private-key) and pulsar-public.pem');
+  console.log('  Put the public key in Info.plist <key>CodePushPublicKey</key> to require signed updates.');
+}
 
 const CONFIG_DIR = path.join(os.homedir(), '.pulsar');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
@@ -22,9 +44,12 @@ function saveConfig(config) {
   fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
 }
 
-async function api(pathname, {method = 'GET', body, headers = {}, raw} = {}) {
+async function api(pathname, {method = 'GET', body, headers = {}, raw, allowAnonymous} = {}) {
   const {apiUrl, token} = loadConfig();
   if (!apiUrl) die('No API url. Run: pulsar login <apiUrl>');
+  // Every call except the login handshake must carry a token, so an expired or
+  // cleared session fails here rather than silently issuing anonymous requests.
+  if (!token && !allowAnonymous) die('Not authenticated. Run: pulsar login <apiUrl>');
   const response = await fetch(apiUrl.replace(/\/$/, '') + pathname, {
     method,
     headers: {
@@ -35,9 +60,23 @@ async function api(pathname, {method = 'GET', body, headers = {}, raw} = {}) {
     body: raw ? body : body ? JSON.stringify(body) : undefined,
   });
   const text = await response.text();
-  const data = text ? JSON.parse(text) : {};
-  if (!response.ok) die(`${response.status}: ${data.error || text}`);
-  return data;
+  // Check the status BEFORE parsing: an edge/proxy error (413, 502, 524) returns
+  // an HTML page, and parsing that first turned every such failure into an
+  // opaque "Unexpected token '<'" SyntaxError instead of the real status.
+  if (!response.ok) {
+    let detail = text;
+    try {
+      detail = JSON.parse(text).error || text;
+    } catch {
+      detail = text.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 300);
+    }
+    die(`${response.status} ${response.statusText}: ${detail}`);
+  }
+  try {
+    return text ? JSON.parse(text) : {};
+  } catch {
+    die(`${response.status}: expected JSON, got ${text.slice(0, 200)}`);
+  }
 }
 
 function die(message) {
@@ -92,6 +131,41 @@ function zipContents(contentsDir) {
   return zipPath;
 }
 
+// Build a differential package: only the files that changed vs the base, plus a hotcodepush.json
+// manifest listing deleted files. The client reconstructs the full bundle from its current copy +
+// this diff, then verifies the result against the target hash. Returns the diff dir, or null if the
+// base couldn't be fetched.
+async function buildDiffPackage(baseZip, newDir) {
+  const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsar-base-'));
+  const basePath = path.join(os.tmpdir(), `pulsar-base-${Date.now()}.zip`);
+  fs.writeFileSync(basePath, baseZip);
+  execFileSync('unzip', ['-qq', '-o', basePath, '-d', baseDir]);
+
+  const baseHashes = fileHashes(baseDir);
+  const newHashes = fileHashes(newDir);
+  const diffDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsar-diff-'));
+
+  for (const [relativePath, hash] of Object.entries(newHashes)) {
+    if (baseHashes[relativePath] === hash) continue;
+    const dest = path.join(diffDir, relativePath);
+    fs.mkdirSync(path.dirname(dest), {recursive: true});
+    fs.copyFileSync(path.join(newDir, relativePath), dest);
+  }
+  const deletedFiles = Object.keys(baseHashes).filter((relativePath) => !(relativePath in newHashes));
+  fs.writeFileSync(path.join(diffDir, 'hotcodepush.json'), JSON.stringify({deletedFiles}));
+  // The signature isn't part of the content hash, so it's excluded above — but the patched bundle
+  // still needs it to verify, so carry it into the diff when the release is signed.
+  const signature = path.join(newDir, '.codepushrelease');
+  if (fs.existsSync(signature)) fs.copyFileSync(signature, path.join(diffDir, '.codepushrelease'));
+  return diffDir;
+}
+
+async function fetchBlob(apiUrl, appId, fileName) {
+  const response = await fetch(`${apiUrl.replace(/\/$/, '')}/download/${appId}/${fileName}`);
+  if (!response.ok) throw new Error(`download ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
 function getFlag(args, name, fallback) {
   const index = args.indexOf(`--${name}`);
   return index >= 0 ? args[index + 1] : fallback;
@@ -102,7 +176,7 @@ async function cmdLogin(args) {
   const email = await prompt('Email: ');
   const password = await prompt('Password: ', true);
   saveConfig({apiUrl, token: undefined});
-  const {token, user} = await api('/auth/login', {method: 'POST', body: {email, password}});
+  const {token, user} = await api('/auth/login', {method: 'POST', body: {email, password}, allowAnonymous: true});
   saveConfig({apiUrl, token});
   console.log(`✓ logged in as ${user.email} (${user.platformRole})`);
 }
@@ -118,21 +192,16 @@ async function cmdApps() {
   }
 }
 
-async function cmdRelease(args) {
-  const [nameOrId, deployment = 'Staging'] = args;
-  if (!nameOrId) die('Usage: pulsar release <app> <Staging|Production> --platform ios|android --target <ver> [--mandatory] [--disabled] [--rollout N] [--devices id1,id2,...] [--description "..."]');
-  const platform = getFlag(args, 'platform', 'ios');
-  const target = getFlag(args, 'target');
-  if (!target) die('--target <binary version> is required (e.g. --target 1.0.0)');
-
-  const app = await resolveApp(nameOrId);
-  const contentsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsar-build-'));
-  bundle(platform, contentsDir);
-
-  const packageHash = computePackageHash(contentsDir);
-  const zipPath = zipContents(contentsDir);
-  const zip = fs.readFileSync(zipPath);
-  console.log(`• hash ${packageHash.slice(0, 12)}…  size ${(zip.length / 1e6).toFixed(2)} MB`);
+// Push an already-built (and optionally signed) bundle to one app's deployment, then generate and
+// upload a differential patch against whatever that deployment was serving.
+async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash, zip) {
+  let prevLatest = null;
+  if (!args.includes('--no-diff')) {
+    try {
+      const existing = await api(`/apps/${app.id}/deployments/${deployment}/releases`);
+      prevLatest = [...existing].reverse().find((entry) => !entry.isDisabled) || existing[existing.length - 1] || null;
+    } catch {}
+  }
 
   const release = await api(`/apps/${app.id}/deployments/${deployment}/release`, {
     method: 'POST',
@@ -140,19 +209,95 @@ async function cmdRelease(args) {
     body: zip,
     headers: {
       'content-type': 'application/zip',
-      'x-app-version': target,
+      'x-app-version': getFlag(args, 'target'),
       'x-package-hash': packageHash,
       'x-is-mandatory': String(args.includes('--mandatory')),
       'x-disabled': String(args.includes('--disabled')),
       'x-rollout': String(getFlag(args, 'rollout', '100')),
       'x-client-ids': getFlag(args, 'devices', ''),
-      'x-description': getFlag(args, 'description', ''),
+      'x-description': encodeURIComponent(getFlag(args, 'description', '')),
     },
   });
-  const reach = release.clientIds?.length
-    ? `${release.clientIds.length} device(s)`
-    : `${release.rollout}% of devices`;
+  const reach = release.clientIds?.length ? `${release.clientIds.length} device(s)` : `${release.rollout}% of devices`;
   console.log(`✓ released ${release.label} to ${app.name}/${deployment} — ${release.isDisabled ? 'DISABLED' : reach}`);
+
+  if (prevLatest && prevLatest.packageHash && prevLatest.packageHash !== packageHash) {
+    try {
+      const {apiUrl} = loadConfig();
+      const baseZip = await fetchBlob(apiUrl, app.id, `${prevLatest.packageHash}.zip`);
+      const diffDir = await buildDiffPackage(baseZip, contentsDir);
+      const diffZip = fs.readFileSync(zipContents(diffDir));
+      await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/diff`, {
+        method: 'POST',
+        raw: true,
+        body: diffZip,
+        headers: {'content-type': 'application/zip', 'x-base-hash': prevLatest.packageHash},
+      });
+      const saved = Math.round((1 - diffZip.length / zip.length) * 100);
+      console.log(`• diff vs ${prevLatest.label}: ${(diffZip.length / 1e3).toFixed(0)} KB (${saved}% smaller)`);
+    } catch (err) {
+      console.log(`• diff skipped (full bundle still serves): ${err.message}`);
+    }
+  }
+  return release;
+}
+
+// Build the JS bundle once, sign it if requested, and return the reusable artifacts.
+function buildOnce(args) {
+  const platform = getFlag(args, 'platform', 'ios');
+  const contentsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsar-build-'));
+  bundle(platform, contentsDir);
+  const packageHash = computePackageHash(contentsDir);
+  const privateKeyPath = getFlag(args, 'private-key');
+  if (privateKeyPath) {
+    fs.writeFileSync(path.join(contentsDir, '.codepushrelease'), signCodePushJWT(fs.readFileSync(privateKeyPath, 'utf8'), packageHash));
+    console.log('• signed release — devices with CodePushPublicKey set will verify it');
+  }
+  const zip = fs.readFileSync(zipContents(contentsDir));
+  console.log(`• hash ${packageHash.slice(0, 12)}…  size ${(zip.length / 1e6).toFixed(2)} MB`);
+  return {contentsDir, packageHash, zip};
+}
+
+async function cmdRelease(args) {
+  const [nameOrId, deployment = 'Staging'] = args;
+  if (!nameOrId) die('Usage: pulsar release <app> <Staging|Production> --platform ios|android --target <ver> [--mandatory] [--disabled] [--rollout N] [--devices id1,id2,...] [--private-key key.pem] [--no-diff] [--description "..."]');
+  if (!getFlag(args, 'target')) die('--target <binary version> is required (e.g. --target 1.0.0)');
+  const app = await resolveApp(nameOrId);
+  const {contentsDir, packageHash, zip} = buildOnce(args);
+  await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, zip);
+}
+
+// Release the same built bundle to several apps at once (shared-codebase / white-label fleets).
+async function cmdReleaseTrain(args) {
+  const platform = getFlag(args, 'platform', 'ios');
+  if (!getFlag(args, 'target')) die('--target <binary version> is required');
+  const orgName = getFlag(args, 'org');
+  const all = await api('/apps');
+  let apps;
+  let deployment;
+  if (orgName) {
+    deployment = args[0] && !args[0].startsWith('--') ? args[0] : 'Staging';
+    const org = (await api('/orgs')).find((entry) => entry.name.toLowerCase() === orgName.toLowerCase());
+    if (!org) die(`Organization not found: ${orgName}`);
+    apps = all.filter((app) => app.orgId === org.id);
+  } else {
+    if (!args[0] || args[0].startsWith('--')) die('Usage: pulsar release-train <App1,App2,…|--org Name> <deployment> --platform ios|android --target <ver> [...release flags]');
+    deployment = args[1] && !args[1].startsWith('--') ? args[1] : 'Staging';
+    const names = args[0].split(',').map((name) => name.trim().toLowerCase());
+    apps = all.filter((app) => names.includes(app.name.toLowerCase()) || names.includes(app.id));
+  }
+  apps = apps.filter((app) => app.os === platform);
+  if (!apps.length) die(`No ${platform} apps matched.`);
+
+  const {contentsDir, packageHash, zip} = buildOnce(args);
+  console.log(`• release train → ${apps.length} app(s): ${apps.map((app) => app.name).join(', ')}`);
+  for (const app of apps) {
+    try {
+      await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, zip);
+    } catch (err) {
+      console.log(`✗ ${app.name}: ${err.message}`);
+    }
+  }
 }
 
 async function cmdPromote(args) {
@@ -216,19 +361,75 @@ async function cmdPatch(args) {
   console.log(`✓ patched ${label}: rollout ${release.rollout}%${release.isMandatory ? ' mandatory' : ''}${release.isDisabled ? ' disabled' : ''}`);
 }
 
+// Deployment keys for a whole React Native project (its -Android and -iOS apps), shaped as the
+// PULSAR_* env vars the mobile clients read. DEV maps to Staging, LIVE maps to Production.
+const KEY_VAR = (platform, deployment) => `PULSAR_${platform.toUpperCase()}_${deployment === 'Production' ? 'LIVE' : 'DEV'}_KEY`;
+
+async function cmdKeys(args) {
+  const project = args.find((arg) => !arg.startsWith('--'));
+  if (!project) die('Usage: pulsar keys <project> [--write <path/to/.env>] [--json]');
+  const apps = await api('/apps');
+  const matches = apps.filter((app) => app.name.toLowerCase().startsWith(`${project.toLowerCase()}-`));
+  if (!matches.length) die(`No apps for project "${project}". Known: ${apps.map((app) => app.name).join(', ')}`);
+
+  const vars = {};
+  for (const app of matches) {
+    for (const deployment of ['Staging', 'Production']) {
+      const key = app.deployments?.[deployment]?.key;
+      if (key) vars[KEY_VAR(app.os, deployment)] = key;
+    }
+  }
+
+  const target = getFlag(args, 'write');
+  if (!target) {
+    if (args.includes('--json')) return console.log(JSON.stringify(vars, null, 2));
+    for (const [name, value] of Object.entries(vars)) console.log(`${name}=${value}`);
+    return;
+  }
+
+  // Merge into the project's .env: update the PULSAR_* lines in place, append any that are
+  // missing, and leave every other line (and every other secret) untouched.
+  const existing = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+  const lines = existing.split('\n');
+  const written = new Set();
+  const merged = lines.map((line) => {
+    const match = line.match(/^([A-Z0-9_]+)(\s*=\s*)(.*)$/);
+    if (!match || !(match[1] in vars)) return line;
+    written.add(match[1]);
+    return `${match[1]}${match[2]}${vars[match[1]]}`;
+  });
+  const missing = Object.keys(vars).filter((name) => !written.has(name));
+  if (missing.length) {
+    if (merged[merged.length - 1] !== '') merged.push('');
+    merged.push('# Pulsar OTA keys (DEV = Staging deployment, LIVE = Production)');
+    for (const name of missing) merged.push(`${name}=${vars[name]}`);
+  }
+  fs.writeFileSync(target, merged.join('\n'));
+  console.log(`✓ wrote ${Object.keys(vars).length} key(s) to ${target} (${written.size} updated, ${missing.length} added)`);
+}
+
 const [command, ...rest] = process.argv.slice(2);
 const commands = {
   login: cmdLogin,
   apps: cmdApps,
   release: cmdRelease,
+  'release-train': cmdReleaseTrain,
   promote: cmdPromote,
   rollback: cmdRollback,
   deployment: cmdDeployment,
   history: cmdHistory,
   patch: cmdPatch,
+  keygen: cmdKeygen,
+  keys: cmdKeys,
 };
 
+const ANONYMOUS_COMMANDS = new Set(['login', 'keygen']);
+
+if (commands[command] && !ANONYMOUS_COMMANDS.has(command) && !loadConfig().token) {
+  die('Not authenticated. Run: pulsar login <apiUrl>');
+}
+
 (commands[command] || (() => {
-  console.log('pulsar <login|apps|release|promote|rollback|deployment|history|patch>');
+  console.log('pulsar <login|apps|keys|release|release-train|promote|rollback|deployment|history|patch|keygen>');
   process.exit(command ? 1 : 0);
 }))(rest);