mirinjs 0.0.1-alpha.14 → 0.0.1-alpha.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirinjs",
-  "version": "0.0.1-alpha.14",
+  "version": "0.0.1-alpha.16",
   "description": "Build desktop apps with Bun, TypeScript, and Chromium (CEF). The Bun-native Electron alternative.",
   "type": "module",
   "license": "MIT",

package/src/app.ts

@@ -8,6 +8,8 @@ import type { Router, EventProc } from "./rpc.ts";
 import type { WindowConfig, WindowMaterial, WindowMaterialOptions } from "./config.ts";
 import { updater } from "./updater.ts";
 import type { Updater } from "./updater.ts";
+import { sidecar as spawnSidecar } from "./sidecar.ts";
+import type { SidecarOptions, SidecarProcess } from "./sidecar.ts";
 
 /** Which native backend a window's `material` resolved to. */
 export type WindowMaterialInfo = {
@@ -313,6 +315,14 @@ class MirinApp extends Emitter<AppEvents> {
     return rpcEmitters((method, payload) => runtime().rpc.broadcast(method, payload));
   }
 
+  /**
+   * Spawn a bundled sidecar binary (declared in `mirin.config.ts` `sidecars`).
+   * Resolves the in-bundle path and tracks the child so it's killed on quit.
+   */
+  sidecar(name: string, opts?: SidecarOptions): SidecarProcess {
+    return spawnSidecar(name, opts);
+  }
+
   quit(): void {
     runtime().core.quit();
   }

package/src/config.ts

@@ -101,9 +101,47 @@ export interface MirinConfig {
    * notary credentials are set) notarized + stapled like the `.app`.
    */
   dmg?: boolean | DmgConfig;
+  /**
+   * External binaries bundled into the `.app` and spawned at runtime with
+   * `app.sidecar(name)`. Maps a logical name to a path (relative to the project
+   * root) or a {@link SidecarSpec}. Each binary is copied into
+   * `Contents/Resources/sidecars/<name>`, codesigned (hardened runtime), and —
+   * when notary credentials are set — notarized with the rest of the app.
+   *
+   * Prefer a binary already on the user's PATH (`Bun.spawn("git", …)`) or a
+   * download-on-first-run when size/licensing matter; bundle only when you need
+   * a pinned version offline.
+   */
+  sidecars?: Record<string, string | SidecarSpec>;
+  /**
+   * Extra Bun Worker entry files (relative to the project root) bundled next to
+   * the main worker. Resolve one at runtime with `resolveWorker(name)` and pass
+   * it to `new Worker(...)` from `node:worker_threads`. These run off the main
+   * thread for CPU/IO offload and must NOT call window/native APIs — only the
+   * app worker owns AppKit/CEF (see docs/architecture.md).
+   */
+  workers?: Record<string, string>;
   windows: Record<string, WindowConfig>;
 }
 
