waybetter 0.1.1 → 0.7.0

package/cli/release.mjs

@@ -0,0 +1,437 @@
+// `waybetter release windows|macos`: a signed native release of a wayBetter app and its update
+// manifest (`latest.json`). It never uploads anything: it prints the exact upload steps for the
+// owner to run. Configured by the app's `waybetter.release.json` (found from the working directory
+// up, or `--config <file>`):
+//
+//   {
+//     "product": "wayBetter for X",           // names in messages
+//     "artifact": "wayBetter-for-X",          // space-free file names on the CDN
+//     "desktopDir": "apps/desktop",           // the Tauri app (package.json, src-tauri/)
+//     "keysDir": "~/.better-twttr-keys",      // holds native.key (minisign); never committed
+//     "keysDirEnv": "BT_KEYS_DIR",            // env override of keysDir
+//     "cdnBase": "https://cdn1.crt.fyi/better-twttr",
+//     "apiBase": "https://twttr.crt.fyi",     // the update API (verification steps)
+//     "outDir": "releases",                   // releases/upload (files), releases/native/latest.json
+//     "manifestValidator": { "module": "packages/contracts/dist/index.js", "export": "NativeRelease",
+//                            "hint": "build packages/contracts first" },  // optional, zod-like .parse
+//     "prepareCommand": "bun install --frozen-lockfile",  // remote/WSL builds: runs first in the unpacked sources
+//     "distribution": { "publisher": "CRT", "id": "CRT.Name", "homepage": "https://...", "license": "...", "shortDescription": "...", "downloadBase": "https://..." },
+//                                                        // manifests written after each release step (see cli/manifests.mjs)
+//     "exportExclude": ["verification"]                     // remote/WSL builds: app-repo paths left out of the upload
+//   }
+//
+// The Windows build runs with the path-free build environment (cli/buildenv.mjs). Every artifact
+// (the installer, the main binary, the front end, the dmg and the updater bundle) goes through the
+// optional release check (cli/releasecheck.mjs, WAYBETTER_RELEASE_CHECK) before anything is
+// copied, signed or written.
+//
+// The private key is read only into the build's environment (Windows) or handed to the Tauri
+// signer by path (macOS). Nothing here prints, copies or moves it.
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { pathFreeBuildEnv } from './buildenv.mjs';
+import { runReleaseCheck } from './releasecheck.mjs';
+import { CHANNELS, resolveSpec, writeManifests } from './manifests.mjs';
+import { buildLinuxWsl, buildMacRemote, scanBuilt } from './remote.mjs';
+
+export const CONFIG_FILE = 'waybetter.release.json';
+
+export const RELEASE_USAGE = `Usage:
+  waybetter release windows [--skip-build] [--notes "text"] [--config <file>]
+      Signed NSIS build (Tauri, updater artifacts), the installer and .sig in <outDir>/upload,
+      <outDir>/native/latest.json (other platforms of the same version kept), upload steps printed.
+  waybetter release macos --dmg <file.dmg> --updater <file.app.tar.gz> [--arch universal] [--config <file>]
+      Signs the updater bundle of a universal macOS build here, copies both into <outDir>/upload and
+      adds darwin-aarch64 and darwin-x86_64 to latest.json (run the Windows step first).
+  waybetter release macos --remote <user@host> [--ssh-key <file>] [--remote-dir <dir>] [--commit <ref>] [--build-only]
+      Builds the COMMITTED state (HEAD, or --commit <ref>, and the submodules at their recorded commits, exported with
+      git archive, never the working tree) on a Mac over SSH, universal and ad-hoc signed, without
+      a build path in it; brings the .dmg and .app.tar.gz to <outDir>/build/macos, scans them here,
+      then (unless --build-only) continues as above. The built .app stays in the remote work
+      folder (<remote-dir>/out); nothing is installed or replaced on the Mac. Env: WAYBETTER_MAC_SSH (user@host), WAYBETTER_MAC_SSH_KEY.
+  waybetter release linux --wsl [<distro>] [--remote-dir <dir>] [--commit <ref>] [--build-only]
+      Builds the committed state in WSL (default distro Ubuntu-22.04, or WAYBETTER_WSL_DISTRO): the
+      AppImage and the .deb in <outDir>/build/linux, scanned here; then (unless --build-only) the
+      same as \`release linux --appimage\`.
+  waybetter release linux --appimage <file.AppImage> --deb <file.deb> [--config <file>]
+      Signs the AppImage (the Linux update payload) here, copies both into <outDir>/upload and adds
+      linux-x86_64 to latest.json (run the Windows step first).
+
+Config: ${CONFIG_FILE} in the app's root (product, artifact, desktopDir, keysDir, keysDirEnv,
+cdnBase, apiBase, outDir, optional manifestValidator). Env: CARGO_TARGET_DIR, CDN_BASE,
+DEPLOY_TARGET, CDN_DIR, RELEASES_DIR, WAYBETTER_RELEASE_CHECK (an optional command run on every
+artifact first). The build is path-free (waybetter build-env). Nothing is ever uploaded.`;
+
+class ReleaseError extends Error {}
+const fail = message => { throw new ReleaseError(message); };
+
+/** Finds and reads the release config: `--config`, else the nearest waybetter.release.json. */
+export function loadReleaseConfig(cwd, file) {
+  let path = file ? resolve(cwd, file) : undefined;
+  if (!path) {
+    for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+      if (existsSync(join(dir, CONFIG_FILE))) { path = join(dir, CONFIG_FILE); break; }
+      if (dirname(dir) === dir) fail(`no ${CONFIG_FILE} in ${cwd} or above (or pass --config)`);
+    }
+  }
+  if (!existsSync(path)) fail(`config not found: ${path}`);
+  let raw;
+  try { raw = JSON.parse(readFileSync(path, 'utf8')); } catch (error) { fail(`${path}: ${error.message}`); }
+  return normalizeReleaseConfig(raw, dirname(path));
+}
+
+const home = value => value.replace(/^~(?=$|[\\/])/, homedir());
+
+/** Validated config with absolute paths (`root`: the folder holding the config file). */
+export function normalizeReleaseConfig(raw, root) {
+  const text = (key, fallback) => {
+    const value = raw[key] ?? fallback;
+    if (typeof value !== 'string' || !value.trim()) fail(`${CONFIG_FILE}: "${key}" must be a non-empty string`);
+    return value.trim();
+  };
+  const url = key => {
+    const value = text(key).replace(/\/+$/, '');
+    if (!/^https:\/\/[^\s/]+/.test(value)) fail(`${CONFIG_FILE}: "${key}" must be an https URL`);
+    return value;
+  };
+  const artifact = text('artifact');
+  if (!/^[A-Za-z0-9._-]+$/.test(artifact)) fail(`${CONFIG_FILE}: "artifact" must be a space-free file name part`);
+  const validator = raw.manifestValidator;
+  if (validator !== undefined && (typeof validator?.module !== 'string' || typeof validator?.export !== 'string')) {
+    fail(`${CONFIG_FILE}: "manifestValidator" needs "module" and "export"`);
+  }
+  const at = value => (isAbsolute(value) ? value : resolve(root, value));
+  const desktopDir = at(text('desktopDir'));
+  return {
+    root,
+    product: text('product'),
+    artifact,
+    desktopDir,
+    tauriDir: join(desktopDir, 'src-tauri'),
+    keysDir: at(home(text('keysDir'))),
+    keysDirEnv: raw.keysDirEnv === undefined ? undefined : text('keysDirEnv'),
+    keyFile: text('keyFile', 'native.key'),
+    cdnBase: url('cdnBase'),
+    apiBase: url('apiBase'),
+    outDir: at(text('outDir', 'releases')),
+    buildCommand: text('buildCommand', 'bun run tauri build'),
+    prepareCommand: text('prepareCommand', 'bun install --frozen-lockfile'),
+    distribution: raw.distribution,
+    exportExclude: Array.isArray(raw.exportExclude) ? raw.exportExclude.map(String) : [],
+    manifestValidator: validator && { module: at(validator.module), export: validator.export, hint: validator.hint },
+  };
+}
+
+function keyPath(config, env) {
+  const dir = (config.keysDirEnv && env[config.keysDirEnv]) || config.keysDir;
+  return join(home(dir), config.keyFile);
+}
+
+/** The shape every update manifest must have (also when the app adds its own validator). */
+export function checkManifest(manifest) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(manifest.version ?? '')) fail(`manifest: bad version ${manifest.version}`);
+  if (typeof manifest.notes !== 'string' || typeof manifest.pubDate !== 'string') fail('manifest: notes and pubDate must be strings');
+  const platforms = Object.entries(manifest.platforms ?? {});
+  if (!platforms.length) fail('manifest: no platforms');
+  for (const [key, entry] of platforms) {
+    if (!/^(windows|darwin|linux)-(x86_64|aarch64|i686|armv7)$/.test(key)) fail(`manifest: unknown platform ${key}`);
+    if (!/^https:\/\/\S+$/.test(entry?.url ?? '')) fail(`manifest: ${key} url must be https`);
+    if (typeof entry.signature !== 'string' || !entry.signature.trim()) fail(`manifest: ${key} has no signature`);
+  }
+  return manifest;
+}
+
+async function validate(config, manifest) {
+  checkManifest(manifest);
+  if (!config.manifestValidator) return manifest;
+  const { module, export: name, hint } = config.manifestValidator;
+  const loaded = await import(pathToFileURL(module).href).catch(() => fail(hint || `cannot load ${module}`));
+  const schema = loaded[name];
+  if (!schema || typeof schema.parse !== 'function') fail(`${module} has no ${name}.parse`);
+  return schema.parse(manifest);
+}
+
+function readVersion(config) {
+  const version = JSON.parse(readFileSync(join(config.root, 'package.json'), 'utf8')).version;
+  const conf = JSON.parse(readFileSync(join(config.tauriDir, 'tauri.conf.json'), 'utf8'));
+  const cargo = /^version\s*=\s*"([^"]+)"/m.exec(readFileSync(join(config.tauriDir, 'Cargo.toml'), 'utf8'))?.[1];
+  const desktop = JSON.parse(readFileSync(join(config.desktopDir, 'package.json'), 'utf8')).version;
+  const rel = path => relative(config.root, path).replaceAll('\\', '/');
+  for (const [name, value] of [
+    [rel(join(config.tauriDir, 'tauri.conf.json')), conf.version],
+    [rel(join(config.tauriDir, 'Cargo.toml')), cargo],
+    [rel(join(config.desktopDir, 'package.json')), desktop],
+  ]) {
+    if (value !== version) fail(`${name} has version ${value}, root package.json has ${version}. Sync them first.`);
+  }
+  const dist = typeof conf.build?.frontendDist === 'string' && !/^https?:/.test(conf.build.frontendDist) ? resolve(config.tauriDir, conf.build.frontendDist) : undefined;
+  const binary = conf.mainBinaryName ?? /^name\s*=\s*"([^"]+)"/m.exec(readFileSync(join(config.tauriDir, 'Cargo.toml'), 'utf8'))?.[1];
+  return { version, productName: conf.productName, binary, dist };
+}
+
+/** The optional release check (cli/releasecheck.mjs) over every artifact that exists. */
+function gate(config, paths, env, log) {
+  runReleaseCheck(paths.filter(path => path && existsSync(path)), { env, log, label: 'release: check' });
+}
+
+function option(args, name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+const pubDate = () => new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+/**
+ * Distribution manifests (winget, Chocolatey, Homebrew, AUR) for the installers now in
+ * <outDir>/upload, written to <outDir>/distribution/<version>. Needs "distribution" in the config
+ * and the public download URL (--download-base, WAYBETTER_DOWNLOAD_BASE or distribution.downloadBase):
+ * without it nothing is written, because that URL is not ours to guess.
+ */
+export function writeDistribution(config, version, args, { env = process.env, log = console.log } = {}) {
+  const d = config.distribution;
+  if (!d) return undefined;
+  const base = option(args, '--download-base') ?? env.WAYBETTER_DOWNLOAD_BASE ?? d.downloadBase;
+  if (!base) {
+    log('manifests: skipped: the public download URL is not known yet (pass --download-base <url>, or set WAYBETTER_DOWNLOAD_BASE); run the release step again or `waybetter manifests` once it is');
+    return undefined;
+  }
+  const upload = join(config.outDir, 'upload');
+  const found = name => (existsSync(join(upload, name)) ? { file: join(upload, name) } : undefined);
+  const exe = found(`${config.artifact}_${version}_x64-setup.exe`);
+  const dmg = found(`${config.artifact}_${version}_universal.dmg`);
+  const deb = found(`${config.artifact}_${version}_amd64.deb`);
+  const appImage = found(`${config.artifact}_${version}_amd64.AppImage`);
+  const spec = resolveSpec({
+    ...d,
+    name: d.name ?? config.product,
+    version,
+    windows: exe && { ...d.windows, ...exe },
+    macos: dmg && { ...d.macos, ...dmg },
+    linux: (deb || appImage) && { ...d.linux, ...(deb && { deb }), ...(appImage && { appImage }) },
+  }, { baseDir: config.root, downloadBase: base });
+  const out = join(config.outDir, 'distribution', version);
+  const { written, skipped } = writeManifests(spec, out, { only: CHANNELS });
+  log(`manifests: ${written.length} file(s) in ${relative(config.root, out).replaceAll('\\', '/')}${skipped.length ? ` (${skipped.join(', ')}: no installer for that platform yet)` : ''}`);
+  return { out, written, skipped };
+}
+
+/** `waybetter release windows`. */
+export async function releaseWindows(config, args, { env = process.env, log = console.log } = {}) {
+  const { version, productName, binary, dist } = readVersion(config);
+  log(`release: ${config.product} ${version}`);
+
+  // Signed build (updater artifacts need the minisign private key; its password is empty).
+  const targetDir = env.CARGO_TARGET_DIR ? resolve(env.CARGO_TARGET_DIR) : join(config.tauriDir, 'target');
+  const bundleDir = join(targetDir, 'release', 'bundle', 'nsis');
+  if (!args.includes('--skip-build')) {
+    const key = keyPath(config, env);
+    if (!existsSync(key)) fail(`signing key not found at ${key}`);
+    // A fixed command string from the app's own config (no user input), so the shell is safe.
+    const result = spawnSync(config.buildCommand, {
+      cwd: config.desktopDir,
+      stdio: 'inherit',
+      shell: true,
+      env: { ...env, ...pathFreeBuildEnv({ root: config.root, env }).env, TAURI_SIGNING_PRIVATE_KEY: readFileSync(key, 'utf8').trim(), TAURI_SIGNING_PRIVATE_KEY_PASSWORD: '' },
+    });
+    if (result.status !== 0) fail(`tauri build failed (exit ${result.status})`);
+  }
+
+  // The NSIS installer is also the updater payload (createUpdaterArtifacts, v2 format).
+  if (!existsSync(bundleDir)) fail(`no NSIS bundle folder at ${bundleDir}`);
+  // Exactly the current productName: the folder may still hold installers built under an older name.
+  const installer = readdirSync(bundleDir).find(name => name === `${productName}_${version}_x64-setup.exe`);
+  if (!installer) fail(`no x64 setup.exe for ${version} in ${bundleDir}`);
+  const sigPath = join(bundleDir, `${installer}.sig`);
+  if (!existsSync(sigPath)) fail(`missing ${installer}.sig (was TAURI_SIGNING_PRIVATE_KEY set?)`);
+  // Before anything is copied or written: the installer (opened), and what went into it.
+  gate(config, [join(bundleDir, installer), sigPath, binary && join(targetDir, 'release', `${binary}.exe`), dist], env, log);
+
+  const uploadDir = join(config.outDir, 'upload');
+  mkdirSync(join(config.outDir, 'native'), { recursive: true });
+  mkdirSync(uploadDir, { recursive: true });
+  // Versioned, space-free names: immutable on the CDN and safe in URLs.
+  const fileName = `${config.artifact}_${version}_x64-setup.exe`;
+  copyFileSync(join(bundleDir, installer), join(uploadDir, fileName));
+  copyFileSync(sigPath, join(uploadDir, `${fileName}.sig`));
+
+  const cdnBase = (env.CDN_BASE ?? config.cdnBase).replace(/\/+$/, '');
+  const manifestPath = join(config.outDir, 'native', 'latest.json');
+  // macOS and Linux entries of the same version are kept.
+  let others = {};
+  try {
+    const previous = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (previous.version === version) others = Object.fromEntries(Object.entries(previous.platforms ?? {}).filter(([key]) => key !== 'windows-x86_64'));
+  } catch { /* no previous manifest */ }
+  const manifest = await validate(config, {
+    version,
+    notes: option(args, '--notes') ?? '',
+    pubDate: pubDate(),
+    platforms: { ...others, 'windows-x86_64': { url: `${cdnBase}/${fileName}`, signature: readFileSync(sigPath, 'utf8').trim() } },
+  });
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  log(`release: wrote ${manifestPath}`);
+
+  // Installer first, manifest last, so clients never see a manifest pointing at a missing file.
+  const target = env.DEPLOY_TARGET ?? '<user>@<host>';
+  const cdnDir = env.CDN_DIR ?? `<cdn folder served at ${cdnBase.replace(/^https:\/\//, '')}>`;
+  const releasesDir = env.RELEASES_DIR ?? '<API RELEASES_DIR>';
+  const rel = path => relative(config.root, path).replaceAll('\\', '/');
+  log(`
+Nothing was uploaded. Run these steps yourself, in this order:
+
+  1. Upload the installer and its signature to the CDN:
+     scp "${rel(join(uploadDir, fileName))}" "${rel(join(uploadDir, `${fileName}.sig`))}" ${target}:${cdnDir}/
+
+  2. Check it is reachable before publishing the manifest:
+     curl -sSfI ${cdnBase}/${fileName}
+
+  3. Publish the manifest (the API hot-reloads it by mtime; no restart needed):
+     scp "${rel(manifestPath)}" ${target}:${releasesDir}/native/latest.json.tmp
+     ssh ${target} "mv ${releasesDir}/native/latest.json.tmp ${releasesDir}/native/latest.json"
+
+  4. Verify the update endpoint answers an older client:
+     curl -sS ${config.apiBase}/v1/updates/windows/x86_64/0.0.0
+`);
+  writeDistribution(config, version, args, { env, log });
+  return { version, manifestPath, files: [fileName, `${fileName}.sig`] };
+}
+
+/** Signs a copy in the upload folder (the signature's trusted comment names the file and binds the version). */
+function signFile(config, file, version, env) {
+  const key = keyPath(config, env);
+  if (!existsSync(key)) fail(`signing key not found at ${key}`);
+  const exe = process.platform === 'win32' ? 'tauri.exe' : 'tauri';
+  const tauri = [join(config.desktopDir, 'node_modules', '.bin', exe), join(config.root, 'node_modules', '.bin', exe)].find(existsSync);
+  if (!tauri) fail('Tauri CLI not installed (bun install)');
+  const signed = spawnSync(tauri, ['signer', 'sign', '-f', key, '-p', '', '--app-version', version, file], {
+    stdio: ['ignore', 'ignore', 'inherit'], // stdout would echo the signature; the .sig file holds it
+  });
+  if (signed.status !== 0) fail(`tauri signer sign failed (exit ${signed.status})`);
+  const sigPath = `${file}.sig`;
+  if (!existsSync(sigPath)) fail(`signer wrote no ${sigPath}`);
+  return sigPath;
+}
+
+/** `waybetter release macos`: adds a universal macOS build (built unsigned on the Mac) to the release. */
+export async function releaseMacos(config, args, { env = process.env, log = console.log } = {}) {
+  let version = JSON.parse(readFileSync(join(config.root, 'package.json'), 'utf8')).version;
+  let dmg = option(args, '--dmg');
+  let updater = option(args, '--updater');
+  const target = option(args, '--remote') ?? (dmg ? undefined : env.WAYBETTER_MAC_SSH);
+  if (target) {
+    const built = buildMacRemote({ config, target, key: option(args, '--ssh-key') ?? env.WAYBETTER_MAC_SSH_KEY, remoteDir: option(args, '--remote-dir'), ref: option(args, '--commit'), env, log });
+    scanBuilt(config, [built.dmg, built.updater], { env, log });
+    if (option(args, '--commit')) version = built.version;
+    else if (built.version !== version) fail(`the committed version is ${built.version} but the working tree says ${version}: commit or sync first`);
+    if (args.includes('--build-only')) {
+      log(`release-macos: built ${built.sha.slice(0, 12)} in ${relative(config.root, built.dir).replaceAll('\\', '/')} (scanned, not signed)`);
+      return { version, dir: built.dir, files: [built.dmg, built.updater] };
+    }
+    dmg = built.dmg;
+    updater = built.updater;
+  }
+  const arch = option(args, '--arch') ?? 'universal';
+  if (!dmg || !updater) fail('usage: --dmg <file.dmg> --updater <file.app.tar.gz> [--arch universal]');
+  if (arch !== 'universal') fail('only universal builds are supported (one file serves both darwin arches)');
+  for (const file of [dmg, updater]) if (!existsSync(file)) fail(`not found: ${file}`);
+  if (!updater.endsWith('.app.tar.gz')) fail('--updater must be the .app.tar.gz Tauri wrote');
+  gate(config, [resolve(dmg), resolve(updater)], env, log);
+
+  const uploadDir = join(config.outDir, 'upload');
+  mkdirSync(uploadDir, { recursive: true });
+  const dmgName = `${config.artifact}_${version}_${arch}.dmg`;
+  const updaterName = `${config.artifact}_${version}_${arch}.app.tar.gz`;
+  copyFileSync(dmg, join(uploadDir, dmgName));
+  copyFileSync(updater, join(uploadDir, updaterName));
+
+  const sigPath = signFile(config, join(uploadDir, updaterName), version, env);
+
+  const manifestPath = join(config.outDir, 'native', 'latest.json');
+  if (!existsSync(manifestPath)) fail(`no ${relative(config.root, manifestPath)}: run \`waybetter release windows\` first`);
+  const current = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (current.version !== version) fail(`latest.json is ${current.version}, this build is ${version}`);
+  const cdnBase = (env.CDN_BASE ?? config.cdnBase).replace(/\/+$/, '');
+  const entry = { url: `${cdnBase}/${updaterName}`, signature: readFileSync(sigPath, 'utf8').trim() };
+  const manifest = await validate(config, { ...current, platforms: { ...current.platforms, 'darwin-aarch64': entry, 'darwin-x86_64': entry } });
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  log(`release-macos: ${dmgName}, ${updaterName} (+ .sig) in ${relative(config.root, uploadDir).replaceAll('\\', '/')}; latest.json now has ${Object.keys(manifest.platforms).join(', ')}`);
+  log(`
+Nothing was uploaded. Upload the dmg, the updater bundle and its .sig to the CDN next to the
+Windows installer (same target and folder as \`waybetter release windows\` prints), check
+  curl -sSfI ${cdnBase}/${updaterName}
+then publish latest.json the same way (tmp file, then mv), and verify
+  curl -sS ${config.apiBase}/v1/updates/darwin/aarch64/0.0.0
+  curl -sS ${config.apiBase}/v1/updates/darwin/x86_64/0.0.0
+`);
+  writeDistribution(config, version, args, { env, log });
+  return { version, manifestPath, files: [dmgName, updaterName, `${updaterName}.sig`] };
+}
+
+/** `waybetter release linux`: adds the AppImage (signed here: it is the update payload) and the .deb. */
+export async function releaseLinux(config, args, { env = process.env, log = console.log } = {}) {
+  let version = JSON.parse(readFileSync(join(config.root, 'package.json'), 'utf8')).version;
+  let appimage = option(args, '--appimage');
+  let deb = option(args, '--deb');
+  if (args.includes('--wsl')) {
+    const next = args[args.indexOf('--wsl') + 1];
+    const distro = next && !next.startsWith('--') ? next : env.WAYBETTER_WSL_DISTRO;
+    const built = buildLinuxWsl({ config, distro, remoteDir: option(args, '--remote-dir'), ref: option(args, '--commit'), env, log });
+    scanBuilt(config, [built.appimage, built.deb], { env, log });
+    if (option(args, '--commit')) version = built.version;
+    else if (built.version !== version) fail(`the committed version is ${built.version} but the working tree says ${version}: commit or sync first`);
+    if (args.includes('--build-only')) {
+      log(`release-linux: built ${built.sha.slice(0, 12)} in ${relative(config.root, built.dir).replaceAll('\\', '/')} (scanned, not signed)`);
+      return { version, dir: built.dir, files: [built.appimage, built.deb] };
+    }
+    appimage = built.appimage;
+    deb = built.deb;
+  }
+  if (!appimage || !deb) fail('usage: --appimage <file.AppImage> --deb <file.deb>  (or --wsl)');
+  for (const file of [appimage, deb]) if (!existsSync(file)) fail(`not found: ${file}`);
+  if (!appimage.endsWith('.AppImage')) fail('--appimage must be the .AppImage Tauri wrote');
+  if (!deb.endsWith('.deb')) fail('--deb must be the .deb Tauri wrote');
+  gate(config, [resolve(appimage), resolve(deb)], env, log);
+
+  const uploadDir = join(config.outDir, 'upload');
+  mkdirSync(uploadDir, { recursive: true });
+  const appimageName = `${config.artifact}_${version}_amd64.AppImage`;
+  const debName = `${config.artifact}_${version}_amd64.deb`;
+  copyFileSync(appimage, join(uploadDir, appimageName));
+  copyFileSync(deb, join(uploadDir, debName));
+  const sigPath = signFile(config, join(uploadDir, appimageName), version, env);
+
+  const manifestPath = join(config.outDir, 'native', 'latest.json');
+  if (!existsSync(manifestPath)) fail(`no ${relative(config.root, manifestPath)}: run \`waybetter release windows\` first`);
+  const current = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (current.version !== version) fail(`latest.json is ${current.version}, this build is ${version}`);
+  const cdnBase = (env.CDN_BASE ?? config.cdnBase).replace(/\/+$/, '');
+  const entry = { url: `${cdnBase}/${appimageName}`, signature: readFileSync(sigPath, 'utf8').trim() };
+  const manifest = await validate(config, { ...current, platforms: { ...current.platforms, 'linux-x86_64': entry } });
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  log(`release-linux: ${appimageName} (+ .sig), ${debName} in ${relative(config.root, uploadDir).replaceAll('\\', '/')}; latest.json now has ${Object.keys(manifest.platforms).join(', ')}`);
+  log(`
+Nothing was uploaded. Upload the AppImage, its .sig and the .deb to the CDN next to the Windows
+installer (same target and folder as \`waybetter release windows\` prints), check
+  curl -sSfI ${cdnBase}/${appimageName}
+then publish latest.json the same way (tmp file, then mv), and verify
+  curl -sS ${config.apiBase}/v1/updates/linux/x86_64/0.0.0
+`);
+  writeDistribution(config, version, args, { env, log });
+  return { version, manifestPath, files: [appimageName, `${appimageName}.sig`, debName] };
+}
+
+/** `waybetter release <windows|macos|linux> ...` from the command line (or an app's wrapper script). */
+export async function releaseCommand(args, { cwd = process.cwd(), env = process.env, log = console.log } = {}) {
+  const [platform, ...rest] = args;
+  if (platform !== 'windows' && platform !== 'macos' && platform !== 'linux') {
+    log(RELEASE_USAGE);
+    if (platform && platform !== '--help' && platform !== '-h') fail(`unknown release target ${platform}`);
+    return undefined;
+  }
+  const config = loadReleaseConfig(cwd, option(rest, '--config'));
+  const release = { windows: releaseWindows, macos: releaseMacos, linux: releaseLinux }[platform];
+  return release(config, rest, { env, log });
+}

package/cli/releasecheck.mjs

@@ -0,0 +1,15 @@
+// An optional, owner-supplied check run on every artifact before a release copies, signs or writes
+// anything: WAYBETTER_RELEASE_CHECK names a command (run through the shell) that gets the artifact
+// paths as arguments. A non-zero exit stops the release. Unset, nothing runs.
+import { spawnSync } from 'node:child_process';
+
+export const RELEASE_CHECK_ENV = 'WAYBETTER_RELEASE_CHECK';
+
+export function runReleaseCheck(paths, { env = process.env, log = console.log, label = 'release check' } = {}) {
+  const command = env[RELEASE_CHECK_ENV];
+  if (!command || !paths.length) return;
+  const quoted = paths.map(path => `'${String(path).replaceAll("'", "'\\''")}'`).join(' ');
+  log(`${label}: ${paths.length} file(s)`);
+  const result = spawnSync(`${command} ${quoted}`, { shell: true, stdio: 'inherit', env });
+  if (result.status !== 0) throw new Error(`${label} failed (exit ${result.status ?? result.signal})`);
+}