@mirinjs/cli 0.1.0-alpha.10 → 0.1.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirinjs/cli",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.11",
   "description": "CLI for mirin apps: dev, build, init.",
   "type": "module",
   "license": "MIT",
@@ -27,12 +27,12 @@
     "bun": ">=1.2.0"
   },
   "dependencies": {
-    "create-mirinjs": "0.1.0-alpha.10",
-    "mirinjs": "0.1.0-alpha.10"
+    "create-mirinjs": "0.1.0-alpha.11",
+    "mirinjs": "0.1.0-alpha.11"
   },
   "optionalDependencies": {
-    "@mirinjs/darwin-arm64": "0.1.0-alpha.10",
-    "@mirinjs/win32-x64": "0.1.0-alpha.10"
+    "@mirinjs/darwin-arm64": "0.1.0-alpha.11",
+    "@mirinjs/win32-x64": "0.1.0-alpha.11"
   },
   "publishConfig": {
     "access": "public"

package/src/artifacts.ts

@@ -67,7 +67,9 @@ export async function resolveArtifacts(opts: { release: boolean }): Promise<Arti
 
 /** The native core library file name for the host platform (MSVC has no `lib` prefix). */
 function coreFileName(): string {
-  return process.platform === "win32" ? "mirin_core.dll" : "libmirin_core.dylib";
+  if (process.platform === "win32") return "mirin_core.dll";
+  if (process.platform === "linux") return "libmirin_core.so";
+  return "libmirin_core.dylib";
 }
 
 /** The CEF subprocess binary name for the host platform. */
@@ -78,10 +80,12 @@ function helperFileName(): string {
 function assertSupportedPlatform(): void {
   const supported =
     (process.platform === "darwin" && process.arch === "arm64") ||
-    (process.platform === "win32" && process.arch === "x64");
+    (process.platform === "win32" && process.arch === "x64") ||
+    (process.platform === "linux" && process.arch === "x64");
   if (!supported) {
     throw new Error(
-      `mirin alpha supports macOS arm64 and Windows x64 (got ${process.platform}/${process.arch}).`,
+      `mirin alpha supports macOS arm64, Windows x64, and Linux x64 ` +
+        `(got ${process.platform}/${process.arch}).`,
     );
   }
 }
@@ -113,9 +117,12 @@ function cliVersion(): string {
 }
 
 /** A file/dir that, if present in a CEF dir, means the distribution is unpacked.
- *  macOS ships the framework bundle; Windows ships a flat dir with libcef.dll. */
+ *  macOS ships the framework bundle; Windows ships a flat dir with libcef.dll;
+ *  Linux ships a flat dir with libcef.so. */
 function cefMarker(): string {
-  return process.platform === "win32" ? "libcef.dll" : "Chromium Embedded Framework.framework";
+  if (process.platform === "win32") return "libcef.dll";
+  if (process.platform === "linux") return "libcef.so";
+  return "Chromium Embedded Framework.framework";
 }
 
 async function ensureCef(): Promise<string> {

package/src/build.ts

@@ -20,12 +20,15 @@ import { mkdirSync, rmSync, readFileSync, writeFileSync, existsSync } from "node
 import { join } from "node:path";
 import { buildAppBundle } from "./bundle.ts";
 import { buildWindowsBundle } from "./bundle-win.ts";
+import { buildLinuxBundle } from "./bundle-linux.ts";
+import { buildLinuxPackages, resolveLinuxFormats } from "./package-linux.ts";
 import { makeWindowsIcon } from "./icon-win.ts";
 import { resolveArtifacts } from "./artifacts.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 {
@@ -121,14 +124,23 @@ export interface BuildResult {
   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 {
@@ -138,7 +150,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 });
@@ -149,12 +173,13 @@ 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 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;
 
   console.log(`[mirin build] ${appName} ${version}`);
@@ -190,7 +215,8 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
   const extraWorkers = await compileWorkers(projectDir, config.workers, join(work, "workers"), true);
 
   // 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
@@ -218,6 +244,17 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
         icon: config.icon ? join(projectDir, config.icon) : undefined,
         resources: { ...resources, sidecars: sidecars.map((s) => ({ name: s.name, src: s.src })) },
       })
+    : IS_LINUX
+    ? await buildLinuxBundle({
+        appName,
+        outDir,
+        hostExe,
+        coreDll: artifacts.coreDylib,
+        helperExe: artifacts.helperBin,
+        cefPath: artifacts.cefPath,
+        icon: config.icon ? join(projectDir, config.icon) : undefined,
+        resources: { ...resources, sidecars: sidecars.map((s) => ({ name: s.name, src: s.src })) },
+      })
     : await buildAppBundle({
         appName,
         bundleId,
@@ -234,6 +271,29 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
       });
 
   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: config.icon ? join(projectDir, config.icon) : undefined,
+      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,
@@ -246,7 +306,9 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
     dmg,
     nsis,
     inno,
+    linux,
     publisher,
+    icon: config.icon ? join(projectDir, config.icon) : undefined,
     signIdentity,
   };
 }

