cross-packer 0.1.0

package/src/electron/download.ts

@@ -0,0 +1,121 @@
+/**
+ * Electron distribution download + cache + checksum validation.
+ */
+import { createHash } from 'node:crypto'
+import {
+  createReadStream,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+} from 'node:fs'
+import http from 'node:http'
+import https from 'node:https'
+import path from 'node:path'
+import { Arch, type NodePlatform } from '../shared/platform.ts'
+
+export interface DownloadElectronOptions {
+  version: string
+  platform: NodePlatform
+  arch: Arch
+  mirror?: string
+  cacheDir?: string
+  expectedChecksum: string
+}
+
+/**
+ * Compose the Electron distribution archive name for a target. The Electron
+ * release artifacts use "x64" rather than "amd64" for the x86-64 architecture,
+ * for example version "33.2.0" yields "electron-v33.2.0-win32-x64.zip".
+ */
+export function electronArchiveName(version: string, platform: NodePlatform, arch: Arch): string {
+  const electronArch = arch === Arch.AMD64 ? 'x64' : arch
+  return `electron-v${version}-${platform}-${electronArch}.zip`
+}
+
+/** Streams a file through sha256 and compares against the expected hex digest. */
+export async function validateArchiveChecksum(
+  archivePath: string,
+  expectedChecksum: string,
+): Promise<void> {
+  const hash = createHash('sha256')
+  for await (const chunk of createReadStream(archivePath)) {
+    hash.update(chunk)
+  }
+  const actual = hash.digest('hex')
+  if (actual !== expectedChecksum) {
+    throw new Error(
+      `Checksum mismatch for ${archivePath}: expected ${expectedChecksum}, got ${actual}`,
+    )
+  }
+}
+
+/** Download a file with cache support and return the cached archive path. */
+export async function downloadElectron({
+  version,
+  platform,
+  arch,
+  mirror = 'https://github.com/electron/electron/releases/download/',
+  cacheDir,
+  expectedChecksum,
+}: DownloadElectronOptions): Promise<string> {
+  const zipName = electronArchiveName(version, platform, arch)
+  const base = mirror.endsWith('/') ? mirror : `${mirror}/`
+  const url = `${base}v${version}/${zipName}`
+
+  const dir = cacheDir ?? path.join(process.cwd(), '.electron-cache')
+  const cachePath = path.join(dir, zipName)
+
+  if (existsSync(cachePath)) {
+    try {
+      await validateArchiveChecksum(cachePath, expectedChecksum)
+      return cachePath
+    } catch {
+      rmSync(cachePath, { force: true })
+    }
+  }
+
+  mkdirSync(dir, { recursive: true })
+  const tmpPath = `${cachePath}.downloading`
+  try {
+    await downloadFile(url, tmpPath)
+    await validateArchiveChecksum(tmpPath, expectedChecksum)
+    renameSync(tmpPath, cachePath)
+  } catch (err) {
+    rmSync(tmpPath, { force: true })
+    throw err
+  }
+  return cachePath
+}
+
+/** Download a file while following redirects. No external dependencies. */
+export function downloadFile(url: string, destPath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const follow = (current: string): void => {
+      const client = current.startsWith('https') ? https : http
+      client
+        .get(current, { timeout: 300_000 }, (res) => {
+          const statusCode = res.statusCode ?? 0
+          if (statusCode >= 300 && statusCode < 400 && res.headers.location) {
+            follow(res.headers.location)
+            return
+          }
+          if (statusCode !== 200) {
+            reject(new Error(`Download failed: HTTP ${statusCode} from ${current}`))
+            return
+          }
+          const file = createWriteStream(destPath)
+          res.pipe(file)
+          file.on('finish', () => {
+            file.close()
+            resolve()
+          })
+          file.on('error', reject)
+          res.on('error', reject)
+        })
+        .on('error', reject)
+    }
+    follow(url)
+  })
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export type { PrebuiltModuleRule } from './asar/fileset/platform-fileset.ts'
+export { setPrebuiltDirResolver } from './asar/fileset/platform-fileset.ts'
+export type {
+  LoadConfigOverrides,
+  NormalizedConfig,
+} from './config/index.ts'
+export { loadConfig, normalizeConfig, resolveConfigPath } from './config/index.ts'
+export type { ExtraResourceEntry } from './packer/common/extra-resources.ts'
+export type { PackResult, PipelineOptions, TargetResult, TargetSpec } from './pipeline/pipeline.ts'
+export { runPack } from './pipeline/pipeline.ts'
+export { Arch, NodePlatform, nodeArchName, Platform } from './shared/platform.ts'
+export { buildBlockMap } from './update/blockmap.ts'
+export type { UpdateMetadataOptions } from './update/metadata.ts'
+export { generateUpdateMetadata } from './update/metadata.ts'

