cross-packer 0.1.0

package/src/shared/logger.ts

@@ -0,0 +1,91 @@
+/**
+ * Logging facade. All output is written through process.stdout.write or
+ * process.stderr.write; quiet mode suppresses every channel.
+ */
+import type { Arch, Platform } from './platform.ts'
+
+interface LoggerOptions {
+  quiet?: boolean
+}
+
+interface BannerSummary {
+  platforms: Platform[]
+  arches: Arch[]
+}
+
+interface TargetResult {
+  platform: Platform
+  arch: Arch
+  output?: string
+  error?: string
+}
+
+interface SummaryResult {
+  targets: TargetResult[]
+}
+
+/** Project identity fields shown in the banner; any config object with these fields works. */
+export interface BannerInput {
+  productName: string
+  version: string
+  electronVersion: string
+}
+
+export interface Logger {
+  info: (message: string) => void
+  warn: (message: string) => void
+  error: (message: string) => void
+  step: (label: string, message: string) => void
+  banner: (project: BannerInput, summary: BannerSummary) => void
+  summary: (result: SummaryResult) => void
+}
+
+export function createLogger(options: LoggerOptions = {}): Logger {
+  const { quiet = false } = options
+
+  const emit = (stream: NodeJS.WriteStream, prefix: string, message: string): void => {
+    if (quiet) return
+    stream.write(`${prefix ? `${prefix} ` : ''}${message}\n`)
+  }
+
+  return {
+    info: (message) => emit(process.stdout, '', message),
+    warn: (message) => emit(process.stderr, '[warn]', message),
+    error: (message) => emit(process.stderr, '[error]', message),
+    step: (label, message) => emit(process.stdout, `  [${label}]`, message),
+
+    banner(project, summary) {
+      if (quiet) return
+      const targets = summary.platforms.join(' + ')
+      const lines = [
+        '=========================================',
+        '  cross-packer — Cross-platform packaging',
+        '=========================================',
+        `  Project: ${project.productName} v${project.version}`,
+        `  Electron: v${project.electronVersion}`,
+        `  Targets: ${targets}`,
+        `  Architectures: ${summary.arches.join(', ')}`,
+        '=========================================',
+      ]
+      process.stdout.write(`${lines.join('\n')}\n`)
+    },
+
+    summary(result) {
+      if (quiet) return
+      const lines = [
+        '\n=========================================',
+        '  Packaging Results',
+        '=========================================',
+      ]
+      for (const r of result.targets) {
+        const status = r.error ? 'FAIL' : 'OK'
+        lines.push(`  [${status}] ${r.platform}-${r.arch}: ${r.output || r.error}`)
+      }
+      lines.push('=========================================')
+      process.stdout.write(`${lines.join('\n')}\n`)
+    },
+  }
+}
+
+/** Shared default logger instance, used by packer/collector/util modules. */
+export const logger: Logger = createLogger()

package/src/shared/platform.ts

@@ -0,0 +1,41 @@
+/**
+ * Cross-layer platform vocabulary: target platforms, architectures, and
+ * Node.js host platforms. Zero project dependencies; both config and the
+ * asar domain consume these enums.
+ */
+export enum Platform {
+  WIN = 'win',
+  MAC = 'mac',
+  LINUX = 'linux',
+}
+
+export enum Arch {
+  AMD64 = 'amd64',
+  ARM64 = 'arm64',
+}
+
+export enum NodePlatform {
+  WIN32 = 'win32',
+  DARWIN = 'darwin',
+  LINUX = 'linux',
+}
+
+export function nodeArchName(arch: Arch): 'x64' | 'arm64' {
+  return arch === Arch.AMD64 ? 'x64' : 'arm64'
+}
+
+/** All runtime values of NodePlatform, used for narrowing `process.platform`. */
+const NODE_PLATFORMS: readonly NodePlatform[] = Object.values(NodePlatform)
+
+/**
+ * Narrow the host's `process.platform` to NodePlatform.
+ * Throws on unsupported hosts (node_modules collection is only defined
+ * for win32 / darwin / linux).
+ */
+export function nodePlatformOf(host: NodeJS.Platform): NodePlatform {
+  const narrow = NODE_PLATFORMS.find((p) => p === host)
+  if (narrow === undefined) {
+    throw new Error(`Unsupported host platform: ${host}`)
+  }
+  return narrow
+}

