@novacraft-engineering/pulsar-cli 1.2.1 → 1.2.3

package/README.md

@@ -1,19 +1,27 @@
 # @novacraft-engineering/pulsar-cli
 
-Release CLI for [Pulsar](https://pulsar.novacraft.africa) — bundle your React Native JavaScript, hash it exactly the way the client does, and ship it over-the-air.
+Release CLI for [Pulsar](https://usepulsar.dev) — the free, self-hostable **CodePush alternative** for React Native. Bundle your JavaScript, hash it exactly the way the on-device client does, and ship it over-the-air to live apps in seconds. No app-store review.
+
+Microsoft App Center CodePush was retired in March 2025. Pulsar speaks the same CodePush protocol, so migrating is a deployment key and a server URL — not a rewrite. See [usepulsar.dev/codepush-alternative](https://usepulsar.dev/codepush-alternative).
 
 ## Install
 
 ```bash
 npm i -g @novacraft-engineering/pulsar-cli
 # or run without installing:
-npx @novacraft-engineering/pulsar-cli login https://api.pulsar.novacraft.africa
+npx @novacraft-engineering/pulsar-cli login https://api.usepulsar.dev
 ```
 
+`<apiUrl>` is whatever Pulsar server you release against. `api.usepulsar.dev`
+is the hosted one; point it at your own if you self-host. The CLI talks to the
+Pulsar API and nothing else, so it has no host compiled into it.
+
 ## Commands
 
 ```bash
-pulsar login <apiUrl>                 # authenticate, saved to ~/.pulsar/config.json
+pulsar login <apiUrl>                 # authenticate (API key or browser), saved to ~/.pulsar/config.json
+                                      #   --api-key  paste a key from Settings → API keys
+                                      #   --browser  sign in via the dashboard, no key to manage
 pulsar apps                           # list your apps and deployment keys
 
 pulsar release <app> <deployment> --platform ios|android --target <ver> \
@@ -35,9 +43,6 @@ pulsar patch <app> <deployment> <label> [--rollout N] [--mandatory] [--disable]
 - `--disabled` — upload the bundle but don't serve it (flip on later with `pulsar patch … --enable`).
 - `--target <range>` — semver range of native binary versions the release applies to.
 
-```bash
-```
-
 ## How a release works
 
 `release` runs the React Native bundler, computes the **CodePush package hash** (the exact
@@ -47,6 +52,27 @@ then downloads it in the background and swaps it in on next launch.
 
 Auth is read from `PULSAR_API_URL` / `PULSAR_TOKEN` env, or `~/.pulsar/config.json` (written by `pulsar login`). Nothing is committed.
 
+## Use it from CI
+
+Both env vars are all a GitHub Actions / GitLab CI job needs:
+
+```yaml
+- run: npm i -g @novacraft-engineering/pulsar-cli
+- run: pulsar release MyApp Production --platform ios --target 1.4.0 --rollout 25
+  env:
+    PULSAR_API_URL: https://api.usepulsar.dev
+    PULSAR_TOKEN: ${{ secrets.PULSAR_TOKEN }}
+```
+
+Or connect the repo in the dashboard and fire a release for any commit without leaving the browser.
+
+## Related
+
+- [`@novacraft-engineering/pulsar-code-push`](https://github.com/Novacraft-Africa/pulsar-code-push) — the React Native client this CLI ships to
+- [Pulsar vs CodePush vs RevoPush](https://usepulsar.dev/blog/codepush-vs-revopush-vs-pulsar)
+- [How React Native OTA updates actually work](https://usepulsar.dev/blog/how-react-native-ota-updates-work)
+- [Staged rollouts and instant rollback](https://usepulsar.dev/blog/staged-rollouts-instant-rollback-react-native)
+
 ## License
 
 MIT © Novacraft Engineering

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novacraft-engineering/pulsar-cli",
-  "version": "1.2.1",
-  "description": "Pulsar OTA release CLI \u2014 bundle, hash, and ship React Native updates over-the-air.",
+  "version": "1.2.3",
+  "description": "Pulsar OTA release CLI — bundle, hash, and ship React Native updates over-the-air.",
   "type": "module",
   "bin": {
     "pulsar": "./pulsar.js"
@@ -16,7 +16,7 @@
     "type": "git",
     "url": "git+https://github.com/Novacraft-Africa/pulsar-cli.git"
   },
-  "homepage": "https://pulsar.novacraft.africa",
+  "homepage": "https://usepulsar.dev",
   "license": "MIT",
   "author": "Novacraft Engineering",
   "publishConfig": {
@@ -26,15 +26,19 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/hash.test.js && node test/security.test.js"
+    "test": "node test/hash.test.js && node test/security.test.js && node test/signing.test.js"
   },
   "keywords": [
-    "react-native",
-    "ota",
+    "cli",
     "code-push",
+    "codepush-alternative",
+    "hot-update",
+    "ota",
+    "ota-updates",
+    "over-the-air",
     "pulsar",
-    "cli",
-    "release",
-    "hot-update"
+    "react-native",
+    "react-native-ota",
+    "release"
   ]
 }

package/pulsar.js

@@ -9,7 +9,10 @@ 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.
+// CodePushPublicKey (Info.plist). Both native SDKs read it from <update>/CodePush/.codepushrelease
+// and nowhere else; a signature anywhere else counts as no signature.
+const SIGNATURE_PATH = 'CodePush/.codepushrelease';
+
 function signCodePushJWT(privateKeyPem, contentHash) {
   const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
   const signingInput = `${encode({alg: 'RS256', typ: 'JWT'})}.${encode({contentHash})}`;
@@ -246,8 +249,11 @@ async function buildDiffPackage(baseZip, newDir) {
   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'));
+  const signature = path.join(newDir, SIGNATURE_PATH);
+  if (fs.existsSync(signature)) {
+    fs.mkdirSync(path.dirname(path.join(diffDir, SIGNATURE_PATH)), {recursive: true});
+    fs.copyFileSync(signature, path.join(diffDir, SIGNATURE_PATH));
+  }
   return diffDir;
 }
 
@@ -257,6 +263,35 @@ async function fetchBlob(apiUrl, appId, fileName) {
   return Buffer.from(await response.arrayBuffer());
 }
 
+const splitList = (value, separator) => String(value || '').split(separator).map((entry) => entry.trim()).filter(Boolean);
+
+// --schedule takes either an absolute instant ("2026-09-20T09:00:00Z", "2026-09-20 09:00") or a
+// relative offset from now ("+90m", "+6h", "+3d"). Resolved here so the API only sees ISO.
+function parseSchedule(value) {
+  if (value === undefined) return null;
+  const raw = String(value).trim();
+  const relative = raw.match(/^\+(\d+(?:\.\d+)?)\s*(m|h|d)$/i);
+  if (relative) {
+    const unit = {m: 60000, h: 3600000, d: 86400000}[relative[2].toLowerCase()];
+    return new Date(Date.now() + Number(relative[1]) * unit).toISOString();
+  }
+  const at = Date.parse(raw.includes('T') || !raw.includes(' ') ? raw : raw.replace(' ', 'T'));
+  if (!Number.isFinite(at)) die(`Invalid --schedule "${raw}". Use an ISO instant or a relative offset like +6h.`);
+  if (at <= Date.now()) die(`--schedule "${raw}" is in the past.`);
+  return new Date(at).toISOString();
+}
+
+// --ramp takes "<to>@<hours>" ("100@48") or just "<hours>" (ramps to 100).
+function parseRamp(value) {
+  if (value === undefined) return null;
+  const raw = String(value).trim();
+  const match = raw.match(/^(?:(\d{1,3})@)?(\d+(?:\.\d+)?)$/);
+  if (!match) die(`Invalid --ramp "${raw}". Use <toPercent>@<hours>, e.g. 100@48.`);
+  const to = match[1] === undefined ? 100 : Number(match[1]);
+  if (to > 100) die('--ramp target cannot exceed 100.');
+  return {to, hours: Number(match[2])};
+}
+
 function getFlag(args, name, fallback) {
   const index = args.indexOf(`--${name}`);
   return index >= 0 ? args[index + 1] : fallback;
@@ -268,17 +303,31 @@ async function cmdLogin(args) {
 
   let mode;
   if (args.includes('--browser')) mode = 'browser';
+  else if (args.includes('--api-key') || args.includes('--apikey')) mode = 'apikey';
   else if (args.includes('--terminal')) mode = 'terminal';
   else {
-    const answer = (await prompt('Sign in with [b]rowser or [t]erminal? (b/t): ')).toLowerCase();
-    mode = answer.startsWith('t') ? 'terminal' : 'browser';
+    const answer = (await prompt('Sign in with [a]pi key or [b]rowser? (a/b): ')).toLowerCase();
+    mode = answer.startsWith('a') ? 'apikey' : 'browser';
+  }
+
+  if (mode === 'apikey') {
+    const token = (await prompt('Paste your Pulsar API key: ', true)).trim();
+    if (!token) die('No API key provided.');
+    saveConfig({apiUrl, token});
+    const me = await api('/auth/me').catch(() => null);
+    if (!me?.user?.email) {
+      saveConfig({apiUrl, token: undefined});
+      die('That API key was rejected. Create one in the dashboard → Settings → API keys.');
+    }
+    console.log(`✓ logged in as ${me.user.email} (api key)`);
+    return;
   }
 
   if (mode === 'browser') {
     const token = await browserLogin(apiUrl);
     saveConfig({apiUrl, token});
     const me = await api('/auth/me').catch(() => null);
-    console.log(`✓ logged in${me?.email ? ` as ${me.email}` : ''} (browser)`);
+    console.log(`✓ logged in${me?.user?.email ? ` as ${me.user.email}` : ''} (browser)`);
     return;
   }
 
@@ -311,6 +360,8 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
     } catch {}
   }
 
+  const startsAt = parseSchedule(getFlag(args, 'schedule'));
+  const ramp = parseRamp(getFlag(args, 'ramp'));
   const release = await api(`/apps/${app.id}/deployments/${deployment}/release`, {
     method: 'POST',
     raw: true,
@@ -324,11 +375,25 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
       'x-disabled': String(args.includes('--disabled')),
       'x-rollout': String(getFlag(args, 'rollout', '100')),
       'x-client-ids': getFlag(args, 'devices', ''),
+      // JSON-encoded: iOS model ids contain a comma ("iPhone14,3"), so separate models with ';'.
+      'x-target-devices': JSON.stringify(splitList(getFlag(args, 'device-models', ''), ';')),
+      'x-target-users': JSON.stringify(splitList(getFlag(args, 'users', ''), ',')),
+      'x-target-from': JSON.stringify(splitList(getFlag(args, 'from', ''), ',')),
       'x-description': encodeURIComponent(getFlag(args, 'description', '')),
+      ...(startsAt ? {'x-starts-at': startsAt} : {}),
+      ...(ramp ? {'x-rollout-to': String(ramp.to), 'x-rollout-hours': String(ramp.hours)} : {}),
     },
   });
-  const reach = release.clientIds?.length ? `${release.clientIds.length} device(s)` : `${release.rollout}% of devices`;
+  const scopes = [
+    release.clientIds?.length ? `${release.clientIds.length} device id(s)` : null,
+    release.targetDevices?.length ? `${release.targetDevices.length} device model(s)` : null,
+    release.targetUserIds?.length ? `${release.targetUserIds.length} user(s)` : null,
+    release.targetFromLabels?.length ? `devices on ${release.targetFromLabels.join('/')}` : null,
+  ].filter(Boolean);
+  const reach = scopes.length ? scopes.join(' + ') : `${release.rollout}% of devices`;
   console.log(`✓ released ${release.label} to ${app.name}/${deployment} — ${release.isDisabled ? 'DISABLED' : reach}`);
+  if (release.startsAt) console.log(`  scheduled — goes live ${new Date(release.startsAt).toLocaleString()}`);
+  if (release.rolloutRamp) console.log(`  gradual rollout — ${release.rollout}% to ${release.rolloutRamp.to}% over ${release.rolloutRamp.hours}h`);
 
   if (prevLatest && prevLatest.packageHash && prevLatest.packageHash !== packageHash) {
     try {
@@ -358,9 +423,20 @@ function buildOnce(args) {
   const contentsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsar-build-'));
   bundle(platform, contentsDir);
   const packageHash = computePackageHash(contentsDir);
+  // CI secrets arrive as environment variables holding the key itself, not as files, so the key can
+  // come from PULSAR_SIGNING_KEY as well as --private-key <file>. An unset or empty secret means
+  // "don't sign", exactly as before.
   const privateKeyPath = getFlag(args, 'private-key');
-  if (privateKeyPath) {
-    fs.writeFileSync(path.join(contentsDir, '.codepushrelease'), signCodePushJWT(fs.readFileSync(privateKeyPath, 'utf8'), packageHash));
+  const signingKey = privateKeyPath ? fs.readFileSync(privateKeyPath, 'utf8') : (process.env.PULSAR_SIGNING_KEY || '').trim();
+  if (signingKey) {
+    let signature;
+    try {
+      signature = signCodePushJWT(signingKey, packageHash);
+    } catch (error) {
+      die(`could not sign with the provided key (${error.message}) — nothing was uploaded`);
+    }
+    fs.mkdirSync(path.join(contentsDir, 'CodePush'), {recursive: true});
+    fs.writeFileSync(path.join(contentsDir, SIGNATURE_PATH), signature);
     console.log('• signed release — devices with CodePushPublicKey set will verify it');
   }
   const zip = fs.readFileSync(zipContents(contentsDir));
@@ -370,7 +446,7 @@ function buildOnce(args) {
 
 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 (!nameOrId) die('Usage: pulsar release <app> <Staging|Production> --platform ios|android --target <ver> [--mandatory] [--disabled] [--rollout N] [--schedule +6h|ISO] [--ramp 100@48] [--from v6,ota,binary] [--devices id1,id2,...] [--device-models model1;model2] [--users u1,u2] [--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, getFlag(args, 'platform', 'ios'));
   if (app.os !== getFlag(args, 'platform', 'ios')) {
@@ -454,13 +530,17 @@ async function cmdHistory(args) {
   if (!releases.length) return console.log('(no releases)');
   for (const release of [...releases].reverse()) {
     const flags = `${release.isMandatory ? ' [mandatory]' : ''}${release.isDisabled ? ' [disabled]' : ''}`;
-    console.log(`  ${release.label.padEnd(5)} target ${String(release.appVersion).padEnd(10)} rollout ${String(release.rollout).padStart(3)}%${flags}  ${release.description || ''}`);
+    const rollout = release.currentRollout ?? release.rollout;
+    const state = release.state && release.state !== 'live' ? ` [${release.state}]` : '';
+    const when = release.startsAt ? ` starts ${new Date(release.startsAt).toLocaleString()}` : '';
+    const ramping = release.rolloutRamp ? ` ->${release.rolloutRamp.to}%/${release.rolloutRamp.hours}h` : '';
+    console.log(`  ${release.label.padEnd(5)} target ${String(release.appVersion).padEnd(10)} rollout ${String(rollout).padStart(3)}%${ramping}${flags}${state}${when}  ${release.description || ''}`);
   }
 }
 
 async function cmdPatch(args) {
   const [nameOrId, deployment, label] = args;
-  if (!label) die('Usage: pulsar patch <app> <deployment> <label> [--rollout N] [--mandatory] [--disable] [--enable] [--devices id1,id2,...]');
+  if (!label) die('Usage: pulsar patch <app> <deployment> <label> [--rollout N] [--schedule +6h|ISO|none] [--ramp 100@48|none] [--from v6,ota,binary] [--mandatory] [--disable] [--enable] [--devices id1,id2,...] [--device-models model1;model2] [--users u1,u2]');
   const app = await resolveApp(nameOrId, getFlag(args, 'platform'));
   const body = {};
   const rollout = getFlag(args, 'rollout');
@@ -469,9 +549,19 @@ async function cmdPatch(args) {
   if (args.includes('--disable')) body.isDisabled = true;
   if (args.includes('--enable')) body.isDisabled = false;
   const devices = getFlag(args, 'devices');
-  if (devices !== undefined) body.clientIds = devices.split(',').map((id) => id.trim()).filter(Boolean);
+  if (devices !== undefined) body.clientIds = splitList(devices, ',');
+  const deviceModels = getFlag(args, 'device-models');
+  if (deviceModels !== undefined) body.targetDevices = splitList(deviceModels, ';');
+  const users = getFlag(args, 'users');
+  if (users !== undefined) body.targetUserIds = splitList(users, ',');
+  const from = getFlag(args, 'from');
+  if (from !== undefined) body.targetFromLabels = from === 'none' ? [] : splitList(from, ',');
+  const schedule = getFlag(args, 'schedule');
+  if (schedule !== undefined) body.startsAt = schedule === 'none' ? null : parseSchedule(schedule);
+  const ramp = getFlag(args, 'ramp');
+  if (ramp !== undefined) body.rolloutRamp = ramp === 'none' ? null : parseRamp(ramp);
   const release = await api(`/apps/${app.id}/deployments/${deployment}/releases/${label}`, {method: 'PATCH', body});
-  console.log(`✓ patched ${label}: rollout ${release.rollout}%${release.isMandatory ? ' mandatory' : ''}${release.isDisabled ? ' disabled' : ''}`);
+  console.log(`✓ patched ${label}: rollout ${release.rollout}%${release.rolloutRamp ? ` to ${release.rolloutRamp.to}% over ${release.rolloutRamp.hours}h` : ''}${release.startsAt ? ` starting ${new Date(release.startsAt).toLocaleString()}` : ''}${release.isMandatory ? ' mandatory' : ''}${release.isDisabled ? ' disabled' : ''}`);
 }
 
 // Deployment keys for a whole React Native project (its -Android and -iOS apps), shaped as the
@@ -521,7 +611,7 @@ async function cmdKeys(args) {
   console.log(`✓ wrote ${Object.keys(vars).length} key(s) to ${target} (${written.size} updated, ${missing.length} added)`);
 }
 
-export {saveConfig, browserLogin};
+export {saveConfig, browserLogin, signCodePushJWT, SIGNATURE_PATH};
 
 // Only dispatch when run as the CLI — importing the module (e.g. from tests) must not execute a command.
 if (import.meta.url === `file://${process.argv[1]}`) {