package/src/packer/common/app-update-yml.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared app-update.yml rendering, used by the win and mac packers.
+ */
+import { readFile } from 'node:fs/promises'
+import type { NormalizedConfig } from '../../config/index.ts'
+import { getTemplatesDir, renderTemplate } from './template.ts'
+
+/** Derive the electron-updater cache directory name for a config. */
+export function getUpdaterCacheDirName(config: NormalizedConfig): string {
+  return `${config.name.toLowerCase()}-updater`
+}
+
+/** Render the shared app-update.yml template. */
+export async function renderAppUpdateYml(config: NormalizedConfig): Promise<string> {
+  const template = await readFile(getTemplatesDir('mac', 'app-update.yml'), 'utf8')
+  return renderTemplate(template, {
+    updateServerUrl: config.update.url,
+    updaterCacheDirName: getUpdaterCacheDirName(config),
+    channel: config.update.channel,
+  })
+}

package/src/packer/common/extra-resources.ts

@@ -0,0 +1,83 @@
+/**
+ * Extra-resource entry filtering, shared by the win/mac/linux packers.
+ */
+import { existsSync, type Stats } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import path from 'node:path'
+import type { CollectDirectoryOptions } from '../../archive/tar.ts'
+import type { NormalizedConfig } from '../../config/index.ts'
+
+export interface ExtraResourceEntry {
+  from?: string
+  to?: string
+  required?: boolean
+  exclude?: string[]
+  collectOptions?: CollectDirectoryOptions
+}
+
+/** A resolved extra resource: source path, stat, and in-archive destination. */
+export interface ResolvedExtraResource {
+  res: ExtraResourceEntry
+  srcPath: string
+  srcStat: Stats
+  destPath: string
+}
+
+/**
+ * Resolve every configured extra resource into a source path plus stat.
+ * Missing optional sources are skipped; required sources throw via
+ * assertRequiredExtraResource.
+ */
+export async function resolveExtraResources(
+  config: NormalizedConfig,
+): Promise<ResolvedExtraResource[]> {
+  const resolved: ResolvedExtraResource[] = []
+  for (const res of config.extraResources) {
+    if (!res.from || !res.to) continue
+    assertRequiredExtraResource(config.projectDir, res)
+    const srcPath = path.join(config.projectDir, res.from)
+    if (!existsSync(srcPath)) continue
+    resolved.push({ res, srcPath, srcStat: await stat(srcPath), destPath: res.to })
+  }
+  return resolved
+}
+
+/**
+ * Check whether a directory entry (relative to the resource root) matches
+ * the resource's exclude list. A matched path or any path under it is excluded.
+ */
+export function isExtraResourcePathExcluded(
+  resource: ExtraResourceEntry,
+  relativePath: string,
+): boolean {
+  const normalized = relativePath.replaceAll('\\', '/').replace(/^\.\//, '')
+  return (resource.exclude || []).some(
+    (excludedPath) =>
+      normalized === excludedPath || normalized.startsWith(`${excludedPath.replace(/\/$/, '')}/`),
+  )
+}
+
+/**
+ * Ensures required extra resources exist before packaging.
+ * The optional hint callback returns an appended instruction telling the
+ * user how to obtain the missing resource (e.g. a project-specific
+ * download command); returning undefined falls back to the plain message.
+ * @throws when a required resource path is missing
+ */
+export function assertRequiredExtraResource(
+  projectDir: string,
+  res: ExtraResourceEntry,
+  missingHint?: (from: string) => string | undefined,
+): void {
+  if (!res.required) return
+
+  const srcPath = path.join(projectDir, res.from ?? '')
+  if (!existsSync(srcPath)) {
+    const hint = missingHint?.(res.from ?? '')
+    throw new Error(
+      hint
+        ? `Required extra resource not found: ${res.from}. ${hint}`
+        : `Required extra resource not found: ${res.from}`,
+    )
+  }
+}

package/src/packer/common/staging.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-target staging directory creation and removal, shared by the platform
+ * packers.
+ */
+import { mkdir, rm } from 'node:fs/promises'
+import path from 'node:path'
+import { logger } from '../../shared/logger.ts'
+import type { Arch } from '../../shared/platform.ts'
+
+export async function createStagingDir(
+  outputDir: string,
+  label: string,
+  arch: Arch,
+): Promise<string> {
+  const stagingDir = path.join(outputDir, `cross-packer-${label}-${arch}-staging`)
+  await mkdir(stagingDir, { recursive: true })
+  return stagingDir
+}
+
+export async function removeStagingDir(stagingDir: string): Promise<void> {
+  try {
+    await rm(stagingDir, {
+      recursive: true,
+      force: true,
+      maxRetries: 5,
+      retryDelay: 1000,
+    })
+  } catch (err) {
+    logger.warn(
+      `Could not remove staging directory ${stagingDir}: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+}

package/src/packer/common/template.ts

@@ -0,0 +1,24 @@
+/**
+ * Generic {{placeholder}} template rendering with CRLF normalization.
+ */
+import path from 'node:path'
+
+export function getTemplatesDir(...segments: string[]): string {
+  return path.join(import.meta.dirname, '..', '..', '..', 'templates', ...segments)
+}
+
+export function renderTemplate(
+  template: string,
+  replacements: Record<string, string | number>,
+): string {
+  let rendered = template
+  for (const [key, value] of Object.entries(replacements)) {
+    rendered = rendered.replaceAll(`{{${key}}}`, String(value))
+  }
+  return normalizeUnixLineEndings(rendered)
+}
+
+/** Normalize CRLF and CR line endings to LF. */
+function normalizeUnixLineEndings(content: string): string {
+  return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+}

package/src/packer/linux/linux.ts

@@ -0,0 +1,329 @@
+/**
+ * Linux .deb packer.
+ */
+import { existsSync, readFileSync, type Stats } from 'node:fs'
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { type ReadEntry, create as tarCreate } from 'tar'
+import { type ArEntry, createArArchive } from '../../archive/ar.ts'
+import { compress } from '../../archive/seven-za.ts'
+import { collectDirectoryEntries, type TarEntry, writeTarFromEntries } from '../../archive/tar.ts'
+import {
+  getEntryBuffer,
+  getSymlinkTarget,
+  isDefaultAppEntry,
+  isSymlink,
+  type ZipEntry,
+} from '../../archive/zip-reader.ts'
+import type { NormalizedConfig } from '../../config/index.ts'
+import { downloadAndReadElectron } from '../../electron/dist-zip.ts'
+import type { PackerContext } from '../../pipeline/targets.ts'
+import { logger } from '../../shared/logger.ts'
+import { type Arch, NodePlatform } from '../../shared/platform.ts'
+import { generateUpdateMetadata } from '../../update/metadata.ts'
+import { isExtraResourcePathExcluded, resolveExtraResources } from '../common/extra-resources.ts'
+import { createStagingDir, removeStagingDir } from '../common/staging.ts'
+import { getTemplatesDir, renderTemplate } from '../common/template.ts'
+
+const TEMPLATES_DIR = getTemplatesDir('linux')
+
+export async function packLinux({
+  config,
+  arch,
+  outputDir,
+  asarPath,
+  unpackedDir,
+}: PackerContext): Promise<string> {
+  if (asarPath === undefined) throw new Error('packLinux: asarPath is required')
+  logger.info(`\n[Linux] ${arch} packaging started`)
+  const stagingDir = await createStagingDir(outputDir, 'linux', arch)
+
+  try {
+    logger.info('  [1/5] Downloading and reading Linux Electron dist ...')
+    const { entries } = await downloadAndReadElectron(NodePlatform.LINUX, arch, config)
+
+    logger.info('  [2/5] Building data.tar.xz ...')
+    const installPrefix = `opt/${config.linux.installDir}`
+    const dataEntries = buildDataEntries(entries, { config, installPrefix, asarPath })
+    await appendUnpackedEntries(dataEntries, unpackedDir, installPrefix)
+    dataEntries.push(await createDesktopEntry(config))
+    dataEntries.push(...(await collectIconEntries(config)))
+    dataEntries.push(...(await collectExtraResourceEntries(config)))
+
+    const dataTarPath = path.join(stagingDir, 'data.tar.xz')
+    await writeDataTarXz(dataEntries, dataTarPath, stagingDir)
+
+    const installedSize = Math.ceil((await stat(dataTarPath)).size / 1024)
+
+    logger.info('  [3/5] Building control.tar.xz ...')
+    const controlDir = path.join(stagingDir, 'control')
+    await mkdir(controlDir, { recursive: true })
+    await createControlFiles(controlDir, config, arch, installedSize)
+    const controlTarPath = path.join(stagingDir, 'control.tar.xz')
+    await writeControlTarXz(controlDir, controlTarPath, stagingDir)
+
+    logger.info('  [4/5] Assembling .deb ...')
+    const debFilename = `${config.artifactName}_${config.version}_${arch}.deb`
+    const debPath = path.join(outputDir, debFilename)
+    const arFiles: ArEntry[] = [
+      { name: 'debian-binary', content: Buffer.from('2.0\n'), mode: 0o100644 },
+      { name: 'control.tar.xz', content: await readFile(controlTarPath), mode: 0o100644 },
+      { name: 'data.tar.xz', content: await readFile(dataTarPath), mode: 0o100644 },
+    ]
+    await writeFile(debPath, createArArchive(arFiles))
+
+    if (config.update.generateMetadata) {
+      logger.info('  [5/5] Generating update metadata ...')
+      generateUpdateMetadata({
+        filePath: debPath,
+        version: config.version,
+        outputDir,
+        platform: NodePlatform.LINUX,
+        channel: config.update.channel,
+      })
+    }
+
+    logger.info(`  [Linux] ${arch} packaging complete: ${debPath}`)
+    return debPath
+  } finally {
+    await removeStagingDir(stagingDir)
+  }
+}
+
+function buildDataEntries(
+  electronEntries: ZipEntry[],
+  {
+    config,
+    installPrefix,
+    asarPath,
+  }: { config: NormalizedConfig; installPrefix: string; asarPath: string },
+): TarEntry[] {
+  const dataEntries: TarEntry[] = []
+
+  for (const e of electronEntries) {
+    // The default application is replaced by the user's asar.
+    if (isDefaultAppEntry(e.path)) continue
+
+    let destPath = e.path
+    if (e.path === 'electron') destPath = config.name
+
+    const fullDestPath = `${installPrefix}/${destPath}`
+
+    if (e.dir) {
+      dataEntries.push({ type: 'dir', path: fullDestPath, mode: Number(e.mode) || 0o40755 })
+    } else if (isSymlink(e)) {
+      dataEntries.push({
+        type: 'link',
+        path: fullDestPath,
+        mode: Number(e.mode) || 0o120755,
+        getTarget: () => getSymlinkTarget(e.entry),
+      })
+    } else {
+      dataEntries.push({
+        type: 'file',
+        path: fullDestPath,
+        mode: Number(e.mode) || 0o100644,
+        getBuffer: () => getEntryBuffer(e.entry),
+      })
+    }
+  }
+
+  dataEntries.push({
+    type: 'file',
+    path: `${installPrefix}/resources/app.asar`,
+    mode: 0o100644,
+    filePath: asarPath,
+  })
+
+  return dataEntries
+}
+
+async function appendUnpackedEntries(
+  dataEntries: TarEntry[],
+  unpackedDir: string | undefined,
+  installPrefix: string,
+): Promise<void> {
+  if (!unpackedDir || !existsSync(unpackedDir)) return
+  dataEntries.push(
+    ...(await collectDirectoryEntries(unpackedDir, `${installPrefix}/resources/app.asar.unpacked`)),
+  )
+}
+
+/** Render the .desktop entry from the template and config. */
+async function createDesktopEntry(config: NormalizedConfig): Promise<TarEntry> {
+  const template = readFileSync(path.join(TEMPLATES_DIR, 'app.desktop'), 'utf8')
+  const mimeType = config.linux.mimeType ? `MimeType=${config.linux.mimeType};\n` : ''
+
+  let desktopExtra = ''
+  if (config.linux.desktopExtraFile) {
+    const fragment = readFileSync(
+      path.join(config.projectDir, config.linux.desktopExtraFile),
+      'utf8',
+    )
+    desktopExtra = `${renderTemplate(fragment, {
+      productName: config.productName,
+      description: config.description || config.productName,
+      name: config.name,
+      installDir: config.linux.installDir,
+    }).trimEnd()}\n`
+  }
+  const content = renderTemplate(template, {
+    productName: config.productName,
+    description: config.description || config.productName,
+    name: config.name,
+    installDir: config.linux.installDir,
+    mimeType,
+    desktopExtra,
+  })
+  return {
+    type: 'file',
+    path: `usr/share/applications/${config.name}.desktop`,
+    mode: 0o100644,
+    content: Buffer.from(content),
+  }
+}
+
+/** Collect hicolor icon entries for every configured icon size. */
+async function collectIconEntries(config: NormalizedConfig): Promise<TarEntry[]> {
+  const entries: TarEntry[] = []
+  const iconDir = config.linux.iconDir
+
+  for (const size of config.linux.iconSizes) {
+    const iconSrc = path.join(config.projectDir, iconDir, `${size}x${size}.png`)
+    if (!existsSync(iconSrc)) {
+      throw new Error(`Missing Linux icon (${size}x${size}): ${iconSrc}`)
+    }
+    entries.push({
+      type: 'file',
+      path: `usr/share/icons/hicolor/${size}x${size}/apps/${config.name}.png`,
+      mode: 0o100644,
+      filePath: iconSrc,
+    })
+  }
+
+  if (entries.length > 0) logger.info('    Collected Linux icons')
+  return entries
+}
+
+/** Collect extra resource entries for the /opt install prefix. */
+async function collectExtraResourceEntries(config: NormalizedConfig): Promise<TarEntry[]> {
+  const entries: TarEntry[] = []
+  const installPrefix = `opt/${config.linux.installDir}`
+
+  for (const { res, srcPath, srcStat, destPath: resTo } of await resolveExtraResources(config)) {
+    const destPrefix = `${installPrefix}/resources/${resTo}`
+    if (srcStat.isDirectory()) {
+      const dirEntries = await collectDirectoryEntries(srcPath, destPrefix, res.collectOptions)
+      entries.push(
+        ...dirEntries.filter(
+          (entry) => !isExtraResourcePathExcluded(res, entry.path.slice(destPrefix.length + 1)),
+        ),
+      )
+    } else {
+      entries.push({ type: 'file', path: destPrefix, mode: 0o100644, filePath: srcPath })
+    }
+  }
+
+  if (entries.length > 0) logger.info('    Collected Linux extra resources')
+  return entries
+}
+
+async function createControlFiles(
+  controlDir: string,
+  config: NormalizedConfig,
+  debArch: Arch,
+  installedSize: number,
+): Promise<void> {
+  const depends = (config.linux.debDepends || []).join(', ')
+  const recommends = config.linux.debRecommends ? `Recommends: ${config.linux.debRecommends}\n` : ''
+
+  const controlTemplate = await readFile(path.join(TEMPLATES_DIR, 'control'), 'utf8')
+  const controlContent = renderTemplate(controlTemplate, {
+    name: config.name,
+    version: config.version,
+    debArch,
+    maintainer: config.linux.maintainer || config.author || 'Unknown',
+    depends,
+    recommends,
+    installedSize,
+    description: config.description || config.productName,
+  })
+  await writeFile(path.join(controlDir, 'control'), controlContent)
+
+  const scriptReplacements = {
+    productName: config.productName,
+    name: config.name,
+    installDir: config.linux.installDir,
+  }
+  await writeMaintainerScript(
+    controlDir,
+    'preinst',
+    path.join(TEMPLATES_DIR, 'preinst'),
+    scriptReplacements,
+  )
+  await writeMaintainerScript(
+    controlDir,
+    'postinst',
+    path.join(TEMPLATES_DIR, 'postinst'),
+    scriptReplacements,
+  )
+  await writeMaintainerScript(
+    controlDir,
+    'prerm',
+    path.join(TEMPLATES_DIR, 'prerm'),
+    scriptReplacements,
+  )
+  await writeMaintainerScript(controlDir, 'postrm', path.join(TEMPLATES_DIR, 'postrm'), {
+    installDir: config.linux.installDir,
+  })
+}
+
+async function writeDataTarXz(
+  entries: TarEntry[],
+  destPath: string,
+  stagingDir: string,
+): Promise<void> {
+  const tarPath = path.join(stagingDir, 'data.tar')
+  await writeTarFromEntries(entries, tarPath)
+  compress({ src: tarPath, dest: destPath, format: 'xz', level: 9 })
+}
+
+async function writeControlTarXz(
+  controlDir: string,
+  destPath: string,
+  stagingDir: string,
+): Promise<void> {
+  const tarPath = path.join(stagingDir, 'control.tar')
+  await tarCreate(
+    {
+      gzip: false,
+      file: tarPath,
+      cwd: controlDir,
+      portable: true,
+      noPax: true,
+      filter: (entryPath: string, entryStat: ReadEntry | Stats) => {
+        const p = entryPath.replace(/^\.\//, '')
+        if (p === '.') return true
+        entryStat.mode =
+          p === 'preinst' || p === 'postinst' || p === 'prerm' || p === 'postrm'
+            ? 0o100755
+            : 0o100644
+        return true
+      },
+    },
+    ['.'],
+  )
+  compress({ src: tarPath, dest: destPath, format: 'xz', level: 9 })
+}
+
+/** Render a maintainer script template and write it into the deb control dir. */
+async function writeMaintainerScript(
+  controlDir: string,
+  fileName: string,
+  templatePath: string,
+  replacements: Record<string, string | number>,
+): Promise<void> {
+  const template = await readFile(templatePath, 'utf8')
+  const content = renderTemplate(template, replacements)
+  await writeFile(path.join(controlDir, fileName), content, { encoding: 'utf8' })
+}