@mirinjs/cli 0.1.0-alpha.18 → 0.1.0-alpha.19

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

@@ -8,6 +8,7 @@
 import { mkdirSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { $ } from "bun";
+import { createReporter, type Reporter } from "./shared/report.ts";
 
 /** 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[] }>;
@@ -77,6 +78,8 @@ 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> = {};
@@ -84,11 +87,10 @@ export async function compileWorkers(
     const safeName = safeExtraAssetName(name, "worker name");
     const js = join(outDir, `${safeName}.js`);
     const src = projectRelativePath(projectDir, entry, `worker "${safeName}" 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);
-    }
+    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)) {

package/src/index.ts

@@ -1,14 +1,17 @@
 #!/usr/bin/env bun
 /**
- * mirin CLI — `dev`, `build`, `init`.
+ * mirin CLI — `dev`, `check`, `doctor`, `build`, `release`, `init`, `skill`.
  */
 
 import { resolve } from "node:path";
 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 { skill } from "./skill.ts";
 
 /** Minimal flag parser: `--k=v`, `--k v`, and boolean `--k`; the rest are positionals. */
 function parseArgs(argv: string[]): {
@@ -49,20 +52,61 @@ const USAGE = `mirin — build desktop apps with Bun + Chromium
 
 Usage:
   mirin dev          run the app against the Vite dev server (HMR + typed RPC)
+  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": {
@@ -70,7 +114,20 @@ switch (command) {
     const target = typeof opts["linux-target"] === "string" ? opts["linux-target"] : undefined;
     const linuxFormats = target ? parseLinuxFormats(target) : undefined;
     const packageLinux = opts.linux === true || linuxFormats != null;
-    await build(process.cwd(), { version, packageLinux, linuxFormats });
+    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;
   }
@@ -83,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/shared/driver.ts

@@ -0,0 +1,240 @@
+/**
+ * The `CheckDriver` a scenario is handed, implemented over a running app's
+ * inspector (docs/agent-devtools.md). Failures throw; `runScenario` turns the
+ * throw into a failed check.
+ */
+
+import type { CheckDriver, CheckWindow, WindowTarget } from "mirinjs/check";
+import type { DevEvent, DevEventQuery } from "mirinjs/devtools/session";
+import type { InspectorClient } from "./inspector.ts";
+
+/** How long `expectText` waits for the UI to catch up with an RPC round trip. */
+const EXPECT_TIMEOUT_MS = 2_000;
+const EXPECT_POLL_MS = 100;
+
+/** Thrown by `assert` / `expectText`, and by a step that fails. */
+export class CheckAssertionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CheckAssertionError";
+  }
+}
+
+export interface ScenarioStep {
+  name: string;
+  ok: boolean;
+  ms: number;
+}
+
+export interface ScenarioOutcome {
+  steps: ScenarioStep[];
+  screenshots: string[];
+  /** Set when the scenario threw; the step it was in is in `steps`. */
+  failure?: { step: string; message: string };
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function windowQuery(options: WindowTarget | undefined): string {
+  return options?.window !== undefined ? `?window=${options.window}` : "";
+}
+
+function windowsOf(state: unknown): CheckWindow[] {
+  const list = record(state).windows;
+  if (!Array.isArray(list)) return [];
+  return list.flatMap((entry) => {
+    const win = record(entry);
+    const id = win.id;
+    const name = win.name;
+    if (typeof id !== "number") return [];
+    return [
+      {
+        id,
+        name: typeof name === "string" ? name : `window-${id}`,
+        ...(typeof win.url === "string" ? { url: win.url } : {}),
+        ...(typeof win.title === "string" ? { title: win.title } : {}),
+      },
+    ];
+  });
+}
+
+/** `onStep` mirrors steps into the event stream, so the app's log and the
+ *  scenario's progress interleave in one timeline. */
+export function createDriver(
+  client: InspectorClient,
+  onStep?: (name: string) => void,
+): { driver: CheckDriver; outcome: ScenarioOutcome; finishStep(ok: boolean): void } {
+  const steps: ScenarioStep[] = [];
+  const screenshots: string[] = [];
+  const outcome: ScenarioOutcome = { steps, screenshots };
+  let startedAt = Date.now();
+
+  const finishStep = (ok: boolean): void => {
+    const current = steps.at(-1);
+    if (current !== undefined && current.ms === -1) {
+      current.ok = ok;
+      current.ms = Date.now() - startedAt;
+    }
+  };
+
+  const act = async (body: Record<string, unknown>, options?: WindowTarget): Promise<void> => {
+    await client.post(`/act${windowQuery(options)}`, body);
+  };
+
+  const driver: CheckDriver = {
+    step(name) {
+      finishStep(true);
+      steps.push({ name, ok: false, ms: -1 });
+      startedAt = Date.now();
+      onStep?.(name);
+    },
+
+    async click(selector, options) {
+      await act(
+        {
+          action: "click",
+          selector,
+          ...(options?.clickCount !== undefined ? { clickCount: options.clickCount } : {}),
+        },
+        options,
+      );
+    },
+
+    async type(text, options) {
+      await act(
+        {
+          action: "type",
+          text,
+          ...(options?.selector !== undefined ? { selector: options.selector } : {}),
+        },
+        options,
+      );
+    },
+
+    async key(name, options) {
+      await act({ action: "key", key: name }, options);
+    },
+
+    async scroll(options) {
+      await act(
+        { action: "scroll", deltaY: options.deltaY ?? 0, deltaX: options.deltaX ?? 0 },
+        options,
+      );
+    },
+
+    async waitFor(selector, options) {
+      await act(
+        {
+          action: "wait",
+          selector,
+          ...(options?.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        },
+        options,
+      );
+    },
+
+    async sleep(ms) {
+      await Bun.sleep(ms);
+    },
+
+    async snapshot(options) {
+      const query = new URLSearchParams();
+      if (options?.window !== undefined) query.set("window", String(options.window));
+      if (options?.format !== undefined) query.set("format", options.format);
+      const suffix = query.size > 0 ? `?${query.toString()}` : "";
+      const result = record(await client.get(`/snapshot${suffix}`));
+      const snapshot = result.snapshot;
+      if (typeof snapshot !== "string") throw new Error("the app returned no snapshot");
+      return snapshot;
+    },
+
+    async evaluate(expression, options) {
+      const result = record(await client.post(`/eval${windowQuery(options)}`, { expression }));
+      // The route reports a page-side throw as ok:false rather than as HTTP 500.
+      if (result.ok === false) {
+        throw new Error(`eval failed: ${String(result.error ?? "unknown error")}`);
+      }
+      return result.value as never;
+    },
+
+    async screenshot(label, options) {
+      const query = new URLSearchParams();
+      if (options?.window !== undefined) query.set("window", String(options.window));
+      // Default the label to the current step, so screenshots stay identifiable.
+      query.set("label", label ?? steps.at(-1)?.name ?? `shot-${screenshots.length + 1}`);
+      const result = record(await client.get(`/screenshot?${query.toString()}`));
+      const path = result.path;
+      if (typeof path !== "string") throw new Error("the app returned no screenshot path");
+      screenshots.push(path);
+      return path;
+    },
+
+    async windows() {
+      return windowsOf(await client.get("/state"));
+    },
+
+    async exposed() {
+      return record(record(await client.get("/state")).exposed);
+    },
+
+    async logs(query: DevEventQuery = {}) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value === undefined) continue;
+        for (const entry of Array.isArray(value) ? value : [value]) {
+          params.append(key, String(entry));
+        }
+      }
+      const suffix = params.size > 0 ? `?${params.toString()}` : "";
+      const events = record(await client.get(`/logs${suffix}`)).events;
+      return Array.isArray(events) ? (events as DevEvent[]) : [];
+    },
+
+    async cdp(method, params, options) {
+      const result = record(
+        await client.post(`/cdp${windowQuery(options)}`, { method, params: params ?? {} }),
+      );
+      if (result.ok === false) {
+        throw new Error(`${method} failed: ${String(result.error ?? "unknown error")}`);
+      }
+      return result.result as never;
+    },
+
+    assert(condition, message) {
+      if (!condition) throw new CheckAssertionError(message);
+    },
+
+    async waitUntil(condition, message, options) {
+      const timeoutMs = options?.timeoutMs ?? EXPECT_TIMEOUT_MS;
+      const deadline = Date.now() + timeoutMs;
+      for (;;) {
+        // A condition that throws counts as "not yet"; the timeout makes it a failure.
+        let held: unknown = false;
+        try {
+          held = await condition();
+        } catch {
+          held = false;
+        }
+        if (held) return;
+        if (Date.now() >= deadline) {
+          throw new CheckAssertionError(`${message} (waited ${timeoutMs}ms)`);
+        }
+        await Bun.sleep(EXPECT_POLL_MS);
+      }
+    },
+
+    async expectText(text, options) {
+      await driver.waitUntil(
+        async () => (await driver.snapshot(options)).includes(text),
+        `expected the UI to contain ${JSON.stringify(text)}`,
+        ...(options?.timeoutMs !== undefined ? [{ timeoutMs: options.timeoutMs }] : []),
+      );
+    },
+  };
+
+  return { driver, outcome, finishStep };
+}

package/src/shared/inspector.ts

@@ -0,0 +1,64 @@
+/**
+ * Client for a running app's inspector (docs/agent-devtools.md). Responses come
+ * back as `unknown`; callers narrow what they need.
+ */
+
+import type { InspectorEndpoint } from "mirinjs/devtools/session";
+
+/** Per-request deadline. Screenshots of a big window are the slow case. */
+const REQUEST_TIMEOUT_MS = 20_000;
+
+export class InspectorError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "InspectorError";
+    this.status = status;
+  }
+}
+
+export class InspectorClient {
+  readonly base: string;
+  #token: string;
+
+  constructor(endpoint: InspectorEndpoint) {
+    this.base = `http://127.0.0.1:${endpoint.port}`;
+    this.#token = endpoint.token;
+  }
+
+  /** GET a JSON route. `path` starts with `/` and may carry a query string. */
+  async get(path: string): Promise<unknown> {
+    return this.#request(path, { method: "GET" });
+  }
+
+  async post(path: string, body: unknown): Promise<unknown> {
+    return this.#request(path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  }
+
+  async #request(path: string, init: RequestInit): Promise<unknown> {
+    const res = await fetch(`${this.base}${path}`, {
+      ...init,
+      headers: { ...init.headers, authorization: `Bearer ${this.#token}` },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const text = await res.text();
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = undefined;
+    }
+    if (!res.ok) {
+      const message =
+        typeof parsed === "object" && parsed !== null && "error" in parsed
+          ? String((parsed as { error: unknown }).error)
+          : text.slice(0, 200);
+      throw new InspectorError(res.status, `${path}: ${message}`);
+    }
+    return parsed;
+  }
+}