package/src/bundle-linux.ts

@@ -0,0 +1,234 @@
+/**
+ * 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 { cpSync, mkdirSync, rmSync, writeFileSync, existsSync, readdirSync, chmodSync, statSync } from "node:fs";
+import { join, extname, basename } from "node:path";
+
+/** 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 = ["locales", "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)
+  /** 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 MAX_SIDE = 128;
+    const pick =
+      preferred.find((p) => pngs.includes(p)) ??
+      pngs
+        .slice()
+        .sort((a, b) => iconsetPixels(b) - iconsetPixels(a))
+        .find((p) => iconsetPixels(p) <= MAX_SIDE * MAX_SIDE) ??
+      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=${opts.name}`];
+  if (opts.comment) lines.push(`Comment=${opts.comment}`);
+  lines.push(
+    `Exec=${opts.exec}`,
+    `Icon=${opts.iconPng}`,
+    `StartupWMClass=${opts.wmClass}`,
+    "Terminal=false",
+  );
+  if (opts.categories) {
+    lines.push(`Categories=${opts.categories.endsWith(";") ? opts.categories : `${opts.categories};`}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** 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);
+
+  // 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): 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 });
+  }
+  // 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/dev.ts

@@ -9,14 +9,22 @@
  */
 
 import { $ } from "bun";
-import { mkdirSync, rmSync, symlinkSync, existsSync } from "node:fs";
+import { mkdirSync, rmSync, symlinkSync, existsSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { join } from "node:path";
 import { buildAppBundle } from "./bundle.ts";
 import { buildWindowsBundle } from "./bundle-win.ts";
+import {
+  buildLinuxBundle,
+  resolveLinuxIconPng,
+  resolveLinuxDesktopIconPng,
+  desktopEntry,
+} from "./bundle-linux.ts";
+import { homedir } from "node:os";
 import { resolveArtifacts } from "./artifacts.ts";
 
 const IS_WINDOWS = process.platform === "win32";
+const IS_LINUX = process.platform === "linux";
 import { sweepBuildTemps } from "./temps.ts";
 import { normalizeSidecars, compileWorkers } from "./extras.ts";
 
@@ -36,6 +44,11 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
   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 iconSrc = config.icon ? join(projectDir, config.icon) : undefined;
+  // Linux: resolve the app icon to a concrete PNG the core stamps onto the window
+  // as `_NET_WM_ICON` (cosmic dock/taskbar). Passed straight through in dev — no
+  // bundling; the file is read from the project at window-create time.
+  const linuxIconPng = IS_LINUX && iconSrc ? resolveLinuxIconPng(iconSrc) : undefined;
 
   // --- native artifacts ---
   const artifacts = await resolveArtifacts({ release: false });
@@ -61,7 +74,7 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
     else console.warn(`[mirin dev] sidecar "${sc.name}" not found: ${sc.src}`);
   }
 
-  // --- assemble the dev bundle (Windows app folder, or macOS .app) ---
+  // --- assemble the dev bundle (Windows/Linux app folder, or macOS .app) ---
   console.log("[mirin dev] assembling dev bundle…");
   const { app, exe } = IS_WINDOWS
     ? await buildWindowsBundle({
@@ -71,7 +84,17 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
         coreDll: artifacts.coreDylib,
         helperExe: artifacts.helperBin,
         cefPath: artifacts.cefPath,
-        icon: config.icon ? join(projectDir, config.icon) : undefined,
+        icon: iconSrc,
+      })
+    : IS_LINUX
+    ? await buildLinuxBundle({
+        appName,
+        outDir: work,
+        hostExe,
+        coreDll: artifacts.coreDylib,
+        helperExe: artifacts.helperBin,
+        cefPath: artifacts.cefPath,
+        icon: iconSrc,
       })
     : await buildAppBundle({
         appName,
@@ -81,19 +104,41 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
         coreDylib: artifacts.coreDylib,
         helperBin: artifacts.helperBin,
         cefPath: artifacts.cefPath,
-        icon: config.icon ? join(projectDir, config.icon) : undefined,
+        icon: iconSrc,
         urlSchemes: config.urlSchemes,
       });
 
