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

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/sources.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolve the manifest's `icon` — a path, or per-platform {@link IconSources} —
+ * to the absolute path this build's target platform should use.
+ */
+
+import { join } from "node:path";
+import type { IconSources } from "mirinjs/config";
+
+export type IconPlatform = "macos" | "windows" | "linux";
+
+export function currentIconPlatform(platform: NodeJS.Platform = process.platform): IconPlatform {
+  if (platform === "win32") return "windows";
+  if (platform === "darwin") return "macos";
+  return "linux";
+}
+
+export function resolveIconSource(
+  icon: string | IconSources | undefined,
+  projectDir: string,
+  platform: IconPlatform = currentIconPlatform(),
+): string | undefined {
+  if (!icon) return undefined;
+  const picked = typeof icon === "string" ? icon : (icon[platform] ?? icon.default);
+  return picked ? join(projectDir, picked) : undefined;
+}

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";

package/src/index.ts

@@ -1,32 +1,133 @@
 #!/usr/bin/env bun
 /**
- * mirin CLI — `dev`, `build`, `init`.
+ * mirin CLI — `dev`, `check`, `doctor`, `build`, `release`, `init`, `skill`.
  */
 
 import { resolve } from "node:path";
-import { dev } from "./dev.ts";
+import { scaffold } from "create-mirinjs";
 import { build } from "./build.ts";
+import { check } from "./check.ts";
+import { dev } from "./dev.ts";
+import { doctor } from "./doctor.ts";
+import { parseLinuxFormats } from "./package/linux/index.ts";
 import { release } from "./release.ts";
-import { scaffold } from "create-mirinjs";
+import { skill } from "./skill.ts";
 
-const [command, arg] = Bun.argv.slice(2);
+/** Minimal flag parser: `--k=v`, `--k v`, and boolean `--k`; the rest are positionals. */
+function parseArgs(argv: string[]): {
+  positionals: string[];
+  opts: Record<string, string | boolean>;
+} {
+  const opts: Record<string, string | boolean> = {};
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === undefined) continue;
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) {
+        opts[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+          opts[key] = next;
+          i++;
+        } else {
+          opts[key] = true;
+        }
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { positionals, opts };
+}
+
+const [command, ...rest] = Bun.argv.slice(2);
+const { positionals, opts } = parseArgs(rest);
+const arg = positionals[0];
 
 const USAGE = `mirin — build desktop apps with Bun + Chromium
 
 Usage:
   mirin dev          run the app against the Vite dev server (HMR + typed RPC)
-  mirin build        package a standalone, signed .app (output: ./build)
+  mirin check        boot once, capture a screenshot + UI snapshot, report, exit
+  mirin doctor       check the project and environment without building
+  mirin build        package a standalone app (output: ./build)
   mirin release      build + emit update artifacts (output: ./build/release)
   mirin init [dir]   scaffold a new app
+  mirin skill        install the agent skill into this project (.claude/skills/mirin)
+
+Options (build):
+  --version <v>              override the app version (else package.json)
+  --linux                    also emit Linux packages (AppImage + .deb + .rpm)
+  --linux-target <a,b,…>     restrict Linux packaging to these formats
+                             (appimage,deb,rpm) — implies --linux
+
+Options (check):
+  --timeout <ms>             how long to wait for a window (default 45000)
+  --settle <ms>              quiet time before capturing (default 1000)
+  --scenario <file>          drive the app with a scenario before capturing;
+                             the file default-exports defineCheck(async app => …)
+
+Options (check, doctor, dev, build):
+  --json                     machine-readable output on stdout
 `;
 
+/** `--flag <n>` as a positive integer, or undefined when absent/unusable. */
+function intOpt(key: string): number | undefined {
+  const raw = opts[key];
+  if (typeof raw !== "string") return undefined;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+const asJson = opts.json === true;
+
 switch (command) {
   case "dev": {
-    process.exit(await dev());
+    process.exit(await dev(process.cwd(), asJson ? { json: true } : undefined));
+    break;
+  }
+  case "check": {
+    process.exit(
+      await check(process.cwd(), {
+        json: asJson,
+        ...(intOpt("timeout") !== undefined ? { timeoutMs: intOpt("timeout") } : {}),
+        ...(intOpt("settle") !== undefined ? { settleMs: intOpt("settle") } : {}),
+        ...(typeof opts.scenario === "string" ? { scenario: opts.scenario } : {}),
+      }),
+    );
+    break;
+  }
+  case "doctor": {
+    process.exit(await doctor(process.cwd(), { json: asJson }));
+    break;
+  }
+  case "skill": {
+    process.exit(await skill(process.cwd(), { json: asJson }));
     break;
   }
   case "build": {
-    await build();
+    const version = typeof opts.version === "string" ? opts.version : undefined;
+    const target = typeof opts["linux-target"] === "string" ? opts["linux-target"] : undefined;
+    const linuxFormats = target ? parseLinuxFormats(target) : undefined;
+    const packageLinux = opts.linux === true || linuxFormats != null;
+    const result = await build(process.cwd(), { version, packageLinux, linuxFormats });
+    if (asJson) {
+      // Only what a caller needs; the rest of BuildResult is plumbing for `mirin release`.
+      console.log(
+        JSON.stringify({
+          phase: "result",
+          app: result.app,
+          appName: result.appName,
+          bundleId: result.bundleId,
+          version: result.version,
+          channel: result.channel,
+        }),
+      );
+    }
     process.exit(0);
     break;
   }
@@ -39,6 +140,7 @@ switch (command) {
     try {
       const name = scaffold(targetDir);
       console.log(`\n✓ Created ${name} in ${arg ?? "my-mirin-app"}`);
+      console.log("  .claude/skills/mirin/ — agent skill for verifying changes");
       console.log("  bun install && bun run dev");
       process.exit(0);
     } catch (err) {