@omega.js/desktop 0.1.0

package/dist/lib/sign-helpers/auto-unlock.js

@@ -0,0 +1,95 @@
+// Auto-unlocks SafeNet / eToken password dialogs that signtool triggers when
+// using a SafeNet-managed EV cert (selected via /sha1 thumbprint).
+//
+// Strategy: in parallel with the signtool invocation, poll the Win32 window
+// list (via automately.getWindows() — a single native call, ~1-5ms) looking
+// for a "Token Logon" window. When detected, focus it and type the password
+// + Enter via automately (a maintained nutjs fork).
+//
+// Falls back to a no-op if:
+//   - automately isn't installed (optional dep, may have failed to compile)
+//   - WIN_CSC_KEY_PASSWORD isn't set (signing in thumbprint mode without auto-unlock)
+//   - not on Windows
+//
+// Returns { stop } so the caller can cancel polling once signtool finishes.
+
+let automately;
+try {
+  automately = require('automately');
+} catch (e) {
+  automately = null;
+}
+
+const POLL_INTERVAL_MS    = 500;    // automately.getWindows() is fast — poll twice a second
+const POLL_TIMEOUT_MS     = 60000;
+const PRE_TYPE_DELAY_MS   = 2000;   // safety wait after detecting dialog before typing
+const PER_CHAR_DELAY_MS   = 60;     // small delay between keystrokes — some dialogs drop chars on fast input
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+async function findTokenLogonWindow() {
+  const windows = await automately.getWindows();
+  for (const w of windows) {
+    let title = '';
+    try { title = await w.title; } catch (e) { continue; }
+    if (title && title.startsWith('Token Logon')) return title;
+  }
+  return null;
+}
+
+function startAutoUnlock({ password, logger }) {
+  if (process.platform !== 'win32') return { stop: () => {} };
+  if (!password) return { stop: () => {} };
+  if (!automately) {
+    if (logger) logger.warn('automately not installed — SafeNet password prompt will need manual entry. Run `npm install` in the @omega.js/desktop repo to enable auto-unlock.');
+    return { stop: () => {} };
+  }
+
+  let stopped = false;
+  let typed   = false;
+  const startedAt = Date.now();
+
+  (async function poll() {
+    let attempt = 0;
+    while (!stopped && !typed && Date.now() - startedAt < POLL_TIMEOUT_MS) {
+      attempt += 1;
+      const elapsed = Math.round((Date.now() - startedAt) / 1000);
+      const pollStart = Date.now();
+      let title = null;
+      try {
+        title = await findTokenLogonWindow();
+      } catch (e) {
+        if (logger) logger.log(`auto-unlock: poll ${attempt} (${elapsed}s) — getWindows error: ${e.message}`);
+      }
+      const pollMs = Date.now() - pollStart;
+
+      if (title) {
+        if (logger) logger.log(`auto-unlock: SafeNet Token Logon dialog detected (attempt ${attempt}, ${elapsed}s, poll took ${pollMs}ms) — title: "${title}" — waiting ${PRE_TYPE_DELAY_MS}ms before typing...`);
+        await sleep(PRE_TYPE_DELAY_MS);
+
+        if (logger) logger.log(`auto-unlock: typing password (${password.length} chars, ~${PER_CHAR_DELAY_MS}ms each)...`);
+        for (const ch of password) {
+          if (stopped) return;
+          await automately.keyboard.type(ch);
+          await sleep(PER_CHAR_DELAY_MS);
+        }
+        await automately.keyboard.type(automately.Key.Enter);
+        typed = true;
+        if (logger) logger.log('auto-unlock: password typed + Enter pressed.');
+        return;
+      }
+
+      if (logger) logger.log(`auto-unlock: poll ${attempt} (${elapsed}s, took ${pollMs}ms) — no Token Logon window`);
+      await sleep(POLL_INTERVAL_MS);
+    }
+    if (!typed && !stopped && logger) logger.warn(`auto-unlock: timed out after ${Math.round(POLL_TIMEOUT_MS / 1000)}s without seeing the Token Logon dialog`);
+  })().catch((e) => {
+    if (logger) logger.warn(`auto-unlock: poll error: ${e.message}`);
+  });
+
+  return {
+    stop: () => { stopped = true; },
+  };
+}
+
+module.exports = { startAutoUnlock };

