@novacraft-engineering/pulsar-cli 1.3.0 → 1.4.1

package/README.md

@@ -34,6 +34,7 @@ pulsar deployment ls <app>            # list deployments + keys
 pulsar deployment add <app> <name>    # create a new deployment (e.g. QA)
 pulsar history <app> <deployment>     # release history
 pulsar patch <app> <deployment> <label> [--rollout N] [--mandatory] [--disable] [--enable] [--devices id1,id2,...]
+pulsar migrate --from <serverUrl> --access-key <key>   # move apps from RevoPush / code-push-server (see below)
 ```
 
 ### Targeting a release's reach
@@ -52,6 +53,40 @@ 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.
 
+## Migrating from RevoPush / code-push-server
+
+`pulsar migrate` copies apps from any server that speaks the CodePush management API
+(RevoPush, a self-hosted `microsoft/code-push-server`) into Pulsar:
+
+```bash
+pulsar migrate --from https://<your-codepush-server> --access-key <source access key> \
+       [--apps MyApp-iOS,MyApp-Android] [--org "My Org"] [--platform ios|android] \
+       [--releases latest|none] [--dry-run]
+```
+
+- Each source app becomes a Pulsar app in `--org` (optional when you belong to one org), or reuses
+  the Pulsar app with the same name and platform. Deployments keep their names; existing ones are reused.
+- The platform comes from the source app's `os`, or its name (`*-iOS`, `*-Android`). Pass
+  `--platform` for apps named neither way.
+- `--releases latest` (default) downloads each deployment's current release, re-hashes and signs it
+  the way `pulsar release` does, and publishes it with the same target version, description,
+  mandatory flag, rollout and disabled state. A release that can't be downloaded or unzipped is
+  reported and skipped. Re-running is safe: a bundle already on the Pulsar deployment is not re-uploaded.
+- `--dry-run` reads both servers and prints the plan without writing anything to Pulsar.
+
+The run ends with a table of source key → new Pulsar key per deployment. Devices keep checking the
+old server until each app is rebuilt with its new key and Pulsar's URL:
+
+```xml
+<!-- iOS Info.plist -->
+<key>CodePushDeploymentKey</key><string>NEW_PULSAR_KEY</string>
+<key>CodePushServerURL</key><string>https://api.usepulsar.dev</string>
+
+<!-- Android res/values/strings.xml -->
+<string moduleConfig="true" name="CodePushDeploymentKey">NEW_PULSAR_KEY</string>
+<string moduleConfig="true" name="CodePushServerUrl">https://api.usepulsar.dev</string>
+```
+
 ## Use it from CI
 
 Both env vars are all a GitHub Actions / GitLab CI job needs:

package/migrate.js

@@ -0,0 +1,181 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import {api, die, getFlag, loadConfig, pushBuiltRelease, splitList} from './pulsar.js';
+import {computePackageHash} from './hash.js';
+
+const USAGE = 'Usage: pulsar migrate --from <serverUrl> --access-key <key> [--apps A,B] [--org <name>] [--platform ios|android] [--releases latest|none] [--dry-run]';
+
+async function sourceGet(source, pathname) {
+  const response = await fetch(source.url + pathname, {
+    headers: {authorization: `Bearer ${source.accessKey}`, accept: 'application/vnd.code-push.v2+json'},
+  });
+  if (!response.ok) throw new Error(`GET ${pathname} → ${response.status} ${response.statusText}`);
+  return response.json();
+}
+
+function platformOf(sourceApp, fallback) {
+  const declared = String(sourceApp.os || '').toLowerCase();
+  if (declared === 'ios' || declared === 'android') return declared;
+  if (/android/i.test(sourceApp.name)) return 'android';
+  if (/(^|[^a-z])ios([^a-z]|$)/i.test(sourceApp.name)) return 'ios';
+  return fallback;
+}
+
+async function chooseOrg(orgName) {
+  const orgs = await api('/orgs');
+  if (orgName) {
+    const match = orgs.find((org) => org.name.toLowerCase() === orgName.toLowerCase());
+    if (!match) die(`Organization not found: ${orgName}. Known: ${orgs.map((org) => org.name).join(', ') || '(none)'}`);
+    return match;
+  }
+  if (orgs.length === 1) return orgs[0];
+  die(`Pass --org <name> to choose where the apps go. Known: ${orgs.map((org) => org.name).join(', ') || '(none)'}`);
+}
+
+async function migrateRelease({source, pulsarApp, deploymentName, sourcePackage, dryRun}) {
+  if (!sourcePackage) return 'no release on source';
+  if (!sourcePackage.appVersion) return `not migrated: ${sourcePackage.label} has no target app version`;
+  if (dryRun) return `would re-release ${sourcePackage.label} (target ${sourcePackage.appVersion})`;
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsar-migrate-'));
+  const zipPath = path.join(workDir, 'source.zip');
+  const contentsDir = path.join(workDir, 'contents');
+  try {
+    const response = await fetch(new URL(sourcePackage.blobUrl, source.url)).catch((err) => {
+      throw new Error(`download failed (${err.message})`);
+    });
+    if (!response.ok) throw new Error(`download failed (${response.status})`);
+    fs.writeFileSync(zipPath, Buffer.from(await response.arrayBuffer()));
+    try {
+      execFileSync('unzip', ['-qq', '-o', zipPath, '-d', contentsDir], {stdio: 'pipe'});
+    } catch {
+      throw new Error('downloaded bundle is not a readable zip');
+    }
+    const packageHash = computePackageHash(contentsDir);
+    const existing = await api(`/apps/${pulsarApp.id}/deployments/${deploymentName}/releases`);
+    const already = existing.find((entry) => entry.packageHash === packageHash);
+    if (already) return `${sourcePackage.label} already on Pulsar as ${already.label}`;
+
+    const releaseArgs = [
+      '--target', sourcePackage.appVersion,
+      '--description', sourcePackage.description || '',
+      '--rollout', String(sourcePackage.rollout ?? 100),
+      ...(sourcePackage.isMandatory ? ['--mandatory'] : []),
+      ...(sourcePackage.isDisabled ? ['--disabled'] : []),
+    ];
+    const localKey = (process.env.PULSAR_SIGNING_KEY || '').trim();
+    const release = await pushBuiltRelease(pulsarApp, deploymentName, releaseArgs, contentsDir, packageHash, localKey);
+    const notes = [
+      sourcePackage.packageHash && sourcePackage.packageHash !== packageHash ? 're-hashed: source hash differed' : null,
+      release.signed === false ? 'UNSIGNED, blocked until an org owner approves it' : null,
+      release.isDisabled ? 'disabled' : null,
+    ].filter(Boolean);
+    return `${sourcePackage.label} → ${release.label}${notes.length ? ` (${notes.join('; ')})` : ''}`;
+  } catch (err) {
+    return `not migrated: ${err.message}`;
+  } finally {
+    fs.rmSync(workDir, {recursive: true, force: true});
+  }
+}
+
+async function migrateApp({source, sourceApp, org, pulsarApps, args, dryRun, rows}) {
+  const name = sourceApp.name.split(':').pop();
+  const platform = platformOf(sourceApp, getFlag(args, 'platform'));
+  const skipRow = (reason) => rows.push({app: name, deployment: '-', sourceKey: '-', pulsarKey: '-', release: reason});
+  if (!platform) return skipRow('skipped: platform unknown, pass --platform ios|android');
+
+  let deployments;
+  try {
+    ({deployments} = await sourceGet(source, `/apps/${encodeURIComponent(sourceApp.name)}/deployments`));
+  } catch (err) {
+    return skipRow(`skipped: ${err.message}`);
+  }
+
+  let pulsarApp = pulsarApps.find((app) => app.orgId === org.id && app.name === name && app.os === platform);
+  if (pulsarApp) console.log(`• ${name} [${platform}]: reusing the existing Pulsar app`);
+  else if (dryRun) console.log(`• ${name} [${platform}]: would create in ${org.name}`);
+  else {
+    pulsarApp = await api('/apps', {method: 'POST', body: {name, os: platform, orgId: org.id}});
+    console.log(`• ${name} [${platform}]: created in ${org.name}`);
+  }
+
+  for (const {name: deploymentName} of deployments) {
+    const row = {app: `${name} [${platform}]`, deployment: deploymentName, sourceKey: '-', pulsarKey: '-', release: ''};
+    rows.push(row);
+    let sourceDeployment;
+    try {
+      ({deployment: sourceDeployment} = await sourceGet(
+        source,
+        `/apps/${encodeURIComponent(sourceApp.name)}/deployments/${encodeURIComponent(deploymentName)}`,
+      ));
+    } catch (err) {
+      row.release = `not migrated: ${err.message}`;
+      continue;
+    }
+    row.sourceKey = sourceDeployment.key || '-';
+
+    row.pulsarKey = pulsarApp?.deployments?.[deploymentName]?.key;
+    if (!row.pulsarKey && dryRun) row.pulsarKey = '(new)';
+    else if (!row.pulsarKey) {
+      ({key: row.pulsarKey} = await api(`/apps/${pulsarApp.id}/deployments`, {method: 'POST', body: {name: deploymentName}}));
+      console.log(`  added deployment ${deploymentName}`);
+    }
+
+    row.release = getFlag(args, 'releases', 'latest') === 'none'
+      ? 'skipped (--releases none)'
+      : await migrateRelease({source, pulsarApp, deploymentName, sourcePackage: sourceDeployment.package, dryRun});
+  }
+}
+
+function printSummary(rows) {
+  const columns = [['app', 'App'], ['deployment', 'Deployment'], ['sourceKey', 'Source key'], ['pulsarKey', 'Pulsar key'], ['release', 'Release']];
+  const widths = columns.map(([field, title]) => Math.max(title.length, ...rows.map((row) => String(row[field]).length)));
+  const line = (cells) => cells.map((cell, index) => String(cell).padEnd(widths[index])).join('  ').trimEnd();
+  console.log(`\n${line(columns.map(([, title]) => title))}`);
+  console.log(line(widths.map((width) => '-'.repeat(width))));
+  for (const row of rows) console.log(line(columns.map(([field]) => row[field])));
+}
+
+function printRebuildReminder(serverUrl) {
+  console.log(`
+Devices keep checking the old server until each app is rebuilt with its new Pulsar key and server URL.
+
+  iOS — Info.plist:
+    <key>CodePushDeploymentKey</key>
+    <string>PULSAR_KEY_FROM_TABLE</string>
+    <key>CodePushServerURL</key>
+    <string>${serverUrl}</string>
+
+  Android — android/app/src/main/res/values/strings.xml:
+    <string moduleConfig="true" name="CodePushDeploymentKey">PULSAR_KEY_FROM_TABLE</string>
+    <string moduleConfig="true" name="CodePushServerUrl">${serverUrl}</string>`);
+}
+
+export async function migrate(args) {
+  const from = getFlag(args, 'from');
+  const accessKey = getFlag(args, 'access-key');
+  if (!from || !accessKey) die(USAGE);
+  const releasesMode = getFlag(args, 'releases', 'latest');
+  if (!['latest', 'none'].includes(releasesMode)) die(`--releases must be latest or none\n${USAGE}`);
+  const dryRun = args.includes('--dry-run');
+  const source = {url: from.replace(/\/$/, ''), accessKey};
+
+  const {apps: sourceApps = []} = await sourceGet(source, '/apps').catch((err) => die(`Could not list apps on ${from}: ${err.message}`));
+  const wanted = splitList(getFlag(args, 'apps'), ',');
+  const selected = wanted.length ? sourceApps.filter((app) => wanted.includes(app.name) || wanted.includes(app.name.split(':').pop())) : sourceApps;
+  const unmatched = wanted.filter((wantedName) => !selected.some((app) => app.name === wantedName || app.name.split(':').pop() === wantedName));
+  if (unmatched.length) console.log(`⚠ not on the source server: ${unmatched.join(', ')}`);
+  if (!selected.length) die(`No apps to migrate. Source has: ${sourceApps.map((app) => app.name).join(', ') || '(none)'}`);
+
+  const org = await chooseOrg(getFlag(args, 'org'));
+  const pulsarApps = await api('/apps');
+  console.log(`${dryRun ? 'DRY RUN — nothing will be written to Pulsar.\n' : ''}Migrating ${selected.length} app(s) from ${source.url} into ${org.name}`);
+
+  const rows = [];
+  for (const sourceApp of selected) {
+    await migrateApp({source, sourceApp, org, pulsarApps, args, dryRun, rows});
+  }
+  printSummary(rows);
+  printRebuildReminder(loadConfig().apiUrl);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novacraft-engineering/pulsar-cli",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Pulsar OTA release CLI — bundle, hash, and ship React Native updates over-the-air.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "pulsar.js",
     "hash.js",
+    "migrate.js",
     "README.md",
     "LICENSE"
   ],
@@ -26,7 +27,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/hash.test.js && node test/security.test.js && node test/signing.test.js && node test/entry.test.js"
+    "test": "node test/hash.test.js && node test/security.test.js && node test/signing.test.js && node test/entry.test.js && node test/migrate.test.js"
   },
   "keywords": [
     "cli",

package/pulsar.js

@@ -8,6 +8,7 @@ import {execFileSync} from 'node:child_process';
 import crypto from 'node:crypto';
 import {fileURLToPath} from 'node:url';
 import {computePackageHash, fileHashes} from './hash.js';
+import {migrate} from './migrate.js';
 
 // Code signing: sign the package hash into an RS256 JWT the client verifies against its
 // CodePushPublicKey (Info.plist). Both native SDKs read it from <update>/CodePush/.codepushrelease
@@ -41,18 +42,20 @@ function loadConfig() {
   return {
     apiUrl: process.env.PULSAR_API_URL || fromFile.apiUrl,
     token: process.env.PULSAR_TOKEN || fromFile.token,
+    deviceId: fromFile.deviceId,
   };
 }
 
 function saveConfig(config) {
   // 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.
+  const deviceId = config.deviceId || loadConfig().deviceId;
   fs.mkdirSync(CONFIG_DIR, {recursive: true, mode: 0o700});
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {mode: 0o600});
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify({...config, deviceId}, 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} = {}) {
+async function api(pathname, {method = 'GET', body, headers = {}, raw, allowAnonymous, onUploadProgress, optional} = {}) {
   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
@@ -95,6 +98,7 @@ async function api(pathname, {method = 'GET', body, headers = {}, raw, allowAnon
     } catch {
       detail = text.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 300);
     }
+    if (optional) throw new Error(`${response.status} ${detail}`);
     die(`${response.status} ${response.statusText}: ${detail}`);
   }
   try {
@@ -201,7 +205,7 @@ async function resolveApp(nameOrId, platform) {
   die(`Multiple apps named "${nameOrId}" (${named.map((app) => app.os).join(', ')}). Pass --platform ios|android, or use the app id.`);
 }
 
-function bundle(platform, contentsDir) {
+function bundle(platform, contentsDir, sourcemapPath) {
   const bundleName = platform === 'ios' ? 'main.jsbundle' : 'index.android.bundle';
   fs.mkdirSync(contentsDir, {recursive: true});
   console.log(`• bundling ${platform}…`);
@@ -215,11 +219,22 @@ function bundle(platform, contentsDir) {
       '--entry-file', 'index.js',
       '--bundle-output', path.join(contentsDir, bundleName),
       '--assets-dest', contentsDir,
+      ...(sourcemapPath ? ['--sourcemap-output', sourcemapPath] : []),
     ],
     {stdio: 'inherit'},
   );
 }
 
+function fileManifest(contentsDir) {
+  const hashes = fileHashes(contentsDir);
+  return Object.fromEntries(Object.entries(hashes).map(([relativePath, hash]) => [relativePath, {hash, size: fs.statSync(path.join(contentsDir, relativePath)).size}]));
+}
+
+function sizeGrowth(previousSize, nextSize) {
+  if (!(previousSize > 0) || !(nextSize > 0)) return null;
+  return Math.round(((nextSize - previousSize) / previousSize) * 100);
+}
+
 function zipContents(contentsDir) {
   const zipPath = path.join(os.tmpdir(), `pulsar-${Date.now()}.zip`);
   execFileSync('zip', ['-qq', '-r', '-X', zipPath, '.'], {cwd: contentsDir});
@@ -334,8 +349,9 @@ async function cmdLogin(args) {
 
   const email = await prompt('Email: ');
   const password = await prompt('Password: ', true);
-  const {token, user} = await api('/auth/login', {method: 'POST', body: {email, password}, allowAnonymous: true});
-  saveConfig({apiUrl, token});
+  const deviceId = loadConfig().deviceId || crypto.randomBytes(16).toString('hex');
+  const {token, user} = await api('/auth/login', {method: 'POST', body: {email, password}, headers: {'x-device-id': deviceId}, allowAnonymous: true});
+  saveConfig({apiUrl, token, deviceId});
   console.log(`✓ logged in as ${user.email} (${user.platformRole})`);
 }
 
@@ -376,15 +392,30 @@ async function signForApp(app, deployment, contentsDir, packageHash, localKey) {
 
 // Sign and push an already-built 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, localKey) {
+async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath} = {}) {
   await signForApp(app, deployment, contentsDir, packageHash, localKey);
   const zip = fs.readFileSync(zipContents(contentsDir));
   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 {}
+  try {
+    const existing = await api(`/apps/${app.id}/deployments/${deployment}/releases`, {optional: true});
+    prevLatest = [...existing].reverse().find((entry) => !entry.isDisabled) || existing[existing.length - 1] || null;
+  } catch {}
+  try {
+    const target = getFlag(args, 'target');
+    const {versions, reach, recentDays} = await api(`/apps/${app.id}/binary-versions?target=${encodeURIComponent(target)}`, {optional: true});
+    if (versions?.length && reach && !reach.everLaunched) {
+      console.log(`⚠ no device has reported a store build matching ${target}; this release reaches nobody yet (builds seen: ${versions.slice(0, 5).map((entry) => entry.version).join(', ')})`);
+    } else if (versions?.length && reach && !reach.recentLaunches) {
+      console.log(`⚠ no store build matching ${target} was opened in the last ${recentDays} days (matches: ${reach.matchingVersions.join(', ')})`);
+    }
+  } catch {}
+  const growth = sizeGrowth(prevLatest?.size, zip.length);
+  if (growth !== null && growth > 20) {
+    console.log(`⚠ bundle is ${growth}% larger than ${prevLatest.label} (${(prevLatest.size / 1e6).toFixed(2)}MB → ${(zip.length / 1e6).toFixed(2)}MB)`);
+  }
+  const maxGrowth = getFlag(args, 'max-growth');
+  if (maxGrowth !== undefined && growth !== null && growth > Number(maxGrowth)) {
+    die(`bundle grew ${growth}%, more than --max-growth ${maxGrowth}%. Nothing was released.`);
   }
 
   const startsAt = parseSchedule(getFlag(args, 'schedule'));
@@ -419,13 +450,38 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
   ].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.approval && !release.approval.approvedAt) {
+    console.log(`⏸ waiting for approval: ${deployment} needs a second admin or owner to approve ${release.label} in the dashboard before devices get it`);
+  }
   if (release.signed === false) {
     console.log('⚠ UNSIGNED — this build is blocked and will not reach devices. An org owner can enable it from the dashboard.');
   }
   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 {
+    await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/manifest`, {method: 'POST', body: {files: fileManifest(contentsDir)}, optional: true});
+  } catch (err) {
+    console.log(`• file list not recorded: ${err.message}`);
+  }
+  if (sourcemapPath && fs.existsSync(sourcemapPath)) {
+    try {
+      const map = fs.readFileSync(sourcemapPath);
+      await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/sourcemap`, {
+        method: 'POST',
+        raw: true,
+        optional: true,
+        body: map,
+        onUploadProgress: uploadProgress(`uploading ${(map.length / 1e6).toFixed(1)}MB source map`),
+        headers: {'content-type': 'application/json'},
+      });
+      console.log('• source map uploaded: crash stacks for this release will show your source files');
+    } catch (err) {
+      console.log(`• source map not uploaded: ${err.message}`);
+    }
+  }
+
+  if (!args.includes('--no-diff') && prevLatest && prevLatest.packageHash && prevLatest.packageHash !== packageHash) {
     try {
       const {apiUrl} = loadConfig();
       const baseZip = await fetchBlob(apiUrl, app.id, `${prevLatest.packageHash}.zip`);
@@ -434,6 +490,7 @@ async function pushBuiltRelease(app, deployment, args, contentsDir, packageHash,
       await api(`/apps/${app.id}/deployments/${deployment}/releases/${release.label}/diff`, {
         method: 'POST',
         raw: true,
+        optional: true,
         body: diffZip,
         onUploadProgress: uploadProgress(`uploading ${(diffZip.length / 1e6).toFixed(1)}MB diff`),
         headers: {'content-type': 'application/zip', 'x-base-hash': prevLatest.packageHash},
@@ -455,22 +512,23 @@ function buildOnce(args) {
   if (privateKeyPath && !fs.existsSync(privateKeyPath)) die(`no signing key at ${privateKeyPath} — drop --private-key to have Pulsar sign`);
   const localKey = privateKeyPath ? fs.readFileSync(privateKeyPath, 'utf8') : (process.env.PULSAR_SIGNING_KEY || '').trim();
   const contentsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsar-build-'));
-  bundle(platform, contentsDir);
+  const sourcemapPath = args.includes('--no-sourcemap') ? null : `${contentsDir}.map`;
+  bundle(platform, contentsDir, sourcemapPath);
   const packageHash = computePackageHash(contentsDir);
   console.log(`• hash ${packageHash.slice(0, 12)}…`);
-  return {contentsDir, packageHash, localKey};
+  return {contentsDir, packageHash, localKey, sourcemapPath};
 }
 
 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] [--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 (!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] [--no-sourcemap] [--max-growth <percent>] [--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')) {
     console.log(`• note: resolved app "${app.name}" is ${app.os}; bundling ${getFlag(args, 'platform', 'ios')}`);
   }
-  const {contentsDir, packageHash, localKey} = buildOnce(args);
-  await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey);
+  const {contentsDir, packageHash, localKey, sourcemapPath} = buildOnce(args);
+  await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath});
 }
 
 // Release the same built bundle to several apps at once (shared-codebase / white-label fleets).
@@ -495,11 +553,11 @@ async function cmdReleaseTrain(args) {
   apps = apps.filter((app) => app.os === platform);
   if (!apps.length) die(`No ${platform} apps matched.`);
 
-  const {contentsDir, packageHash, localKey} = buildOnce(args);
+  const {contentsDir, packageHash, localKey, sourcemapPath} = 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, localKey);
+      await pushBuiltRelease(app, deployment, args, contentsDir, packageHash, localKey, {sourcemapPath});
     } catch (err) {
       console.log(`✗ ${app.name}: ${err.message}`);
     }
@@ -628,7 +686,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, signCodePushJWT, SIGNATURE_PATH};
+export {saveConfig, browserLogin, signCodePushJWT, SIGNATURE_PATH, api, die, getFlag, loadConfig, pushBuiltRelease, splitList};
 
 // Only dispatch when run as the CLI — importing the module (e.g. from tests) must not execute a command.
 // Compare real paths: a global install runs through a bin symlink, so argv[1] is not this file's path.
@@ -654,6 +712,7 @@ if (invokedAsCli()) {
     patch: cmdPatch,
     keygen: cmdKeygen,
     keys: cmdKeys,
+    migrate,
   };
 
   const ANONYMOUS_COMMANDS = new Set(['login', 'keygen']);
@@ -663,7 +722,7 @@ if (invokedAsCli()) {
   }
 
   (commands[command] || (() => {
-    console.log('pulsar <login|apps|keys|release|release-train|promote|rollback|deployment|history|patch|keygen>');
+    console.log('pulsar <login|apps|keys|release|release-train|promote|rollback|deployment|history|patch|keygen|migrate>');
     process.exit(command ? 1 : 0);
   }))(rest);
 }