+/** A bundled sidecar binary with optional hardened-runtime entitlements. */
+export interface SidecarSpec {
+  /** Path to the binary, relative to the project root. */
+  bin: string;
+  /**
+   * Extra codesign entitlements for this binary under the hardened runtime.
+   * Most plain CLIs need none. Use `disable-library-validation` for a binary
+   * that loads dylibs not signed by your Team ID, or the JIT entitlements for a
+   * binary that runs its own JIT (another Bun/V8/Node).
+   */
+  entitlements?: SidecarEntitlement[];
+}
+
+export type SidecarEntitlement =
+  | "allow-jit"
+  | "allow-unsigned-executable-memory"
+  | "disable-library-validation";
+
 export interface DmgConfig {
   /** Volume name shown when the DMG is mounted. Default: the app name. */
   volumeName?: string;

package/src/host.ts

@@ -24,6 +24,10 @@ const resourcesDir = join(exeDir, "..", "Resources");
 
 const corePath = process.env.MIRIN_CORE ?? join(exeDir, "libmirin_core.dylib");
 const workerPath = process.env.MIRIN_WORKER ?? join(resourcesDir, "worker.js");
+// Bundled-asset dirs for sidecars (Bun.spawn binaries) and extra workers. Dev
+// overrides via env (dev.ts stages them under .mirin); prod resolves in-bundle.
+const sidecarDir = process.env.MIRIN_SIDECAR_DIR ?? join(resourcesDir, "sidecars");
+const workersDir = process.env.MIRIN_WORKERS_DIR ?? join(resourcesDir, "workers");
 
 if (!existsSync(corePath) || !existsSync(workerPath)) {
   console.error(`[mirin host] missing core (${corePath}) or worker (${workerPath})`);
@@ -48,7 +52,14 @@ const coreConfig = JSON.parse(
 const core = new Core(corePath);
 
 const worker = new Worker(workerPath, {
-  workerData: { corePath, manifest, devUrl: process.env.MIRIN_DEV_URL, resourcesDir },
+  workerData: {
+    corePath,
+    manifest,
+    devUrl: process.env.MIRIN_DEV_URL,
+    resourcesDir,
+    sidecarDir,
+    workersDir,
+  },
 });
 worker.on("error", (err) => console.error("[mirin worker]", err));
 

package/src/index.ts

@@ -24,7 +24,8 @@ export { clipboard } from "./clipboard.ts";
 export { globalShortcut } from "./shortcut.ts";
 export { logger, setLogLevel, getLogLevel, Logger } from "./logger.ts";
 export { updater, Updater } from "./updater.ts";
-export { NotAttachedError } from "./runtime.ts";
+export { sidecar } from "./sidecar.ts";
+export { NotAttachedError, resolveWorker } from "./runtime.ts";
 
 export type {
   WindowEvents,
@@ -40,6 +41,7 @@ export type {
 export type { MenuItemTemplate, MenuRole } from "./menu.ts";
 export type { LogLevel } from "./logger.ts";
 export type { UpdaterStatus, UpdateInfo, UpdateProgress, UpdaterEvents } from "./updater.ts";
+export type { SidecarOptions, SidecarProcess } from "./sidecar.ts";
 export type { TrayOptions } from "./tray.ts";
 export type { OpenDialogOptions, SaveDialogOptions, MessageDialogOptions } from "./dialog.ts";
 export type {
@@ -49,6 +51,8 @@ export type {
   WindowMaterialOptions,
   ReleaseConfig,
   DmgConfig,
+  SidecarSpec,
+  SidecarEntitlement,
 } from "./config.ts";
 
 wireAppEvents();

package/src/runtime.ts

@@ -5,6 +5,7 @@
  */
 
 import { workerData } from "node:worker_threads";
+import { join } from "node:path";
 import { Core } from "./native.ts";
 import { RpcServer } from "./rpc-server.ts";
 import type { WindowConfig } from "./config.ts";
@@ -22,6 +23,10 @@ export interface Runtime {
   resourcesDir?: string;
   /** Path to libmirin_core (for the updater codec). */
   corePath?: string;
+  /** Dir holding bundled sidecar binaries (for `app.sidecar`). */
+  sidecarDir?: string;
+  /** Dir holding bundled extra-worker JS (for `resolveWorker`). */
+  workersDir?: string;
 }
 
 export class NotAttachedError extends Error {
@@ -84,6 +89,8 @@ export function boot(): void {
     manifest?: { windows?: Record<string, WindowConfig> };
     devUrl?: string;
     resourcesDir?: string;
+    sidecarDir?: string;
+    workersDir?: string;
   };
   const corePath = data.corePath ?? process.env.MIRIN_CORE;
   if (!corePath) return; // not under the host; the API stays detached
@@ -104,6 +111,20 @@ export function boot(): void {
     devUrl: data.devUrl,
     resourcesDir: data.resourcesDir,
     corePath,
+    sidecarDir: data.sidecarDir,
+    workersDir: data.workersDir,
   };
   core.onEvent(dispatch);
 }
+
+/**
+ * Resolve a bundled extra-worker (declared in `mirin.config.ts` `workers`) to an
+ * absolute path, for `new Worker(resolveWorker(name))` from `node:worker_threads`.
+ * Works in `mirin dev` and the built `.app`. Extra workers run off the main
+ * thread and must not call window/native APIs.
+ */
+export function resolveWorker(name: string): string {
+  const dir = current?.workersDir;
+  if (!dir) throw new NotAttachedError("resolveWorker");
+  return join(dir, `${name}.js`);
+}

package/src/sidecar.ts

@@ -0,0 +1,107 @@
+/**
+ * Sidecars — spawn a binary bundled into the `.app` (declared in
+ * `mirin.config.ts` `sidecars`). A thin wrapper over `Bun.spawn` that resolves
+ * the bundled path (dev or prod, via `runtime().sidecarDir`) and tracks the
+ * child so it's killed when the app quits — the two things hand-rolled
+ * `Bun.spawn` gets wrong (path resolution + orphaned processes).
+ *
+ * Sidecars run as separate OS processes, so they may do anything a CLI can; they
+ * just can't touch the app's AppKit/CEF UI (nothing off the main thread can).
+ */
+
+import { join } from "node:path";
+import { runtime, onNativeEvent } from "./runtime.ts";
+
+export interface SidecarOptions {
+  /** Arguments passed after the binary path. */
+  args?: string[];
+  cwd?: string;
+  /** Extra env on top of the inherited environment. */
+  env?: Record<string, string>;
+  /** Defaults: stdin "pipe", stdout "pipe", stderr "inherit". */
+  stdin?: Bun.SpawnOptions.Writable;
+  stdout?: Bun.SpawnOptions.Readable;
+  stderr?: Bun.SpawnOptions.Readable;
+}
+
+/** A running sidecar. Mirrors the subset of `Bun.Subprocess` apps need. */
+export interface SidecarProcess {
+  readonly pid: number;
+  readonly stdin: Bun.Subprocess["stdin"];
+  readonly stdout: Bun.Subprocess["stdout"];
+  readonly stderr: Bun.Subprocess["stderr"];
+  /** Resolves with the exit code when the process ends. */
+  readonly exited: Promise<number>;
+  /** Send a signal (default SIGTERM) and stop tracking it. */
+  kill(signal?: number | NodeJS.Signals): void;
+}
+
+const children = new Set<Bun.Subprocess>();
+let hooked = false;
+
+function killAll(): void {
+  for (const child of children) {
+    try {
+      child.kill();
+    } catch {
+      // already gone
+    }
+  }
+  children.clear();
+}
+
+/** Register shutdown hooks once, so sidecars don't outlive the app. */
+function ensureHooks(): void {
+  if (hooked) return;
+  hooked = true;
+  // App fully quit (last window closed / Cmd-Q path surfaces here).
+  onNativeEvent("window.all-closed", killAll);
+  // Worker-process shutdown backstops (normal exit / signals). `terminate()` is
+  // abrupt and won't fire these, hence the native-event hook above as well.
+  for (const sig of ["exit", "SIGINT", "SIGTERM"] as const) {
+    process.on(sig, killAll);
+  }
+}
+
+/**
+ * Spawn a bundled sidecar binary by its config name. Throws if the runtime
+ * isn't attached or no `sidecarDir` is known (e.g. run outside the host).
+ */
+export function sidecar(name: string, opts: SidecarOptions = {}): SidecarProcess {
+  const dir = runtime().sidecarDir;
+  if (!dir) {
+    throw new Error(`app.sidecar("${name}"): no sidecar dir (is this running under the mirin host?)`);
+  }
+  ensureHooks();
+
+  const bin = join(dir, name);
+  const child = Bun.spawn([bin, ...(opts.args ?? [])], {
+    cwd: opts.cwd,
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+    stdin: opts.stdin ?? "pipe",
+    stdout: opts.stdout ?? "pipe",
+    stderr: opts.stderr ?? "inherit",
+  });
+  children.add(child);
+  void child.exited.then(() => children.delete(child));
+
+  return {
+    get pid() {
+      return child.pid;
+    },
+    get stdin() {
+      return child.stdin;
+    },
+    get stdout() {
+      return child.stdout;
+    },
+    get stderr() {
+      return child.stderr;
+    },
+    exited: child.exited,
+    kill(signal) {
+      children.delete(child);
+      child.kill(signal as number | undefined);
+    },
+  };
+}