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

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

package/src/extras.ts

@@ -5,10 +5,12 @@
  * place so the two CLI paths stay in sync.
  */
 
+import { mkdirSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { $ } from "bun";
-import { join } from "node:path";
+import { createReporter, type Reporter } from "./shared/report.ts";
 
-/** Config shapes (mirrors packages/mirin/src/config.ts; CLI can't import the runtime). */
+/** Config shapes (mirrors packages/mirin/src/config/index.ts; CLI can't import the runtime). */
 export type SidecarConfig = Record<string, string | { bin: string; entitlements?: string[] }>;
 export type WorkersConfig = Record<string, string>;
 
@@ -21,16 +23,47 @@ export interface NormalizedSidecar {
   entitlements: string[];
 }
 
+const SAFE_EXTRA_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * Extra asset names become bundle filenames, so keep them as path segments. This
+ * prevents config keys such as "../tool" from escaping resources/sidecars or
+ * resources/workers in dev and production bundles.
+ */
+export function safeExtraAssetName(name: string, label: string): string {
+  if (!SAFE_EXTRA_NAME.test(name) || name === "." || name === "..") {
+    throw new Error(
+      `[mirin] invalid ${label} "${name}" — use letters, digits, ".", "_" or "-", ` +
+        "and do not include path separators.",
+    );
+  }
+  return name;
+}
+
+function projectRelativePath(projectDir: string, file: string, label: string): string {
+  if (isAbsolute(file)) {
+    throw new Error(`[mirin] ${label} must be relative to the project root: ${file}`);
+  }
+  const root = resolve(projectDir);
+  const full = resolve(root, file);
+  const rel = relative(root, full);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`[mirin] ${label} escapes the project root: ${file}`);
+  }
+  return full;
+}
+
 /** Resolve `config.sidecars` to absolute source paths. */
 export function normalizeSidecars(
   projectDir: string,
   sidecars: SidecarConfig | undefined,
 ): NormalizedSidecar[] {
   return Object.entries(sidecars ?? {}).map(([name, value]) => {
+    const safeName = safeExtraAssetName(name, "sidecar name");
     const spec = typeof value === "string" ? { bin: value } : value;
     return {
-      name,
-      src: join(projectDir, spec.bin),
+      name: safeName,
+      src: projectRelativePath(projectDir, spec.bin, `sidecar "${safeName}" path`),
       entitlements: spec.entitlements ?? [],
     };
   });
@@ -45,17 +78,23 @@ export async function compileWorkers(
   workers: WorkersConfig | undefined,
   outDir: string,
   minify: boolean,
+  /** Where `bun build`'s output goes. Defaults to human mode, which prints it. */
+  reporter: Reporter = createReporter(false),
 ): Promise<Record<string, string>> {
+  mkdirSync(outDir, { recursive: true });
   const out: Record<string, string> = {};
-  for (const [name, entry] of Object.entries(workers ?? {})) {
-    const js = join(outDir, `${name}.js`);
-    const src = join(projectDir, entry);
-    if (minify) {
-      await $`bun build ${src} --target=bun --minify --outfile ${js}`.cwd(projectDir);
-    } else {
-      await $`bun build ${src} --target=bun --outfile ${js}`.cwd(projectDir);
-    }
-    out[name] = js;
+  const compiled = Object.entries(workers ?? {}).map(async ([name, entry]) => {
+    const safeName = safeExtraAssetName(name, "worker name");
+    const js = join(outDir, `${safeName}.js`);
+    const src = projectRelativePath(projectDir, entry, `worker "${safeName}" entry`);
+    const minifyFlag = minify ? ["--minify"] : [];
+    await reporter.build(
+      $`bun build ${src} --target=bun ${minifyFlag} --outfile ${js}`.cwd(projectDir),
+    );
+    return { name: safeName, js };
+  });
+  for (const worker of await Promise.all(compiled)) {
+    out[worker.name] = worker.js;
   }
   return out;
 }

package/src/icons/macos/appearance.ts

@@ -0,0 +1,96 @@
+/**
+ * Compile macOS appearance-variant app icons (light / dark / tinted, macOS 26+).
+ *
+ * `.icns` has no notion of appearance — the Dock picks a variant out of a
+ * compiled asset catalog keyed by `CFBundleIconName`, and the only input that
+ * produces one is an Icon Composer `.icon` document. `actool` compiles it to
+ * the same `Assets.car` shape Apple's own bundled apps ship.
+ *
+ * Best-effort throughout: `actool` only ships with a full Xcode, so a machine
+ * with just Command Line Tools warns and keeps the plain `.icns`.
+ */
+
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { $ } from "bun";
+
+/** True when the source is an Icon Composer document, which actool reads directly. */
+export const isIconComposerDoc = (path: string): boolean => path.endsWith(".icon");
+
+/** Asset-catalog icon name; also the `CFBundleIconName` written to Info.plist. */
+const ICON_NAME = "AppIcon";
+
+/**
+ * Locate `actool`. `xcrun` honours the selected developer dir, which is often
+ * Command Line Tools (no actool), so fall back to a full Xcode if one is
+ * installed but not selected.
+ */
+async function findActool(): Promise<string | undefined> {
+  const xcrun = await $`xcrun --find actool`.nothrow().quiet();
+  if (xcrun.exitCode === 0) {
+    const path = xcrun.stdout.toString().trim();
+    if (path && existsSync(path)) return path;
+  }
+  for (const app of ["/Applications/Xcode.app", "/Applications/Xcode-beta.app"]) {
+    const path = join(app, "Contents/Developer/usr/bin/actool");
+    if (existsSync(path)) return path;
+  }
+  return undefined;
+}
+
+export interface AppearanceCatalog {
+  /** Goes in Info.plist as `CFBundleIconName`. */
+  name: string;
+  /** The legacy `.icns` actool derives alongside the catalog, if it emitted one. */
+  icns?: string;
+}
+
+/**
+ * Compile `icon` into `<Resources>/Assets.car`, or return undefined if the
+ * catalog could not be built (no actool, unreadable art) — callers then keep
+ * the plain `.icns` path.
+ */
+export async function writeAppearanceCatalog(
+  iconDoc: string,
+  resourcesDir: string,
+  workDir: string,
+): Promise<AppearanceCatalog | undefined> {
+  // actool resolves its own arguments, so hand it absolute paths regardless of
+  // what the caller passed and of the subprocess working directory.
+  const resources = resolve(resourcesDir);
+  const work = resolve(workDir);
+  const actool = await findActool();
+  if (!actool) {
+    console.warn(
+      "[mirin] actool not found — appearance variants need a full Xcode " +
+        "(Command Line Tools alone is not enough); shipping the default icon only.",
+    );
+    return undefined;
+  }
+
+  rmSync(work, { recursive: true, force: true });
+  mkdirSync(work, { recursive: true });
+
+  const doc = join(work, `${ICON_NAME}.icon`);
+  cpSync(iconDoc, doc, { recursive: true });
+
+  const compiled = join(work, "compiled");
+  mkdirSync(compiled, { recursive: true });
+  const res =
+    await $`${actool} --output-format human-readable-text --notices --warnings --app-icon ${ICON_NAME} --output-partial-info-plist ${join(work, "partial.plist")} --enable-on-demand-resources NO --target-device mac --minimum-deployment-target 26.0 --platform macosx --compile ${compiled} ${doc}`
+      .nothrow()
+      .quiet();
+
+  const car = join(compiled, "Assets.car");
+  if (res.exitCode !== 0 || !existsSync(car)) {
+    console.warn(
+      `[mirin] actool failed (exit ${res.exitCode}) — shipping the default icon only.\n` +
+        res.stdout.toString().trim(),
+    );
+    return undefined;
+  }
+
+  cpSync(car, join(resources, "Assets.car"));
+  const icns = join(compiled, `${ICON_NAME}.icns`);
+  return { name: ICON_NAME, icns: existsSync(icns) ? icns : undefined };
+}

package/src/icons/macos/index.ts

@@ -0,0 +1 @@
+export { isIconComposerDoc, writeAppearanceCatalog } from "./appearance.ts";

package/src/icons/windows/icon.ts

@@ -0,0 +1,255 @@
+/**
+ * Produce a Windows `.ico` from the app's icon source (mirrors the macOS `.icns`
+ * path in `bundle.ts`). Emits **classic DIB/BMP icon entries** (32bpp BGRA + AND
+ * mask), NOT PNG-compressed entries: Bun's `--windows-icon` embedder silently
+ * ignores PNG-format ICOs (the exe keeps Bun's default icon), and some shells
+ * mis-scale them. Accepts a `.ico` (copied), a `.iconset` directory (its
+ * `icon_NxN.png` renditions), or a single square `.png`.
+ */
+
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { inflateSync } from "node:zlib";
+
+/** Standard Windows icon sizes; intermediate sizes are downscaled from these by
+ *  the shell, so the 256 entry keeps large views crisp. */
+const ICO_SIZES = [16, 32, 48, 64, 128, 256];
+
+interface IcoEntry {
+  size: number;
+  /** DIB image (small sizes) or raw PNG bytes (256) — see {@link rendition}. */
+  data: Buffer;
+  /** True when `data` is a PNG blob (the 256 convention) rather than a DIB. */
+  png: boolean;
+}
+
+/**
+ * Minimal PNG decoder → top-down RGBA. Handles 8-bit, non-interlaced, color
+ * types 0/2/4/6 (the renditions macOS `iconutil`/`sips` and design tools emit).
+ * Throws on anything else so the caller skips just that rendition.
+ */
+function decodePng(buf: Buffer): { width: number; height: number; rgba: Buffer } {
+  if (buf.readUInt32BE(0) !== 0x89504e47) throw new Error("not a PNG");
+  let width = 0;
+  let height = 0;
+  let bitDepth = 0;
+  let colorType = 0;
+  let interlace = 0;
+  const idat: Buffer[] = [];
+  let pos = 8;
+  while (pos + 8 <= buf.length) {
+    const len = buf.readUInt32BE(pos);
+    const type = buf.toString("latin1", pos + 4, pos + 8);
+    const data = buf.subarray(pos + 8, pos + 8 + len);
+    if (type === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      bitDepth = data[8]!;
+      colorType = data[9]!;
+      interlace = data[12]!;
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+    pos += 12 + len;
+  }
+  if (bitDepth !== 8 || interlace !== 0) {
+    throw new Error(`unsupported PNG (depth ${bitDepth}, interlace ${interlace})`);
+  }
+  const channels =
+    colorType === 6 ? 4 : colorType === 2 ? 3 : colorType === 4 ? 2 : colorType === 0 ? 1 : 0;
+  if (!channels) throw new Error(`unsupported color type ${colorType}`);
+
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const rgba = Buffer.alloc(width * height * 4);
+  let prev = Buffer.alloc(stride);
+  let rp = 0;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[rp++]!;
+    const cur = Buffer.from(raw.subarray(rp, rp + stride));
+    rp += stride;
+    unfilter(filter, cur, prev, channels);
+    for (let x = 0; x < width; x++) {
+      const s = x * channels;
+      let r: number;
+      let g: number;
+      let b: number;
+      let a: number;
+      if (channels === 4) {
+        r = cur[s]!;
+        g = cur[s + 1]!;
+        b = cur[s + 2]!;
+        a = cur[s + 3]!;
+      } else if (channels === 3) {
+        r = cur[s]!;
+        g = cur[s + 1]!;
+        b = cur[s + 2]!;
+        a = 255;
+      } else if (channels === 2) {
+        r = g = b = cur[s]!;
+        a = cur[s + 1]!;
+      } else {
+        r = g = b = cur[s]!;
+        a = 255;
+      }
+      const d = (y * width + x) * 4;
+      rgba[d] = r;
+      rgba[d + 1] = g;
+      rgba[d + 2] = b;
+      rgba[d + 3] = a;
+    }
+    prev = cur;
+  }
+  return { width, height, rgba };
+}
+
+/** Reverse a PNG scanline filter in place (None/Sub/Up/Average/Paeth). */
+function unfilter(filter: number, cur: Buffer, prev: Buffer, bpp: number): void {
+  for (let i = 0; i < cur.length; i++) {
+    const a = i >= bpp ? cur[i - bpp]! : 0;
+    const b = prev[i]!;
+    const c = i >= bpp ? prev[i - bpp]! : 0;
+    let v = cur[i]!;
+    if (filter === 1) v += a;
+    else if (filter === 2) v += b;
+    else if (filter === 3) v += (a + b) >> 1;
+    else if (filter === 4) {
+      const p = a + b - c;
+      const pa = Math.abs(p - a);
+      const pb = Math.abs(p - b);
+      const pc = Math.abs(p - c);
+      v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+    }
+    cur[i] = v & 0xff;
+  }
+}
+
+/** Encode one icon image as a DIB: BITMAPINFOHEADER + bottom-up 32bpp BGRA + a
+ *  (zeroed) 1bpp AND mask — the alpha channel drives transparency. */
+function dibEntry(size: number, rgba: Buffer): Buffer {
+  const xor = Buffer.alloc(size * size * 4);
+  for (let dy = 0; dy < size; dy++) {
+    const sy = size - 1 - dy; // DIB rows run bottom-to-top
+    for (let x = 0; x < size; x++) {
+      const s = (sy * size + x) * 4;
+      const d = (dy * size + x) * 4;
+      xor[d] = rgba[s + 2]!; // B
+      xor[d + 1] = rgba[s + 1]!; // G
+      xor[d + 2] = rgba[s]!; // R
+      xor[d + 3] = rgba[s + 3]!; // A
+    }
+  }
+  const andStride = Math.ceil(size / 32) * 4; // 1bpp, rows padded to 4 bytes
+  const andMask = Buffer.alloc(andStride * size, 0);
+  const hdr = Buffer.alloc(40);
+  hdr.writeUInt32LE(40, 0); // biSize
+  hdr.writeInt32LE(size, 4); // biWidth
+  hdr.writeInt32LE(size * 2, 8); // biHeight = XOR rows + AND rows
+  hdr.writeUInt16LE(1, 12); // biPlanes
+  hdr.writeUInt16LE(32, 14); // biBitCount
+  hdr.writeUInt32LE(0, 16); // BI_RGB
+  hdr.writeUInt32LE(xor.length + andMask.length, 20);
+  return Buffer.concat([hdr, xor, andMask]);
+}
+
+/** Assemble the ICONDIR + entries into a `.ico`. */
+function packIco(entries: IcoEntry[]): Buffer {
+  const dirSize = 6 + entries.length * 16;
+  const dir = Buffer.alloc(dirSize);
+  dir.writeUInt16LE(0, 0); // reserved
+  dir.writeUInt16LE(1, 2); // type 1 = icon
+  dir.writeUInt16LE(entries.length, 4);
+  let offset = dirSize;
+  entries.forEach((e, i) => {
+    const base = 6 + i * 16;
+    dir[base] = e.size >= 256 ? 0 : e.size; // width (0 = 256)
+    dir[base + 1] = e.size >= 256 ? 0 : e.size; // height
+    dir.writeUInt16LE(1, base + 4); // planes
+    dir.writeUInt16LE(32, base + 6); // bits per pixel
+    dir.writeUInt32LE(e.data.length, base + 8); // bytes in resource
+    dir.writeUInt32LE(offset, base + 12); // image offset
+    offset += e.data.length;
+  });
+  return Buffer.concat([dir, ...entries.map((e) => e.data)]);
+}
+
+/**
+ * Build one icon entry from a square PNG rendition. Sizes ≥256 are stored as the
+ * raw PNG blob (the Windows convention — a 256×256 DIB is non-standard and is
+ * rejected by Bun/rcedit/the resource compiler); smaller sizes are decoded to a
+ * DIB. Returns undefined if the file isn't the expected square size.
+ */
+function rendition(file: string, size: number): IcoEntry | undefined {
+  try {
+    const buf = readFileSync(file);
+    if (size >= 256) return { size, data: buf, png: true };
+    const { width, height, rgba } = decodePng(buf);
+    if (width !== size || height !== size) return undefined;
+    return { size, data: dibEntry(size, rgba), png: false };
+  } catch (e) {
+    console.warn(`[mirin] icon: skipping ${file} (${e instanceof Error ? e.message : e})`);
+    return undefined;
+  }
+}
+
+/**
+ * Write `outPath` (an `.ico`) from `iconSrc`, returning it, or undefined if no
+ * usable source was found. With `onlyLargest`, emits a single (largest) entry —
+ * needed for the **exe** icon, since rcedit's multi-size icon replacement fails on
+ * Bun-compiled exes (single-entry works, and Windows downscales 256 cleanly for
+ * small views). The full multi-size form is fine for `icon.ico` (NSIS + WM_SETICON).
+ */
+export function makeWindowsIcon(
+  iconSrc: string,
+  outPath: string,
+  opts?: { onlyLargest?: boolean },
+): string | undefined {
+  if (!existsSync(iconSrc)) {
+    console.warn(`[mirin] icon not found, skipping: ${iconSrc}`);
+    return undefined;
+  }
+  if (iconSrc.endsWith(".ico")) {
+    copyFileSync(iconSrc, outPath);
+    return outPath;
+  }
+
+  const entries: IcoEntry[] = [];
+  if (iconSrc.endsWith(".iconset")) {
+    const sizes = opts?.onlyLargest ? [...ICO_SIZES].reverse() : ICO_SIZES;
+    for (const size of sizes) {
+      const png = join(iconSrc, `icon_${size}x${size}.png`);
+      if (existsSync(png)) {
+        const e = rendition(png, size);
+        if (e) {
+          entries.push(e);
+          if (opts?.onlyLargest) break;
+        }
+      }
+    }
+  } else if (iconSrc.endsWith(".png")) {
+    try {
+      const buf = readFileSync(iconSrc);
+      const { width, height, rgba } = decodePng(buf);
+      if (width !== height || width > 256) {
+        console.warn(`[mirin] icon png must be square ≤256px (got ${width}×${height})`);
+      } else if (width === 256) {
+        entries.push({ size: 256, data: buf, png: true });
+      } else {
+        entries.push({ size: width, data: dibEntry(width, rgba), png: false });
+      }
+    } catch (e) {
+      console.warn(
+        `[mirin] icon: cannot decode ${iconSrc} (${e instanceof Error ? e.message : e})`,
+      );
+    }
+  }
+
+  if (!entries.length) {
+    console.warn(`[mirin] no usable icon renditions in ${iconSrc}`);
+    return undefined;
+  }
+  writeFileSync(outPath, packIco(entries));
+  return outPath;
+}

package/src/icons/windows/index.ts

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