@novacraft-engineering/pulsar-cli 1.2.0 → 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,7 +1,7 @@
 {
   "name": "@novacraft-engineering/pulsar-cli",
-  "version": "1.2.0",
-  "description": "Pulsar OTA release CLI — bundle, hash, and ship React Native updates over-the-air.",
+  "version": "1.2.2",
+  "description": "Pulsar OTA release CLI \u2014 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"
+    "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

@@ -23,7 +23,7 @@ function cmdKeygen() {
     publicKeyEncoding: {type: 'spki', format: 'pem'},
     privateKeyEncoding: {type: 'pkcs8', format: 'pem'},
   });
-  fs.writeFileSync('pulsar-private.pem', privateKey);
+  fs.writeFileSync('pulsar-private.pem', privateKey, {mode: 0o600});
   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.');
@@ -41,8 +41,11 @@ function loadConfig() {
 }
 
 function saveConfig(config) {
-  fs.mkdirSync(CONFIG_DIR, {recursive: true});
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+  // The config holds a bearer token — keep the dir and file owner-only so other local users on a
+  // shared host can't read the session.
+  fs.mkdirSync(CONFIG_DIR, {recursive: true, mode: 0o700});
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {mode: 0o600});
+  try { fs.chmodSync(CONFIG_FILE, 0o600); } catch { /* best-effort on pre-existing files */ }
 }
 
 async function api(pathname, {method = 'GET', body, headers = {}, raw, allowAnonymous, onUploadProgress} = {}) {
@@ -153,19 +156,26 @@ function dashboardUrl(apiUrl) {
 // Browser login: spin up a throwaway localhost server, open the dashboard's /cli-login page which
 // (once you're signed in) redirects back here with a token. No password ever touches the terminal.
 function browserLogin(apiUrl) {
+  // A random nonce ties the callback to THIS login: the dashboard echoes it back and we reject any
+  // callback whose state doesn't match, so a stray page spraying the loopback port range can't inject
+  // its own token into our config (login fixation).
+  const state = crypto.randomUUID();
   return new Promise((resolve, reject) => {
     const server = http.createServer((req, res) => {
       const requestUrl = new URL(req.url, 'http://127.0.0.1');
+      if (requestUrl.pathname !== '/callback') { res.writeHead(204); res.end(); return; }
       const token = requestUrl.searchParams.get('token');
-      res.writeHead(token ? 200 : 400, {'content-type': 'text/html'});
-      res.end(`<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;background:#080a0f;color:#eef2f7;display:grid;place-items:center;height:100vh;margin:0"><div style="text-align:center"><h2 style="font-weight:600">${token ? 'Pulsar CLI authorized ✓' : 'No token received'}</h2><p style="color:#8f98a6">You can close this tab and return to your terminal.</p></div></body>`);
+      const ok = token && requestUrl.searchParams.get('state') === state;
+      res.writeHead(ok ? 200 : 400, {'content-type': 'text/html'});
+      res.end(`<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;background:#080a0f;color:#eef2f7;display:grid;place-items:center;height:100vh;margin:0"><div style="text-align:center"><h2 style="font-weight:600">${ok ? 'Pulsar CLI authorized ✓' : 'Authorization failed'}</h2><p style="color:#8f98a6">You can close this tab and return to your terminal.</p></div></body>`);
+      if (!ok) return;
       setTimeout(() => { try { server.close(); } catch {} }, 100);
-      if (token) resolve(token); else reject(new Error('No token received from the browser'));
+      resolve(token);
     });
     server.on('error', reject);
     server.listen(0, '127.0.0.1', () => {
       const {port} = server.address();
-      const authUrl = `${dashboardUrl(apiUrl)}/cli-login?port=${port}`;
+      const authUrl = `${dashboardUrl(apiUrl)}/cli-login?port=${port}&state=${state}`;
       console.log(`\n  Authorize the CLI in your browser:\n  ${authUrl}\n`);
       openBrowser(authUrl);
       console.log('  Waiting for authorization…');
@@ -247,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;
@@ -258,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;
   }
 
@@ -301,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,
@@ -314,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 {
@@ -360,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')) {
@@ -444,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');
@@ -459,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
@@ -511,28 +594,33 @@ async function cmdKeys(args) {
   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,
-};
+export {saveConfig, browserLogin};
+
+// 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]}`) {
+  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']);
+  const ANONYMOUS_COMMANDS = new Set(['login', 'keygen']);
 
-if (commands[command] && !ANONYMOUS_COMMANDS.has(command) && !loadConfig().token) {
-  die('Not authenticated. Run: pulsar login <apiUrl>');
-}
+  if (commands[command] && !ANONYMOUS_COMMANDS.has(command) && !loadConfig().token) {
+    die('Not authenticated. Run: pulsar login <apiUrl>');
+  }
 
-(commands[command] || (() => {
-  console.log('pulsar <login|apps|keys|release|release-train|promote|rollback|deployment|history|patch|keygen>');
-  process.exit(command ? 1 : 0);
-}))(rest);
+  (commands[command] || (() => {
+    console.log('pulsar <login|apps|keys|release|release-train|promote|rollback|deployment|history|patch|keygen>');
+    process.exit(command ? 1 : 0);
+  }))(rest);
+}