@mirinjs/cli 0.1.0-alpha.2 → 0.1.0-alpha.22

package/src/build.ts

@@ -1,11 +1,9 @@
 /**
  * `mirin build` — package a standalone, signed .app (docs/macos-mvp.md).
  *
- * 1. vite build               → production UI in dist/
- * 2. resolve native artifacts → core + helper (in-repo build or prebuilt)
- * 3. compile host (minified)  → Contents/MacOS/<exe>
- * 4. bundle Worker (minified) → Resources/worker.js
- * 5. assemble + sign the .app → dist/ui, manifest, dylib, helpers, CEF
+ * 1. vite build + native artifact resolution run in parallel.
+ * 2. compile host + bundle Workers run in parallel.
+ * 3. assemble + sign the app from the completed artifacts.
  *
  * The result runs with no env and no dev server: the host resolves everything
  * from inside the bundle, and webviews load their `app://` URLs served from
@@ -15,16 +13,103 @@
  * ID to produce a distributable, notarizable app.
  */
 
-import { $ } from "bun";
-import { mkdirSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { buildAppBundle } from "./bundle.ts";
-import { buildWindowsBundle } from "./bundle-win.ts";
+import { $ } from "bun";
 import { resolveArtifacts } from "./artifacts.ts";
+import { buildLinuxBundle } from "./bundle/linux/index.ts";
+import { buildAppBundle } from "./bundle/macos/index.ts";
+import { normalizeCefLocales } from "./bundle/shared/cef-locales.ts";
+import { buildWindowsBundle } from "./bundle/windows/index.ts";
+import { compileWorkers, normalizeSidecars } from "./extras.ts";
+import { resolveIconSource } from "./icons/sources.ts";
+import { makeWindowsIcon } from "./icons/windows/index.ts";
+import { buildLinuxPackages, resolveLinuxFormats } from "./package/linux/index.ts";
 import { sweepBuildTemps } from "./temps.ts";
-import { normalizeSidecars, compileWorkers } from "./extras.ts";
 
 const IS_WINDOWS = process.platform === "win32";
+const IS_LINUX = process.platform === "linux";
+
+/** A PE FILEVERSION (`x.y.z.w`) from a semver string (pre-release suffix dropped). */
+function winFileVersion(v: string): string {
+  const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? `${m[1]}.${m[2]}.${m[3]}.0` : "0.0.0.0";
+}
+
+/**
+ * Flip a PE exe from the CONSOLE subsystem (3) to GUI (2) so Windows allocates
+ * **no console window** when it's launched from a shortcut. Bun's
+ * `--windows-hide-console` only hides the console at runtime (a brief flash);
+ * GUI subsystem prevents it entirely — the equivalent of Electrobun's
+ * `exe.subsystem = .Windows`. The optional-header Subsystem field is at
+ * `e_lfanew + 24 (PE sig + COFF) + 68`.
+ */
+function patchPeToGuiSubsystem(exePath: string): void {
+  const buf = readFileSync(exePath);
+  const peOff = buf.readUInt32LE(0x3c);
+  if (buf.readUInt32LE(peOff) !== 0x0000_4550) return; // not "PE\0\0"
+  const subsystemOff = peOff + 92;
+  if (buf.readUInt16LE(subsystemOff) === 3 /* CONSOLE */) {
+    buf.writeUInt16LE(2 /* GUI */, subsystemOff);
+    writeFileSync(exePath, buf);
+  }
+}
+
+/**
+ * Stamp a Bun-compiled Windows exe with the app icon + version metadata via
+ * rcedit. Bun's `--windows-icon` is a silent no-op on Windows hosts, so without
+ * this the exe keeps Bun's icon — which the Start Menu / Desktop shortcut, the
+ * taskbar, and Explorer all show. Uses a single largest-size icon: rcedit's
+ * multi-size replacement silently fails on Bun's appended-payload exes, while a
+ * single 256 entry takes and Windows downscales it cleanly for smaller views.
+ * Best-effort — warns (doesn't fail the build) if rcedit isn't installed.
+ */
+async function brandWindowsExe(
+  exe: string,
+  opts: {
+    work: string;
+    appName: string;
+    version: string;
+    /** Absolute path to the icon source. */
+    icon?: string;
+    publisher: string;
+  },
+): Promise<void> {
+  if (!Bun.which("rcedit")) {
+    console.warn(
+      "[mirin build] rcedit not found — the Windows exe keeps Bun's default icon. " +
+        "Install it: `scoop install rcedit` (or `choco install rcedit`).",
+    );
+    return;
+  }
+  const args: string[] = [];
+  if (opts.icon) {
+    const ico = makeWindowsIcon(opts.icon, join(opts.work, "exe-icon.ico"), {
+      onlyLargest: true,
+    });
+    if (ico) args.push("--set-icon", ico);
+  }
+  const fv = winFileVersion(opts.version);
+  args.push(
+    "--set-version-string",
+    "ProductName",
+    opts.appName,
+    "--set-version-string",
+    "FileDescription",
+    opts.appName,
+    "--set-version-string",
+    "CompanyName",
+    opts.publisher,
+    "--set-file-version",
+    fv,
+    "--set-product-version",
+    fv,
+  );
+  const res = await $`rcedit ${exe} ${args}`.nothrow();
+  if (res.exitCode !== 0) {
+    console.warn(`[mirin build] rcedit failed (exit ${res.exitCode}) — exe branding skipped.`);
+  }
+}
 
 export interface BuildResult {
   /** Path to the assembled .app. */
@@ -37,20 +122,37 @@ export interface BuildResult {
   channel: string;
   /** Update baseUrl, if `release` is configured. */
   baseUrl?: string;
+  /** Markdown release notes embedded in the updater manifest, if configured. */
+  releaseNotes?: string;
   /** libmirin_core path (for the updater codec at release time). */
   coreDylib: string;
+  /** Standalone updater codec executable used at release time. */
+  codecBin: string;
   /** Project root (so `mirin release` can resolve relative asset paths). */
   projectDir: string;
   /** DMG config from mirin.config.ts (`true`/object/`false`); default `true`. */
   dmg: boolean | import("mirinjs").DmgConfig;
   /** NSIS installer config (Windows) — `true`/object/`false`; default `true`. */
   nsis: boolean | import("mirinjs").NsisConfig;
+  /** Inno Setup installer config (Windows) — preferred over NSIS; default `true`. */
+  inno: boolean | import("mirinjs").InnoConfig;
+  /** Linux packaging config (`mirin.config.ts` `linux`) — `true`/object/`false`; default `true`. */
+  linux: boolean | import("mirinjs").LinuxConfig;
+  /** Publisher / company name (config.publisher ?? appName). */
+  publisher: string;
+  /** Absolute path to the app icon source (config.icon), if set — for Linux packaging. */
+  icon?: string;
   /** Codesign identity used for the bundle, if any (MIRIN_SIGN_IDENTITY). */
   signIdentity?: string;
 }
 
-/** Read the project's package.json version (the single source of app version). */
+/**
+ * The app version: `$MIRIN_APP_VERSION` (release-pipeline override) wins, otherwise
+ * the project's package.json `version` (the single source of truth).
+ */
 function appVersion(projectDir: string): string {
+  const override = process.env.MIRIN_APP_VERSION;
+  if (override) return override;
   const pkgPath = join(projectDir, "package.json");
   if (!existsSync(pkgPath)) return "0.0.0";
   try {
@@ -60,7 +162,19 @@ function appVersion(projectDir: string): string {
   }
 }
 
-export async function build(projectDir = process.cwd()): Promise<BuildResult> {
+export interface BuildOptions {
+  /** Override the app version (else `$MIRIN_APP_VERSION` / package.json). */
+  version?: string;
+  /** On Linux, also emit distributable packages (AppImage/deb/rpm) after assembling. */
+  packageLinux?: boolean;
+  /** Restrict Linux packaging to these formats (else config.linux.formats / all). */
+  linuxFormats?: import("mirinjs").LinuxPackageFormat[];
+}
+
+export async function build(
+  projectDir = process.cwd(),
+  opts: BuildOptions = {},
+): Promise<BuildResult> {
   const outDir = join(projectDir, "build");
   const work = join(projectDir, ".mirin");
   mkdirSync(outDir, { recursive: true });
@@ -71,35 +185,62 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
   const appName: string = config.name ?? "Mirin App";
   const bundleId: string = config.id ?? "dev.mirin.app";
   const mainEntry = join(projectDir, config.main ?? "main/main.ts");
-  const version = appVersion(projectDir);
+  const version = opts.version ?? appVersion(projectDir);
   const channel: string = config.release?.channel ?? "stable";
   const baseUrl: string | undefined = config.release?.baseUrl;
+  const releaseNotes: string | undefined = config.release?.notes;
   const dmg: boolean | import("mirinjs").DmgConfig = config.dmg ?? true;
   const nsis: boolean | import("mirinjs").NsisConfig = config.nsis ?? true;
+  const inno: boolean | import("mirinjs").InnoConfig = config.inno ?? true;
+  const linux: boolean | import("mirinjs").LinuxConfig = config.linux ?? true;
+  const publisher: string = config.publisher ?? appName;
+  const cefLocales = normalizeCefLocales(config.cef?.locales);
+  // `.icon` documents are macOS-only, so the platform picks its own source.
+  const appIconPath = resolveIconSource(config.icon, projectDir);
 
   console.log(`[mirin build] ${appName} ${version}`);
 
-  // 1. production UI
-  console.log("[mirin build] vite build…");
-  await $`bunx vite build`.cwd(projectDir);
-
-  // 2. native artifacts (release)
-  const artifacts = await resolveArtifacts({ release: true });
+  // Production UI and native artifacts do not share outputs, so overlap them.
+  console.log("[mirin build] building UI + native artifacts…");
+  const [, artifacts] = await Promise.all([
+    $`bunx vite build`.cwd(projectDir),
+    resolveArtifacts({ release: true }),
+  ]);
 
-  // 3 + 4. host + worker (minified)
-  console.log("[mirin build] compiling host + bundling main process…");
+  // Host compilation, main Worker bundling, and extra Worker bundling are independent.
+  console.log("[mirin build] compiling host + bundling workers…");
   const signIdentity = process.env.MIRIN_SIGN_IDENTITY;
   const hostExe = join(work, IS_WINDOWS ? "host-release.exe" : "host-release");
   const workerJs = join(work, "worker.release.js");
-  await $`bun build --compile --minify ${artifacts.hostEntry} --outfile ${hostExe}`.cwd(projectDir);
-  await $`bun build ${mainEntry} --target=bun --minify --outfile ${workerJs}`.cwd(projectDir);
-
-  // Extra assets: resolve sidecar binaries + compile any extra worker entries.
   const sidecars = normalizeSidecars(projectDir, config.sidecars);
-  const extraWorkers = await compileWorkers(projectDir, config.workers, join(work, "workers"), true);
+  const hostBuild = (async (): Promise<void> => {
+    // Bun's Windows arm64 build currently has no bun:ffi/TinyCC runtime. The
+    // win32-arm64 Mirin package therefore carries an x64 compatibility payload,
+    // which Windows 11 ARM executes through its built-in x64 emulation layer.
+    const target = IS_WINDOWS && process.arch === "arm64" ? ["--target=bun-windows-x64"] : [];
+    await $`bun build --compile --minify ${target} ${artifacts.hostEntry} --outfile ${hostExe}`.cwd(
+      projectDir,
+    );
+    if (IS_WINDOWS) {
+      patchPeToGuiSubsystem(hostExe);
+      await brandWindowsExe(hostExe, {
+        work,
+        appName,
+        version,
+        icon: appIconPath,
+        publisher,
+      });
+    }
+  })();
+  const workerBuild = $`bun build ${mainEntry} --target=bun --minify --outfile ${workerJs}`.cwd(
+    projectDir,
+  );
+  const extraWorkersBuild = compileWorkers(projectDir, config.workers, join(work, "workers"), true);
+  const [, , extraWorkers] = await Promise.all([hostBuild, workerBuild, extraWorkersBuild]);
 
   // 5. assemble (+ sign on macOS)
-  console.log(`[mirin build] assembling ${IS_WINDOWS ? "app folder" : ".app"}…`);
+  const artifactKind = IS_WINDOWS ? "app folder" : IS_LINUX ? "app folder" : ".app";
+  console.log(`[mirin build] assembling ${artifactKind}…`);
   // version.json embeds the running app's update identity (read by app.updater).
   // Only when `release` is configured — otherwise the app has no updater.
   const versionJson = baseUrl
@@ -108,7 +249,13 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
   const resources = {
     uiDir: join(projectDir, "dist"),
     workerJs,
-    manifestJson: JSON.stringify({ windows: config.windows }),
+    manifestJson: JSON.stringify({
+      id: bundleId,
+      windows: config.windows,
+      singleInstance: config.singleInstance,
+      // Lets a diagnostic build opt in via `devtools.production`; otherwise fully off.
+      devtools: config.devtools,
+    }),
     versionJson,
     workers: extraWorkers,
   };
@@ -120,25 +267,65 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
         coreDll: artifacts.coreDylib,
         helperExe: artifacts.helperBin,
         cefPath: artifacts.cefPath,
-        icon: config.icon ? join(projectDir, config.icon) : undefined,
+        cefLocales,
+        icon: appIconPath,
         resources: { ...resources, sidecars: sidecars.map((s) => ({ name: s.name, src: s.src })) },
       })
-    : await buildAppBundle({
-        appName,
-        bundleId,
-        outDir,
-        hostExe,
-        coreDylib: artifacts.coreDylib,
-        helperBin: artifacts.helperBin,
-        cefPath: artifacts.cefPath,
-        version,
-        icon: config.icon ? join(projectDir, config.icon) : undefined,
-        signIdentity,
-        urlSchemes: config.urlSchemes,
-        resources: { ...resources, sidecars },
-      });
+    : IS_LINUX
+      ? await buildLinuxBundle({
+          appName,
+          outDir,
+          hostExe,
+          coreDll: artifacts.coreDylib,
+          helperExe: artifacts.helperBin,
+          cefPath: artifacts.cefPath,
+          cefLocales,
+          icon: appIconPath,
+          resources: {
+            ...resources,
+            sidecars: sidecars.map((s) => ({ name: s.name, src: s.src })),
+          },
+        })
+      : await buildAppBundle({
+          appName,
+          bundleId,
+          outDir,
+          hostExe,
+          coreDylib: artifacts.coreDylib,
+          helperBin: artifacts.helperBin,
+          cefPath: artifacts.cefPath,
+          cefLocales,
+          version,
+          icon: appIconPath,
+          signIdentity,
+          urlSchemes: config.urlSchemes,
+          resources: { ...resources, sidecars },
+        });
 
   console.log(`\n[mirin build] done → ${app}`);
+
+  // Linux: optionally emit distributable packages (AppImage/deb/rpm) straight from
+  // `mirin build`. `mirin release` does its own packaging into build/release, so it
+  // never sets `packageLinux` — this path only runs for a direct build request.
+  if (IS_LINUX && opts.packageLinux && linux !== false) {
+    const formats = resolveLinuxFormats(linux, opts.linuxFormats);
+    console.log(`[mirin build] packaging Linux artifacts (${formats.join(", ")})…`);
+    const pkgs = await buildLinuxPackages({
+      appDir: app,
+      appName,
+      bundleId,
+      version,
+      publisher,
+      outDir,
+      projectDir,
+      icon: appIconPath,
+      options: typeof linux === "object" ? linux : {},
+      formats,
+    });
+    const mb = (n: number) => (n / 1e6).toFixed(1);
+    for (const p of pkgs) console.log(`  ${p.path} (${mb(p.size)} MB)`);
+  }
+
   return {
     app,
     appName,
@@ -146,10 +333,16 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
     version,
     channel,
     baseUrl,
+    releaseNotes,
     coreDylib: artifacts.coreDylib,
+    codecBin: artifacts.codecBin,
     projectDir,
     dmg,
     nsis,
+    inno,
+    linux,
+    publisher,
+    icon: appIconPath,
     signIdentity,
   };
 }

package/src/bundle/linux/app.ts

@@ -0,0 +1,275 @@
+/**
+ * Assemble a Linux app folder for a mirin app. Like Windows, Linux has no `.app`
+ * bundle — just a flat directory the dynamic loader can resolve libcef.so + the
+ * CEF runtime from, next to the host binary:
+ *
+ *   <App>/
+ *     <App>                    compiled Bun host (process.execPath)
+ *     libmirin_core.so         loaded by the host via bun:ffi
+ *     mirin-helper             CEF subprocess (browser_subprocess_path)
+ *     libcef.so, libEGL.so, libGLESv2.so, *.pak, icudtl.dat,
+ *     v8_context_snapshot.bin, locales/, chrome-sandbox, …  (CEF runtime)
+ *     resources/               (production only — dev serves from the Vite URL)
+ *       ui/, worker.js, mirin.manifest.json, version.json, sidecars/, workers/
+ *
+ * Wayland-only (docs/linux-port.md); the CEF subprocess name (`mirin-helper`) and
+ * the `resources/` layout match what mirin-core derives at runtime
+ * (engine::derive_subprocess_path, host.ts). libcef.so is resolved via
+ * LD_LIBRARY_PATH set on the host (dev.ts) or an rpath at build time.
+ */
+
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, extname, join } from "node:path";
+import { copyFlatCefLocales } from "../shared/cef-locales.ts";
+
+/** Source dir (vendor/cef on Linux) must contain libcef.so. */
+const CEF_MARKER = "libcef.so";
+
+/** CEF runtime files copied next to the host binary. Everything else in the Linux
+ *  distribution (include/, cmake/, CMakeLists.txt, archive.json, libcef_dll/) is
+ *  build-time only and intentionally left out. `.so` covers libcef/libEGL/
+ *  libGLESv2/libvk_swiftshader; the extras list catches the non-extension names. */
+const CEF_RUNTIME_EXTS = new Set([".so", ".bin", ".pak", ".dat"]);
+const CEF_RUNTIME_EXTRAS = ["vk_swiftshader_icd.json", "libvulkan.so.1", "chrome-sandbox"];
+
+export interface LinuxBundleOptions {
+  appName: string; // also the host binary stem → <appName>
+  outDir: string;
+  hostExe: string; // compiled Bun host (no extension)
+  coreDll: string; // libmirin_core.so
+  helperExe: string; // mirin-helper
+  cefPath: string; // dir containing the Linux CEF runtime (vendor/cef)
+  /** Production CEF locale allowlist. Undefined keeps every locale. */
+  cefLocales?: string[];
+  /** App icon source (.png / .iconset); resolved to a PNG at resources/icon.png for
+   *  the window's `_NET_WM_ICON` (taskbar/dock). */
+  icon?: string;
+  /** Production-only resources placed under <App>/resources. */
+  resources?: {
+    uiDir?: string; // Vite dist/ → resources/ui (served via app://ui)
+    workerJs?: string; // bundled main-process Worker → resources/worker.js
+    manifestJson?: string; // serialized manifest → resources/mirin.manifest.json
+    versionJson?: string; // serialized version.json → resources/version.json (updater)
+    sidecars?: { name: string; src: string }[]; // → resources/sidecars/<name>
+    workers?: Record<string, string>; // name → abs path → resources/workers/<name>.js
+  };
+}
+
+/**
+ * Resolve the app config's `icon` to a concrete square PNG usable on Linux (for
+ * the window's `_NET_WM_ICON`). Accepts a `.png` (used as-is) or a `.iconset`
+ * directory (pick a good mid/large size). Returns undefined for `.icns` (which the
+ * Linux core can't decode) or a missing/empty source.
+ *
+ * @param icon absolute path to the icon source (`config.icon` joined with the project root).
+ */
+export function resolveLinuxIconPng(icon: string): string | undefined {
+  if (!existsSync(icon)) return undefined;
+  if (statSync(icon).isDirectory()) {
+    const pngs = readdirSync(icon).filter((f) => extname(f).toLowerCase() === ".png");
+    if (!pngs.length) return undefined;
+    // Prefer 128×128: crisp in the dock, and small enough that its `_NET_WM_ICON`
+    // (a 128²+2 CARDINAL array ≈ 64 KB) stays under X11's ~256 KB max request size —
+    // a 256×256 icon (≈ 256 KB) can exceed it and get dropped. Fall back to the
+    // largest available under that ceiling (by pixels parsed from the iconset name).
+    const preferred = ["icon_128x128.png", "icon_64x64.png", "icon_256x256.png"];
+    const MaxSide = 128;
+    const pick =
+      preferred.find((p) => pngs.includes(p)) ??
+      pngs
+        .slice()
+        .sort((a, b) => iconsetPixels(b) - iconsetPixels(a))
+        .find((p) => iconsetPixels(p) <= MaxSide * MaxSide) ??
+      pngs.sort((a, b) => iconsetPixels(a) - iconsetPixels(b))[0];
+    return pick ? join(icon, pick) : undefined;
+  }
+  return extname(icon).toLowerCase() === ".png" ? icon : undefined;
+}
+
+/**
+ * Resolve the app config's `icon` to the *largest* concrete PNG (for a `.desktop`
+ * `Icon=`, which is a file path with no X11 request-size limit — so we want it
+ * crisp, unlike the window `_NET_WM_ICON`). `.png` used as-is; `.iconset` → biggest
+ * PNG inside. Undefined for `.icns` or a missing source.
+ */
+export function resolveLinuxDesktopIconPng(icon: string): string | undefined {
+  if (!existsSync(icon)) return undefined;
+  if (statSync(icon).isDirectory()) {
+    const pngs = readdirSync(icon).filter((f) => extname(f).toLowerCase() === ".png");
+    if (!pngs.length) return undefined;
+    const biggest = pngs.sort((a, b) => iconsetPixels(b) - iconsetPixels(a))[0];
+    return biggest ? join(icon, biggest) : undefined;
+  }
+  return extname(icon).toLowerCase() === ".png" ? icon : undefined;
+}
+
+/**
+ * A freedesktop `.desktop` entry body for a mirin app. cosmic's dock resolves an
+ * X11 window's icon by matching its `WM_CLASS` (which the core sets to the app id)
+ * against a desktop entry's `StartupWMClass`, then uses that entry's `Icon` — the
+ * reliable path on cosmic (its `_NET_WM_ICON` fallback is unreliable). `wmClass`
+ * MUST equal the core's `res_class` (the bundle id).
+ */
+export function desktopEntry(opts: {
+  name: string;
+  exec: string;
+  iconPng: string;
+  wmClass: string;
+  /** Freedesktop main category (e.g. "Utility", "Development"). A trailing `;` is
+   *  added if missing (the spec requires list values to end with one). Omitted → no
+   *  Categories line. Used by the .deb/.rpm/AppImage entries (dev needs none). */
+  categories?: string;
+  /** Optional Comment= (tooltip / description) line. */
+  comment?: string;
+}): string {
+  const lines = ["[Desktop Entry]", "Type=Application", `Name=${desktopValue("Name", opts.name)}`];
+  if (opts.comment) lines.push(`Comment=${desktopValue("Comment", opts.comment)}`);
+  lines.push(
+    `Exec=${desktopExec(opts.exec)}`,
+    `Icon=${desktopValue("Icon", opts.iconPng)}`,
+    `StartupWMClass=${desktopValue("StartupWMClass", opts.wmClass)}`,
+    "Terminal=false",
+  );
+  if (opts.categories) {
+    lines.push(`Categories=${desktopCategories(opts.categories)}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function desktopValue(field: string, value: string): string {
+  assertDesktopScalar(field, value);
+  return value.replace(/\\/g, "\\\\").replace(/\t/g, "\\t");
+}
+
+function desktopExec(value: string): string {
+  assertDesktopScalar("Exec", value);
+  if (/^[A-Za-z0-9._/+:-]+$/.test(value)) return value;
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function desktopCategories(value: string): string {
+  const normalized = value.endsWith(";") ? value : `${value};`;
+  assertDesktopScalar("Categories", normalized);
+  if (!/^[A-Za-z0-9][A-Za-z0-9-]*(;[A-Za-z0-9][A-Za-z0-9-]*)*;$/.test(normalized)) {
+    throw new Error(
+      `[mirin] invalid Linux desktop category "${value}" — use freedesktop category names separated by semicolons.`,
+    );
+  }
+  return normalized;
+}
+
+function assertDesktopScalar(field: string, value: string): void {
+  if (value.length === 0 || /[\0\r\n]/.test(value)) {
+    throw new Error(`[mirin] invalid Linux desktop ${field} value.`);
+  }
+}
+
+/** Effective pixel count encoded in an iconset filename (`icon_256x256@2x.png` → 512²). */
+function iconsetPixels(name: string): number {
+  const m = basename(name).match(/(\d+)x(\d+)(@(\d+)x)?/);
+  if (!m) return 0;
+  const scale = m[4] ? Number(m[4]) : 1;
+  return Number(m[1]) * Number(m[2]) * scale * scale;
+}
+
+/** Build the Linux app folder and return its path + the host binary to launch. */
+export async function buildLinuxBundle(
+  opts: LinuxBundleOptions,
+): Promise<{ app: string; exe: string }> {
+  const { appName, cefPath } = opts;
+  if (!existsSync(join(cefPath, CEF_MARKER))) {
+    throw new Error(`CEF runtime not found at ${cefPath} — run: bun scripts/fetch-cef.ts`);
+  }
+
+  const app = join(opts.outDir, appName);
+  rmSync(app, { recursive: true, force: true });
+  mkdirSync(app, { recursive: true });
+
+  const exe = join(app, appName);
+  cpSync(opts.hostExe, exe);
+  chmodSync(exe, 0o755);
+  cpSync(opts.coreDll, join(app, "libmirin_core.so"));
+  const helper = join(app, "mirin-helper");
+  cpSync(opts.helperExe, helper);
+  chmodSync(helper, 0o755);
+
+  copyCefRuntime(cefPath, app, opts.cefLocales);
+
+  // The window taskbar/dock icon (`_NET_WM_ICON`) is set by the core from a PNG at
+  // `resources/icon.png`; host.ts points the init config's `icon_path` there in prod.
+  // (Dev serves it directly from the project via MIRIN_CONFIG_JSON, not the bundle.)
+  const iconPng = opts.icon ? resolveLinuxIconPng(opts.icon) : undefined;
+  if (iconPng) {
+    const res = join(app, "resources");
+    mkdirSync(res, { recursive: true });
+    cpSync(iconPng, join(res, "icon.png"));
+  }
+
+  // Production resources (dev passes none — paths come from env + the Vite URL).
+  if (opts.resources) {
+    const res = join(app, "resources");
+    mkdirSync(res, { recursive: true });
+    if (opts.resources.uiDir) cpSync(opts.resources.uiDir, join(res, "ui"), { recursive: true });
+    if (opts.resources.workerJs) cpSync(opts.resources.workerJs, join(res, "worker.js"));
+    if (opts.resources.manifestJson != null) {
+      writeFileSync(join(res, "mirin.manifest.json"), opts.resources.manifestJson);
+    }
+    if (opts.resources.versionJson != null) {
+      writeFileSync(join(res, "version.json"), opts.resources.versionJson);
+    }
+    if (opts.resources.workers && Object.keys(opts.resources.workers).length) {
+      const workersDir = join(res, "workers");
+      mkdirSync(workersDir, { recursive: true });
+      for (const [name, src] of Object.entries(opts.resources.workers)) {
+        cpSync(src, join(workersDir, `${name}.js`));
+      }
+    }
+    if (opts.resources.sidecars?.length) {
+      const sidecarsDir = join(res, "sidecars");
+      mkdirSync(sidecarsDir, { recursive: true });
+      for (const sc of opts.resources.sidecars) {
+        if (!existsSync(sc.src)) throw new Error(`sidecar "${sc.name}" not found: ${sc.src}`);
+        const dst = join(sidecarsDir, sc.name);
+        cpSync(sc.src, dst);
+        chmodSync(dst, 0o755);
+      }
+    }
+  }
+
+  return { app, exe };
+}
+
+/** Copy the CEF runtime (shared libs, paks, snapshot, icu data, locales) into `dest`. */
+function copyCefRuntime(cefPath: string, dest: string, locales: string[] | undefined): void {
+  for (const entry of readdirSync(cefPath)) {
+    if (CEF_RUNTIME_EXTS.has(extname(entry).toLowerCase())) {
+      cpSync(join(cefPath, entry), join(dest, entry));
+    }
+  }
+  for (const extra of CEF_RUNTIME_EXTRAS) {
+    const src = join(cefPath, extra);
+    if (existsSync(src)) cpSync(src, join(dest, extra), { recursive: true });
+  }
+  copyFlatCefLocales(join(cefPath, "locales"), join(dest, "locales"), locales);
+  // chrome-sandbox works setuid-root (mode 4755) or, on kernels with unprivileged
+  // user namespaces, via the namespace sandbox with no special perms. We can't
+  // setuid without root here; leave it executable and let CEF pick the userns path.
+  const sandbox = join(dest, "chrome-sandbox");
+  if (existsSync(sandbox)) {
+    try {
+      require("node:fs").chmodSync(sandbox, 0o755);
+    } catch {
+      /* best-effort */
+    }
+  }
+}

package/src/bundle/linux/index.ts

@@ -0,0 +1 @@
+export * from "./app.ts";