@novacraft-engineering/pulsar-cli 1.2.1 → 1.2.2

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,6 +1,6 @@
 {
   "name": "@novacraft-engineering/pulsar-cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Pulsar OTA release CLI \u2014 bundle, hash, and ship React Native updates over-the-air.",
   "type": "module",
   "bin": {
@@ -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": {
@@ -29,12 +29,16 @@
     "test": "node test/hash.test.js && node test/security.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

@@ -257,6 +257,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 +297,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 +354,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 +369,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 {
@@ -370,7 +429,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 +513,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 +532,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