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

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) {

package/src/installer-inno.ts

@@ -0,0 +1,141 @@
+/**
+ * Windows installer via **Inno Setup** — a modern, clean wizard (the installer VS
+ * Code ships). Generates an `.iss` script from the app folder + config and compiles
+ * it with `iscc`. Like the NSIS path it installs per-user (`%LOCALAPPDATA%\Programs`,
+ * no elevation) or per-machine (Program Files), creates Start Menu + Desktop
+ * shortcuts, and registers an uninstaller / Add-Remove-Programs entry — but with
+ * Inno's `WizardStyle=modern` flat UI instead of NSIS's dated one.
+ *
+ * Requires `iscc` (Inno Setup 6+) on PATH; the caller checks `hasInno()` and falls
+ * back to NSIS / the portable `.zip` when it's absent.
+ */
+
+import { existsSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { $ } from "bun";
+import type { InnoConfig } from "mirinjs";
+import { makeWindowsIcon } from "./icons/windows/index.ts";
+
+export interface BuildInnoInput {
+  appDir: string; // the assembled app folder (build/<App>)
+  appName: string;
+  exeName: string; // <App>.exe
+  version: string;
+  bundleId: string; // reverse-DNS id → AppId / uninstall key
+  outDir: string; // build/release
+  fileName: string; // e.g. stable-win32-x64-Anko-setup.exe
+  options: InnoConfig;
+  projectDir: string;
+}
+
+/** Whether the Inno Setup compiler `iscc` is on PATH. */
+export function hasInno(): boolean {
+  return Bun.which("iscc") != null;
+}
+
+const resolve = (projectDir: string, p: string) => (isAbsolute(p) ? p : join(projectDir, p));
+/** Escape an Inno directive value: `{` is the constant sigil. */
+const v = (s: string) => s.replace(/\{/g, "{{");
+
+/** Build the installer with `iscc`, returning the setup.exe path. */
+export async function buildInnoInstaller(input: BuildInnoInput): Promise<string> {
+  const { appDir, appName, exeName, version, bundleId, outDir, fileName, options, projectDir } =
+    input;
+  const out = join(outDir, fileName);
+  rmSync(out, { force: true });
+  if (!fileName.endsWith(".exe")) throw new Error("inno: fileName must end with .exe");
+  const baseName = fileName.slice(0, -".exe".length);
+
+  const perMachine = options.perMachine === true;
+  const minimal = options.oneClick === true;
+  const desktop = options.desktopShortcut !== false;
+  const startMenu = options.startMenuShortcut !== false;
+  const runAfter = options.runAfterFinish !== false;
+  const changeDir = options.allowChangeInstallDir !== false && !minimal;
+  const publisher = options.publisher ?? appName;
+  const installDir =
+    options.installDir ??
+    (perMachine ? "{autopf}\\" + appName : "{localappdata}\\Programs\\" + appName);
+
+  // Setup icon: an explicit .ico, else the app's bundled icon.ico.
+  let icon: string | undefined;
+  if (options.installerIcon) {
+    icon = makeWindowsIcon(resolve(projectDir, options.installerIcon), join(outDir, "_inno.ico"));
+  } else if (existsSync(join(appDir, "icon.ico"))) {
+    icon = join(appDir, "icon.ico");
+  }
+  const license = options.license ? resolve(projectDir, options.license) : undefined;
+  if (license && !existsSync(license)) throw new Error(`inno: license not found: ${license}`);
+
+  const L: string[] = [];
+  L.push("[Setup]");
+  L.push(`AppId={{${bundleId}}`);
+  L.push(`AppName=${v(appName)}`);
+  L.push(`AppVersion=${v(version)}`);
+  // Without this, Inno's display name defaults to "<name> version <x>" (shown in
+  // the wizard title + Add/Remove Programs); pin it to the app name.
+  L.push(`AppVerName=${v(appName)}`);
+  L.push(`AppPublisher=${v(publisher)}`);
+  L.push("WizardStyle=modern");
+  L.push(`DefaultDirName=${installDir}`);
+  L.push(`DefaultGroupName=${v(appName)}`);
+  L.push(`PrivilegesRequired=${perMachine ? "admin" : "lowest"}`);
+  L.push(`OutputDir=${outDir}`);
+  L.push(`OutputBaseFilename=${baseName}`);
+  // CEF is the bulk of the installer. Normal compression plus two independent
+  // LZMA2 blocks is substantially faster on CI with a modest size tradeoff.
+  L.push("Compression=lzma2/normal");
+  L.push("LZMANumBlockThreads=2");
+  L.push("SolidCompression=yes");
+  L.push("ArchitecturesAllowed=x64compatible");
+  L.push("ArchitecturesInstallIn64BitMode=x64compatible");
+  L.push(`UninstallDisplayIcon={app}\\${exeName}`);
+  if (icon) L.push(`SetupIconFile=${icon}`);
+  if (license) L.push(`LicenseFile=${license}`);
+  if (minimal) {
+    L.push("DisableWelcomePage=yes");
+    L.push("DisableReadyPage=yes");
+  }
+  if (!changeDir) L.push("DisableDirPage=yes");
+  if (!startMenu) L.push("DisableProgramGroupPage=yes");
+  if (options.include) L.push("", "; --- user include ---", options.include, "");
+
+  L.push("", "[Files]");
+  L.push(
+    `Source: "${appDir}\\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs`,
+  );
+
+  if (desktop) {
+    L.push("", "[Tasks]");
+    L.push(
+      `Name: "desktopicon"; Description: "Create a desktop shortcut"; GroupDescription: "Additional:"`,
+    );
+  }
+
+  L.push("", "[Icons]");
+  if (startMenu) L.push(`Name: "{group}\\${v(appName)}"; Filename: "{app}\\${exeName}"`);
+  if (desktop) {
+    L.push(
+      `Name: "{autodesktop}\\${v(appName)}"; Filename: "{app}\\${exeName}"; Tasks: desktopicon`,
+    );
+  }
+
+  if (runAfter) {
+    L.push("", "[Run]");
+    L.push(
+      `Filename: "{app}\\${exeName}"; Description: "Launch ${v(appName)}"; ` +
+        "Flags: nowait postinstall skipifsilent",
+    );
+  }
+
+  const script = join(outDir, "_installer.iss");
+  writeFileSync(script, L.join("\n") + "\n");
+  console.log(`[mirin release] compiling Inno Setup installer → ${fileName}`);
+  const res = await $`iscc /Q ${script}`.nothrow();
+  rmSync(script, { force: true });
+  rmSync(join(outDir, "_inno.ico"), { force: true });
+  if (res.exitCode !== 0 || !existsSync(out)) {
+    throw new Error(`iscc failed (exit ${res.exitCode})`);
+  }
+  return out;
+}

package/src/installer-win.ts

@@ -12,11 +12,11 @@
  * falls back to the portable `.zip` when it's absent.
  */
 
-import { $ } from "bun";
 import { existsSync, rmSync, writeFileSync } from "node:fs";
-import { join, isAbsolute } from "node:path";
+import { isAbsolute, join } from "node:path";
+import { $ } from "bun";
 import type { NsisConfig } from "mirinjs";
-import { makeWindowsIcon } from "./icon-win.ts";
+import { makeWindowsIcon } from "./icons/windows/index.ts";
 
 export interface BuildNsisInput {
   /** The assembled app folder (build/<App>). */
@@ -50,7 +50,8 @@ const resolve = (projectDir: string, p: string) => (isAbsolute(p) ? p : join(pro
 
 /** Build the installer with `makensis`, returning the setup.exe path. */
 export async function buildNsisInstaller(input: BuildNsisInput): Promise<string> {
-  const { appDir, appName, exeName, version, bundleId, outDir, fileName, options, projectDir } = input;
+  const { appDir, appName, exeName, version, bundleId, outDir, fileName, options, projectDir } =
+    input;
   const out = join(outDir, fileName);
   rmSync(out, { force: true });
 
@@ -63,12 +64,16 @@ export async function buildNsisInstaller(input: BuildNsisInput): Promise<string>
   const publisher = options.publisher ?? appName;
   const root = perMachine ? "HKLM" : "HKCU";
   const installDir =
-    options.installDir ?? (perMachine ? `$PROGRAMFILES64\\${appName}` : `$LOCALAPPDATA\\Programs\\${appName}`);
+    options.installDir ??
+    (perMachine ? `$PROGRAMFILES64\\${appName}` : `$LOCALAPPDATA\\Programs\\${appName}`);
 
   // Installer/uninstaller icon: an explicit .ico, else the app's bundled icon.ico.
   let icon: string | undefined;
   if (options.installerIcon) {
-    icon = makeWindowsIcon(resolve(projectDir, options.installerIcon), join(outDir, "_installer.ico"));
+    icon = makeWindowsIcon(
+      resolve(projectDir, options.installerIcon),
+      join(outDir, "_installer.ico"),
+    );
   } else if (existsSync(join(appDir, "icon.ico"))) {
     icon = join(appDir, "icon.ico");
   }
@@ -85,7 +90,7 @@ export async function buildNsisInstaller(input: BuildNsisInput): Promise<string>
   L.push(`OutFile "${nsis(out)}"`);
   L.push(`InstallDir "${installDir}"`);
   L.push(`RequestExecutionLevel ${perMachine ? "admin" : "user"}`);
-  L.push(`!define MUI_ABORTWARNING`);
+  L.push("!define MUI_ABORTWARNING");
   if (icon) {
     L.push(`!define MUI_ICON "${nsis(icon)}"`);
     L.push(`!define MUI_UNICON "${nsis(icon)}"`);
@@ -127,14 +132,15 @@ export async function buildNsisInstaller(input: BuildNsisInput): Promise<string>
   // Estimated size for Add/Remove Programs.
   L.push(`  \${GetSize} "$INSTDIR" "/S=0K" $0 $1 $2`);
   L.push(`  IntFmt $0 "0x%08X" $0`);
-  const reg = (name: string, val: string) => L.push(`  WriteRegStr ${root} "${key}" "${name}" "${val}"`);
+  const reg = (name: string, val: string) =>
+    L.push(`  WriteRegStr ${root} "${key}" "${name}" "${val}"`);
   reg("DisplayName", nsis(appName));
   reg("DisplayVersion", nsis(version));
   reg("Publisher", nsis(publisher));
   reg("DisplayIcon", `$INSTDIR\\${nsis(exeName)}`);
   reg("InstallLocation", "$INSTDIR");
-  reg("UninstallString", '$INSTDIR\\Uninstall.exe');
-  reg("QuietUninstallString", '$INSTDIR\\Uninstall.exe /S');
+  reg("UninstallString", "$INSTDIR\\Uninstall.exe");
+  reg("QuietUninstallString", "$INSTDIR\\Uninstall.exe /S");
   L.push(`  WriteRegDWORD ${root} "${key}" "NoModify" 1`);
   L.push(`  WriteRegDWORD ${root} "${key}" "NoRepair" 1`);
   L.push(`  WriteRegDWORD ${root} "${key}" "EstimatedSize" $0`);
@@ -142,7 +148,7 @@ export async function buildNsisInstaller(input: BuildNsisInput): Promise<string>
   L.push("SectionEnd");
 
   // Uninstall section.
-  L.push("Section \"Uninstall\"");
+  L.push('Section "Uninstall"');
   L.push(`  SetShellVarContext ${ctx}`);
   if (desktop) L.push(`  Delete "$DESKTOP\\${nsis(appName)}.lnk"`);
   if (startMenu) {

package/src/package/linux/index.ts

@@ -0,0 +1,2 @@
+export * from "./package.ts";
+export * from "./types.ts";

package/src/package/linux/lib/defaults.ts

@@ -0,0 +1,53 @@
+import type { LinuxPackageFormat } from "../types.ts";
+
+/** CEF/GTK runtime deps on Debian/Ubuntu package naming (best-effort; overridable). */
+export const DEFAULT_DEB_DEPENDS = [
+  "libgtk-3-0",
+  "libnss3",
+  "libnspr4",
+  "libasound2",
+  "libx11-6",
+  "libxcomposite1",
+  "libxdamage1",
+  "libxext6",
+  "libxfixes3",
+  "libxrandr2",
+  "libgbm1",
+  "libxkbcommon0",
+  "libpango-1.0-0",
+  "libcairo2",
+  "libatk1.0-0",
+  "libatk-bridge2.0-0",
+  "libcups2",
+  "libdrm2",
+  "libdbus-1-3",
+];
+
+/** CEF/GTK runtime deps on RPM (Fedora/RHEL/openSUSE) package naming. */
+export const DEFAULT_RPM_DEPENDS = [
+  "gtk3",
+  "nss",
+  "nspr",
+  "alsa-lib",
+  "libX11",
+  "libXcomposite",
+  "libXdamage",
+  "libXext",
+  "libXfixes",
+  "libXrandr",
+  "mesa-libgbm",
+  "libxkbcommon",
+  "pango",
+  "cairo",
+  "atk",
+  "at-spi2-atk",
+  "cups-libs",
+  "libdrm",
+  "dbus-libs",
+];
+
+export const LINUX_FORMATS = [
+  "appimage",
+  "deb",
+  "rpm",
+] as const satisfies readonly LinuxPackageFormat[];

package/src/package/linux/lib/tools.ts

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Resolve an external tool path: an explicit `$ENV` override (if it exists), then
+ * PATH, then the first existing `fallback`. Throws a clear, actionable error when
+ * none resolve (no user-specific absolute path is baked into committed code).
+ */
+function resolveTool(bin: string, envVar: string, fallbacks: string[]): string {
+  const fromEnv = process.env[envVar];
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+  const onPath = Bun.which(bin);
+  if (onPath) return onPath;
+  for (const f of fallbacks) if (existsSync(f)) return f;
+  throw new Error(
+    `[mirin] "${bin}" not found — install it and put it on PATH, or set $${envVar} ` +
+      "to its absolute path.",
+  );
+}
+
+/** `~/.local/share/gem/ruby/<ver>/bin` (RubyGems user install dir), if resolvable. */
+function gemUserBin(): string | undefined {
+  const ruby = Bun.which("ruby");
+  if (!ruby) return undefined;
+  try {
+    const dir = Bun.spawnSync([ruby, "-e", "print Gem.user_dir"]).stdout.toString().trim();
+    return dir ? join(dir, "bin") : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveFpm(): string {
+  const fallbacks: string[] = [];
+  const gemBin = gemUserBin();
+  if (gemBin) fallbacks.push(join(gemBin, "fpm"));
+  return resolveTool("fpm", "MIRIN_FPM", fallbacks);
+}
+
+export function resolveAppimagetool(): string {
+  return resolveTool("appimagetool", "MIRIN_APPIMAGETOOL", [
+    join(homedir(), ".local", "bin", "appimagetool"),
+  ]);
+}

package/src/package/linux/lib/validation.ts

@@ -0,0 +1,71 @@
+import type { LinuxPackageFormat, LinuxPackageInput } from "../types.ts";
+import { LINUX_FORMATS } from "./defaults.ts";
+
+/** A Debian/RPM-friendly package name: lowercase, alnum + `.-+`, no leading sigil. */
+function shortName(input: string): string {
+  return (
+    input
+      .toLowerCase()
+      .replace(/[^a-z0-9.\-+]/g, "-")
+      .replace(/^[.\-+]+/, "") || "app"
+  );
+}
+
+export function safeLinuxPackageInput(input: LinuxPackageInput): LinuxPackageInput {
+  return {
+    ...input,
+    appName: safeAppBinaryName(input.appName),
+    bundleId: safeLinuxIdentifier(input.bundleId),
+    version: safePackageVersion(input.version),
+  };
+}
+
+function safeLinuxIdentifier(value: string): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) || value === "." || value === "..") {
+    throw new Error(
+      `[mirin] invalid Linux app id "${value}" — use a reverse-DNS style id with letters, ` +
+        'digits, ".", "_" or "-".',
+    );
+  }
+  return value;
+}
+
+function safeAppBinaryName(value: string): string {
+  if (value.length === 0 || value === "." || value === ".." || /[\0\r\n/"\\`$]/.test(value)) {
+    throw new Error(
+      `[mirin] invalid Linux app name "${value}" — it becomes a binary path segment, ` +
+        "so it cannot contain path separators, quotes, shell expansion characters, or newlines.",
+    );
+  }
+  return value;
+}
+
+function safePackageVersion(value: string): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9.+:~_-]*$/.test(value)) {
+    throw new Error(
+      `[mirin] invalid Linux package version "${value}" — use only letters, digits, ".", "+", ":", "~", "_" or "-".`,
+    );
+  }
+  return value;
+}
+
+export function safePackageName(value: string): string {
+  return shortName(value);
+}
+
+export function validateLinuxFormats(
+  formats: readonly string[],
+  source: string,
+): LinuxPackageFormat[] {
+  const allowed = new Set<string>(LINUX_FORMATS);
+  const out: LinuxPackageFormat[] = [];
+  for (const format of formats) {
+    if (!allowed.has(format)) {
+      throw new Error(
+        `[mirin] invalid Linux package format "${format}" in ${source}; expected appimage, deb, or rpm.`,
+      );
+    }
+    if (!out.includes(format as LinuxPackageFormat)) out.push(format as LinuxPackageFormat);
+  }
+  return out;
+}