+  // Linux: install a dev `.desktop` entry so cosmic's dock can resolve the app's
+  // icon. cosmic matches a running X11 window's `WM_CLASS` (which the core sets to
+  // the bundle id) against `StartupWMClass`, then shows that entry's `Icon`. Written
+  // to the per-user applications dir; harmless on other DEs.
+  if (IS_LINUX && iconSrc) {
+    const desktopIcon = resolveLinuxDesktopIconPng(iconSrc);
+    if (desktopIcon) {
+      const appsDir = join(homedir(), ".local", "share", "applications");
+      mkdirSync(appsDir, { recursive: true });
+      writeFileSync(
+        join(appsDir, `${bundleId}.desktop`),
+        desktopEntry({ name: appName, exec: exe, iconPng: desktopIcon, wmClass: bundleId }),
+      );
+    }
+  }
+
   // --- start Vite on a free port so concurrent dev sessions don't collide ---
   // `--port <free> --strictPort` pins Vite to the port we probed (overriding any
   // port/strictPort in the app's vite.config) and passes the real URL to the app,
   // so the host and Vite never disagree about which port is in use.
+  //
+  // Bind + address on 127.0.0.1 (IPv4), NOT "localhost": on hosts where Vite binds
+  // IPv6-only (`[::1]`) while Chromium resolves `localhost` to IPv4 (common on
+  // Linux), the webview's page load is refused and the window stays blank. Pinning
+  // both sides to 127.0.0.1 avoids the family mismatch (and matches the loopback
+  // RPC server). `--host 127.0.0.1` forces Vite's bind.
   const port = await findFreePort(DEV_PORT_BASE);