package/src/shared/types.ts

@@ -0,0 +1,82 @@
+/**
+ * Zero-dependency shared types.
+ *
+ * This file may only import from `node:` builtins and external type
+ * packages — never from project modules. Every other layer depends on
+ * `shared/`, which keeps type-only dependencies acyclic at the module level.
+ */
+import type { Stats } from 'node:fs'
+
+/** The kind of an asar-storable entry. */
+export enum EntryKind {
+  FILE = 'file',
+  DIRECTORY = 'directory',
+  LINK = 'link',
+}
+
+/** A plain JSON object: arbitrary string keys, JSON-compatible values. */
+export type JsonObject = Record<string, unknown>
+
+/** A logical file set: an absolute source dir plus the collected files. */
+export interface FileSet {
+  src: string
+  destination: string
+  files: string[]
+  metadata: Map<string, FileStat>
+}
+
+/** File filter predicate used across collectors. */
+export type FileFilter = (file: string, stat: FileStat) => boolean
+
+/**
+ * Callback invoked for each collected node_modules file; returning true
+ * forces the file to be included even if it matches default exclusions.
+ */
+export type FileVisitor = (file: string) => boolean
+
+/**
+ * Collected entry metadata: the entry kind plus the module metadata that
+ * the collectors attach. Pure data with no behavior.
+ */
+export interface FileStat {
+  type: EntryKind
+  size: number
+  mode: number
+  /** Real on-disk source path when the packed file differs from the logical path. */
+  realFilePath?: string
+  /** Name of the node module the file belongs to. */
+  moduleName?: string
+  /** Root directory of the owning module. */
+  moduleRootPath?: string
+  /** Full path relative to the module root. */
+  moduleFullFilePath?: string
+  /** Symlink target relative to the module root. */
+  relativeLink?: string
+  /** Symlink target relative to the link's directory. */
+  linkRelativeToFile?: string
+}
+
+/** A resolved production dependency reported by the collector. */
+export interface DependencyEntry {
+  name: string
+  dir: string
+  dependencies?: DependencyEntry[]
+}
+
+/** A parsed minimatch pattern (from the `minimatch` package). */
+export interface MinimatchPattern {
+  match: (p: string, partial?: boolean) => boolean
+  set: Array<Array<string | object | symbol>>
+  negate: boolean
+}
+
+/**
+ * Map an fs stat result to its entry kind, or null for special entries
+ * (sockets, FIFOs, devices) that the asar format cannot store.
+ */
+export function entryKind(stat: Stats): EntryKind | null {
+  if (stat.isSymbolicLink()) return EntryKind.LINK
+  if (stat.isFile()) return EntryKind.FILE
+  if (stat.isDirectory()) return EntryKind.DIRECTORY
+  return null
+}

package/src/update/blockmap.ts