package/dist/lib/sign-helpers/entitlements.js

@@ -0,0 +1,98 @@
+// Generate dist/config/entitlements.mac.plist from @omega.js/desktop defaults + consumer overrides.
+//
+// Consumer config schema (in omega.json5):
+//   entitlements: {
+//     mac: {
+//       'com.apple.security.cs.allow-jit': false,           // override default `true`
+//       'com.apple.security.network.client': true,          // add a key not in defaults
+//     },
+//   }
+//
+// Empty/missing → defaults only. Consumer keys override defaults. Setting a key to `null` or
+// `undefined` removes it from the merged set (escape hatch to drop a default entitlement).
+
+const path    = require('path');
+const jetpack = require('fs-jetpack');
+
+// @omega.js/desktop's canonical mac entitlement defaults. Mirrors the legacy build/entitlements.mac.plist.
+const DEFAULT_MAC_ENTITLEMENTS = {
+  // Hardened runtime — required for notarization.
+  'com.apple.security.cs.allow-jit':                          true,
+  'com.apple.security.cs.allow-unsigned-executable-memory':   true,
+  'com.apple.security.cs.allow-dyld-environment-variables':   true,
+
+  // Network — Firebase Auth, auto-update, web requests.
+  'com.apple.security.network.client':                        true,
+  'com.apple.security.network.server':                        true,
+
+  // Files — electron-store reads/writes user-selected files.
+  'com.apple.security.files.user-selected.read-write':        true,
+
+  // Library validation off — Electron helpers + native modules load fine despite signing chain mismatch.
+  'com.apple.security.cs.disable-library-validation':         true,
+};
+
+function mergeMacEntitlements(consumerOverrides) {
+  const merged = { ...DEFAULT_MAC_ENTITLEMENTS };
+  if (consumerOverrides && typeof consumerOverrides === 'object') {
+    for (const [key, value] of Object.entries(consumerOverrides)) {
+      if (value === null || value === undefined) {
+        delete merged[key];                  // explicit removal
+      } else {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+function renderPlist(entitlements) {
+  // Plist format is XML. Bool values render as <true/> or <false/>; strings as <string>...</string>;
+  // numbers as <integer> or <real>. We only emit bool/string/number — that covers all known mac entitlements.
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+  ];
+
+  for (const [key, value] of Object.entries(entitlements)) {
+    lines.push(`  <key>${escapeXml(key)}</key>`);
+    if (typeof value === 'boolean') {
+      lines.push(value ? '  <true/>' : '  <false/>');
+    } else if (typeof value === 'number') {
+      lines.push(Number.isInteger(value) ? `  <integer>${value}</integer>` : `  <real>${value}</real>`);
+    } else if (Array.isArray(value)) {
+      lines.push('  <array>');
+      for (const v of value) {
+        if (typeof v === 'string') lines.push(`    <string>${escapeXml(v)}</string>`);
+      }
+      lines.push('  </array>');
+    } else {
+      lines.push(`  <string>${escapeXml(String(value))}</string>`);
+    }
+  }
+
+  lines.push('</dict>', '</plist>', '');
+  return lines.join('\n');
+}
+
+function escapeXml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// Materialize the merged plist file. Returns the absolute path to the written file.
+function writeMacEntitlements(distRoot, consumerOverrides) {
+  const merged  = mergeMacEntitlements(consumerOverrides);
+  const xml     = renderPlist(merged);
+  const outPath = path.join(distRoot, 'config', 'entitlements.mac.plist');
+  jetpack.write(outPath, xml);
+  return outPath;
+}
+
+module.exports = {
+  DEFAULT_MAC_ENTITLEMENTS,
+  mergeMacEntitlements,
+  renderPlist,
+  writeMacEntitlements,
+};

package/dist/lib/sign-helpers/resolve-icons.js

@@ -0,0 +1,171 @@
+// Resolve icon paths via a convention-only waterfall, copy resolved files into
+// dist/config/icons/, and return the paths electron-builder.yml needs.
+//
+// Resolution order per slot, per platform (most specific wins):
+//   1. <projectRoot>/config/icons/<platform>/<file>       — platform-specific override
+//   2. <projectRoot>/config/icons/global/<file>           — universal fallback (shared by all platforms)
+//   3. <projectRoot>/config/icons/windows/<file>          — Linux-only extra: legacy Linux→Windows fallback
+//   4. <@omega.js/desktop>/dist/config/icons/<platform>/<file>           — @omega.js/desktop bundled default
+//
+// Note the DMG slot is macOS-only by definition. Its lookup chain skips step 3
+// entirely and step 2 only checks `global/` for the DMG file specifically (which
+// almost never exists — a "global DMG background" makes no sense).
+//
+// Retina (@2x) variants are DERIVED. Consumers ship ONE file at the @2x (native) size.
+// @omega.js/desktop downscales it to write the @1x sibling. So `tray.png` is the 32x32 native retina
+// source (consumer-facing input name), and @omega.js/desktop emits both `trayTemplate.png` (16x16)
+// and `trayTemplate@2x.png` (32x32) into `dist/config/icons/macos/`. The output name
+// diverges from the input on macOS because the `Template` suffix is a system magic
+// marker that triggers auto-inversion in dark mode. Same retina derivation for
+// `dmg.png` (1080x760 native → emits 540x380 + 1080x760, no name change).
+//
+// Special fallbacks:
+//   - Windows tray slot falls back to the Windows app icon if no tray source resolves.
+//   - Linux uses the Windows resolved paths if its own chain produces nothing.
+
+const path    = require('path');
+const jetpack = require('fs-jetpack');
+const sharp   = require('sharp');
+
+// Slot defs: per platform, a list of { slot, file, outFile, retina } entries.
+//   slot    = key under resolved[platform] (e.g. 'app' → resolved.macos.app)
+//   file    = INPUT filename — what consumers ship in config/icons/<platform>/ (or global/)
+//   outFile = OUTPUT filename written into dist/config/icons/<platform>/.
+//             Defaults to `file`. Diverges only when the on-disk runtime name
+//             carries magic meaning (e.g. macOS tray icons must end in
+//             `Template.png` for the OS to auto-invert them in dark mode —
+//             @omega.js/desktop owns that detail so consumers can just call it `tray.png`).
+//   retina  = if set, the SOURCE file is treated as @2x (native). @omega.js/desktop downscales it
+//             to produce the @1x sibling. Both files are written into dist/.
+const SLOTS = {
+  macos: [
+    { slot: 'app',   file: 'icon.png' },
+    { slot: 'tray',  file: 'tray.png', outFile: 'trayTemplate.png', retina: true },
+    { slot: 'dmg',   file: 'dmg.png',                                retina: true },
+  ],
+  windows: [
+    { slot: 'app',   file: 'icon.png' },
+    { slot: 'tray',  file: 'tray.png' },        // optional; falls back to app icon if missing
+  ],
+  linux: [
+    { slot: 'app',   file: 'icon.png' },
+    { slot: 'tray',  file: 'tray.png' },
+  ],
+};
+
+// Given a non-retina file path, return its @2x sibling (`foo.png` → `foo@2x.png`).
+function retinaSibling(p) {
+  const dir  = path.dirname(p);
+  const ext  = path.extname(p);
+  const base = path.basename(p, ext);
+  return path.join(dir, `${base}@2x${ext}`);
+}
+
+// Find the source file for a slot on a platform via the convention waterfall.
+// Most-specific-wins: platform-specific override beats global fallback beats
+// bundled default. Linux gets an extra step: it falls back to the Windows
+// consumer dir before going to bundled defaults (legacy compat — Linux apps
+// historically reuse Windows assets).
+function findSource({ slot, file }, platform, opts) {
+  const { projectRoot, emDefaultsRoot } = opts;
+
+  // 1. Platform-specific override.
+  const platformPath = path.join(projectRoot, 'config', 'icons', platform, file);
+  if (jetpack.exists(platformPath)) return platformPath;
+
+  // 2. Universal fallback (shared by all platforms). Skip for macOS-only slots
+  // like `dmg` where a global file makes no sense — but we still allow it (if
+  // someone REALLY wants a global dmg.png, fine; we don't enforce semantics).
+  const globalPath = path.join(projectRoot, 'config', 'icons', 'global', file);
+  if (jetpack.exists(globalPath)) return globalPath;
+
+  // 3. Linux-only: legacy fallback through Windows consumer dir.
+  if (platform === 'linux') {
+    const winFallback = path.join(projectRoot, 'config', 'icons', 'windows', file);
+    if (jetpack.exists(winFallback)) return winFallback;
+  }
+
+  // 4. @omega.js/desktop bundled default.
+  const bundled = path.join(emDefaultsRoot, 'icons', platform, file);
+  if (jetpack.exists(bundled)) return bundled;
+
+  // Linux gets one more shot at bundled defaults via the Windows chain.
+  if (platform === 'linux') {
+    const bundledWin = path.join(emDefaultsRoot, 'icons', 'windows', file);
+    if (jetpack.exists(bundledWin)) return bundledWin;
+  }
+
+  return null;
+}
+
+// Downscale an @2x source to its @1x sibling. Source is written as the @2x output,
+// and a half-sized copy is written alongside as the @1x output. Returns { ref1x, ref2x }.
+async function emitRetinaPair(src, dest) {
+  const dest2x = retinaSibling(dest);
+
+  // @2x output is a straight copy of the native source.
+  jetpack.copy(src, dest2x, { overwrite: true });
+
+  // @1x output is the source downscaled by 50%.
+  const meta = await sharp(src).metadata();
+  const w1x = Math.max(1, Math.round((meta.width  || 2) / 2));
+  const h1x = Math.max(1, Math.round((meta.height || 2) / 2));
+  await sharp(src)
+    .resize(w1x, h1x, { fit: 'fill' })
+    .toFile(dest);
+
+  return { ref1x: dest, ref2x: dest2x };
+}
+
+// Resolve all icons, copy into dist/config/icons/, return the wiring object that
+// build-config consumes.
+async function resolveAndCopy({ config, projectRoot, distRoot, emDefaultsRoot }) {
+  const distIconsRoot = path.join(distRoot, 'config', 'icons');
+  jetpack.dir(distIconsRoot);
+
+  const resolved = { macos: {}, windows: {}, linux: {} };
+
+  // First pass: resolve each platform/slot. For retina slots, source file is treated as
+  // @2x; @omega.js/desktop emits both <slot>.png (downscaled) and <slot>@2x.png (the source) into dist.
+  for (const platform of Object.keys(SLOTS)) {
+    for (const def of SLOTS[platform]) {
+      const src = findSource(def, platform, { projectRoot, emDefaultsRoot });
+      if (!src) continue;
+
+      const outFile = def.outFile || def.file;
+      const dest = path.join(distIconsRoot, platform, outFile);
+      jetpack.dir(path.dirname(dest));
+
+      if (def.retina) {
+        const { ref1x, ref2x } = await emitRetinaPair(src, dest);
+        resolved[platform][def.slot]            = ref1x;
+        resolved[platform][`${def.slot}2x`]     = ref2x;
+      } else {
+        jetpack.copy(src, dest, { overwrite: true });
+        resolved[platform][def.slot] = dest;
+      }
+    }
+  }
+
+  // Special fallbacks:
+  //   - Windows tray → Windows app icon if tray didn't resolve.
+  if (!resolved.windows.tray && resolved.windows.app) {
+    resolved.windows.tray = resolved.windows.app;
+  }
+  //   - Linux entirely follows Windows resolved paths if its own chain produced nothing.
+  for (const slot of ['app', 'tray']) {
+    if (!resolved.linux[slot] && resolved.windows[slot]) {
+      resolved.linux[slot] = resolved.windows[slot];
+    }
+  }
+
+  return resolved;
+}
+
+module.exports = {
+  SLOTS,
+  retinaSibling,
+  findSource,
+  emitRetinaPair,
+  resolveAndCopy,
+};

package/dist/lib/sign-helpers/sign-events.js

@@ -0,0 +1,75 @@
+// Structured signing event log — appends JSONL lines to `<runner-dir>/omega-signing.log`
+// (or another path via `OMEGA_SIGN_LOG`) so a separate `mgr runner monitor` process can
+// tail + pretty-print them in real time on the Windows box.
+//
+// Why JSONL not plain text: lets the monitor pretty-print durations, color the failure
+// events distinctively, and group sign-start / sign-done pairs without parsing English.
+//
+// Where the file lands (resolved in this priority order):
+//   1. `OMEGA_SIGN_LOG` env var (explicit override) — wins if set
+//   2. `<OMEGA_RUNNER_HOME>/omega-signing.log` — when caller has set the runner home
+//   3. `<defaultRunnerHome()>/omega-signing.log` on Windows — the runner home the
+//      install actually uses (`%LOCALAPPDATA%\omega-runner`), read from
+//      src/commands/runner.js so the two can never drift again. This is the
+//      machine-wide default, so EVERY signing job from every org/repo writes to
+//      the same file and `npx omega runner monitor` with no args picks it up.
+//   4. `<RUNNER_TOOLSDIRECTORY>/omega-signing.log` — fallback if someone runs
+//      sign-windows outside the runner-installed path
+//   5. `<process.cwd()>/logs/signing.log` — local dev fallback (matches dev.log, build.log, etc.)
+
+const os      = require('os');
+const path    = require('path');
+const jetpack = require('fs-jetpack');
+
+const logger = new (require('../../build.js'))().logger('sign-events');
+
+function resolveLogPath(env, platform) {
+  env      = env || process.env;
+  platform = platform || process.platform;
+
+  if (env.OMEGA_SIGN_LOG) return env.OMEGA_SIGN_LOG;
+  if (env.OMEGA_RUNNER_HOME) {
+    return path.join(env.OMEGA_RUNNER_HOME, 'omega-signing.log');
+  }
+  if (platform === 'win32') {
+    // Required lazily: runner.js pulls sign-events in from `monitor`, and a
+    // top-level require here would make that a cycle.
+    const { defaultRunnerHome } = require('../../commands/runner.js');
+    return path.join(defaultRunnerHome(platform, env), 'omega-signing.log');
+  }
+  const ciRoot = env.RUNNER_TOOLSDIRECTORY
+    || env.RUNNER_WORKSPACE
+    || env.RUNNER_ROOT;
+  if (ciRoot) {
+    return path.join(ciRoot, 'omega-signing.log');
+  }
+  return path.join(process.cwd(), 'logs', 'signing.log');
+}
+
+const logPath = resolveLogPath();
+
+function emit(event, data) {
+  const line = `${JSON.stringify({
+    ts:    new Date().toISOString(),
+    pid:   process.pid,
+    host:  os.hostname(),
+    event,
+    ...data,
+  })}\n`;
+  try {
+    // jetpack.append creates the parent directory when it is missing. The first
+    // event of a job is often the first thing to touch the runner home, and a
+    // dropped first line is a whole signing run with no trail.
+    jetpack.append(logPath, line);
+  } catch (e) {
+    // If we can't write the event file, don't crash the sign — warn on the
+    // framework logger so the GH Actions runner log still has the trace.
+    logger.warn(`write failed: ${e.message}`);
+  }
+}
+
+module.exports = {
+  getLogPath: () => logPath,
+  emit,
+  resolveLogPath,
+};

package/dist/lib/sign-helpers/update-info.js

@@ -0,0 +1,186 @@
+// Generate the Windows auto-updater feed file (`latest.yml`) + accompanying
+// `.blockmap` for each signed installer.
+//
+// Why this exists: electron-builder generates `latest.yml` ONLY as part of its
+// publish flow. Our pipeline signs Windows .exe out-of-band (separate self-hosted
+// runner job, EV USB token, signtool — see commands/sign-windows.js), so by the
+// time we have a signed binary, electron-builder is long gone. We have to write
+// `latest.yml` ourselves against the signed exe; otherwise its sha512 wouldn't
+// match the binary in the releases repo and electron-updater would reject the update.
+//
+// `latest.yml` is the public client-side contract that electron-updater reads
+// from the GitHub release. Schema reference:
+// node_modules/builder-util-runtime/out/updateInfo.d.ts (UpdateInfo + UpdateFileInfo).
+//
+// We also generate a `.blockmap` for each installer using app-builder-bin's
+// `blockmap` subcommand. The blockmap enables delta updates — electron-updater
+// downloads only changed chunks instead of the whole .exe on minor updates.
+// Blockmap generation is best-effort: if app-builder-bin isn't resolvable, we
+// warn and skip (auto-updater still works full-download style without it).
+//
+// Sister `latest-mac.yml` / `latest-linux.yml` are produced by electron-builder's
+// own publish step on those jobs, where they're built+signed in one process and
+// the yml lands naturally. Only Windows is split.
+
+const path    = require('path');
+const fs      = require('fs');
+const crypto  = require('crypto');
+const jetpack = require('fs-jetpack');
+const yaml    = require('js-yaml');
+const { execute } = require('node-powertools');
+
+// SHA-512 of a file → base64 (raw bytes encoded), matching electron-builder's wire format.
+// electron-updater verifies updates by recomputing this and comparing — must be base64
+// of the raw 64-byte digest, NOT hex, NOT base64 of the hex string.
+function sha512Base64(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha512');
+    const stream = fs.createReadStream(filePath);
+    stream.on('error', reject);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('base64')));
+  });
+}
+
+// Resolve the app-builder binary path via app-builder-bin. Returns null if the
+// dep isn't installed (consumer hasn't run electron-builder build → its node_modules
+// won't contain app-builder-bin). Caller should warn-and-skip rather than throw.
+function resolveAppBuilderPath() {
+  try {
+    const { appBuilderPath } = require('app-builder-bin');
+    if (jetpack.exists(appBuilderPath)) return appBuilderPath;
+  } catch (e) {
+    // app-builder-bin not installed — likely no electron-builder in this consumer.
+  }
+  return null;
+}
+
+// Generate <exe>.blockmap next to the signed exe via `app-builder blockmap`.
+// Returns the blockmap path on success, null if app-builder-bin isn't available
+// or generation failed (the latter is surfaced as a warning by the caller).
+async function generateBlockmap({ exePath, logger }) {
+  const builder = resolveAppBuilderPath();
+  if (!builder) {
+    if (logger) logger.warn('  app-builder-bin not resolvable — skipping blockmap (auto-updater will still work, just no delta updates).');
+    return null;
+  }
+
+  const blockmapPath = `${exePath}.blockmap`;
+  try {
+    // gzip is electron-updater's expected format. -i input -o output.
+    await execute(`"${builder}" blockmap --input "${exePath}" --output "${blockmapPath}" --compression gzip`, { log: false });
+    return blockmapPath;
+  } catch (e) {
+    if (logger) logger.warn(`  Blockmap generation failed (skipping, non-fatal): ${e.message}`);
+    return null;
+  }
+}
+
+// Build the `latest.yml` content from a list of signed installers + their metadata.
+// Schema mirrors what electron-builder produces for the windows nsis target. Fields
+// kept in the same order electron-builder emits, for diff-friendliness if anyone
+// inspects the yml by hand.
+//
+// `files` is the canonical list. `path` and top-level `sha512` are deprecated but
+// kept for backward compat with old electron-updater clients.
+function buildUpdateInfo({ version, releaseDate, files }) {
+  if (!files.length) {
+    throw new Error('writeUpdateInfo: no files supplied — nothing to describe.');
+  }
+
+  const primary = files[0];
+
+  return {
+    version,
+    files: files.map((f) => {
+      const entry = {
+        url: f.url,
+        sha512: f.sha512,
+        size: f.size,
+      };
+      if (f.blockMapSize !== undefined) entry.blockMapSize = f.blockMapSize;
+      return entry;
+    }),
+    path: primary.url,
+    sha512: primary.sha512,
+    releaseDate,
+  };
+}
+
+// Main entry. Given a set of signed Windows installers, generate per-exe blockmaps
+// (best-effort) and write a single `latest.yml` describing them all.
+//
+//   signedExes  : Array<{ filePath, urlName }> — absolute path + the URL-style name
+//                 the file will have on the GH release (usually basename(filePath)).
+//   outDir      : where to drop latest.yml + the blockmaps. Typically same dir as the
+//                 signed exes; finalize-release uploads everything in this dir.
+//   version     : package.json version (no leading 'v').
+//   releaseDate : ISO 8601 string. Defaults to now() if omitted.
+//
+// Returns the path to the written latest.yml.
+async function writeUpdateInfo({ signedExes, outDir, version, releaseDate, logger }) {
+  if (!signedExes || signedExes.length === 0) {
+    throw new Error('writeUpdateInfo: signedExes is empty.');
+  }
+  if (!version) {
+    throw new Error('writeUpdateInfo: version is required.');
+  }
+
+  jetpack.dir(outDir);
+  const finalReleaseDate = releaseDate || new Date().toISOString();
+
+  const files = [];
+  for (const { filePath, urlName } of signedExes) {
+    const stat   = fs.statSync(filePath);
+    const sha512 = await sha512Base64(filePath);
+    const blockmapPath = await generateBlockmap({ exePath: filePath, logger });
+
+    let blockMapSize;
+    if (blockmapPath && jetpack.exists(blockmapPath)) {
+      blockMapSize = fs.statSync(blockmapPath).size;
+    }
+
+    files.push({
+      url:  urlName || path.basename(filePath),
+      sha512,
+      size: stat.size,
+      ...(blockMapSize !== undefined ? { blockMapSize } : {}),
+    });
+  }
+
+  const updateInfo = buildUpdateInfo({ version, releaseDate: finalReleaseDate, files });
+  const ymlPath = path.join(outDir, 'latest.yml');
+
+  // Use single-quoted strings for date (matches electron-builder output style).
+  const ymlContent = yaml.dump(updateInfo, {
+    lineWidth: -1,        // never wrap (auto-updater clients parse line-by-line)
+    quotingType: "'",
+    forceQuotes: false,
+  });
+
+  fs.writeFileSync(ymlPath, ymlContent, 'utf8');
+
+  if (logger) {
+    logger.log(`  ✓ Wrote latest.yml (${files.length} file${files.length === 1 ? '' : 's'}, ${blockmapBlurb(files)})`);
+  }
+
+  return ymlPath;
+}
+
+function blockmapBlurb(files) {
+  const withBlockmap = files.filter((f) => f.blockMapSize !== undefined).length;
+  if (withBlockmap === files.length) return 'all with blockmap';
+  if (withBlockmap === 0)            return 'no blockmaps — delta updates disabled';
+  return `${withBlockmap}/${files.length} with blockmap`;
+}
+
+module.exports = {
+  writeUpdateInfo,
+  // Exported for unit tests.
+  _internals: {
+    sha512Base64,
+    buildUpdateInfo,
+    generateBlockmap,
+    resolveAppBuilderPath,
+  },
+};