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

package/src/check.ts

@@ -0,0 +1,271 @@
+/**
+ * `mirin check` — boot the app once, capture a screenshot and accessibility
+ * snapshot, collect errors, exit non-zero on failure (docs/agent-devtools.md).
+ */
+
+import type { CheckScenario } from "mirinjs/check";
+import type { DevEvent } from "mirinjs/devtools/session";
+import { readEventsFile, sessionPaths } from "mirinjs/devtools/session";
+import { dev } from "./dev.ts";
+import type { ScenarioOutcome } from "./shared/driver.ts";
+import { InspectorClient } from "./shared/inspector.ts";
+import { createReporter, type Reporter } from "./shared/report.ts";
+import { loadScenario, runScenario } from "./shared/scenario.ts";
+
+/** How long to wait for the app to show a window before giving up. */
+const DEFAULT_TIMEOUT_MS = 45_000;
+
+/** Quiet time after the first window appears, so the capture shows painted UI
+ *  rather than an empty frame. */
+const DEFAULT_SETTLE_MS = 1_000;
+
+export interface CheckOptions {
+  timeoutMs?: number;
+  settleMs?: number;
+  json?: boolean;
+  /** Path to a scenario module (`mirin check --scenario ./check.ts`). */
+  scenario?: string;
+}
+
+export interface CheckReport {
+  ok: boolean;
+  reason?: string;
+  session: string | null;
+  inspector: string | null;
+  windows: { id: number; name?: string; url?: string; title?: string }[];
+  /** Path to the captured screenshot. */
+  screenshot: string | null;
+  /** Accessibility snapshot of the first window. */
+  snapshot: string | null;
+  /** Slices the app published with `devtools.expose`, read at the end of the run. */
+  exposed: Record<string, unknown>;
+  errors: DevEvent[];
+  eventCount: number;
+  durationMs: number;
+  /** Present when `--scenario` ran. */
+  scenario?: { file: string } & ScenarioOutcome;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function windowsOf(state: unknown): CheckReport["windows"] {
+  const list = record(state).windows;
+  if (!Array.isArray(list)) return [];
+  return list.flatMap((entry) => {
+    const win = record(entry);
+    const id = win.id;
+    if (typeof id !== "number") return [];
+    return [
+      {
+        id,
+        ...(typeof win.name === "string" ? { name: win.name } : {}),
+        ...(typeof win.url === "string" ? { url: win.url } : {}),
+        ...(typeof win.title === "string" ? { title: win.title } : {}),
+      },
+    ];
+  });
+}
+
+/** Poll `/state` until a window exists, or the deadline passes. */
+async function waitForWindow(
+  client: InspectorClient,
+  deadline: number,
+): Promise<CheckReport["windows"]> {
+  let last: CheckReport["windows"] = [];
+  while (Date.now() < deadline) {
+    try {
+      last = windowsOf(await client.get("/state"));
+      if (last.length > 0) return last;
+    } catch {
+      // The inspector may still be binding; keep trying until the deadline.
+    }
+    await Bun.sleep(250);
+  }
+  return last;
+}
+
+async function capture(client: InspectorClient, report: CheckReport): Promise<void> {
+  try {
+    const shot = record(await client.get("/screenshot"));
+    if (typeof shot.path === "string") report.screenshot = shot.path;
+  } catch (err) {
+    report.errors.push(syntheticError(`screenshot failed: ${message(err)}`));
+  }
+  try {
+    const snap = record(await client.get("/snapshot"));
+    if (typeof snap.snapshot === "string") report.snapshot = snap.snapshot;
+  } catch (err) {
+    report.errors.push(syntheticError(`snapshot failed: ${message(err)}`));
+  }
+  try {
+    report.exposed = record(record(await client.get("/state")).exposed);
+  } catch {
+    // The app publishing nothing is the common case; not worth an error.
+  }
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** A failure of the check itself, shaped like a stream event so one list suffices. */
+function syntheticError(text: string): DevEvent {
+  return { seq: 0, ts: Date.now(), src: "main", level: "error", type: "check.error", msg: text };
+}
+
+function renderReport(report: CheckReport): void {
+  const mark = report.ok ? "✓" : "✗";
+  console.log(`\n${mark} mirin check ${report.ok ? "passed" : "failed"} in ${report.durationMs}ms`);
+  if (report.reason !== undefined) console.log(`  reason: ${report.reason}`);
+
+  if (report.windows.length > 0) {
+    console.log(`  windows: ${report.windows.length}`);
+    for (const win of report.windows) {
+      const label = [win.name, win.title].filter(Boolean).join(" / ");
+      console.log(
+        `    #${win.id}${label.length > 0 ? ` ${label}` : ""} ${win.url ?? ""}`.trimEnd(),
+      );
+    }
+  }
+  if (report.scenario !== undefined) {
+    const { file, steps, screenshots, failure } = report.scenario;
+    console.log(`  scenario: ${file}`);
+    for (const step of steps) {
+      const mark = step.ok ? "✓" : "✗";
+      console.log(`    ${mark} ${step.name}${step.ms >= 0 ? ` (${step.ms}ms)` : ""}`);
+    }
+    if (failure !== undefined) console.log(`    → ${failure.message}`);
+    for (const shot of screenshots) console.log(`    shot: ${shot}`);
+  }
+  const exposedKeys = Object.keys(report.exposed);
+  if (exposedKeys.length > 0) {
+    console.log(`  app state: ${JSON.stringify(report.exposed).slice(0, 400)}`);
+  }
+  if (report.screenshot !== null) console.log(`  screenshot: ${report.screenshot}`);
+  if (report.session !== null) console.log(`  session: ${report.session}`);
+  console.log(`  events: ${report.eventCount}, errors: ${report.errors.length}`);
+
+  for (const error of report.errors.slice(0, 10)) {
+    console.log(`\n  [${error.src}] ${error.type}: ${error.msg}`);
+    const stack = record(error.data).stack;
+    if (Array.isArray(stack)) {
+      for (const frame of stack.slice(0, 4)) console.log(`      at ${String(frame)}`);
+    }
+  }
+  if (report.errors.length > 10) {
+    console.log(`\n  … ${report.errors.length - 10} more errors (see the session's events.jsonl)`);
+  }
+  if (report.snapshot !== null) {
+    console.log(`\n  ui snapshot:\n${report.snapshot.replace(/^/gm, "    ")}`);
+  }
+}
+
+/** Run the check. Returns the process exit code: 0 when the app came up clean. */
+export async function check(
+  projectDir = process.cwd(),
+  options: CheckOptions = {},
+): Promise<number> {
+  const reporter: Reporter = createReporter(options.json === true);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
+  const startedAt = Date.now();
+
+  const report: CheckReport = {
+    ok: false,
+    session: null,
+    inspector: null,
+    windows: [],
+    screenshot: null,
+    snapshot: null,
+    exposed: {},
+    errors: [],
+    eventCount: 0,
+    durationMs: 0,
+  };
+
+  reporter.event("start", { projectDir, timeoutMs });
+
+  // Load the scenario before anything is built: a typo in the path should cost a
+  // second, not a cold compile.
+  let scenario: CheckScenario | undefined;
+  if (options.scenario !== undefined) {
+    try {
+      scenario = await loadScenario(projectDir, options.scenario);
+    } catch (err) {
+      report.reason = message(err);
+      report.durationMs = Date.now() - startedAt;
+      reporter.finish({ ...report }, () => renderReport(report));
+      return 1;
+    }
+  }
+
+  await dev(projectDir, {
+    // Inherit the output mode: in JSON mode `mirin dev`'s prose would otherwise
+    // interleave with the report and break parsing.
+    json: options.json === true,
+    async onLaunched(context) {
+      const deadline = Date.now() + timeoutMs;
+      const session = context.session;
+      if (session === undefined) {
+        report.reason = "no dev session was created — devtools artifacts are unavailable";
+        return;
+      }
+      report.session = session.paths.dir;
+
+      reporter.event("await-inspector");
+      const endpoint = await session.waitForInspector(Math.max(1_000, deadline - Date.now()));
+      if (endpoint === undefined) {
+        report.reason = "the app never published an inspector endpoint";
+        return;
+      }
+      report.inspector = `http://127.0.0.1:${endpoint.port}`;
+      const client = new InspectorClient(endpoint);
+
+      reporter.event("await-window");
+      report.windows = await waitForWindow(client, deadline);
+      if (report.windows.length === 0) {
+        report.reason = `no window appeared within ${timeoutMs}ms`;
+        return;
+      }
+
+      // Let the first paint land, or the capture shows an empty frame and tree.
+      await Bun.sleep(settleMs);
+
+      if (scenario !== undefined && options.scenario !== undefined) {
+        reporter.event("scenario", { file: options.scenario });
+        const outcome = await runScenario(client, scenario, (name) =>
+          reporter.event("step", { name }),
+        );
+        report.scenario = { file: options.scenario, ...outcome };
+        if (outcome.failure !== undefined) {
+          report.reason = `scenario failed at "${outcome.failure.step}": ${outcome.failure.message}`;
+        }
+      }
+
+      // Capture after the scenario, so artifacts show the state the run ended in.
+      reporter.event("capture", { windows: report.windows.length });
+      await capture(client, report);
+    },
+  });
+
+  // Read the stream from disk rather than the inspector: by now the app has exited,
+  // and the file is the complete record of the run.
+  if (report.session !== null) {
+    const events = readEventsFile(sessionPaths(report.session).events);
+    report.eventCount = events.length;
+    report.errors.push(...events.filter((event) => event.level === "error"));
+  }
+
+  report.durationMs = Date.now() - startedAt;
+  report.ok = report.reason === undefined && report.errors.length === 0;
+  if (!report.ok && report.reason === undefined) {
+    report.reason = `${report.errors.length} error-level event(s) during startup`;
+  }
+
+  reporter.finish({ ...report }, () => renderReport(report));
+  return report.ok ? 0 : 1;
+}

package/src/dev.ts

@@ -6,25 +6,61 @@
  * 3. assemble + ad-hoc-sign the dev .app
  * 4. start the Vite dev server (rolldown-vite) for the UI
  * 5. launch the app pointed at the Vite URL, with RPC injected into the webview
+ *
+ * Each run also opens a dev session under `.mirin/dev/` and records its phase
+ * timeline there (docs/agent-devtools.md).
  */
 
-import { $ } from "bun";
-import { mkdirSync, rmSync, symlinkSync, existsSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
+import { homedir } from "node:os";
 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,
+  desktopEntry,
+  resolveLinuxDesktopIconPng,
+  resolveLinuxIconPng,
+} from "./bundle/linux/index.ts";
+import { buildAppBundle } from "./bundle/macos/index.ts";
+import { buildWindowsBundle } from "./bundle/windows/index.ts";
 
 const IS_WINDOWS = process.platform === "win32";
+const IS_LINUX = process.platform === "linux";
+
+import { compileWorkers, normalizeSidecars } from "./extras.ts";
+import { createReporter } from "./shared/report.ts";
+import { DevSession } from "./shared/session.ts";
 import { sweepBuildTemps } from "./temps.ts";
-import { normalizeSidecars, compileWorkers } from "./extras.ts";
 
 /** Vite's default port. `mirin dev` probes upward from here for a free one, so a
  *  second dev session (or anything already on 5173) doesn't collide. */
 const DEV_PORT_BASE = 5173;
 
-export async function dev(projectDir = process.cwd()): Promise<number> {
+/** Where the CEF DevTools-protocol port search starts. Well clear of Vite's range
+ *  so concurrent dev sessions of different apps don't fight over either. */
+const CDP_PORT_BASE = 9222;
+
+export interface DevLaunchContext {
+  session?: DevSession;
+  devUrl: string;
+  cdpPort: number;
+  pid: number;
+  /** Stop the app and the Vite server. */
+  stop(): void;
+}
+
+export interface DevOptions {
+  /** Emit newline-delimited JSON progress instead of prose. */
+  json?: boolean;
+  /** Called once the app is running. The app is always stopped after the hook
+   *  settles, whether it threw or not. */
+  onLaunched?(context: DevLaunchContext): Promise<void> | void;
+}
+
+export async function dev(projectDir = process.cwd(), options?: DevOptions): Promise<number> {
+  const reporter = createReporter(options?.json === true);
   const work = join(projectDir, ".mirin");
   mkdirSync(work, { recursive: true });
   // `bun build --compile` drops temp *.bun-build files in the cwd; clear any left
@@ -36,22 +72,46 @@ 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;
+
+  // --- open the dev session (agent devtools) ---
+  const session = DevSession.create({
+    projectDir,
+    appName,
+    appId: bundleId,
+    version: typeof config.version === "string" ? config.version : undefined,
+  });
 
   // --- native artifacts ---
-  const artifacts = await resolveArtifacts({ release: false });
+  const artifacts = await resolveArtifacts({ release: false, reporter });
 
   // --- compile the Bun host + bundle the Worker ---
-  console.log("[mirin dev] compiling host + bundling main process…");
+  const compilePhase = session?.phase("compile");
+  reporter.info("[mirin dev] compiling host + bundling main process…");
+  reporter.event("compile");
   // `bun build --compile` emits an `.exe` on Windows; name it so explicitly.
   const hostExe = join(work, IS_WINDOWS ? "host.exe" : "host");
   const workerJs = join(work, "worker.js");
-  await $`bun build --compile ${artifacts.hostEntry} --outfile ${hostExe}`.cwd(projectDir);
-  await $`bun build ${mainEntry} --target=bun --outfile ${workerJs}`.cwd(projectDir);
+  const hostTarget =
+    process.platform === "win32" && process.arch === "arm64" ? ["--target=bun-windows-x64"] : [];
+  await reporter.build(
+    $`bun build --compile ${hostTarget} ${artifacts.hostEntry} --outfile ${hostExe}`.cwd(
+      projectDir,
+    ),
+  );
+  await reporter.build(
+    $`bun build ${mainEntry} --target=bun --outfile ${workerJs}`.cwd(projectDir),
+  );
+  compilePhase?.ok();
 
   // Extra assets (dev): compile workers into .mirin/workers and symlink sidecar
   // binaries into .mirin/sidecars (no copy/sign in dev — they run unsigned locally).
   const workersDir = join(work, "workers");
-  await compileWorkers(projectDir, config.workers, workersDir, false);
+  await compileWorkers(projectDir, config.workers, workersDir, false, reporter);
   const sidecarsDir = join(work, "sidecars");
   mkdirSync(sidecarsDir, { recursive: true });
   for (const sc of normalizeSidecars(projectDir, config.sidecars)) {
@@ -61,8 +121,10 @@ 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) ---
-  console.log("[mirin dev] assembling dev bundle…");
+  // --- assemble the dev bundle (Windows/Linux app folder, or macOS .app) ---
+  const bundlePhase = session?.phase("bundle");
+  reporter.info("[mirin dev] assembling dev bundle…");
+  reporter.event("bundle");
   const { app, exe } = IS_WINDOWS
     ? await buildWindowsBundle({
         appName,
@@ -71,56 +133,154 @@ 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,
       })
-    : await buildAppBundle({
-        appName,
-        bundleId,
-        outDir: work,
-        hostExe,
-        coreDylib: artifacts.coreDylib,
-        helperBin: artifacts.helperBin,
-        cefPath: artifacts.cefPath,
-        icon: config.icon ? join(projectDir, config.icon) : undefined,
-        urlSchemes: config.urlSchemes,
-      });
+    : IS_LINUX
+      ? await buildLinuxBundle({
+          appName,
+          outDir: work,
+          hostExe,
+          coreDll: artifacts.coreDylib,
+          helperExe: artifacts.helperBin,
+          cefPath: artifacts.cefPath,
+          icon: iconSrc,
+        })
+      : await buildAppBundle({
+          appName,
+          bundleId,
+          outDir: work,
+          hostExe,
+          coreDylib: artifacts.coreDylib,
+          helperBin: artifacts.helperBin,
+          cefPath: artifacts.cefPath,
+          icon: iconSrc,
+          urlSchemes: config.urlSchemes,
+        });
+  bundlePhase?.ok();
+
+  // 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}`;
-  console.log(`[mirin dev] starting Vite dev server on ${devUrl}…`);
+  const cdpPort = await findFreePort(CDP_PORT_BASE);
+  const devUrl = `http://127.0.0.1:${port}`;
+  const vitePhase = session?.phase("vite");
+  session?.setDevUrl(devUrl);
+  reporter.info(`[mirin dev] starting Vite dev server on ${devUrl}…`);
+  reporter.event("vite", { 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"],
+      stdio: reporter.childStdio,
     },
   );
-  await waitForUrl(devUrl, 15_000);
+  try {
+    await waitForUrl(devUrl, 15_000);
+    vitePhase?.ok(devUrl);
+  } catch (err) {
+    vitePhase?.fail(err instanceof Error ? err.message : String(err));
+    vite.kill();
+    throw err;
+  }
 
   // --- launch the app ---
-  console.log(`[mirin dev] launching ${appName}…`);
+  const launchPhase = session?.phase("launch");
+  reporter.info(`[mirin dev] launching ${appName}…`);
   const appProc = Bun.spawn([exe], {
     cwd: projectDir,
     env: {
       ...process.env,
       MIRIN_CORE: IS_WINDOWS
         ? join(app, "mirin_core.dll")
-        : join(app, "Contents", "MacOS", "libmirin_core.dylib"),
+        : 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({ windows: config.windows }),
+      MIRIN_MANIFEST_JSON: JSON.stringify({
+        id: bundleId,
+        windows: config.windows,
+        devtools: config.devtools,
+      }),
       // 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,
+      // CEF's DevTools-protocol port (screenshots, snapshots, eval, input).
+      // Loopback only, and only ever set for a dev run (docs/agent-devtools.md).
+      MIRIN_CDP_PORT: String(cdpPort),
+      ...(session?.env() ?? {}),
     },
-    stdio: ["ignore", "inherit", "inherit"],
+    stdio: reporter.childStdio,
   });
+  session?.setPid(appProc.pid);
+  launchPhase?.ok();
+  reporter.event("launch", {
+    pid: appProc.pid,
+    devUrl,
+    cdpPort,
+    session: session?.paths.dir ?? null,
+  });
+  if (session) {
+    reporter.info(`[mirin dev] dev session: ${session.paths.dir}`);
+    // The app publishes its inspector endpoint once the Worker binds it; report it
+    // when it lands, without holding up the dev loop if it never does.
+    void session.waitForInspector().then((endpoint) => {
+      if (endpoint === undefined) return;
+      reporter.info(
+        `[mirin dev] inspector: http://127.0.0.1:${endpoint.port} — token in inspector.json`,
+      );
+      reporter.event("inspector", { url: `http://127.0.0.1:${endpoint.port}` });
+    });
+  }
 
   const cleanup = () => {
     vite.kill();
@@ -129,8 +289,26 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
   process.on("SIGINT", cleanup);
   process.on("SIGTERM", cleanup);
 
+  if (options?.onLaunched !== undefined) {
+    try {
+      await options.onLaunched({
+        ...(session !== undefined ? { session } : {}),
+        devUrl,
+        cdpPort,
+        pid: appProc.pid,
+        stop: cleanup,
+      });
+    } catch (err) {
+      console.error(`[mirin] launch hook failed: ${err instanceof Error ? err.message : err}`);
+    } finally {
+      // A hooked run is a one-shot: stop the app whether the hook succeeded or not.
+      cleanup();
+    }
+  }
+
   const code = await appProc.exited;
   vite.kill();
+  session?.finish(code, appProc.signalCode ?? undefined);
   return code;
 }
 

package/src/dmg.ts

@@ -15,10 +15,10 @@
  * stapled so a fresh download opens without a Gatekeeper prompt.
  */
 
-import { $ } from "bun";
-import { cpSync, mkdirSync, rmSync, symlinkSync, existsSync } from "node:fs";
-import { join, basename, isAbsolute } from "node:path";
+import { cpSync, existsSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
+import { $ } from "bun";
 
 export interface DmgOptions {
   volumeName?: string;
@@ -148,12 +148,20 @@ export async function buildDmg(input: BuildDmgInput): Promise<string> {
     let built = false;
     if (wantsLayout(options)) {
       try {
-        await buildLaidOutDmg({ staging, vol, format, dmgPath, options, projectDir, appFile: basename(app) });
+        await buildLaidOutDmg({
+          staging,
+          vol,
+          format,
+          dmgPath,
+          options,
+          projectDir,
+          appFile: basename(app),
+        });
         built = true;
       } catch (e) {
         console.warn(
           `[mirin release] DMG layout failed (${e instanceof Error ? e.message : e}); ` +
-            `falling back to a plain DMG.`,
+            "falling back to a plain DMG.",
         );
         rmSync(dmgPath, { force: true });
       }
@@ -190,9 +198,14 @@ async function buildLaidOutDmg(args: {
   const { staging, vol, format, dmgPath, options, projectDir, appFile } = args;
   const win = options.windowSize ?? { width: 640, height: 400 };
   const iconSize = options.iconSize ?? 128;
-  const appPos = options.appPosition ?? { x: Math.round(win.width * 0.25), y: Math.round(win.height * 0.5) };
-  const appsPos =
-    options.applicationsPosition ?? { x: Math.round(win.width * 0.75), y: Math.round(win.height * 0.5) };
+  const appPos = options.appPosition ?? {
+    x: Math.round(win.width * 0.25),
+    y: Math.round(win.height * 0.5),
+  };
+  const appsPos = options.applicationsPosition ?? {
+    x: Math.round(win.width * 0.75),
+    y: Math.round(win.height * 0.5),
+  };
 
   // Stage a background image (if any) under a hidden folder Finder can reference.
   let bgFile: string | undefined;
@@ -214,8 +227,7 @@ async function buildLaidOutDmg(args: {
   await $`hdiutil create -volname ${vol} -srcfolder ${staging} -fs HFS+ -format UDRW -ov ${rw}`.quiet();
 
   // Attach without auto-opening a Finder window; parse the real mountpoint.
-  const attach =
-    await $`hdiutil attach ${rw} -readwrite -noverify -noautoopen`.text();
+  const attach = await $`hdiutil attach ${rw} -readwrite -noverify -noautoopen`.text();
   const mount = attach
     .split("\n")
     .map((l) => l.trim())