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

package/src/{bundle.ts → bundle/macos/app.ts}

@@ -11,9 +11,19 @@
  * "<exe> Helper (Renderer).app/Contents/MacOS/<exe> Helper (Renderer)".
  */
 
-import { $ } from "bun";
-import { cpSync, mkdirSync, rmSync, writeFileSync, existsSync, readdirSync, chmodSync } from "node:fs";
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
+import { $ } from "bun";
+import { isIconComposerDoc, writeAppearanceCatalog } from "../../icons/macos/index.ts";
+import { pruneMacCefLocales } from "../shared/cef-locales.ts";
 
 const FRAMEWORK = "Chromium Embedded Framework.framework";
 
@@ -33,9 +43,14 @@ export interface BundleOptions {
   coreDylib: string; // libmirin_core.dylib
   helperBin: string; // compiled mirin-helper binary
   cefPath: string; // dir containing the CEF framework (vendor/cef)
+  /** Production CEF locale allowlist. Undefined keeps every locale. */
+  cefLocales?: string[];
   /** App version → Info.plist CFBundleShortVersionString/CFBundleVersion. */
   version?: string;
-  /** App icon source: a .icns, a .iconset dir, or a square .png. Optional. */
+  /**
+   * App icon source: a .icns, a .iconset dir, a square .png, or an Icon Composer
+   * .icon document (the only form carrying appearance variants). Optional.
+   */
   icon?: string;
   /** Codesign identity; "-" (default) is ad-hoc. Set to a Developer ID to ship. */
   signIdentity?: string;
@@ -98,19 +113,8 @@ const ICONSET_RENDITIONS = [
   { name: "icon_512x512@2x.png", px: 1024 },
 ];
 
-/**
- * Render the app icon to `Resources/icon.icns` and return the CFBundleIconFile
- * stem ("icon"), or undefined if there's no usable source. Accepts a `.icns`
- * (copied), a `.iconset` directory (iconutil), or a square `.png` (rendered to
- * a full iconset via sips, then iconutil).
- */
-async function writeIcon(iconSrc: string, resources: string): Promise<string | undefined> {
-  if (!existsSync(iconSrc)) {
-    console.warn(`[mirin] icon not found, skipping: ${iconSrc}`);
-    return undefined;
-  }
-  const icns = join(resources, "icon.icns");
-
+/** Render one icon source to `Resources/icon.icns`. */
+async function writeIcns(iconSrc: string, icns: string, resources: string): Promise<void> {
   if (iconSrc.endsWith(".icns")) {
     cpSync(iconSrc, icns);
   } else if (iconSrc.endsWith(".iconset")) {
@@ -125,7 +129,38 @@ async function writeIcon(iconSrc: string, resources: string): Promise<string | u
     await $`iconutil -c icns ${iconset} -o ${icns}`.quiet();
     rmSync(iconset, { recursive: true, force: true });
   }
-  return "icon";
+}
+
+/** The Info.plist keys an icon contributes, empty when there's no usable source. */
+interface IconKeys {
+  /** CFBundleIconFile — `Resources/icon.icns`, read by macOS 25 and earlier. */
+  iconFile?: string;
+  /** CFBundleIconName — `Resources/Assets.car`, preferred on macOS 26+. */
+  iconName?: string;
+}
+
+/**
+ * Render the app icon into Resources. An `.icon` document compiles to an
+ * `Assets.car` (macOS 26+ light/dark/tinted) and contributes the `.icns` actool
+ * derives from it; every other source takes the plain iconutil path.
+ */
+async function writeIcon(iconSrc: string, resources: string, work: string): Promise<IconKeys> {
+  if (!existsSync(iconSrc)) {
+    console.warn(`[mirin] icon not found, skipping: ${iconSrc}`);
+    return {};
+  }
+
+  const icns = join(resources, "icon.icns");
+  if (isIconComposerDoc(iconSrc)) {
+    // An Icon Composer document can't go through iconutil, so the only .icns
+    // available for it is the one actool derives.
+    const catalog = await writeAppearanceCatalog(iconSrc, resources, work);
+    if (catalog?.icns) cpSync(catalog.icns, icns);
+    return { iconFile: existsSync(icns) ? "icon" : undefined, iconName: catalog?.name };
+  }
+
+  await writeIcns(iconSrc, icns, resources);
+  return { iconFile: "icon" };
 }
 
 type PlistValue = string | boolean | PlistValue[] | { [k: string]: PlistValue };
@@ -177,8 +212,12 @@ export async function buildAppBundle(opts: BundleOptions): Promise<{ app: string
   cpSync(opts.coreDylib, join(macos, "libmirin_core.dylib"));
 
   // Render the icon (if any) into Resources before writing the plist, so we
-  // only set CFBundleIconFile when an icon was actually produced.
-  const iconFile = opts.icon ? await writeIcon(opts.icon, join(contents, "Resources")) : undefined;
+  // only set the icon keys when an icon was actually produced.
+  const iconWork = join(opts.outDir, ".mirin-icon");
+  const { iconFile, iconName } = opts.icon
+    ? await writeIcon(opts.icon, join(contents, "Resources"), iconWork)
+    : ({} as IconKeys);
+  rmSync(iconWork, { recursive: true, force: true });
   const version = opts.version ?? "0.0.1";
 
   const info: Record<string, PlistValue> = {
@@ -198,20 +237,23 @@ export async function buildAppBundle(opts: BundleOptions): Promise<{ app: string
     LSEnvironment: { MallocNanoZone: "0" },
   };
   if (iconFile) info.CFBundleIconFile = iconFile;
+  // macOS 26+ resolves the appearance-aware icon out of Assets.car via this key
+  // and falls back to CFBundleIconFile when the catalog has no match.
+  if (iconName) info.CFBundleIconName = iconName;
   // Deep-link schemes: register this app as the macOS handler for app://-style
   // URLs (e.g. anko://…). Delivered at runtime via app.on("open-url").
   if (opts.urlSchemes?.length) {
-    info.CFBundleURLTypes = [
-      { CFBundleURLName: bundleId, CFBundleURLSchemes: opts.urlSchemes },
-    ];
+    info.CFBundleURLTypes = [{ CFBundleURLName: bundleId, CFBundleURLSchemes: opts.urlSchemes }];
   }
 
   writeFileSync(join(contents, "Info.plist"), plist(info));
 
-  cpSync(join(cefPath, FRAMEWORK), join(frameworks, FRAMEWORK), {
+  const bundledFramework = join(frameworks, FRAMEWORK);
+  cpSync(join(cefPath, FRAMEWORK), bundledFramework, {
     recursive: true,
     verbatimSymlinks: true,
   });
+  pruneMacCefLocales(bundledFramework, opts.cefLocales);
 
   // Production resources: the served UI, the Worker bundle, and the manifest.
   const resources = join(contents, "Resources");

package/src/bundle/macos/index.ts

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

package/src/bundle/shared/cef-locales.ts

@@ -0,0 +1,91 @@
+import { cpSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+const CEF_LOCALE = /^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})*$/;
+const MAC_VARIANTS = new Set(["FEMININE", "MASCULINE", "NEUTER"]);
+
+/** Validate and normalize an optional CEF locale allowlist. */
+export function normalizeCefLocales(locales: unknown): string[] | undefined {
+  if (locales == null) return undefined;
+  if (!Array.isArray(locales) || locales.length === 0) {
+    throw new Error("[mirin] cef.locales must contain at least one locale.");
+  }
+
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const value of locales) {
+    if (typeof value !== "string" || !CEF_LOCALE.test(value)) {
+      throw new Error(`[mirin] invalid CEF locale ${JSON.stringify(value)}.`);
+    }
+    const locale = value.replaceAll("_", "-");
+    const key = locale.toLowerCase();
+    if (!seen.has(key)) {
+      seen.add(key);
+      normalized.push(locale);
+    }
+  }
+  return normalized;
+}
+
+/** Copy selected Windows/Linux `locales/<locale>.pak` files, or every locale when unset. */
+export function copyFlatCefLocales(
+  source: string,
+  destination: string,
+  locales: string[] | undefined,
+): void {
+  if (!locales) {
+    cpSync(source, destination, { recursive: true });
+    return;
+  }
+
+  const entries = readdirSync(source, { withFileTypes: true }).filter(
+    (entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".pak"),
+  );
+  const byLocale = new Map(
+    entries.map((entry) => [localeKey(entry.name.slice(0, -".pak".length)), entry.name]),
+  );
+
+  mkdirSync(destination, { recursive: true });
+  for (const locale of locales) {
+    const file = byLocale.get(localeKey(locale));
+    if (!file) throw new Error(`[mirin] CEF locale "${locale}" is not available in ${source}.`);
+    cpSync(join(source, file), join(destination, file));
+  }
+}
+
+/** Remove unselected macOS `.lproj` locale directories from a copied CEF framework. */
+export function pruneMacCefLocales(framework: string, locales: string[] | undefined): void {
+  if (!locales) return;
+
+  const resources = join(framework, "Resources");
+  const localeDirs = readdirSync(resources, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.endsWith(".lproj"))
+    .map((entry) => entry.name);
+  const available = new Set(localeDirs.map((name) => name.slice(0, -".lproj".length)));
+  const keep = new Set<string>();
+
+  for (const locale of locales) {
+    const requested = locale.replaceAll("-", "_");
+    const language = requested.split("_", 1)[0] ?? requested;
+    const root = available.has(requested)
+      ? requested
+      : available.has(language)
+        ? language
+        : undefined;
+    if (!root) throw new Error(`[mirin] CEF locale "${locale}" is not available in ${resources}.`);
+
+    keep.add(`${root}.lproj`);
+    for (const variant of MAC_VARIANTS) {
+      const name = `${root}_${variant}.lproj`;
+      if (localeDirs.includes(name)) keep.add(name);
+    }
+  }
+
+  for (const directory of localeDirs) {
+    if (!keep.has(directory)) rmSync(join(resources, directory), { recursive: true, force: true });
+  }
+}
+
+function localeKey(locale: string): string {
+  return locale.replaceAll("_", "-").toLowerCase();
+}

package/src/{bundle-win.ts → bundle/windows/app.ts}

@@ -15,9 +15,10 @@
  * what mirin-core derives at runtime (engine::derive_subprocess_path, host.ts).
  */
 
-import { cpSync, mkdirSync, rmSync, writeFileSync, existsSync, readdirSync } from "node:fs";
-import { join, extname } from "node:path";
-import { makeWindowsIcon } from "./icon-win.ts";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import { makeWindowsIcon } from "../../icons/windows/index.ts";
+import { copyFlatCefLocales } from "../shared/cef-locales.ts";
 
 /** Source dir (vendor/cef on Windows) must contain libcef.dll. */
 const CEF_MARKER = "libcef.dll";
@@ -26,7 +27,7 @@ const CEF_MARKER = "libcef.dll";
  *  distribution (libcef.lib, include/, cmake/, archive.json, bootstrap*.exe) is
  *  build-time only and intentionally left out. */
 const CEF_RUNTIME_EXTS = new Set([".dll", ".bin", ".pak", ".dat"]);
-const CEF_RUNTIME_EXTRAS = ["vk_swiftshader_icd.json", "locales"];
+const CEF_RUNTIME_EXTRAS = ["vk_swiftshader_icd.json"];
 
 export interface WinBundleOptions {
   appName: string; // also the host exe stem → <appName>.exe
@@ -35,6 +36,8 @@ export interface WinBundleOptions {
   coreDll: string; // mirin_core.dll
   helperExe: string; // mirin-helper.exe
   cefPath: string; // dir containing the Windows CEF runtime (vendor/cef)
+  /** Production CEF locale allowlist. Undefined keeps every locale. */
+  cefLocales?: string[];
   /** App icon source (.ico / .iconset / .png) → <App>/icon.ico, set as the window icon. */
   icon?: string;
   /** Production-only resources placed under <App>/resources. */
@@ -66,7 +69,7 @@ export async function buildWindowsBundle(
   cpSync(opts.coreDll, join(app, "mirin_core.dll"));
   cpSync(opts.helperExe, join(app, "mirin-helper.exe"));
 
-  copyCefRuntime(cefPath, app);
+  copyCefRuntime(cefPath, app, opts.cefLocales);
 
   // App icon → <App>/icon.ico, loaded at runtime by the core and set as the window
   // icon (taskbar / Alt-Tab / title). Sits beside the exe so the core finds it.
@@ -105,7 +108,7 @@ export async function buildWindowsBundle(
 }
 
 /** Copy the CEF runtime (dlls, paks, snapshot, icu data, locales) into `dest`. */
-function copyCefRuntime(cefPath: string, dest: string): void {
+function copyCefRuntime(cefPath: string, dest: string, locales: string[] | undefined): void {
   for (const entry of readdirSync(cefPath)) {
     if (CEF_RUNTIME_EXTS.has(extname(entry).toLowerCase())) {
       cpSync(join(cefPath, entry), join(dest, entry));
@@ -115,4 +118,5 @@ function copyCefRuntime(cefPath: string, dest: string): void {
     const src = join(cefPath, extra);
     if (existsSync(src)) cpSync(src, join(dest, extra), { recursive: true });
   }
+  copyFlatCefLocales(join(cefPath, "locales"), join(dest, "locales"), locales);
 }

package/src/bundle/windows/index.ts

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

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;
+}