@@ -0,0 +1,247 @@
+/**
+ * Pure-JavaScript blockmap generator using Rabin fingerprinting.
+ * Ported from electron-builder v26.15.2 (app-builder-lib/out/targets/blockmap/blockmap.js),
+ * which replaced the Go-based app-builder.exe blockmap command.
+ *
+ * The output format is identical (blockmap v2 JSON), so the generated
+ * .blockmap files are fully compatible with electron-updater.
+ */
+
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { appendFile, writeFile } from 'node:fs/promises'
+import zlib from 'node:zlib'
+import { blake2b } from '@noble/hashes/blake2.js'
+
+// Rabin fingerprinting constants from github.com/aclements/go-rabin:
+//   Poly64 = 0xbfe6b8a5bf378d83 (degree-63 irreducible polynomial over GF(2))
+//   Window = 64 bytes, Avg = 16 KB, Min = 8 KB, Max = 32 KB
+// Boundary condition: (hash & (AVG-1)) === (AVG-1), i.e. all mask bits set.
+//
+// The tables below are precomputed offline (avoiding BigInt in production):
+//   PUSH[i] = (i * x^63 + (i * x^63 mod p)) truncated to 64 bits
+//   POP[i]  = (i * x^(63*8)) mod p
+// Each stored as signed Int32 hi/lo pair; hash = hi*2^32 + lo (unsigned 64-bit).
+// prettier-ignore
+const PUSH_HI = new Int32Array([
+  0, -1075398491, 2144170315, -1070872082, 1081891379, -6626666, 1068575608, -2141744163,
+  1058933955, -2131184538, 1087602056, -13253331, 2137151216, -1065030059, 11478971, -1085694178,
+  2117867910, -1042636509, 32598221, -1105735576, 1044399029, -2119763184, 1099772670, -26506661,
+  1092752709, -20664864, 1055876110, -2130060117, 22957942, -1095174189, 2123578941, -1049262440,
+  1134463913, -59231476, 1012136674, -2085273017, 65196442, -1140561601, 2083496145, -1010231180,
+  2088798058, -1016709169, 55440929, -1129623932, 1023204697, -2095421956, 1127328786, -53013321,
+  1034064431, -2109461878, 1114628964, -41329727, 2111752220, -1036488519, 34847063, -1108016654,
+  45915884, -1118165431, 2104618919, -1030269182, 1119929567, -47809414, 1024308628, -2098524879,
+  953921527, -2026039470, 1192681148, -118462951, 2024273348, -952021663, 124421263, -1198769110,
+  130392884, -1205658735, 2013844095, -940676390, 1203370247, -127975006, 947161164, -2020462359,
+  1189590641, -117371180, 959104826, -2033418337, 110881858, -1182968601, 2035719433, -961534548,
+  2046409394, -971046377, 104123385, -1177390244, 965075073, -2040309724, 1179161034, -106026641,
+  2068128862, -995910405, 76043541, -1150358096, 993623661, -2065709368, 1156845350, -82659453,
+  1146824861, -71462856, 999709142, -2072977037, 69694126, -1144927733, 2078933989, -1005798592,
+  91831768, -1163950723, 2058636435, -984419274, 1157982187, -85729458, 986191520, -2060538363,
+  979841307, -2055108162, 1168785488, -95618827, 2048617256, -973220979, 97917539, -1171217722,
+  1907843054, -833493173, 242888357, -1315138048, 835388893, -1909605000, 1309045910, -236925901,
+  1319719725, -246420600, 828645990, -1904043325, 248842526, -1322012229, 1897429077, -822165264,
+  260785768, -1334968627, 1883649827, -811561082, 1341594715, -267279106, 809135376, -1881352779,
+  815090347, -1888226802, 1331182560, -255950011, 1894322328, -821057475, 254042579, -1329407626,
+  841602119, -1915786014, 1306830092, -234742359, 1918209652, -844754337, 126847026, -1200980652,
+  1300297915, -237634370, 1906513758, -835821708, 237740260, -1327042663, 1911303428, -840027147,
+  126171951, -1202760392,
+])
+// prettier-ignore
+const PUSH_LO = new Int32Array([
+  0, -1086878333, 2121210630, -1051158907, 1139391375, -52546036, 1032233097, -2102317814,
+  954530461, -2016184546, 1183572379, -105092072, 2064466194, -1002779503, 90331668, -1168779369,
+  1909060922, -822183751, 262598204, -1332649025, 840978101, -1927822538, 1280267699, -210184144,
+  1227689895, -166034908, 927077537, -2005559006, 180663336, -1242351189, 1957408558, -878959955,
+  1554278391, -476845452, 583761137, -1644367502, 525196408, -1602596357, 1629669246, -569029891,
+  1681956202, -612953879, 439322220, -1525150737, 665396965, -1734431898, 1506164195, -420368288,
+  762155725, -1839587506, 1392675275, -332069816, 1854155074, -776756031, 283849284, -1344487481,
+  361326672, -1430329901, 1810264918, -724435243, 1449186271, -380150180, 672123097, -1757919910,
+  109003373, -1186410514, 2014337387, -953690904, 1167522274, -90082207, 1006232292, -2066845849,
+  1050392816, -2119420557, 1089774582, -3985803, 2104623999, -1035628804, 52238457, -1138059782,
+  2008463191, -931054892, 165260369, -1225907758, 878644440, -1956085413, 1244665822, -184051107,
+  1330793930, -261767095, 826103500, -1911891121, 213644869, -1282638906, 1926556995, -840736576,
+  1524311450, -437475303, 615792284, -1685867745, 422747669, -1509616746, 1734182163, -664139632,
+  1648353031, -586657148, 475055105, -1553512062, 567698568, -1629361909, 1605992334, -527502835,
+  722653344, -1809490653, 1434307494, -364231131, 1761307439, -674437460, 378826793, -1448870486,
+  334899773, -1396594754, 1838756155, -760300360, 1344246194, -282584015, 779127476, -1857616073,
+  218006746, -1278670503, 1922146268, -844754337, 1326923605, -266292522, 829957203, -1907381808,
+  874151495, -1959922748, 1249207617, -180164414, 2012464584, -926660533, 161275598, -1230286003,
+  2100785632, -1040122781, 56126182, -1133516955, 1054788207, -2115418132, 1085395305, -7971606,
+  1171491709, -85719298, 1002213499, -2071257608, 104476914, -1190281871, 2018847732, -949836169,
+  1348133677, -278040914, 775288875, -1862109784, 330520738,
+])
+// prettier-ignore
+const POP_HI = new Int32Array([
+  0, 2138251555, 1090583266, 1047780289, 1038568800, 1117023299, 2095560578, 60069537, 2077137601,
+  79543266, 986603555, 1170030848, 1177147297, 962262658, 120139075, 2019167328, 1216056615,
+  923315204, 159086533, 1980258022, 1973207111, 183492964, 882653861, 1273961350, 867506150,
+  1288058565, 1924525316, 231132199, 240278150, 1898019749, 1330815076, 807502151, 789684970,
+  1348633545, 1846630408, 291666219, 318173066, 1837485737, 1408636264, 746927179, 1423915051,
+  732698888, 366985929, 1789715434, 1765307723, 374035560, 674795433, 1464577674, 1735012301,
+  404295406, 644535599, 1494873100, 1519215277, 637420430, 462264399, 1694415212, 480556300,
+  1675072559, 1571049454, 584543949, 558102636, 1580259663, 1615004302, 523248557, 1579369941,
+  558916854, 522436407, 1615896084, 1673791669, 481765782, 583332439, 1572328308, 636346132,
+  1520369207, 1693263350, 463340757, 403346036, 1736029015, 1493854358, 645482933, 374917362,
+  1764485585, 1465397776, 673911603, 733971858, 1422697649, 1790934896, 365715027, 1838567987,
+  317027088, 748071121, 1407551986, 1349590867, 788676208, 292677041, 1845675154, 1899161407,
+  239191580, 808590813, 1329675518, 1289071199, 866552700, 232083645, 1923510686, 184319486,
+  1972329693, 1274840860, 881829439, 924528798, 1214779837, 1981532796, 157870943, 961112600,
+  1178225467, 2018087162, 121287129, 78522232, 2078082651, 1169087898, 987626681, 1116205273,
+  1039454714, 59181627, 2096376600, 2137046457, 1285274, 1046497115, 1091790456, 60830479,
+  2094207532, 1117833709, 1037297870, 1044872815, 1093951308, 2135393421, 3450286, 2020518350,
+  119376109, 963531564, 1176334863, 1166664878, 989513101, 76095052, 2079997807, 1272692264,
+  883465995, 182142154, 1973970409, 1983705928, 156226155, 926681514, 1213147273, 806692073,
+  1332086218, 1897258507, 241631016, 233990537, 1921075370, 1290965867, 864137800, 749834725,
+  1405268166, 1840343815, 314722852, 290905221, 1847983526, 1347823207, 790955844, 1467943716,
+  671885831, 377483718, 1762447589, 178,
+])
+// prettier-ignore
+const POP_LO = new Int32Array([
+  0, -1826189856, -1720019389, 173808547, -1916624635, 518270181, 347617094, -2019640666, 461718026,
+  -2002530326, -2097163191, 299456937, -1773673713, 90271471, 255685964, -1675888468, -2009265769,
+  454788215, 289906644, -2107567564, 100640914, -1764153998, -1668989231, 262386481, -1816638563,
+  10405501, 180542942, -1713090498, 511371928, -1923324040, -2030011173, 338096443, -1353867603,
+  1013650253, 909576430, -1525578482, 579813288, -1314278840, -1141528085, 684925963, -1261904729,
+  669929799, 766659300, -1097545980, 956988834, -1439895486, -1603212319, 861300225, 661690170,
+  -1269425446, -1106640519, 757894297, -1431161281, 966048735, 868786300, -1595003492, 1022743856,
+  -1345103664, -1517337741, 917098131, -1321765835, 571603413, 676192886, -1150586986, 1587232090,
+  -843206470, -941511911, 1422337785, -749101985, 1082069439, 1243810332, -653948932, 1159626576,
+  -700910928, -597366509, 1329751283, -925049259, 1543132085, 1369851926, -1031748106, -693750579,
+  1166063917, 1339859598, -587583634, 1533318600, -935192536, -1038220405, 1362660971, -853313849,
+  1577450279, 1415176324, -947950236, 1088542658, -741909982, -644136575, 1253952609, -237591561,
+  1659907607, 1756116404, -74794924, 2081686258, -281899246, -445737807, 1984436561, -363601411,
+  2037738525, 1932097470, -535823778, 1737572600, -189281000, -18098501, 1842174811, 2045487712,
+  -355653760, -527352797, 1941418435, -198636699, 1729070725, 1834196262, -25882426, 1651435626,
+  -246913654, -82543063, 1748169673, -273921681, 2089469071, 1993793324, -437234996, 33683255,
+  -1859683625, -1686412940, 140373140, -1883023822, 484826066, 381272177, -2053157487, 428127549,
+  -1969080099, -2130828418, 332967582, -1807346632, 123771352, 222069371, -1642459237, -1975714144,
+  421163840, 323381475, -2141133565, 134111141, -1797729723, -1635464730, 228738054, -1850098518,
+  43987274, 147008233, -1679448311, 477830575, -1889693617, -2063496212, 371656204, -1387501158,
+  1047192698, 876019673, -1492094407, 546228383, -1635627768, 336483553, -1433766908, -2057987869,
+  82141755, -1254257515, -1910308274, 1756305977, -858749288, 1060136802, -1933640611,
+])
+
+const RABIN_MIN = 8192
+const RABIN_AVG = 16384
+const RABIN_MAX = 32768
+const RABIN_WINDOW = 64
+const RABIN_HASH_MASK = RABIN_AVG - 1 // 0x3FFF
+
+export async function buildBlockMap(
+  inFile: string,
+  compressionFormat: string,
+  outFile?: string | null,
+): Promise<{ sha512: string; size: number; blockMapSize?: number }> {
+  const fileHash = createHash('sha512')
+  const checksums: string[] = []
+  const sizes: number[] = []
+  let totalSize = 0
+
+  const chunkBuf = Buffer.allocUnsafe(RABIN_MAX)
+  let chunkN = 0
+  let hi = 0
+  let lo = 0
+  const win = new Uint8Array(RABIN_WINDOW)
+  let wpos = 0
+
+  function emitChunk(): void {
+    checksums.push(
+      Buffer.from(blake2b(chunkBuf.subarray(0, chunkN), { dkLen: 18 })).toString('base64'),
+    )
+    sizes.push(chunkN)
+    chunkN = 0
+    hi = 0
+    lo = 0
+    win.fill(0)
+    wpos = 0
+  }
+
+  // Feed one byte into the Rabin fingerprint window.
+  function processByte(b: number): void {
+    chunkBuf[chunkN++] = b
+    if (chunkN <= RABIN_MIN - RABIN_WINDOW) {
+      return
+    }
+    if (chunkN <= RABIN_MIN) {
+      win[wpos] = b
+      wpos = (wpos + 1) % RABIN_WINDOW
+      const top = (hi >>> 23) & 0xff
+      const nhi = ((hi << 8) | (lo >>> 24)) & 0x7fffffff
+      const nlo = ((lo << 8) | b) & 0xffffffff
+      hi = (nhi ^ PUSH_HI[top]) | 0
+      lo = (nlo ^ PUSH_LO[top]) | 0
+      if (chunkN === RABIN_MIN && (lo & RABIN_HASH_MASK) === RABIN_HASH_MASK) {
+        emitChunk()
+      }
+      return
+    }
+    const old = win[wpos]
+    win[wpos] = b
+    wpos = (wpos + 1) % RABIN_WINDOW
+    hi = (hi ^ POP_HI[old]) | 0
+    lo = (lo ^ POP_LO[old]) | 0
+    const top = (hi >>> 23) & 0xff
+    const nhi = ((hi << 8) | (lo >>> 24)) & 0x7fffffff
+    const nlo = ((lo << 8) | b) & 0xffffffff
+    hi = (nhi ^ PUSH_HI[top]) | 0
+    lo = (nlo ^ PUSH_LO[top]) | 0
+    if ((lo & RABIN_HASH_MASK) === RABIN_HASH_MASK || chunkN >= RABIN_MAX) {
+      emitChunk()
+    }
+  }
+
+  // Stream-read the file, feeding SHA-512 and the Rabin chunker simultaneously.
+  const done = new Promise<void>((resolve, reject) => {
+    const rs = createReadStream(inFile, { highWaterMark: 256 * 1024 })
+    rs.on('data', (chunk) => {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      fileHash.update(buf)
+      totalSize += buf.length
+      for (let i = 0; i < buf.length; i++) {
+        processByte(buf[i])
+      }
+    })
+    rs.on('end', () => {
+      if (chunkN > 0) {
+        emitChunk()
+      }
+      resolve()
+    })
+    rs.on('error', reject)
+  })
+  await done
+
+  const blockMap = {
+    version: '2',
+    files: [{ name: 'file', offset: 0, checksums, sizes }],
+  }
+  const compressed = compress(Buffer.from(JSON.stringify(blockMap)), compressionFormat)
+
+  if (outFile == null || outFile === '') {
+    const sizeHeader = Buffer.allocUnsafe(4)
+    sizeHeader.writeUInt32BE(compressed.length, 0)
+    const appended = Buffer.concat([compressed, sizeHeader])
+    await appendFile(inFile, appended)
+    fileHash.update(appended)
+    return {
+      size: totalSize + appended.length,
+      sha512: fileHash.digest('base64'),
+      blockMapSize: compressed.length,
+    }
+  }
+
+  await writeFile(outFile, compressed)
+  return {
+    size: totalSize,
+    sha512: fileHash.digest('base64'),
+    blockMapSize: compressed.length,
+  }
+}
+
+function compress(data: Buffer, format: string): Buffer {
+  return format === 'deflate'
+    ? zlib.deflateRawSync(data, { level: 9 })
+    : zlib.gzipSync(data, { level: 9 })
+}

