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

package/src/dev.ts

@@ -6,25 +6,62 @@
  * 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 { resolveIconSource } from "./icons/sources.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 +73,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 = resolveIconSource(config.icon, projectDir);
+  // 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 +122,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 +134,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 +290,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())

package/src/doctor.ts

@@ -0,0 +1,227 @@
+/**
+ * `mirin doctor` — check the project and environment before anything is built,
+ * including the previous session's outcome (docs/agent-devtools.md).
+ */
+
+import { existsSync } from "node:fs";
+import { createServer } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  readCurrentSession,
+  readEventsFile,
+  readSessionInfo,
+  sessionPaths,
+} from "mirinjs/devtools/session";
+import { isInRepo, vendoredCef } from "./artifacts.ts";
+import { createReporter } from "./shared/report.ts";
+
+export type CheckStatus = "ok" | "warn" | "fail";
+
+export interface DoctorCheck {
+  name: string;
+  status: CheckStatus;
+  detail: string;
+  fix?: string;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  projectDir: string;
+  platform: string;
+  checks: DoctorCheck[];
+}
+
+const SUPPORTED = new Set(["darwin-arm64", "win32-x64", "win32-arm64", "linux-x64", "linux-arm64"]);
+
+function ok(name: string, detail: string): DoctorCheck {
+  return { name, status: "ok", detail };
+}
+function warn(name: string, detail: string, fix?: string): DoctorCheck {
+  return { name, status: "warn", detail, ...(fix !== undefined ? { fix } : {}) };
+}
+function fail(name: string, detail: string, fix?: string): DoctorCheck {
+  return { name, status: "fail", detail, ...(fix !== undefined ? { fix } : {}) };
+}
+
+function portFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => server.close(() => resolve(true)));
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+function checkPlatform(): DoctorCheck {
+  const target = `${process.platform}-${process.arch}`;
+  return SUPPORTED.has(target)
+    ? ok("platform", `${target}, bun ${Bun.version}`)
+    : fail(
+        "platform",
+        `${target} is not a supported target`,
+        `supported: ${[...SUPPORTED].join(", ")}`,
+      );
+}
+
+/** Load `mirin.config.ts` and check the fields the CLI and host both require. */
+async function checkConfig(projectDir: string): Promise<DoctorCheck[]> {
+  const path = join(projectDir, "mirin.config.ts");
+  if (!existsSync(path)) {
+    return [fail("config", "mirin.config.ts not found", "run `mirin init` or check the directory")];
+  }
+
+  let config: Record<string, unknown>;
+  try {
+    const loaded: unknown = (await import(path)).default;
+    if (typeof loaded !== "object" || loaded === null) {
+      return [fail("config", "mirin.config.ts has no default export object")];
+    }
+    config = loaded as Record<string, unknown>;
+  } catch (err) {
+    return [
+      fail("config", `mirin.config.ts failed to load: ${err instanceof Error ? err.message : err}`),
+    ];
+  }
+
+  const checks: DoctorCheck[] = [];
+  const missing = ["id", "name", "main", "windows"].filter((key) => config[key] == null);
+  checks.push(
+    missing.length === 0
+      ? ok("config", `${String(config.name)} (${String(config.id)})`)
+      : fail("config", `missing required field(s): ${missing.join(", ")}`),
+  );
+
+  const main = typeof config.main === "string" ? config.main : "main/main.ts";
+  checks.push(
+    existsSync(join(projectDir, main))
+      ? ok("main entry", main)
+      : fail("main entry", `${main} does not exist`, "point `main` at your main-process entry"),
+  );
+
+  const windows =
+    typeof config.windows === "object" && config.windows !== null ? config.windows : {};
+  const names = Object.keys(windows);
+  checks.push(
+    names.length > 0
+      ? ok("windows", names.join(", "))
+      : warn("windows", "no windows declared", "the app will start with nothing visible"),
+  );
+
+  const devtools = config.devtools;
+  if (typeof devtools === "object" && devtools !== null && "production" in devtools) {
+    const enabled = (devtools as { production?: unknown }).production === true;
+    checks.push(
+      enabled
+        ? warn(
+            "devtools",
+            "devtools.production is true — packaged builds will expose the inspector",
+            "remove it before shipping: the inspector can evaluate code in your app",
+          )
+        : ok("devtools", "production access disabled"),
+    );
+  }
+  return checks;
+}
+
+function checkUi(projectDir: string): DoctorCheck[] {
+  const checks: DoctorCheck[] = [];
+  checks.push(
+    existsSync(join(projectDir, "index.html"))
+      ? ok("ui entry", "index.html")
+      : warn("ui entry", "no index.html at the project root", "Vite needs an HTML entry"),
+  );
+  const viteConfig = ["vite.config.ts", "vite.config.js", "vite.config.mts"].find((name) =>
+    existsSync(join(projectDir, name)),
+  );
+  checks.push(
+    viteConfig !== undefined
+      ? ok("vite config", viteConfig)
+      : warn("vite config", "none found", "Vite will run with defaults"),
+  );
+  return checks;
+}
+
+function checkCef(): DoctorCheck {
+  if (isInRepo()) {
+    // Resolved from the CLI's location, not the cwd, which is usually an example app.
+    const vendored = vendoredCef();
+    return vendored.present
+      ? ok("cef", "vendor/cef is present")
+      : warn("cef", `${vendored.path} is missing or incomplete`, "run `bun scripts/fetch-cef.ts`");
+  }
+  const cache = join(homedir(), ".mirinjs", "cef");
+  return existsSync(cache)
+    ? ok("cef", `cached at ${cache}`)
+    : warn("cef", "no cached CEF runtime", "the first `mirin dev` downloads it (a few hundred MB)");
+}
+
+async function checkPorts(): Promise<DoctorCheck[]> {
+  const [vite, cdp] = await Promise.all([portFree(5173), portFree(9222)]);
+  return [
+    vite
+      ? ok("vite port", "5173 is free")
+      : warn("vite port", "5173 is in use", "mirin dev probes upward, so this is not fatal"),
+    cdp
+      ? ok("devtools port", "9222 is free")
+      : warn("devtools port", "9222 is in use", "mirin dev probes upward, so this is not fatal"),
+  ];
+}
+
+function checkLastSession(projectDir: string): DoctorCheck {
+  const dir = readCurrentSession(projectDir);
+  if (dir === undefined) return ok("last session", "none recorded yet");
+
+  const paths = sessionPaths(dir);
+  const info = readSessionInfo(paths);
+  const errors = readEventsFile(paths.events).filter((event) => event.level === "error");
+  const lastPhase = info?.phases.at(-1);
+  const phase =
+    lastPhase !== undefined ? `${lastPhase.name}=${lastPhase.status}` : "no phases recorded";
+
+  if (errors.length === 0) return ok("last session", `${phase}, no errors — ${dir}`);
+  const first = errors[0];
+  return warn(
+    "last session",
+    `${phase}, ${errors.length} error(s) — first: ${first?.msg ?? ""}`,
+    `full stream: ${paths.events}`,
+  );
+}
+
+function renderReport(report: DoctorReport): void {
+  const glyph: Record<CheckStatus, string> = { ok: "✓", warn: "!", fail: "✗" };
+  console.log(`\nmirin doctor — ${report.projectDir}\n`);
+  for (const check of report.checks) {
+    console.log(`  ${glyph[check.status]} ${check.name.padEnd(14)} ${check.detail}`);
+    if (check.fix !== undefined) console.log(`${" ".repeat(19)}→ ${check.fix}`);
+  }
+  const failures = report.checks.filter((check) => check.status === "fail").length;
+  const warnings = report.checks.filter((check) => check.status === "warn").length;
+  console.log(
+    `\n${report.ok ? "✓ ready" : `✗ ${failures} blocking problem(s)`}${warnings > 0 ? `, ${warnings} warning(s)` : ""}\n`,
+  );
+}
+
+/** Run the preflight. Exit code 0 unless a check failed outright. */
+export async function doctor(
+  projectDir = process.cwd(),
+  options: { json?: boolean } = {},
+): Promise<number> {
+  const reporter = createReporter(options.json === true);
+  const checks: DoctorCheck[] = [
+    checkPlatform(),
+    ...(await checkConfig(projectDir)),
+    ...checkUi(projectDir),
+    checkCef(),
+    ...(await checkPorts()),
+    checkLastSession(projectDir),
+  ];
+  const report: DoctorReport = {
+    ok: !checks.some((check) => check.status === "fail"),
+    projectDir,
+    platform: `${process.platform}-${process.arch}`,
+    checks,
+  };
+  reporter.finish({ ...report }, () => renderReport(report));
+  return report.ok ? 0 : 1;
+}