pulse-updates 1.0.11 → 1.0.12

package/scripts/publish.mjs

@@ -7,8 +7,53 @@ import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
 import { execSync, spawnSync } from 'child_process';
+import { fileURLToPath } from 'node:url';
 
-const VERSION = '1.0.1';
+// Read from package.json at runtime so `--version` never drifts from the published package.
+const VERSION = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+).version;
+
+/**
+ * Extract the native modules a JS bundle references, for publish-time crash-prediction.
+ * Native code cannot be shipped over the air, so a bundle referencing a native module that isn't
+ * in the installed binary will crash on launch. Scan the (pre-Hermes) plain JS for the canonical
+ * native-binding call sites. Heuristic, but combined with the server's diff-vs-previous-good it
+ * reliably flags "you added a new native dependency in a JS-only update".
+ */
+export function extractNativeModulesFromSource(source) {
+  const names = new Set();
+  const patterns = [
+    /TurboModuleRegistry\.(?:getEnforcing|get)\(\s*['"]([\w.$-]+)['"]/g,
+    /\brequireNativeComponent\(\s*['"]([\w.$-]+)['"]/g,
+    /\bcodegenNativeComponent(?:<[^>]*>)?\(\s*['"]([\w.$-]+)['"]/g,
+  ];
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(source)) !== null) names.add(m[1]);
+  }
+  return [...names].sort();
+}
+
+export function extractNativeModules(bundlePath) {
+  return extractNativeModulesFromSource(fs.readFileSync(bundlePath, 'utf8'));
+}
+
+/**
+ * Generate an Ed25519 manifest-signing keypair. Returns the raw 32-byte seed (server private key)
+ * and raw 32-byte public key as base64 — exactly the formats the server (Pulse:SigningKey) and the
+ * app (PulseUpdatesSigningPublicKey) expect.
+ */
+export function generateSigningKeyPair(keyId) {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  const privSeed = privateKey.export({ format: 'der', type: 'pkcs8' }).subarray(-32);
+  const pubRaw = publicKey.export({ format: 'der', type: 'spki' }).subarray(-32);
+  return {
+    keyId: keyId || `prod-${crypto.randomBytes(4).toString('hex')}`,
+    privateKeyBase64: Buffer.from(privSeed).toString('base64'),
+    publicKeyBase64: Buffer.from(pubRaw).toString('base64'),
+  };
+}
 
 // ANSI colors
 const colors = {
@@ -520,7 +565,7 @@ function detectRuntimeVersion(platform) {
 
 /**
  * Extract base API URL from full manifest URL
- * e.g., "https://pulse.lyramusic.app/pulse/manifest/lyra" -> "https://pulse.lyramusic.app"
+ * e.g., "https://pulse.example.com/pulse/manifest/my-app" -> "https://pulse.example.com"
  */
 function extractApiUrlFromManifestUrl(manifestUrl) {
   if (!manifestUrl) return null;
@@ -645,12 +690,19 @@ async function publish(options) {
   }
   log(`Bundle Dir: ${bundleDir}\n`);
 
+  let nativeModules = [];
+
   // Step 1: Create bundle (unless skipped)
   if (!config.skipBundle) {
     logStep('1/6', 'Creating bundle...');
     const bundlePath = createBundle(config.platform, bundleDir, config.entryFile);
     logSuccess(`Bundle created: ${bundlePath}`);
 
+    // Crash-prediction fingerprint: extract native module references from the plain JS bundle
+    // (must happen BEFORE Hermes bytecode compilation, while the bundle is still readable JS).
+    nativeModules = extractNativeModules(bundlePath);
+    log(`Native modules referenced: ${nativeModules.length}${nativeModules.length ? ` (${nativeModules.join(', ')})` : ''}`);
+
     // Step 2: Compile with Hermes
     logStep('2/6', 'Compiling with Hermes...');
     compileWithHermes(bundlePath, config.platform);
@@ -665,6 +717,18 @@ async function publish(options) {
   const assets = await collectAssets(bundleDir, config.platform);
   logSuccess(`Found ${assets.length} assets (1 bundle, ${assets.length - 1} assets)`);
 
+  // --dry-run: validate the publish locally (bundle + assets + native-module scan) without creating
+  // a release or touching the server. Useful in CI to catch a broken bundle before a real publish.
+  if (options['dry-run'] || options.dryRun) {
+    log(`\n${colors.bright}Dry run — nothing was published.${colors.reset}`);
+    log(`Would create release: runtimeVersion=${config.runtimeVersion} platform=${config.platform} channel=${config.channel}`);
+    log(`Assets: ${assets.length} (1 bundle + ${assets.length - 1})`);
+    log(`Native modules referenced: ${nativeModules.length}${nativeModules.length ? ` (${nativeModules.join(', ')})` : ''}`);
+    if (config.build) log(`Build: ${config.build}`);
+    if (config.message) log(`Message: ${config.message}`);
+    return;
+  }
+
   // Step 4: Create release
   logStep('4/6', 'Creating release...');
 
@@ -688,6 +752,7 @@ async function publish(options) {
       platform: config.platform,
       channel: config.channel,
       metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+      nativeModules: nativeModules.length ? nativeModules : undefined,
     }),
   });
 
@@ -712,6 +777,41 @@ async function publish(options) {
   }
   logSuccess(`Created release: ${release.id}`);
 
+  // Crash-prediction preflight: REFUSE the publish (fail-closed) if this release references native
+  // modules that weren't in the previous good release for this runtime version — native code can't ship
+  // over the air, so it would crash the installed cohort. Override with --allow-native-change.
+  let preflight = null;
+  try {
+    const pfRes = await fetch(`${config.apiUrl}/api/releases/${release.id}/preflight`, {
+      headers: { 'X-API-Key': config.apiKey },
+    });
+    if (pfRes.ok) preflight = await pfRes.json();
+  } catch {
+    log('⚠  Preflight check could not run (server unreachable); continuing.');
+  }
+  if (preflight) {
+    for (const w of preflight.warnings || []) log(`⚠  ${w}`);
+    // Only NEW NATIVE modules are risky for OTA (native code can't ship over the air); JS changes are
+    // always fine. FAIL-CLOSED by default: a new native module referenced by this JS bundle that isn't
+    // in the previous good build for this runtime-version would CRASH the whole installed cohort on load,
+    // so we refuse the publish. Override only with --allow-native-change (you certify the native module
+    // is already in the installed binary). `--no-native-check` skips the gate entirely.
+    if (!preflight.ok && !options['no-native-check']) {
+      const allow = options['allow-native-change'] || options.force;
+      if (!allow) {
+        throw new Error(
+          `Refusing to publish: this release references native module(s) NOT in the previous good build ` +
+          `for runtime-version ${config.runtimeVersion}/${config.platform}. Native code cannot ship over ` +
+          `the air — this OTA would crash the installed cohort on load. Ship a NEW native binary (and bump ` +
+          `the runtime-version) first. If you are certain the native module is already in the installed ` +
+          `binary, re-run with --allow-native-change.`
+        );
+      }
+      logWarning('--allow-native-change: publishing despite detected native-module changes. If those ' +
+        'native modules are NOT already in the installed binary, this OTA will crash the cohort.');
+    }
+  }
+
   // Step 5: Check which assets already exist and upload missing ones
   logStep('5/6', 'Checking and uploading assets...');
   const checkResponse = await fetch(`${config.apiUrl}/api/releases/${release.id}/assets/check`, {
@@ -827,6 +927,51 @@ async function publish(options) {
   }
 }
 
+/**
+ * Register the native capability set for a runtime version (run at APP BUILD time, against the
+ * embedded JS bundle the app ships with). Powers authoritative crash-prediction in preflight.
+ */
+async function registerCapabilities(options) {
+  const config = loadConfig(options);
+  const bundlePath = options['bundle'] || options['embedded-bundle'];
+  if (!bundlePath) {
+    throw new Error('Provide --bundle <path to the embedded JS bundle> (the bundle built into the app binary).');
+  }
+  const nativeModules = extractNativeModules(bundlePath);
+  log(`Registering ${nativeModules.length} native module(s) for ${config.runtimeVersion}/${config.platform}`);
+  const res = await fetch(`${config.apiUrl}/api/capabilities`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-API-Key': config.apiKey },
+    body: JSON.stringify({
+      runtimeVersion: config.runtimeVersion,
+      platform: config.platform,
+      nativeModules,
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to register capabilities: ${res.status} ${await res.text()}`);
+  }
+  logSuccess(`Capabilities registered (${nativeModules.length} native modules)`);
+}
+
+/**
+ * Print a fresh signing keypair, with copy-paste config for the server and the app.
+ */
+function keygen(options) {
+  const { keyId, privateKeyBase64, publicKeyBase64 } = generateSigningKeyPair(options['key-id']);
+  console.log(`
+${colors.bright}Pulse signing keypair generated${colors.reset}
+
+${colors.cyan}Server${colors.reset} (keep PRIVATE — set in the server secrets):
+  Pulse:SigningKeyId    = ${keyId}
+  Pulse:SigningKey      = ${privateKeyBase64}
+
+${colors.cyan}App${colors.reset} (PUBLIC — set in Info.plist / AndroidManifest):
+  PulseUpdatesSigningKeyId     = ${keyId}
+  PulseUpdatesSigningPublicKey = ${publicKeyBase64}
+`);
+}
+
 /**
  * Show help
  */
@@ -835,10 +980,12 @@ function showHelp() {
 ${colors.bright}Pulse Updates CLI v${VERSION}${colors.reset}
 
 ${colors.cyan}Usage:${colors.reset}
-  pulse-updates publish [options]
+  pulse-updates <command> [options]
 
 ${colors.cyan}Commands:${colors.reset}
-  publish     Create bundle and publish update to server
+  publish                 Create bundle and publish update to server
+  keygen                  Generate an Ed25519 signing keypair (server + app config)
+  register-capabilities   Record the embedded bundle's native capability set (crash-prediction)
 
 ${colors.cyan}Options:${colors.reset}
   --api-url <url>         API server URL (auto-detected from native config)
@@ -849,8 +996,15 @@ ${colors.cyan}Options:${colors.reset}
   --bundle-dir <dir>      Output directory (default: ./dist)
   --entry-file <file>     Entry file (default: index.ts)
   --skip-bundle           Skip bundle creation (use existing)
+  --dry-run               Build + validate locally without creating a release on the server
+  --allow-native-change   Publish even though new native modules were detected (you certify they're
+                          already in the installed binary). Default is FAIL-CLOSED: a new native module
+                          not in the shipped build is refused (it would crash the cohort over the air).
+  --no-native-check       Skip the native-mismatch gate entirely (not recommended)
+  --strict                (deprecated — blocking on native changes is now the default)
   --build <number>        Build number (shown in version, e.g., 1.0.0.42)
   --message <msg>         Release message/notes
+  --key-id <id>           Key id for keygen (default: auto-generated)
 
 ${colors.cyan}Configuration:${colors.reset}
   Options can be set via (in priority order):
@@ -888,6 +1042,12 @@ async function main() {
       case 'publish':
         await publish(options);
         break;
+      case 'register-capabilities':
+        await registerCapabilities(options);
+        break;
+      case 'keygen':
+        keygen(options);
+        break;
       case 'help':
       case '--help':
       case '-h':
@@ -913,4 +1073,15 @@ async function main() {
   }
 }
 
-main();
+// Only run the CLI when executed directly (not when imported by tests). realpath resolves the
+// bin symlink so `pulse-updates` still runs main.
+const isMain = (() => {
+  try {
+    return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  main();
+}

package/src/types.ts

@@ -55,6 +55,16 @@ export interface PulseUpdatesConfig {
   channel?: string;
   signingKeyId?: string;
   signingPublicKey?: string;
+  /**
+   * When true, manifests must carry a valid Ed25519 signature verifying against
+   * `signingPublicKey`; unsigned or unverifiable manifests are rejected (fail-closed).
+   *
+   * NATIVE-CONFIG ONLY: this is read from the Info.plist / AndroidManifest
+   * `PulseUpdatesRequireSignature` meta-data (defaults to `true` in release) and is NOT
+   * accepted by `configure()` — setting it here has no effect. Configure signing via the
+   * native config so a release can never silently flip to refuse-all from JS.
+   */
+  requireSignature?: boolean;
 }
 
 export interface PulseUpdatesState {