package/src/update/metadata.ts

@@ -0,0 +1,97 @@
+/**
+ * electron-updater compatible metadata generation
+ * (latest.yml / latest-mac.yml / latest-linux.yml).
+ */
+import { existsSync, statSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { hashFile } from '../shared/hash.ts'
+import { NodePlatform } from '../shared/platform.ts'
+
+export interface UpdateMetadataOptions {
+  filePath: string
+  version: string
+  outputDir: string
+  platform: NodePlatform
+  blockMapSize?: number
+  channel?: string
+  extraFiles?: string[]
+}
+
+/**
+ * Derive the update channel from a semver prerelease suffix
+ * (for example, 1.2.3-beta.1 yields "beta").
+ */
+export function getUpdateChannel(
+  version: string,
+  explicitChannel?: string,
+  defaultChannel = 'latest',
+): string {
+  if (explicitChannel) return explicitChannel
+  const match = version.match(/^\d+\.\d+\.\d+-([0-9A-Za-z-]+)\.\d+$/)
+  return match ? match[1] : defaultChannel
+}
+
+export function getUpdateMetadataFileName(
+  version: string,
+  explicitChannel?: string,
+  platform: NodePlatform = NodePlatform.WIN32,
+  defaultChannel = 'latest',
+): string {
+  const channel = getUpdateChannel(version, explicitChannel, defaultChannel)
+  if (platform === NodePlatform.DARWIN)
+    return `${channel === 'latest' ? 'latest' : channel}-mac.yml`
+  if (platform === NodePlatform.LINUX)
+    return `${channel === 'latest' ? 'latest' : channel}-linux.yml`
+  return `${channel}.yml`
+}
+
+/** Get a file's size in bytes, 0 when missing. */
+function getFileSize(filePath: string): number {
+  return existsSync(filePath) ? statSync(filePath).size : 0
+}
+
+/** Describe one artifact for the files[] array, with an optional inline blockMapSize. */
+function fileEntryYaml(url: string, sha512: string, size: number, blockMapSize?: number): string {
+  const blockMapEntry = blockMapSize != null ? `\n    blockMapSize: ${blockMapSize}` : ''
+  return `  - url: ${url}\n    sha512: ${sha512}\n    size: ${size}${blockMapEntry}`
+}
+
+export function generateUpdateMetadata({
+  filePath,
+  version,
+  outputDir,
+  platform,
+  blockMapSize,
+  channel,
+  extraFiles = [],
+}: UpdateMetadataOptions): { metadataPath: string; metadataFileName: string } | null {
+  if (!existsSync(filePath)) return null
+
+  const url = path.basename(filePath)
+  const primaryHash = hashFile(filePath, 'sha512', 'base64')
+  const primarySize = getFileSize(filePath)
+  const filesYaml = [
+    fileEntryYaml(url, primaryHash, primarySize, blockMapSize),
+    ...extraFiles
+      .filter((extra) => existsSync(extra) && extra !== filePath)
+      .map((extra) =>
+        fileEntryYaml(
+          path.basename(extra),
+          hashFile(extra, 'sha512', 'base64'),
+          getFileSize(extra),
+        ),
+      ),
+  ].join('\n')
+
+  const metadataFileName = getUpdateMetadataFileName(version, channel, platform)
+  const content = `version: ${version}
+files:
+${filesYaml}
+path: ${url}
+sha512: ${primaryHash}
+releaseDate: ${new Date().toISOString()}
+`
+  const metadataPath = path.join(outputDir, metadataFileName)
+  writeFileSync(metadataPath, content, 'utf8')
+  return { metadataPath, metadataFileName }
+}

package/src/update/version.ts

@@ -0,0 +1,59 @@
+/**
+ * Convert a semver string into the four-part numeric build version.
+ * NSIS VIProductVersion and PE version resources require the X.X.X.X format.
+ * The fourth segment prefers: explicit buildNumber param > prerelease number
+ * in the version string > CI build number (only when CI=true).
+ */
+export function getBuildVersion(version: string, buildNumber?: number | string): string {
+  const ciBuildNumber = getCiBuildNumber()
+  const semverMatch = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(?:beta|rc)\.(\d+))?/i)
+
+  if (semverMatch) {
+    const major = Number.parseInt(semverMatch[1], 10)
+    const minor = Number.parseInt(semverMatch[2], 10)
+    const patch = Number.parseInt(semverMatch[3], 10)
+
+    if (buildNumber != null && /^\d+$/.test(String(buildNumber))) {
+      return `${major}.${minor}.${patch}.${Number.parseInt(String(buildNumber), 10)}`
+    }
+
+    if (ciBuildNumber && /^\d+$/.test(ciBuildNumber)) {
+      return `${major}.${minor}.${patch}.${Number.parseInt(ciBuildNumber, 10)}`
+    }
+
+    const prereleaseBuild = semverMatch[4] ? Number.parseInt(semverMatch[4], 10) : 0
+    return `${major}.${minor}.${patch}.${prereleaseBuild}`
+  }
+
+  const parts = version.replace(/-/g, '.').split('.')
+  const major = Number.parseInt(parts[0], 10) || 0
+  const minor = Number.parseInt(parts[1], 10) || 0
+  const patch = Number.parseInt(parts[2], 10) || 0
+  const fallbackBuild =
+    buildNumber != null && /^\d+$/.test(String(buildNumber))
+      ? Number.parseInt(String(buildNumber), 10)
+      : Number.parseInt(parts[3], 10) || 0
+  const build =
+    ciBuildNumber && /^\d+$/.test(ciBuildNumber)
+      ? Number.parseInt(ciBuildNumber, 10)
+      : fallbackBuild
+
+  return `${major}.${minor}.${patch}.${build}`
+}
+
+/**
+ * Read the CI build number from well-known environment variables.
+ * Only consulted inside a CI runner (CI=true) so that a stray BUILD_NUMBER
+ * on a developer machine cannot silently alter artifact versions.
+ */
+function getCiBuildNumber(): string | undefined {
+  if (process.env.CI !== 'true') return undefined
+  return (
+    process.env.CI_PIPELINE_IID ||
+    process.env.BUILD_BUILDNUMBER ||
+    process.env.CIRCLE_BUILD_NUM ||
+    process.env.APPVEYOR_BUILD_NUMBER ||
+    process.env.TRAVIS_BUILD_NUMBER ||
+    process.env.BUILD_NUMBER
+  )
+}

