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

package/src/release.ts

@@ -16,17 +16,62 @@
  * any static host. Channels coexist because the channel is part of every name.
  */
 
-import { $ } from "bun";
-import { mkdirSync, rmSync, readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { $ } from "bun";
 import { build } from "./build.ts";
-import { buildDmg, notarizeAndStaple, type DmgOptions } from "./dmg.ts";
-import { buildNsisInstaller, hasMakensis } from "./installer-win.ts";
-import { loadCodec } from "mirinjs/codec";
+import { notarizeAndStaple } from "./dmg.ts";
+import { buildReleaseInstaller } from "./release/installers.ts";
+import {
+  assertTrustedReleaseUrl,
+  parsePreviousReleaseManifest,
+  releaseArtifactUrl,
+  trustedReleaseBaseUrl,
+} from "./release/previous.ts";
+
+// Level 10 keeps updater bundles compact without level 19's steep CPU cost.
+// The native codec uses multiple workers, so this scales across CI runner cores.
+const RELEASE_COMPRESSION_LEVEL = 10;
+
+interface ReleaseCodec {
+  compress(src: string, dst: string, level: number): void;
+  decompress(src: string, dst: string): void;
+  diff(oldPath: string, newPath: string, patchPath: string): void;
+}
+
+export function createReleaseCodec(binary: string): ReleaseCodec {
+  const run = (operation: string, ...args: string[]) => {
+    const result = Bun.spawnSync({
+      cmd: [binary, operation, ...args],
+      stdout: "inherit",
+      stderr: "pipe",
+    });
+    if (result.exitCode !== 0) {
+      const detail = new TextDecoder().decode(result.stderr).trim();
+      throw new Error(`codec ${operation} failed${detail ? `: ${detail}` : ""}`);
+    }
+  };
+  return {
+    compress(src, dst, level) {
+      run("compress", src, dst, String(level));
+    },
+    decompress(src, dst) {
+      run("decompress", src, dst);
+    },
+    diff(oldPath, newPath, patchPath) {
+      run("diff", oldPath, newPath, patchPath);
+    },
+  };
+}
 
-const sha256File = (path: string) =>
-  new Bun.CryptoHasher("sha256").update(readFileSync(path)).digest("hex");
+async function sha256File(path: string): Promise<string> {
+  const hasher = new Bun.CryptoHasher("sha256");
+  for await (const chunk of Bun.file(path).stream()) {
+    hasher.update(chunk);
+  }
+  return hasher.digest("hex");
+}
 
 export async function release(projectDir = process.cwd()): Promise<number> {
   const result = await build(projectDir);
@@ -36,13 +81,14 @@ export async function release(projectDir = process.cwd()): Promise<number> {
   }
 
   const isWindows = process.platform === "win32";
-  const platform = isWindows ? "win32" : "darwin";
+  const isLinux = process.platform === "linux";
+  const platform = isWindows ? "win32" : isLinux ? "linux" : "darwin";
   const arch = process.arch; // "arm64" | "x64"
   const prefix = `${result.channel}-${platform}-${arch}`;
   const safeName = result.appName.replace(/[^A-Za-z0-9._-]/g, "");
-  const base = result.baseUrl.replace(/\/$/, "");
-  // The packaged unit: a flat app folder on Windows, an `.app` bundle on macOS.
-  const appArtifact = isWindows ? result.appName : `${result.appName}.app`;
+  const base = trustedReleaseBaseUrl(result.baseUrl);
+  // The packaged unit: a flat app folder on Windows/Linux, an `.app` bundle on macOS.
+  const appArtifact = isWindows || isLinux ? result.appName : `${result.appName}.app`;
 
   const buildDir = join(projectDir, "build");
   const outDir = join(buildDir, "release");
@@ -52,58 +98,81 @@ export async function release(projectDir = process.cwd()): Promise<number> {
   // Notarize + staple the .app (Developer ID, macOS) before packing, when
   // credentials are present. The .tar.zst / patch updater bundles are made from
   // this signed, stapled .app, so the updater swaps in an already-notarized app.
-  if (!isWindows) await notarizeAndStaple(result.app);
+  if (!isWindows && !isLinux) await notarizeAndStaple(result.app);
 
-  // Load the codec (zstd/bsdiff) from the *bundled* core, not the raw build output:
-  // on Windows mirin_core.dll imports libcef.dll. The DLL loader resolves imports
-  // from PATH (and the loader exe's dir), not the dll's own dir, so prepend the
-  // bundle dir to PATH so libcef.dll is found. (On macOS the framework loads at
-  // runtime, so result.coreDylib works directly.)
-  const codecCore = isWindows ? join(result.app, "mirin_core.dll") : result.coreDylib;
-  if (isWindows) process.env.PATH = `${result.app};${process.env.PATH ?? ""}`;
-  const codec = loadCodec(codecCore);
+  // Installer/package tooling runs in child processes and reads the assembled app.
+  // Start it now so it overlaps updater compression and delta generation below.
+  const installerBuild = buildReleaseInstaller({
+    result,
+    buildDir,
+    outDir,
+    appArtifact,
+    prefix,
+    safeName,
+    isWindows,
+    isLinux,
+  });
+
+  // Release tooling runs in plain Bun, including Windows arm64 builds where
+  // bun:ffi is unavailable. The standalone helper also avoids loading CEF merely
+  // to compress updater artifacts.
+  const codec = createReleaseCodec(result.codecBin);
 
   // Uncompressed tar — the identity + diff/patch basis (BSD tar keeps symlinks).
   const newTar = join(outDir, "_new.tar");
   await $`tar -cf ${newTar} -C ${buildDir} ${appArtifact}`;
-  const tarHash = sha256File(newTar);
+  const tarHash = await sha256File(newTar);
 
   // Full bundle: zstd(newTar).
   const bundleName = `${prefix}-${safeName}${isWindows ? "" : ".app"}.tar.zst`;
   const bundlePath = join(outDir, bundleName);
   console.log(`[mirin release] compressing → ${bundleName}`);
-  codec.compress(newTar, bundlePath, 19);
-  const bundleSha = sha256File(bundlePath);
-  const bundleSize = readFileSync(bundlePath).byteLength;
+  codec.compress(newTar, bundlePath, RELEASE_COMPRESSION_LEVEL);
+  const bundleSha = await sha256File(bundlePath);
+  const bundleSize = statSync(bundlePath).size;
 
   // Delta patch vs the previous release (if reachable). Best-effort.
   const patches: Array<{ fromVersion: string; url: string; sha256: string; size: number }> = [];
   try {
-    const prevRes = await fetch(`${base}/${prefix}-update.json?t=${Date.now()}`, { redirect: "follow" });
+    const manifestUrl = new URL(releaseArtifactUrl(base, `${prefix}-update.json`));
+    manifestUrl.searchParams.set("t", String(Date.now()));
+    const prevRes = await fetch(manifestUrl, {
+      redirect: "follow",
+    });
+    assertTrustedReleaseUrl(prevRes.url);
     if (prevRes.ok) {
-      const prev = (await prevRes.json()) as { version: string; bundle?: { url: string } };
-      if (prev.version && prev.version !== result.version && prev.bundle?.url) {
+      const prev = parsePreviousReleaseManifest(await prevRes.json(), {
+        channel: result.channel,
+        platform,
+        arch,
+      });
+      if (prev.version !== result.version) {
         console.log(`[mirin release] generating delta ${prev.version} → ${result.version}…`);
-        const tmp = join(tmpdir(), `mirin-release-${Date.now()}`);
-        mkdirSync(tmp, { recursive: true });
-        const prevZst = join(tmp, "prev.tar.zst");
-        const dl = await fetch(`${base}/${prev.bundle.url}`, { redirect: "follow" });
-        if (!dl.ok || !dl.body) throw new Error(`prev bundle ${dl.status}`);
-        await Bun.write(prevZst, await dl.arrayBuffer());
-        const prevTar = join(tmp, "prev.tar");
-        codec.decompress(prevZst, prevTar);
-        const rawPatch = join(tmp, "patch.bin");
-        codec.diff(prevTar, newTar, rawPatch); // bsdiff
-        const patchName = `${prefix}-${prev.version}.patch`;
-        const patchPath = join(outDir, patchName);
-        codec.compress(rawPatch, patchPath, 19);
-        rmSync(tmp, { recursive: true, force: true });
-        patches.push({
-          fromVersion: prev.version,
-          url: patchName,
-          sha256: sha256File(patchPath),
-          size: readFileSync(patchPath).byteLength,
-        });
+        const tmp = mkdtempSync(join(tmpdir(), "mirin-release-"));
+        try {
+          const prevZst = join(tmp, "prev.tar.zst");
+          await downloadVerified(
+            releaseArtifactUrl(base, prev.bundle.url),
+            prevZst,
+            prev.bundle.sha256,
+            prev.bundle.size,
+          );
+          const prevTar = join(tmp, "prev.tar");
+          codec.decompress(prevZst, prevTar);
+          const rawPatch = join(tmp, "patch.bin");
+          codec.diff(prevTar, newTar, rawPatch); // bsdiff
+          const patchName = `${prefix}-${prev.version}.patch`;
+          const patchPath = join(outDir, patchName);
+          codec.compress(rawPatch, patchPath, RELEASE_COMPRESSION_LEVEL);
+          patches.push({
+            fromVersion: prev.version,
+            url: patchName,
+            sha256: await sha256File(patchPath),
+            size: statSync(patchPath).size,
+          });
+        } finally {
+          rmSync(tmp, { recursive: true, force: true });
+        }
       }
     }
   } catch (e) {
@@ -117,6 +186,7 @@ export async function release(projectDir = process.cwd()): Promise<number> {
     channel: result.channel,
     platform,
     arch,
+    body: result.releaseNotes,
     tarHash,
     bundle: { url: bundleName, sha256: bundleSha, size: bundleSize },
     patches,
@@ -124,76 +194,10 @@ export async function release(projectDir = process.cwd()): Promise<number> {
   const manifestName = `${prefix}-update.json`;
   await Bun.write(join(outDir, manifestName), `${JSON.stringify(manifest, null, 2)}\n`);
 
-  // Distributable installer for first-time installs (the updater uses the
-  // .tar.zst/patch): a drag-to-Applications .dmg on macOS, a .zip of the app
-  // folder on Windows.
-  let installerName: string | undefined;
-  let installerSize = 0;
-  if (isWindows) {
-    // Preferred: a real NSIS installer (Program Files / per-user install, Start
-    // Menu + Desktop shortcuts, uninstaller, Add/Remove Programs). Falls back to a
-    // portable .zip when nsis is disabled or makensis isn't installed.
-    const wantsInstaller = result.nsis !== false;
-    if (wantsInstaller && (await hasMakensis())) {
-      installerName = `${prefix}-${safeName}-setup.exe`;
-      const exePath = await buildNsisInstaller({
-        appDir: result.app,
-        appName: result.appName,
-        exeName: `${result.appName}.exe`,
-        version: result.version,
-        bundleId: result.bundleId,
-        outDir,
-        fileName: installerName,
-        options: typeof result.nsis === "object" ? result.nsis : {},
-        projectDir: result.projectDir,
-      });
-      installerSize = readFileSync(exePath).byteLength;
-    } else {
-      if (wantsInstaller) {
-        console.warn(
-          "[mirin release] makensis (NSIS) not found — shipping the portable .zip. " +
-            "Install NSIS (e.g. `scoop install nsis`) for an installer.",
-        );
-      }
-      installerName = `${prefix}-${safeName}.zip`;
-      console.log(`[mirin release] zipping → ${installerName}`);
-      const zipPath = join(outDir, installerName);
-      rmSync(zipPath, { force: true });
-      // bsdtar (Windows `tar`) creates a .zip from the extension with `-a`.
-      await $`tar -a -cf ${zipPath} -C ${buildDir} ${appArtifact}`;
-      installerSize = readFileSync(zipPath).byteLength;
-    }
-  } else if (result.dmg !== false) {
-    // The DMG is the first-install convenience; the updater bundle + manifest (the
-    // critical artifacts) are already built. Never fail the whole release over a
-    // flaky installer step — warn loudly and ship the rest.
-    const dmgName = `${prefix}-${safeName}.dmg`;
-    console.log(`[mirin release] building installer → ${dmgName}`);
-    try {
-      const options: DmgOptions = typeof result.dmg === "object" ? result.dmg : {};
-      const dmgPath = await buildDmg({
-        app: result.app,
-        appName: result.appName,
-        outDir,
-        fileName: dmgName,
-        options,
-        projectDir: result.projectDir,
-        signIdentity: result.signIdentity,
-      });
-      await notarizeAndStaple(dmgPath); // no-op without notary credentials
-      installerName = dmgName;
-      installerSize = readFileSync(dmgPath).byteLength;
-    } catch (e) {
-      console.warn(
-        `\n[mirin release] ⚠️  DMG build failed: ${e instanceof Error ? e.message : e}\n` +
-          `[mirin release] shipping the updater bundle + manifest WITHOUT a .dmg installer.\n`,
-      );
-      rmSync(join(outDir, dmgName), { force: true });
-    }
-  }
+  const { installerName, installerSize } = await installerBuild;
 
   const mb = (n: number) => (n / 1e6).toFixed(1);
-  console.log(`\n[mirin release] done → build/release/`);
+  console.log("\n[mirin release] done → build/release/");
   console.log(`  ${manifestName}`);
   console.log(`  ${bundleName} (${mb(bundleSize)} MB)`);
   for (const p of patches) console.log(`  ${p.url} (${mb(p.size)} MB delta from ${p.fromVersion})`);
@@ -202,3 +206,49 @@ export async function release(projectDir = process.cwd()): Promise<number> {
   if (existsSync(join(outDir, "_new.tar"))) rmSync(join(outDir, "_new.tar"), { force: true });
   return 0;
 }
+
+async function downloadVerified(
+  url: string,
+  destination: string,
+  expectedSha256: string,
+  expectedSize: number,
+): Promise<void> {
+  const response = await fetch(url, { redirect: "follow" });
+  assertTrustedReleaseUrl(response.url);
+  if (!response.ok || !response.body) throw new Error(`previous bundle ${response.status}`);
+
+  const contentLength = Number(response.headers.get("content-length") ?? 0);
+  if (contentLength > 0 && contentLength !== expectedSize) {
+    throw new Error(
+      `previous bundle size mismatch (expected ${expectedSize}, got ${contentLength})`,
+    );
+  }
+
+  const reader = response.body.getReader();
+  const writer = Bun.file(destination).writer();
+  const hasher = new Bun.CryptoHasher("sha256");
+  let received = 0;
+  try {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        received += value.byteLength;
+        if (received > expectedSize) throw new Error("previous bundle exceeds declared size");
+        hasher.update(value);
+        writer.write(value);
+      }
+    } finally {
+      await writer.end();
+    }
+    if (received !== expectedSize) {
+      throw new Error(`previous bundle size mismatch (expected ${expectedSize}, got ${received})`);
+    }
+    if (hasher.digest("hex") !== expectedSha256) {
+      throw new Error("previous bundle checksum mismatch");
+    }
+  } catch (error) {
+    rmSync(destination, { force: true });
+    throw error;
+  }
+}

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