waybetter 0.1.1 → 0.6.0

package/cli/manifests.mjs

@@ -0,0 +1,383 @@
+// `waybetter manifests <file.json>`: distribution manifests for any app from one small JSON
+// description: a winget manifest set, a Chocolatey package, a Homebrew cask for the publisher's
+// OWN tap and an AUR package (PKGBUILD + .SRCINFO). Generic: nothing here knows wayBetter. Nothing
+// is submitted anywhere and no account is needed; the files are what the owner submits or pushes
+// (see the app's docs/DISTRIBUTION.md).
+//
+// The description (JSON):
+//
+//   {
+//     "publisher": "CRT",                    // winget/choco publisher
+//     "id": "CRT.WayBetterForX",             // winget PackageIdentifier: Publisher.Package[.Sub]
+//     "name": "wayBetter for X",             // display name
+//     "slug": "waybetter-for-x",             // optional lower-case name for choco/brew/aur (derived from name)
+//     "version": "1.0.0",
+//     "shortDescription": "...", "description": "...",   // description optional (defaults to short)
+//     "homepage": "https://...", "license": "GPL-3.0-or-later", "licenseUrl": "https://...", // licenseUrl optional
+//     "releaseNotesUrl": "https://...", "tags": ["a", "b"], "copyright": "...",
+//     "windows": { "url": "https://.../setup.exe", "sha256": "<64 hex>", "silentSwitches": "/S",
+//                  "scope": "user", "architecture": "x64" },
+//     "macos":   { "url": "https://.../app.dmg", "sha256": "...", "app": "wayBetter for X.app", "zap": ["~/Library/..."] },
+//     "linux":   { "deb": { "url": "...", "sha256": "..." }, "appImage": { "url": "...", "sha256": "..." },
+//                  "depends": ["webkit2gtk-4.1", "gtk3"] }
+//   }
+//
+// An installer may give `"file": "<local path>"` instead of `sha256` (hashed here) and, with
+// `--download-base <url>` (or "downloadBase" in the description), instead of `url` too
+// (<base>/<file name>). Unknown URLs are inputs, never guessed. A platform section that is absent
+// skips the channels that need it.
+//
+//   waybetter manifests <file.json> [--out <dir>] [--download-base <url>] [--only winget,chocolatey,homebrew,aur]
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+export const MANIFESTS_USAGE = `Usage:
+  waybetter manifests <file.json> [--out <dir>] [--download-base <url>] [--only winget,chocolatey,homebrew,aur]
+      Writes distribution manifests from a small JSON description (publisher, id, name, version,
+      installer URLs + sha256 or local files, silent switches, licence, homepage): a winget manifest
+      set (schema 1.28.0), a Chocolatey package, a Homebrew cask for your own tap and an AUR
+      PKGBUILD + .SRCINFO. Submits nothing.`;
+
+export const WINGET_MANIFEST_VERSION = '1.28.0';
+export const CHANNELS = ['winget', 'chocolatey', 'homebrew', 'aur'];
+
+class ManifestError extends Error {}
+const fail = message => { throw new ManifestError(message); };
+
+const HTTPS = /^https:\/\/[^\s"'<>]+$/;
+const SHA256 = /^[0-9a-fA-F]{64}$/;
+const VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const WINGET_ID = /^[^.\s\\/:*?"<>|\x01-\x1f]{1,32}(\.[^.\s\\/:*?"<>|\x01-\x1f]{1,32}){1,7}$/;
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+
+export const slugOf = name => name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const sha256File = file => createHash('sha256').update(readFileSync(file)).digest('hex');
+
+/** Resolves `file` installers (hash, URL from the download base) and validates the description. */
+export function resolveSpec(raw, { baseDir = process.cwd(), downloadBase } = {}) {
+  const spec = structuredClone(raw);
+  const text = (key, { optional = false } = {}) => {
+    const value = spec[key];
+    if (value === undefined && optional) return undefined;
+    if (typeof value !== 'string' || !value.trim()) fail(`"${key}" must be a non-empty string`);
+    return value.trim();
+  };
+  spec.publisher = text('publisher');
+  spec.id = text('id');
+  if (!WINGET_ID.test(spec.id)) fail('"id" must look like Publisher.Package (no spaces, at most 32 characters a part)');
+  spec.name = text('name');
+  spec.slug = text('slug', { optional: true }) ?? slugOf(spec.name);
+  if (!SLUG.test(spec.slug)) fail('"slug" must be lower-case letters, digits and hyphens');
+  spec.version = text('version');
+  if (!VERSION.test(spec.version)) fail(`"version" must be like 1.2.3, not ${spec.version}`);
+  spec.shortDescription = text('shortDescription');
+  spec.description = text('description', { optional: true }) ?? spec.shortDescription;
+  spec.homepage = text('homepage');
+  if (!HTTPS.test(spec.homepage)) fail('"homepage" must be an https URL');
+  spec.license = text('license');
+  spec.licenseUrl = text('licenseUrl', { optional: true }) ?? (/^[A-Za-z0-9.+-]+$/.test(spec.license) ? `https://spdx.org/licenses/${spec.license}.html` : undefined);
+  for (const key of ['releaseNotesUrl']) if (spec[key] !== undefined && !HTTPS.test(spec[key])) fail(`"${key}" must be an https URL`);
+  spec.tags = (spec.tags ?? []).map(String);
+
+  const base = (downloadBase ?? spec.downloadBase)?.replace(/\/+$/, '');
+  const installer = (where, entry) => {
+    if (!entry || typeof entry !== 'object') fail(`"${where}" must be an object`);
+    const file = entry.file && resolve(baseDir, entry.file);
+    if (file && !existsSync(file)) fail(`${where}: file not found: ${entry.file}`);
+    entry.sha256 = (entry.sha256 ?? (file && sha256File(file)))?.toLowerCase();
+    entry.url ??= file && base ? `${base}/${basename(file)}` : undefined;
+    if (!entry.url) fail(`${where}: needs "url" (or "file" with --download-base)`);
+    if (!HTTPS.test(entry.url)) fail(`${where}: url must be an https URL`);
+    if (!SHA256.test(entry.sha256 ?? '')) fail(`${where}: needs a 64-digit "sha256" (or "file" to hash)`);
+    return entry;
+  };
+  if (spec.windows) {
+    installer('windows', spec.windows);
+    spec.windows.architecture ??= 'x64';
+    if (!['x86', 'x64', 'arm', 'arm64', 'neutral'].includes(spec.windows.architecture)) fail('windows.architecture must be x86, x64, arm, arm64 or neutral');
+    spec.windows.scope ??= 'user';
+    if (!['user', 'machine'].includes(spec.windows.scope)) fail('windows.scope must be user or machine');
+    spec.windows.silentSwitches ??= '/S';
+    spec.windows.installerType ??= 'nullsoft';
+    if (!['nullsoft', 'inno', 'exe', 'msi', 'wix', 'burn'].includes(spec.windows.installerType)) fail('windows.installerType is not a winget installer type');
+  }
+  if (spec.macos) {
+    installer('macos', spec.macos);
+    spec.macos.app = spec.macos.app ? String(spec.macos.app) : `${spec.name}.app`;
+    if (!spec.macos.app.endsWith('.app') || /[/"\\]/.test(spec.macos.app)) fail('macos.app must be a bundle name like "Name.app"');
+    spec.macos.zap = (spec.macos.zap ?? []).map(String);
+  }
+  if (spec.linux) {
+    if (!spec.linux.deb && !spec.linux.appImage) fail('linux needs "deb" and/or "appImage"');
+    for (const kind of ['deb', 'appImage']) if (spec.linux[kind]) installer(`linux.${kind}`, spec.linux[kind]);
+    spec.linux.depends = (spec.linux.depends ?? ['webkit2gtk-4.1', 'gtk3']).map(String);
+  }
+  if (!spec.windows && !spec.macos && !spec.linux) fail('give at least one of "windows", "macos", "linux"');
+  return spec;
+}
+
+// ---- YAML (only the shapes winget needs: maps, lists, strings, numbers) ----
+
+const plain = /^[A-Za-z0-9_][A-Za-z0-9_./ -]*$/;
+function scalar(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  const text = String(value);
+  // Quote anything YAML could read as something else (numbers, booleans, null, "a: b", "- x", "#").
+  if (plain.test(text) && !/^(true|false|null|yes|no|on|off|~|[-+]?[0-9.]+(e[0-9]+)?)$/i.test(text) && !/ $|: | #/.test(text) && !text.includes('- ') ) return text;
+  return JSON.stringify(text);
+}
+export function toYaml(value, indent = 0) {
+  const pad = ' '.repeat(indent);
+  const lines = [];
+  for (const [key, item] of Object.entries(value)) {
+    if (item === undefined || item === null) continue;
+    if (Array.isArray(item)) {
+      if (!item.length) continue;
+      lines.push(`${pad}${key}:`);
+      for (const entry of item) {
+        if (entry && typeof entry === 'object') {
+          const inner = toYaml(entry, indent + 2).split('\n');
+          lines.push(`${pad}- ${inner[0].trimStart()}`, ...inner.slice(1));
+        } else lines.push(`${pad}- ${scalar(entry)}`);
+      }
+    } else if (typeof item === 'object') {
+      lines.push(`${pad}${key}:`, toYaml(item, indent + 2));
+    } else if (typeof item === 'string' && item.includes('\n')) {
+      lines.push(`${pad}${key}: |-`, ...item.split('\n').map(line => `${pad}  ${line}`));
+    } else lines.push(`${pad}${key}: ${scalar(item)}`);
+  }
+  return lines.join('\n');
+}
+
+// ---- winget ----
+
+const WINGET_LOCALE = 'en-US';
+
+export function wingetManifests(spec) {
+  if (!spec.windows) return undefined;
+  const w = spec.windows;
+  const header = name => `# Created by waybetter manifests\n# yaml-language-server: $schema=https://aka.ms/winget-manifest.${name}.${WINGET_MANIFEST_VERSION}.schema.json\n\n`;
+  const common = { PackageIdentifier: spec.id, PackageVersion: spec.version };
+  const installer = {
+    ...common,
+    InstallerLocale: WINGET_LOCALE,
+    InstallerType: w.installerType,
+    Scope: w.scope,
+    InstallModes: ['interactive', 'silent', 'silentWithProgress'],
+    InstallerSwitches: { Silent: w.silentSwitches, SilentWithProgress: w.silentWithProgress ?? w.silentSwitches },
+    UpgradeBehavior: 'install',
+    Installers: [{ Architecture: w.architecture, InstallerUrl: w.url, InstallerSha256: w.sha256.toUpperCase() }],
+    ManifestType: 'installer',
+    ManifestVersion: WINGET_MANIFEST_VERSION,
+  };
+  const locale = {
+    ...common,
+    PackageLocale: WINGET_LOCALE,
+    Publisher: spec.publisher,
+    PublisherUrl: spec.publisherUrl,
+    PackageName: spec.name,
+    PackageUrl: spec.homepage,
+    License: spec.license,
+    LicenseUrl: spec.licenseUrl,
+    Copyright: spec.copyright,
+    ShortDescription: spec.shortDescription,
+    Description: spec.description,
+    Tags: spec.tags.length ? spec.tags : undefined,
+    ReleaseNotesUrl: spec.releaseNotesUrl,
+    ManifestType: 'defaultLocale',
+    ManifestVersion: WINGET_MANIFEST_VERSION,
+  };
+  const version = { ...common, DefaultLocale: WINGET_LOCALE, ManifestType: 'version', ManifestVersion: WINGET_MANIFEST_VERSION };
+  // winget-pkgs layout: manifests/<first letter>/<Publisher>/<Package>/<version>/<Id>[.installer|.locale.<tag>].yaml
+  const dir = join('winget', 'manifests', spec.id[0].toLowerCase(), ...spec.id.split('.'), spec.version);
+  return {
+    [join(dir, `${spec.id}.yaml`)]: `${header('version')}${toYaml(version)}\n`,
+    [join(dir, `${spec.id}.installer.yaml`)]: `${header('installer')}${toYaml(installer)}\n`,
+    [join(dir, `${spec.id}.locale.${WINGET_LOCALE}.yaml`)]: `${header('defaultLocale')}${toYaml(locale)}\n`,
+  };
+}
+
+// ---- Chocolatey ----
+
+const xml = value => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const psq = value => `'${String(value).replaceAll("'", "''")}'`;
+
+export function chocolateyPackage(spec) {
+  if (!spec.windows) return undefined;
+  const w = spec.windows;
+  const dir = join('chocolatey', spec.slug);
+  const fileType = w.installerType === 'msi' || w.installerType === 'wix' ? 'msi' : 'exe';
+  const nuspec = `<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
+  <metadata>
+    <id>${xml(spec.slug)}</id>
+    <version>${xml(spec.version)}</version>
+    <title>${xml(spec.name)}</title>
+    <authors>${xml(spec.publisher)}</authors>
+    <projectUrl>${xml(spec.homepage)}</projectUrl>${spec.licenseUrl ? `\n    <licenseUrl>${xml(spec.licenseUrl)}</licenseUrl>` : ''}
+    <requireLicenseAcceptance>false</requireLicenseAcceptance>
+    <summary>${xml(spec.shortDescription)}</summary>
+    <description>${xml(spec.description)}</description>${spec.tags.length ? `\n    <tags>${xml(spec.tags.join(' '))}</tags>` : ''}${spec.copyright ? `\n    <copyright>${xml(spec.copyright)}</copyright>` : ''}${spec.releaseNotesUrl ? `\n    <releaseNotes>${xml(spec.releaseNotesUrl)}</releaseNotes>` : ''}
+  </metadata>
+  <files>
+    <file src="tools\\**" target="tools" />
+  </files>
+</package>
+`;
+  const install = `$ErrorActionPreference = 'Stop'
+
+$packageArgs = @{
+  packageName    = $env:ChocolateyPackageName
+  fileType       = ${psq(fileType)}
+  url64bit       = ${psq(w.url)}
+  checksum64     = ${psq(w.sha256.toLowerCase())}
+  checksumType64 = 'sha256'
+  silentArgs     = ${psq(w.silentSwitches)}
+  validExitCodes = @(0)
+}
+
+Install-ChocolateyPackage @packageArgs
+`;
+  return {
+    [join(dir, `${spec.slug}.nuspec`)]: nuspec,
+    [join(dir, 'tools', 'chocolateyInstall.ps1')]: install,
+  };
+}
+
+// ---- Homebrew cask (the publisher's own tap: <tap>/Casks/<slug>.rb) ----
+
+const rb = value => `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('#{', '\\#{')}"`;
+
+export function homebrewCask(spec) {
+  if (!spec.macos) return undefined;
+  const m = spec.macos;
+  // The version inside the URL becomes #{version}, so a bump edits one line.
+  const url = m.url.includes(spec.version) ? `"${m.url.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll(spec.version, '#{version}')}"` : rb(m.url);
+  const zap = m.zap.length ? `\n\n  zap trash: [\n${m.zap.map(path => `    ${rb(path)},`).join('\n')}\n  ]` : '';
+  const cask = `cask ${rb(spec.slug)} do
+  version ${rb(spec.version)}
+  sha256 ${rb(m.sha256)}
+
+  url ${url}
+  name ${rb(spec.name)}
+  desc ${rb(spec.shortDescription)}
+  homepage ${rb(spec.homepage)}
+
+  depends_on macos: ">= :big_sur"
+
+  app ${rb(m.app)}${zap}
+end
+`;
+  return { [join('homebrew', 'Casks', `${spec.slug}.rb`)]: cask };
+}
+
+// ---- AUR: <slug>-bin repackaging the .deb (or, without one, the AppImage) ----
+
+const bash = value => `'${String(value).replaceAll("'", `'\\''`)}'`;
+export function aurPackage(spec) {
+  const l = spec.linux;
+  if (!l) return undefined;
+  const name = `${spec.slug}-bin`;
+  const isDeb = Boolean(l.deb);
+  const source = l.deb ?? l.appImage;
+  const ext = isDeb ? 'deb' : 'AppImage';
+  const pkgver = spec.version.replaceAll('-', '_');
+  const file = `${name}-${pkgver}.${ext}`;
+  // The version in the URL becomes ${pkgver}; a release version with a hyphen keeps its URL literally.
+  const simple = !spec.version.includes('-');
+  const dq = value => value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('$', '\\$');
+  const url = simple ? dq(source.url).replaceAll(spec.version, '${pkgver}') : dq(source.url);
+  const sourceEntry = simple ? `"\${pkgname}-\${pkgver}.${ext}::${url}"` : `"${file}::${url}"`;
+  const depends = isDeb ? l.depends : [];
+  const body = isDeb
+    ? '  bsdtar -xf "$srcdir"/data.tar.* -C "$pkgdir"'
+    : `  install -Dm755 "$srcdir/${file}" "$pkgdir/opt/${spec.slug}/${spec.slug}.AppImage"
+  install -d "$pkgdir/usr/bin"
+  ln -s "/opt/${spec.slug}/${spec.slug}.AppImage" "$pkgdir/usr/bin/${spec.slug}"`;
+  const pkgbuild = `# Maintainer: ${spec.publisher}
+pkgname=${name}
+pkgver=${pkgver}
+pkgrel=1
+pkgdesc=${bash(spec.shortDescription)}
+arch=('x86_64')
+url=${bash(spec.homepage)}
+license=(${bash(spec.license)})
+${depends.length ? `depends=(${depends.map(bash).join(' ')})\n` : ''}provides=(${bash(spec.slug)})
+conflicts=(${bash(spec.slug)})
+options=(!strip !debug)
+${isDeb ? '' : `noextract=("${file}")\n`}source=(${sourceEntry})
+sha256sums=(${bash(source.sha256.toLowerCase())})
+
+package() {
+${body}
+}
+`;
+  const srcinfo = `pkgbase = ${name}
+\tpkgdesc = ${spec.shortDescription}
+\tpkgver = ${pkgver}
+\tpkgrel = 1
+\turl = ${spec.homepage}
+\tarch = x86_64
+\tlicense = ${spec.license}
+${depends.map(dep => `\tdepends = ${dep}\n`).join('')}\toptions = !strip
+\toptions = !debug
+\tprovides = ${spec.slug}
+\tconflicts = ${spec.slug}
+${isDeb ? '' : `\tnoextract = ${file}\n`}\tsource = ${file}::${source.url}
+\tsha256sums = ${source.sha256.toLowerCase()}
+
+pkgname = ${name}
+`;
+  return { [join('aur', name, 'PKGBUILD')]: pkgbuild, [join('aur', name, '.SRCINFO')]: srcinfo };
+}
+
+/** All manifests as `{ relative path: text }`; `only` limits the channels. */
+export function buildManifests(spec, { only = CHANNELS } = {}) {
+  const builders = { winget: wingetManifests, chocolatey: chocolateyPackage, homebrew: homebrewCask, aur: aurPackage };
+  const files = {};
+  const skipped = [];
+  for (const channel of only) {
+    if (!builders[channel]) fail(`unknown channel ${channel} (${CHANNELS.join(', ')})`);
+    const made = builders[channel](spec);
+    if (made) Object.assign(files, made);
+    else skipped.push(channel);
+  }
+  return { files, skipped };
+}
+
+/** Writes them under `outDir` (LF line endings) and returns the written relative paths. */
+export function writeManifests(spec, outDir, options) {
+  const { files, skipped } = buildManifests(spec, options);
+  for (const [path, text] of Object.entries(files)) {
+    const target = join(outDir, path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, text.replaceAll('\r\n', '\n'));
+  }
+  return { written: Object.keys(files), skipped };
+}
+
+function option(args, name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+/** `waybetter manifests ...`; returns the exit code. */
+export function manifestsCommand(argv, { cwd = process.cwd(), log = console.log } = {}) {
+  const file = argv.find((arg, i) => !arg.startsWith('--') && !['--out', '--download-base', '--only'].includes(argv[i - 1]));
+  if (!file || argv.includes('--help') || argv.includes('-h')) {
+    log(MANIFESTS_USAGE);
+    return file ? 0 : 1;
+  }
+  const path = resolve(cwd, file);
+  if (!existsSync(path)) fail(`not found: ${path}`);
+  let raw;
+  try { raw = JSON.parse(readFileSync(path, 'utf8')); } catch (error) { fail(`${path}: ${error.message}`); }
+  const spec = resolveSpec(raw, { baseDir: dirname(path), downloadBase: option(argv, '--download-base') });
+  const only = option(argv, '--only')?.split(',').map(s => s.trim()).filter(Boolean);
+  const out = resolve(cwd, option(argv, '--out') ?? 'distribution');
+  const { written, skipped } = writeManifests(spec, out, { only: only ?? CHANNELS });
+  for (const name of written) log(`manifests: ${join(out, name)}`);
+  if (skipped.length) log(`manifests: skipped ${skipped.join(', ')} (no installer for that platform in the description)`);
+  return 0;
+}