package/templates/linux/app.desktop

@@ -0,0 +1,11 @@
+[Desktop Entry]
+Name={{productName}}
+{{desktopExtra}}Comment={{description}}
+Exec="/opt/{{installDir}}/{{name}}" %U
+Icon={{name}}
+Type=Application
+Categories=Utility;
+{{mimeType}}
+StartupWMClass={{name}}
+StartupNotify=true
+Terminal=false

package/templates/linux/control

@@ -0,0 +1,9 @@
+Package: {{name}}
+Version: {{version}}
+Architecture: {{debArch}}
+Maintainer: {{maintainer}}
+Depends: {{depends}}
+{{recommends}}Section: utils
+Priority: optional
+Installed-Size: {{installedSize}}
+Description: {{description}}

package/templates/linux/postinst

@@ -0,0 +1,10 @@
+#!/bin/sh
+chown root:root "/opt/{{installDir}}/chrome-sandbox"
+chmod 4755 "/opt/{{installDir}}/chrome-sandbox"
+chmod 755 "/opt/{{installDir}}/{{name}}"
+if command -v gtk-update-icon-cache > /dev/null 2>&1; then
+  gtk-update-icon-cache -f -q /usr/share/icons/hicolor 2>/dev/null || true
+fi
+if command -v update-desktop-database > /dev/null 2>&1; then
+  update-desktop-database -q /usr/share/applications 2>/dev/null || true
+fi

package/templates/linux/postrm

@@ -0,0 +1,8 @@
+#!/bin/sh
+rm -rf "/opt/{{installDir}}"
+if command -v gtk-update-icon-cache > /dev/null 2>&1; then
+  gtk-update-icon-cache -f -q /usr/share/icons/hicolor 2>/dev/null || true
+fi
+if command -v update-desktop-database > /dev/null 2>&1; then
+  update-desktop-database -q /usr/share/applications 2>/dev/null || true
+fi