-  const devUrl = `http://localhost:${port}`;
+  const devUrl = `http://127.0.0.1:${port}`;
   console.log(`[mirin dev] starting Vite dev server on ${devUrl}…`);
   const vite = Bun.spawn(
-    ["bunx", "vite", "--clearScreen", "false", "--port", String(port), "--strictPort"],
+    ["bunx", "vite", "--clearScreen", "false", "--host", "127.0.0.1", "--port", String(port), "--strictPort"],
     {
       cwd: projectDir,
       stdio: ["ignore", "inherit", "inherit"],
@@ -109,13 +154,24 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
       ...process.env,
       MIRIN_CORE: IS_WINDOWS
         ? join(app, "mirin_core.dll")
+        : IS_LINUX
+        ? join(app, "libmirin_core.so")
         : join(app, "Contents", "MacOS", "libmirin_core.dylib"),
+      // Linux: the flat app dir holds libcef.so + libmirin_core.so; put it on the
+      // loader path so the host's dlopen and libmirin_core's NEEDED libcef.so (and
+      // the spawned mirin-helper) all resolve. (macOS uses the framework loader;
+      // Windows the exe-dir search — neither needs this.)
+      ...(IS_LINUX ? { LD_LIBRARY_PATH: `${app}${process.env.LD_LIBRARY_PATH ? ":" + process.env.LD_LIBRARY_PATH : ""}` } : {}),
       MIRIN_WORKER: workerJs,
       MIRIN_DEV_URL: devUrl,
       MIRIN_MANIFEST_JSON: JSON.stringify({ id: bundleId, windows: config.windows }),
       // dev: true → enables inspect-element AND gives this run its own `-dev`
       // CEF cache dir, so `mirin dev` can run alongside the installed app.
-      MIRIN_CONFIG_JSON: JSON.stringify({ dev: true }),
+      // `icon_path` (Linux) → the window's `_NET_WM_ICON` (cosmic dock/taskbar).
+      MIRIN_CONFIG_JSON: JSON.stringify({
+        dev: true,
+        ...(linuxIconPng ? { icon_path: linuxIconPng } : {}),
+      }),
       MIRIN_SIDECAR_DIR: sidecarsDir,
       MIRIN_WORKERS_DIR: workersDir,
     },

package/src/index.ts

@@ -8,16 +8,53 @@ import { dev } from "./dev.ts";
 import { build } from "./build.ts";
 import { release } from "./release.ts";
 import { scaffold } from "create-mirinjs";
+import type { LinuxPackageFormat } from "mirinjs";
 
-const [command, arg] = Bun.argv.slice(2);
+/** Minimal flag parser: `--k=v`, `--k v`, and boolean `--k`; the rest are positionals. */
+function parseArgs(argv: string[]): { positionals: string[]; opts: Record<string, string | boolean> } {
+  const opts: Record<string, string | boolean> = {};
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === undefined) continue;
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) {
+        opts[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+          opts[key] = next;
+          i++;
+        } else {
+          opts[key] = true;
+        }
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { positionals, opts };
+}
+
+const [command, ...rest] = Bun.argv.slice(2);
+const { positionals, opts } = parseArgs(rest);
+const arg = positionals[0];
 
 const USAGE = `mirin — build desktop apps with Bun + Chromium
 
 Usage:
   mirin dev          run the app against the Vite dev server (HMR + typed RPC)
-  mirin build        package a standalone, signed .app (output: ./build)
+  mirin build        package a standalone app (output: ./build)
   mirin release      build + emit update artifacts (output: ./build/release)
   mirin init [dir]   scaffold a new app
+
+Options (build):
+  --version <v>              override the app version (else package.json)
+  --linux                    also emit Linux packages (AppImage + .deb + .rpm)
+  --linux-target <a,b,…>     restrict Linux packaging to these formats
+                             (appimage,deb,rpm) — implies --linux
 `;
 
 switch (command) {
@@ -26,7 +63,13 @@ switch (command) {
     break;
   }
   case "build": {
-    await build();
+    const version = typeof opts.version === "string" ? opts.version : undefined;
+    const target = typeof opts["linux-target"] === "string" ? opts["linux-target"] : undefined;
+    const linuxFormats = target
+      ? (target.split(",").map((s) => s.trim()).filter(Boolean) as LinuxPackageFormat[])
+      : undefined;
+    const packageLinux = opts.linux === true || linuxFormats != null;
+    await build(process.cwd(), { version, packageLinux, linuxFormats });
     process.exit(0);
     break;
   }

package/src/package-linux.ts

@@ -0,0 +1,334 @@
+/**
+ * Linux distributable packages for a mirin app — **AppImage**, **.deb**, **.rpm** —
+ * built from the assembled Linux app folder (buildLinuxBundle's output). This is the
+ * Linux analog of dmg.ts (macOS) and installer-inno.ts / installer-win.ts (Windows):
+ * `mirin build` (with packaging requested) and `mirin release` call it after the app
+ * folder is assembled.
+ *
+ * The app folder is a flat, relocatable payload — the host binary, libcef.so + the
+ * CEF runtime, and `resources/`, all resolved at runtime from an `$ORIGIN` rpath and
+ * `dirname(process.execPath)` (host.ts). Every package therefore ships the whole
+ * folder verbatim under one prefix and points a launcher at the *real* host binary
+ * inside it (never a bare PATH name — the host derives everything from its own dir):
+ *
+ *   - deb / rpm: payload → `/opt/<id>/`, a `/usr/bin/<bin>` wrapper `exec`s
+ *     `/opt/<id>/<App>`, plus `/usr/share/applications/<id>.desktop` and a
+ *     `/usr/share/icons/hicolor/256x256/apps/<id>.png`.
+ *   - AppImage: payload → `AppDir/usr/lib/<id>/`, top-level `AppRun` `exec`s it,
+ *     `<id>.desktop` + `<id>.png` (+ `.DirIcon`) at the AppDir root, packed by
+ *     appimagetool.
+ *
+ * Tooling (resolved via $MIRIN_FPM / $MIRIN_APPIMAGETOOL, then PATH, then a
+ * conventional fallback — see resolveTool):
+ *   - **fpm** builds both deb and rpm in pure Ruby (no dpkg/rpmbuild on the host).
+ *   - **appimagetool** packs the AppImage (invoked with `--appimage-extract-and-run`
+ *     so it works on hosts without FUSE).
+ */
+
+import { $ } from "bun";
+import {
+  cpSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  chmodSync,
+  existsSync,
+  symlinkSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { desktopEntry, resolveLinuxDesktopIconPng } from "./bundle-linux.ts";
+import type { LinuxConfig, LinuxPackageFormat } from "mirinjs";
+
+export interface LinuxPackageInput {
+  /** The assembled Linux app folder (build/<App>): the whole relocatable payload. */
+  appDir: string;
+  /** App display name; also the host-binary stem inside `appDir`. */
+  appName: string;
+  /** Reverse-DNS app id, e.g. "dev.netko.anko" (install prefix + `.desktop`/icon name). */
+  bundleId: string;
+  version: string;
+  /** Publisher / company (deb/rpm vendor + maintainer fallback). */
+  publisher: string;
+  /** Directory the artifacts are written into. */
+  outDir: string;
+  projectDir: string;
+  /** Abs path to the app icon source (`.png` / `.iconset`); resolved to a PNG. */
+  icon?: string;
+  /** Resolved Linux config (maintainer, depends, category, …). */
+  options: LinuxConfig;
+  /** Which formats to build. */
+  formats: LinuxPackageFormat[];
+}
+
+export interface LinuxPackageResult {
+  format: LinuxPackageFormat;
+  path: string;
+  size: number;
+}
+
+/** CEF/GTK runtime deps on Debian/Ubuntu package naming (best-effort; overridable). */
+const DEFAULT_DEB_DEPENDS = [
+  "libgtk-3-0", "libnss3", "libnspr4", "libasound2", "libx11-6", "libxcomposite1",
+  "libxdamage1", "libxext6", "libxfixes3", "libxrandr2", "libgbm1", "libxkbcommon0",
+  "libpango-1.0-0", "libcairo2", "libatk1.0-0", "libatk-bridge2.0-0", "libcups2",
+  "libdrm2", "libdbus-1-3",
+];
+
+/** CEF/GTK runtime deps on RPM (Fedora/RHEL/openSUSE) package naming. */
+const DEFAULT_RPM_DEPENDS = [
+  "gtk3", "nss", "nspr", "alsa-lib", "libX11", "libXcomposite", "libXdamage",
+  "libXext", "libXfixes", "libXrandr", "mesa-libgbm", "libxkbcommon", "pango",
+  "cairo", "atk", "at-spi2-atk", "cups-libs", "libdrm", "dbus-libs",
+];
+
+/**
+ * Resolve an external tool path: an explicit `$ENV` override (if it exists), then
+ * PATH, then the first existing `fallback`. Throws a clear, actionable error when
+ * none resolve (no user-specific absolute path is baked into committed code).
+ */
+function resolveTool(bin: string, envVar: string, fallbacks: string[]): string {
+  const fromEnv = process.env[envVar];
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+  const onPath = Bun.which(bin);
+  if (onPath) return onPath;
+  for (const f of fallbacks) if (existsSync(f)) return f;
+  throw new Error(
+    `[mirin] "${bin}" not found — install it and put it on PATH, or set $${envVar} ` +
+      `to its absolute path.`,
+  );
+}
+
+/** `~/.local/share/gem/ruby/<ver>/bin` (RubyGems user install dir), if resolvable. */
+function gemUserBin(): string | undefined {
+  const ruby = Bun.which("ruby");
+  if (!ruby) return undefined;
+  try {
+    const dir = Bun.spawnSync([ruby, "-e", "print Gem.user_dir"]).stdout.toString().trim();
+    return dir ? join(dir, "bin") : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveFpm(): string {
+  const fallbacks: string[] = [];
+  const gemBin = gemUserBin();
+  if (gemBin) fallbacks.push(join(gemBin, "fpm"));
+  return resolveTool("fpm", "MIRIN_FPM", fallbacks);
+}
+
+function resolveAppimagetool(): string {
+  return resolveTool("appimagetool", "MIRIN_APPIMAGETOOL", [
+    join(homedir(), ".local", "bin", "appimagetool"),
+  ]);
+}
+
+/** A Debian/RPM-friendly package name: lowercase, alnum + `.-+`, no leading sigil. */
+function shortName(input: string): string {
+  return (
+    input.toLowerCase().replace(/[^a-z0-9.\-+]/g, "-").replace(/^[.\-+]+/, "") || "app"
+  );
+}
+
+const size = (p: string) => statSync(p).size;
+
+/** Build every requested Linux package; returns each artifact's path + size. */
+export async function buildLinuxPackages(
+  input: LinuxPackageInput,
+): Promise<LinuxPackageResult[]> {
+  mkdirSync(input.outDir, { recursive: true });
+  const binName = input.options.binName ?? shortName(input.bundleId.split(".").pop() ?? input.appName);
+  const results: LinuxPackageResult[] = [];
+
+  // deb + rpm share one staged filesystem tree (payload under /opt, launcher,
+  // .desktop, icon). Build it once and reuse.
+  const needFsTree = input.formats.includes("deb") || input.formats.includes("rpm");
+  let fsRoot: string | undefined;
+  try {
+    if (needFsTree) fsRoot = stageFsTree(input, binName);
+    if (input.formats.includes("deb")) results.push(await buildFpm(input, binName, fsRoot!, "deb"));
+    if (input.formats.includes("rpm")) results.push(await buildFpm(input, binName, fsRoot!, "rpm"));
+    if (input.formats.includes("appimage")) results.push(await buildAppImage(input, binName));
+  } finally {
+    if (fsRoot) rmSync(fsRoot, { recursive: true, force: true });
+  }
+  return results;
+}
+
+/**
+ * Stage the on-disk filesystem layout deb/rpm install: the whole payload under
+ * `/opt/<id>/`, a `/usr/bin/<bin>` wrapper `exec`ing the real host binary, the
+ * `.desktop` entry, and a hicolor icon. Returns the staging root (fpm's `-C` chdir).
+ */
+function stageFsTree(input: LinuxPackageInput, binName: string): string {
+  const root = join(input.outDir, `.pkgroot-${process.pid}`);
+  rmSync(root, { recursive: true, force: true });
+
+  // Payload → /opt/<id>/…
+  const prefix = join(root, "opt", input.bundleId);
+  mkdirSync(prefix, { recursive: true });
+  cpSync(input.appDir, prefix, { recursive: true });
+
+  // /usr/bin/<bin>: a wrapper that exec's the real binary so process.execPath (and
+  // thus the host's core/resources/helper resolution) points into /opt/<id>.
+  const binDir = join(root, "usr", "bin");
+  mkdirSync(binDir, { recursive: true });
+  const launcher = join(binDir, binName);
+  writeFileSync(launcher, `#!/bin/sh\nexec "/opt/${input.bundleId}/${input.appName}" "$@"\n`);
+  chmodSync(launcher, 0o755);
+
+  // /usr/share/applications/<id>.desktop — Icon= is the theme name (<id>), resolved
+  // from the hicolor icon below; Exec= is the /usr/bin launcher on PATH.
+  const appsDir = join(root, "usr", "share", "applications");
+  mkdirSync(appsDir, { recursive: true });
+  writeFileSync(join(appsDir, `${input.bundleId}.desktop`), buildDesktop(input, binName));
+
+  stageHicolorIcon(root, input);
+  return root;
+}
+
+/** Install the app icon at `usr/share/icons/hicolor/256x256/apps/<id>.png` under `root`. */
+function stageHicolorIcon(root: string, input: LinuxPackageInput): void {
+  const png = input.icon ? resolveLinuxDesktopIconPng(input.icon) : undefined;
+  if (!png) return;
+  const dir = join(root, "usr", "share", "icons", "hicolor", "256x256", "apps");
+  mkdirSync(dir, { recursive: true });
+  cpSync(png, join(dir, `${input.bundleId}.png`));
+}
+
+/** The `.desktop` body shared by deb/rpm/AppImage (Exec = launcher name, Icon = <id>). */
+function buildDesktop(input: LinuxPackageInput, binName: string): string {
+  return desktopEntry({
+    name: input.appName,
+    exec: binName,
+    iconPng: input.bundleId,
+    wmClass: input.bundleId,
+    categories: input.options.category ?? "Utility",
+    comment: input.options.description,
+  });
+}
+
+/** Build a .deb or .rpm from the staged tree via fpm. */
+async function buildFpm(
+  input: LinuxPackageInput,
+  binName: string,
+  fsRoot: string,
+  kind: "deb" | "rpm",
+): Promise<LinuxPackageResult> {
+  const fpm = resolveFpm();
+  const arch = kind === "deb" ? "amd64" : "x86_64";
+  const fileName =
+    kind === "deb"
+      ? `${binName}_${input.version}_${arch}.deb`
+      : `${binName}-${input.version}-1.${arch}.rpm`;
+  const out = join(input.outDir, fileName);
+  rmSync(out, { force: true });
+
+  const depends =
+    kind === "deb"
+      ? input.options.debDepends ?? DEFAULT_DEB_DEPENDS
+      : input.options.rpmDepends ?? DEFAULT_RPM_DEPENDS;
+
+  const args: string[] = [
+    "-s", "dir",
+    "-t", kind,
+    "-C", fsRoot,
+    "--package", out,
+    "--name", binName,
+    "--version", input.version,
+    "--iteration", "1",
+    "--architecture", arch,
+    "--maintainer", input.options.maintainer ?? input.publisher,
+    "--vendor", input.publisher,
+    "--description", input.options.description ?? input.appName,
+  ];
+  if (input.options.homepage) args.push("--url", input.options.homepage);
+  if (input.options.license) args.push("--license", input.options.license);
+  for (const d of depends) args.push("--depends", d);
+  // Package the whole staged tree ('.' relative to the -C chdir).
+  args.push(".");
+
+  console.log(`[mirin] building ${kind} → ${fileName}`);
+  const res = await $`${fpm} ${args}`.nothrow().quiet();
+  if (res.exitCode !== 0 || !existsSync(out)) {
+    throw new Error(`fpm (${kind}) failed (exit ${res.exitCode}):\n${res.stderr.toString()}`);
+  }
+  return { format: kind, path: out, size: size(out) };
+}
+
+/** Build an AppDir and pack it into a single-file AppImage via appimagetool. */
+async function buildAppImage(
+  input: LinuxPackageInput,
+  binName: string,
+): Promise<LinuxPackageResult> {
+  const appimagetool = resolveAppimagetool();
+  const appDirRoot = join(input.outDir, `.AppDir-${process.pid}`);
+  rmSync(appDirRoot, { recursive: true, force: true });
+
+  // Payload → AppDir/usr/lib/<id>/ so $ORIGIN resolves within it.
+  const payload = join(appDirRoot, "usr", "lib", input.bundleId);
+  mkdirSync(payload, { recursive: true });
+  cpSync(input.appDir, payload, { recursive: true });
+
+  // AppRun: exec the real host binary (resolves core/resources/helper from its dir).
+  const appRun = join(appDirRoot, "AppRun");
+  writeFileSync(
+    appRun,
+    [
+      "#!/bin/sh",
+      'HERE="$(dirname "$(readlink -f "$0")")"',
+      `exec "$HERE/usr/lib/${input.bundleId}/${input.appName}" "$@"`,
+      "",
+    ].join("\n"),
+  );
+  chmodSync(appRun, 0o755);
+
+  // .desktop at the AppDir root (appimagetool reads it) + the standard location.
+  const desktop = buildDesktop(input, binName);
+  writeFileSync(join(appDirRoot, `${input.bundleId}.desktop`), desktop);
+  const appsDir = join(appDirRoot, "usr", "share", "applications");
+  mkdirSync(appsDir, { recursive: true });
+  writeFileSync(join(appsDir, `${input.bundleId}.desktop`), desktop);
+
+  // Icon: <id>.png + .DirIcon at the root, plus the hicolor copy.
+  const png = input.icon ? resolveLinuxDesktopIconPng(input.icon) : undefined;
+  if (png) {
+    cpSync(png, join(appDirRoot, `${input.bundleId}.png`));
+    try {
+      symlinkSync(`${input.bundleId}.png`, join(appDirRoot, ".DirIcon"));
+    } catch {
+      /* best-effort: some filesystems disallow symlinks */
+    }
+    stageHicolorIcon(appDirRoot, input);
+  }
+
+  const fileName = `${input.appName}-${input.version}-x86_64.AppImage`;
+  const out = join(input.outDir, fileName);
+  rmSync(out, { force: true });
+
+  console.log(`[mirin] building AppImage → ${fileName}`);
+  // --appimage-extract-and-run: run appimagetool without FUSE. ARCH is required by
+  // appimagetool; NO_STRIP avoids stripping the Bun-compiled host (which would break it).
+  const res = await $`${appimagetool} --appimage-extract-and-run ${appDirRoot} ${out}`
+    .env({ ...process.env, ARCH: "x86_64", NO_STRIP: "1" })
+    .nothrow()
+    .quiet();
+  rmSync(appDirRoot, { recursive: true, force: true });
+  if (res.exitCode !== 0 || !existsSync(out)) {
+    throw new Error(`appimagetool failed (exit ${res.exitCode}):\n${res.stderr.toString()}`);
+  }
+  chmodSync(out, 0o755);
+  return { format: "appimage", path: out, size: size(out) };
+}
+
+/** Resolve the effective set of formats from config + an optional CLI/caller override. */
+export function resolveLinuxFormats(
+  linux: boolean | LinuxConfig | undefined,
+  override?: LinuxPackageFormat[],
+): LinuxPackageFormat[] {
+  if (override && override.length) return override;
+  const fromConfig = typeof linux === "object" ? linux.formats : undefined;
+  return fromConfig && fromConfig.length ? fromConfig : ["appimage", "deb", "rpm"];
+}

package/src/release.ts

@@ -18,12 +18,13 @@
 
 import { $ } from "bun";
 import { mkdirSync, rmSync, readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { tmpdir } from "node:os";
 import { build } from "./build.ts";
 import { buildDmg, notarizeAndStaple, type DmgOptions } from "./dmg.ts";
 import { buildNsisInstaller, hasMakensis } from "./installer-win.ts";
 import { buildInnoInstaller, hasInno } from "./installer-inno.ts";
+import { buildLinuxPackages, resolveLinuxFormats } from "./package-linux.ts";
 import { loadCodec } from "mirinjs/codec";
 
 const sha256File = (path: string) =>
@@ -37,13 +38,14 @@ export async function release(projectDir = process.cwd()): Promise<number> {
   }
 
   const isWindows = process.platform === "win32";
-  const platform = isWindows ? "win32" : "darwin";
+  const isLinux = process.platform === "linux";
+  const platform = isWindows ? "win32" : isLinux ? "linux" : "darwin";
   const arch = process.arch; // "arm64" | "x64"
   const prefix = `${result.channel}-${platform}-${arch}`;
   const safeName = result.appName.replace(/[^A-Za-z0-9._-]/g, "");
   const base = result.baseUrl.replace(/\/$/, "");
-  // The packaged unit: a flat app folder on Windows, an `.app` bundle on macOS.
-  const appArtifact = isWindows ? result.appName : `${result.appName}.app`;
+  // The packaged unit: a flat app folder on Windows/Linux, an `.app` bundle on macOS.
+  const appArtifact = isWindows || isLinux ? result.appName : `${result.appName}.app`;
 
   const buildDir = join(projectDir, "build");
   const outDir = join(buildDir, "release");
@@ -53,7 +55,7 @@ export async function release(projectDir = process.cwd()): Promise<number> {
   // Notarize + staple the .app (Developer ID, macOS) before packing, when
   // credentials are present. The .tar.zst / patch updater bundles are made from
   // this signed, stapled .app, so the updater swaps in an already-notarized app.
-  if (!isWindows) await notarizeAndStaple(result.app);
+  if (!isWindows && !isLinux) await notarizeAndStaple(result.app);
 
   // Load the codec (zstd/bsdiff) from the *bundled* core, not the raw build output:
   // on Windows mirin_core.dll imports libcef.dll. The DLL loader resolves imports
@@ -179,6 +181,42 @@ export async function release(projectDir = process.cwd()): Promise<number> {
       await $`tar -a -cf ${zipPath} -C ${buildDir} ${appArtifact}`;
       installerSize = readFileSync(zipPath).byteLength;
     }
+  } else if (isLinux) {
+    // Linux: the first-install convenience is a set of distributable packages
+    // (AppImage + .deb + .rpm), the analog of the macOS .dmg / Windows installer.
+    // Never fail the whole release over a packaging step — warn and ship the rest.
+    if (result.linux !== false) {
+      try {
+        const formats = resolveLinuxFormats(result.linux);
+        console.log(`[mirin release] building Linux packages (${formats.join(", ")})…`);
+        const pkgs = await buildLinuxPackages({
+          appDir: result.app,
+          appName: result.appName,
+          bundleId: result.bundleId,
+          version: result.version,
+          publisher: result.publisher,
+          outDir,
+          projectDir: result.projectDir,
+          icon: result.icon,
+          options: typeof result.linux === "object" ? result.linux : {},
+          formats,
+        });
+        // The AppImage doubles as the primary "installer" line in the summary.
+        const appImage = pkgs.find((p) => p.format === "appimage") ?? pkgs[0];
+        if (appImage) {
+          installerName = basename(appImage.path);
+          installerSize = appImage.size;
+        }
+        for (const p of pkgs) {
+          if (p !== appImage) console.log(`  ${basename(p.path)} (${(p.size / 1e6).toFixed(1)} MB)`);
+        }
+      } catch (e) {
+        console.warn(
+          `\n[mirin release] ⚠️  Linux packaging failed: ${e instanceof Error ? e.message : e}\n` +
+            `[mirin release] shipping the updater bundle + manifest WITHOUT packages.\n`,
+        );
+      }
+    }
   } else if (result.dmg !== false) {
     // The DMG is the first-install convenience; the updater bundle + manifest (the
     // critical artifacts) are already built. Never fail the whole release over a