pi-agent-browser-native 0.9.3 → 0.9.4

package/scripts/doctor-sources.mjs

@@ -0,0 +1,195 @@
+/** Read-only Pi settings and autoload source discovery for the package doctor. */
+import { homedir } from "node:os";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import stripJsonComments from "strip-json-comments";
+
+const PACKAGE_NAME = "pi-agent-browser-native";
+const REPO_URL_FRAGMENT = "github.com/fitchmultz/pi-agent-browser-native";
+const EXTENSION_ENTRYPOINTS = [
+	"extensions/agent-browser/index.ts",
+	"dist/extensions/agent-browser/index.js",
+];
+const THIS_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function isInsidePath(childPath, parentPath) {
+	const child = resolve(childPath);
+	const parent = resolve(parentPath);
+	return child === parent || child.startsWith(`${parent}${sep}`);
+}
+
+function expandUserPath(path) {
+	if (path === "~") {
+		return homedir();
+	}
+	if (path.startsWith("~/")) {
+		return resolve(homedir(), path.slice(2));
+	}
+	return path;
+}
+
+function isPathLikeSource(source) {
+	return (
+		isAbsolute(source) ||
+		source.startsWith("./") ||
+		source.startsWith("../") ||
+		source.startsWith("~")
+	);
+}
+
+function sourceLooksLikeThisPackage(source, cwd, sourceBaseDir = cwd) {
+	const text = String(source ?? "").trim();
+	if (text.length === 0) {
+		return false;
+	}
+	if (
+		/^npm:pi-agent-browser-native(?:@|$)/.test(text) ||
+		text === PACKAGE_NAME ||
+		text.includes(REPO_URL_FRAGMENT)
+	) {
+		return true;
+	}
+	if (!isPathLikeSource(text)) {
+		return false;
+	}
+	const resolvedSource = resolve(sourceBaseDir, expandUserPath(text));
+	return [cwd, THIS_PACKAGE_ROOT].some(
+		(root) =>
+			resolvedSource === root ||
+			EXTENSION_ENTRYPOINTS.some((entrypoint) =>
+				isInsidePath(resolve(root, entrypoint), resolvedSource),
+			),
+	);
+}
+
+function arrayEntries(value) {
+	return Array.isArray(value) ? value.entries() : [];
+}
+
+function entrySource(entry) {
+	if (typeof entry === "string") {
+		return entry;
+	}
+	if (entry && typeof entry === "object") {
+		return entry.source ?? entry.path ?? entry.package;
+	}
+}
+
+function collectSettingsSources(settings, settingsPath, cwd) {
+	const sources = [];
+	const sourceBaseDir = dirname(settingsPath);
+	for (const [field, kind] of [
+		["packages", "package"],
+		["extensions", "extension"],
+	]) {
+		for (const [index, entry] of arrayEntries(settings?.[field])) {
+			const source = entrySource(entry);
+			if (sourceLooksLikeThisPackage(source, cwd, sourceBaseDir)) {
+				sources.push({
+					kind,
+					source: String(source),
+					location: `${settingsPath} ${field}[${index}]`,
+				});
+			}
+		}
+	}
+	return sources;
+}
+
+async function inspectSettingsPath({ path, cwd, readText }) {
+	try {
+		const text = await readText(path);
+		if (text === undefined) {
+			return { sources: [], warnings: [] };
+		}
+		const settings = JSON.parse(stripJsonComments(text));
+		return { sources: collectSettingsSources(settings, path, cwd), warnings: [] };
+	} catch (error) {
+		return {
+			sources: [],
+			warnings: [
+				`Could not inspect Pi settings ${path}: ${error instanceof Error ? error.message : String(error)}`,
+			],
+		};
+	}
+}
+
+async function collectRepoLocalSources({ cwd, pathExists }) {
+	const candidates = [
+		resolve(cwd, ".pi/extensions/agent-browser.ts"),
+		resolve(cwd, ".pi/extensions/agent-browser/index.ts"),
+	];
+	const sources = [];
+	for (const candidate of candidates) {
+		// Inspect one autoload location at a time to preserve the injected read-only I/O order.
+		// oxlint-disable-next-line no-await-in-loop
+		if (await pathExists(candidate)) {
+			sources.push({
+				kind: "repo-local",
+				source: candidate,
+				location: `${candidate} repo-local autoload`,
+			});
+		}
+	}
+	return sources;
+}
+
+/**
+ * @param {{cwd: string, agentDir: string, settingsPaths: readonly string[], readText: (path: string) => Promise<string | undefined>, pathExists: (path: string) => Promise<boolean>}} options
+ * @returns {Promise<{status: "fail" | "pass" | "warn", title: string, lines: string[], warnings: string[]}>}
+ */
+export async function checkPiSources({ cwd, agentDir, settingsPaths, readText, pathExists }) {
+	const defaultSettingsPaths = [
+		resolve(agentDir, "settings.json"),
+		resolve(cwd, ".pi/settings.json"),
+	];
+	const allSettingsPaths = [
+		...new Set([...defaultSettingsPaths, ...settingsPaths].map((path) => resolve(path))),
+	];
+	const sources = [];
+	const warnings = [];
+	for (const path of allSettingsPaths) {
+		// Settings are inspected in configured precedence order; injected I/O preserves that order.
+		// oxlint-disable-next-line no-await-in-loop
+		if (await pathExists(path)) {
+			// Finish reading this settings file before reporting and inspecting the next source.
+			// oxlint-disable-next-line no-await-in-loop
+			const result = await inspectSettingsPath({ path, cwd, readText });
+			sources.push(...result.sources);
+			warnings.push(...result.warnings);
+		}
+	}
+	sources.push(...(await collectRepoLocalSources({ cwd, pathExists })));
+	if (sources.length > 1) {
+		return {
+			status: "fail",
+			title: "Duplicate pi-agent-browser-native sources detected.",
+			lines: [
+				"Pi may register multiple `agent_browser` tools when a checkout source and a package source are both active.",
+				"Detected sources:",
+				...sources.map((source) => `- ${source.source} from ${source.location}`),
+				"Keep exactly one active source:",
+				"- for normal use: keep `pi install npm:pi-agent-browser-native` and remove/disable checkout paths from Pi settings",
+				"- for temporary package or checkout trials: use `pi --approve --no-extensions -e <source>` when you intentionally trust the current project, or omit `--approve` to let Pi prompt in interactive mode",
+				"- for configured-source lifecycle validation: keep exactly one checkout or package source, then launch plain `pi`",
+			],
+			warnings,
+		};
+	}
+	if (sources.length === 1) {
+		return {
+			status: "pass",
+			title: "No duplicate pi-agent-browser-native sources detected.",
+			lines: [`Detected source: ${sources[0].source} from ${sources[0].location}`],
+			warnings,
+		};
+	}
+	return {
+		status: "warn",
+		title: "No configured pi-agent-browser-native source was found in inspected Pi settings.",
+		lines: [
+			"This is OK for isolated runs such as `pi --no-extensions -e npm:pi-agent-browser-native`, but normal package use should install exactly one source with `pi install npm:pi-agent-browser-native`.",
+		],
+		warnings,
+	};
+}

package/scripts/doctor.mjs

@@ -11,46 +11,61 @@ import { execFile as execFileCallback } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
 import { CAPABILITY_BASELINE_SOURCE } from "./agent-browser-capability-baseline.mjs";
-import { MINIMUM_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_SOURCE, TARGET_AGENT_BROWSER_VERSION, isSupportedAgentBrowserVersion } from "./agent-browser-target.mjs";
+import { checkPiSources } from "./doctor-sources.mjs";
+import {
+	MINIMUM_AGENT_BROWSER_VERSION,
+	TARGET_AGENT_BROWSER_SOURCE,
+	TARGET_AGENT_BROWSER_VERSION,
+	isSupportedAgentBrowserVersion,
+} from "./agent-browser-target.mjs";
 
 const execFile = promisify(execFileCallback);
-const PACKAGE_NAME = "pi-agent-browser-native";
-const REPO_URL_FRAGMENT = "github.com/fitchmultz/pi-agent-browser-native";
-const EXTENSION_ENTRYPOINTS = Object.freeze([
-	"extensions/agent-browser/index.ts",
-	"dist/extensions/agent-browser/index.js",
-]);
 const RECOMMENDED_VERSION = TARGET_AGENT_BROWSER_VERSION;
 export const MINIMUM_PI_VERSION = "1.0.0";
 const DEFAULT_AGENT_DIR = resolve(homedir(), ".pi/agent");
-const THIS_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** @typedef {{readonly status: "pass" | "warn" | "fail", readonly title: string, readonly lines: readonly string[], readonly warnings?: readonly string[]}} DoctorCheck */
+/** @typedef {{readonly checks: readonly DoctorCheck[], readonly failures: readonly DoctorCheck[], readonly warnings: readonly string[]}} DoctorReport */
+/** @typedef {{readonly cwd?: string, readonly agentDir?: string, readonly settingsPaths?: readonly string[], readonly skipSourceCheck?: boolean, readonly readText?: (path: string) => Promise<string | undefined>, readonly pathExists?: (path: string) => Promise<boolean>, readonly runAgentBrowser?: (args: readonly string[]) => Promise<string>, readonly runPi?: (args: readonly string[]) => Promise<string>}} DoctorOptions */
 
 export function normalizeAgentBrowserVersion(output) {
-	return String(output ?? "").trim().replace(/^agent-browser\s+/, "");
+	return String(output ?? "")
+		.trim()
+		.replace(/^agent-browser\s+/, "");
 }
 
 export function normalizePiVersion(output) {
-	return String(output ?? "").trim().replace(/^pi\s+/, "");
+	return String(output ?? "")
+		.trim()
+		.replace(/^pi\s+/, "");
 }
 
 function parseVersionParts(version) {
 	const match = String(version ?? "").match(/^(\d+)\.(\d+)\.(\d+)(?:\b|[-+])/);
-	if (!match) return undefined;
+	if (!match) {
+		return;
+	}
 	return match.slice(1).map((part) => Number.parseInt(part, 10));
 }
 
 export function versionAtLeast(actual, minimum) {
 	const actualParts = parseVersionParts(actual);
 	const minimumParts = parseVersionParts(minimum);
-	if (!actualParts || !minimumParts) return undefined;
+	if (!actualParts || !minimumParts) {
+		return;
+	}
 	for (let index = 0; index < minimumParts.length; index += 1) {
-		if (actualParts[index] > minimumParts[index]) return true;
-		if (actualParts[index] < minimumParts[index]) return false;
+		if (actualParts[index] > minimumParts[index]) {
+			return true;
+		}
+		if (actualParts[index] < minimumParts[index]) {
+			return false;
+		}
 	}
 	return true;
 }
@@ -98,7 +113,7 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
 
 	for (let index = 0; index < argv.length; index += 1) {
 		const arg = argv[index];
-		if (arg === "-h" || arg === "--help") {
+		if (["-h", "--help"].includes(arg)) {
 			parsed.showHelp = true;
 			continue;
 		}
@@ -106,15 +121,17 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
 			parsed.skipSourceCheck = true;
 			continue;
 		}
-		if (arg === "--cwd" || arg === "--agent-dir" || arg === "--settings") {
+		if (["--cwd", "--agent-dir", "--settings"].includes(arg)) {
 			const value = argv[index + 1];
 			if (value === undefined || value.startsWith("--")) {
 				throw new Error(`${arg} requires a value. Run with --help for usage.`);
 			}
 			index += 1;
-			if (arg === "--cwd") parsed.cwd = value;
-			if (arg === "--agent-dir") parsed.agentDir = value;
-			if (arg === "--settings") parsed.settingsPaths.push(value);
+			if (arg === "--settings") {
+				parsed.settingsPaths.push(value);
+			} else {
+				parsed[arg === "--cwd" ? "cwd" : "agentDir"] = value;
+			}
 			continue;
 		}
 		throw new Error(`Unknown option: ${arg}. Run with --help for usage.`);
@@ -124,12 +141,18 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
 }
 
 async function defaultRunAgentBrowser(args) {
-	const { stdout, stderr } = await execFile("agent-browser", args, { maxBuffer: 1024 * 1024, ...buildNpmShimExecOptions(process.platform) });
+	const { stdout, stderr } = await execFile("agent-browser", args, {
+		maxBuffer: 1024 * 1024,
+		...buildNpmShimExecOptions(process.platform),
+	});
 	return `${stdout}${stderr}`;
 }
 
 async function defaultRunPi(args) {
-	const { stdout, stderr } = await execFile("pi", args, { maxBuffer: 1024 * 1024, ...buildNpmShimExecOptions(process.platform) });
+	const { stdout, stderr } = await execFile("pi", args, {
+		maxBuffer: 1024 * 1024,
+		...buildNpmShimExecOptions(process.platform),
+	});
 	return `${stdout}${stderr}`;
 }
 
@@ -150,164 +173,6 @@ async function defaultPathExists(path) {
 	}
 }
 
-function isInsidePath(childPath, parentPath) {
-	const child = resolve(childPath);
-	const parent = resolve(parentPath);
-	return child === parent || child.startsWith(`${parent}${sep}`);
-}
-
-function expandUserPath(path) {
-	if (path === "~") return homedir();
-	if (path.startsWith("~/")) return resolve(homedir(), path.slice(2));
-	return path;
-}
-
-function isPathLikeSource(source) {
-	return isAbsolute(source) || source.startsWith("./") || source.startsWith("../") || source.startsWith("~");
-}
-
-function sourceLooksLikeThisPackage(source, cwd, sourceBaseDir = cwd) {
-	const text = String(source ?? "").trim();
-	if (text.length === 0) return false;
-	if (/^npm:pi-agent-browser-native(?:@|$)/.test(text)) return true;
-	if (text === PACKAGE_NAME) return true;
-	if (text.includes(REPO_URL_FRAGMENT)) return true;
-
-	if (!isPathLikeSource(text)) return false;
-	const resolvedSource = resolve(sourceBaseDir, expandUserPath(text));
-	const cwdEntrypoints = EXTENSION_ENTRYPOINTS.map((entrypoint) => resolve(cwd, entrypoint));
-	const packageEntrypoints = EXTENSION_ENTRYPOINTS.map((entrypoint) => resolve(THIS_PACKAGE_ROOT, entrypoint));
-	return (
-		resolvedSource === cwd ||
-		resolvedSource === THIS_PACKAGE_ROOT ||
-		cwdEntrypoints.some((entrypoint) => resolvedSource === entrypoint || isInsidePath(entrypoint, resolvedSource)) ||
-		packageEntrypoints.some((entrypoint) => resolvedSource === entrypoint || isInsidePath(entrypoint, resolvedSource))
-	);
-}
-
-function stripJsonComments(text) {
-	let result = "";
-	let inString = false;
-	let quote = "";
-	let escaped = false;
-	let inLineComment = false;
-	let inBlockComment = false;
-
-	for (let index = 0; index < text.length; index += 1) {
-		const char = text[index];
-		const next = text[index + 1];
-
-		if (inLineComment) {
-			if (char === "\n") {
-				inLineComment = false;
-				result += char;
-			}
-			continue;
-		}
-		if (inBlockComment) {
-			if (char === "*" && next === "/") {
-				inBlockComment = false;
-				index += 1;
-			}
-			continue;
-		}
-		if (inString) {
-			result += char;
-			if (escaped) {
-				escaped = false;
-				continue;
-			}
-			if (char === "\\") {
-				escaped = true;
-				continue;
-			}
-			if (char === quote) {
-				inString = false;
-			}
-			continue;
-		}
-		if (char === '"' || char === "'") {
-			inString = true;
-			quote = char;
-			result += char;
-			continue;
-		}
-		if (char === "/" && next === "/") {
-			inLineComment = true;
-			index += 1;
-			continue;
-		}
-		if (char === "/" && next === "*") {
-			inBlockComment = true;
-			index += 1;
-			continue;
-		}
-		result += char;
-	}
-	return result;
-}
-
-function parseSettingsText(text, path) {
-	return JSON.parse(stripJsonComments(text));
-}
-
-function arrayEntries(value) {
-	return Array.isArray(value) ? value.entries() : [];
-}
-
-function entrySource(entry) {
-	if (typeof entry === "string") return entry;
-	if (entry && typeof entry === "object") return entry.source ?? entry.path ?? entry.package;
-	return undefined;
-}
-
-function collectSettingsSources(settings, settingsPath, cwd) {
-	const sources = [];
-	const sourceBaseDir = dirname(settingsPath);
-	for (const [index, entry] of arrayEntries(settings?.packages)) {
-		const source = entrySource(entry);
-		if (sourceLooksLikeThisPackage(source, cwd, sourceBaseDir)) {
-			sources.push({ kind: "package", source: String(source), location: `${settingsPath} packages[${index}]` });
-		}
-	}
-	for (const [index, entry] of arrayEntries(settings?.extensions)) {
-		const source = entrySource(entry);
-		if (sourceLooksLikeThisPackage(source, cwd, sourceBaseDir)) {
-			sources.push({ kind: "extension", source: String(source), location: `${settingsPath} extensions[${index}]` });
-		}
-	}
-	return sources;
-}
-
-function dedupe(paths) {
-	return [...new Set(paths.map((path) => resolve(path)))];
-}
-
-async function inspectSettingsPath({ path, cwd, readText }) {
-	try {
-		const text = await readText(path);
-		if (text === undefined) return { sources: [], warnings: [] };
-		const settings = parseSettingsText(text, path);
-		return { sources: collectSettingsSources(settings, path, cwd), warnings: [] };
-	} catch (error) {
-		return {
-			sources: [],
-			warnings: [`Could not inspect Pi settings ${path}: ${error instanceof Error ? error.message : String(error)}`],
-		};
-	}
-}
-
-async function collectRepoLocalSources({ cwd, pathExists }) {
-	const candidates = [resolve(cwd, ".pi/extensions/agent-browser.ts"), resolve(cwd, ".pi/extensions/agent-browser/index.ts")];
-	const sources = [];
-	for (const candidate of candidates) {
-		if (await pathExists(candidate)) {
-			sources.push({ kind: "repo-local", source: candidate, location: `${candidate} repo-local autoload` });
-		}
-	}
-	return sources;
-}
-
 async function checkPiVersion({ runPi }) {
 	try {
 		const rawOutput = await runPi(["--version"]);
@@ -327,10 +192,16 @@ async function checkPiVersion({ runPi }) {
 			return {
 				status: "warn",
 				title: `Could not parse pi --version output: ${version || "<empty>"}.`,
-				lines: [`Pi ${MINIMUM_PI_VERSION} or newer is required for this release; run this doctor from the same shell that launches Pi so the setup gate can verify the host runtime.`],
+				lines: [
+					`Pi ${MINIMUM_PI_VERSION} or newer is required for this release; run this doctor from the same shell that launches Pi so the setup gate can verify the host runtime.`,
+				],
 			};
 		}
-		return { status: "pass", title: `Pi version satisfies the minimum runtime floor: ${version}`, lines: [] };
+		return {
+			status: "pass",
+			title: `Pi version satisfies the minimum runtime floor: ${version}`,
+			lines: [],
+		};
 	} catch (error) {
 		const code = error && typeof error === "object" ? error.code : undefined;
 		return {
@@ -361,9 +232,10 @@ async function checkAgentBrowserVersion({ runAgentBrowser }) {
 		}
 		return {
 			status: "pass",
-			title: version === RECOMMENDED_VERSION
-				? `agent-browser version matches recommended baseline: ${version}`
-				: `agent-browser version meets supported floor: ${version} (recommended ${RECOMMENDED_VERSION})`,
+			title:
+				version === RECOMMENDED_VERSION
+					? `agent-browser version matches recommended baseline: ${version}`
+					: `agent-browser version meets supported floor: ${version} (recommended ${RECOMMENDED_VERSION})`,
 			lines: [],
 		};
 	} catch (error) {
@@ -383,89 +255,52 @@ async function checkAgentBrowserVersion({ runAgentBrowser }) {
 	}
 }
 
-async function checkPiSources({ cwd, agentDir, settingsPaths, readText, pathExists }) {
-	const defaultSettingsPaths = [resolve(agentDir, "settings.json"), resolve(cwd, ".pi/settings.json")];
-	const allSettingsPaths = dedupe([...defaultSettingsPaths, ...settingsPaths]);
-	const sources = [];
-	const warnings = [];
-
-	for (const path of allSettingsPaths) {
-		if (await pathExists(path)) {
-			const result = await inspectSettingsPath({ path, cwd, readText });
-			sources.push(...result.sources);
-			warnings.push(...result.warnings);
-		}
-	}
-	sources.push(...(await collectRepoLocalSources({ cwd, pathExists })));
-
-	if (sources.length > 1) {
-		return {
-			status: "fail",
-			title: "Duplicate pi-agent-browser-native sources detected.",
-			lines: [
-				"Pi may register multiple `agent_browser` tools when a checkout source and a package source are both active.",
-				"Detected sources:",
-				...sources.map((source) => `- ${source.source} from ${source.location}`),
-				"Keep exactly one active source:",
-				"- for normal use: keep `pi install npm:pi-agent-browser-native` and remove/disable checkout paths from Pi settings",
-				"- for temporary package or checkout trials: use `pi --approve --no-extensions -e <source>` when you intentionally trust the current project, or omit `--approve` to let Pi prompt in interactive mode",
-				"- for configured-source lifecycle validation: keep exactly one checkout or package source, then launch plain `pi`",
-			],
-			warnings,
-		};
-	}
-	if (sources.length === 1) {
-		return {
-			status: "pass",
-			title: "No duplicate pi-agent-browser-native sources detected.",
-			lines: [`Detected source: ${sources[0].source} from ${sources[0].location}`],
-			warnings,
-		};
-	}
+function doctorIo(options) {
 	return {
-		status: "warn",
-		title: "No configured pi-agent-browser-native source was found in inspected Pi settings.",
-		lines: [
-			"This is OK for isolated runs such as `pi --no-extensions -e npm:pi-agent-browser-native`, but normal package use should install exactly one source with `pi install npm:pi-agent-browser-native`.",
-		],
-		warnings,
+		readText: options.readText ?? ((path) => readFile(path, "utf8")),
+		pathExists: options.pathExists ?? defaultPathExists,
+		runAgentBrowser: options.runAgentBrowser ?? defaultRunAgentBrowser,
+		runPi: options.runPi ?? defaultRunPi,
 	};
 }
 
+/** @param {DoctorOptions} [options] @returns {Promise<DoctorReport>} */
 export async function evaluateDoctor(options = {}) {
 	const cwd = resolve(options.cwd ?? process.cwd());
 	const agentDir = resolve(options.agentDir ?? DEFAULT_AGENT_DIR);
-	const settingsPaths = (options.settingsPaths ?? []).map((path) => resolve(cwd, path));
-	const readText = options.readText ?? ((path) => readFile(path, "utf8"));
-	const pathExists = options.pathExists ?? defaultPathExists;
-	const runAgentBrowser = options.runAgentBrowser ?? defaultRunAgentBrowser;
-	const runPi = options.runPi ?? defaultRunPi;
+	const settingsPaths = Array.from(options.settingsPaths ?? [], (path) => resolve(cwd, path));
+	const { readText, pathExists, runAgentBrowser, runPi } = doctorIo(options);
 	const checks = [];
-	const failures = [];
+
 	const warnings = [];
 
 	const versionCheck = await checkAgentBrowserVersion({ runAgentBrowser });
 	checks.push(versionCheck);
-	if (versionCheck.status === "fail") failures.push(versionCheck);
 
 	const piVersionCheck = await checkPiVersion({ runPi });
 	checks.push(piVersionCheck);
-	if (piVersionCheck.status === "fail") failures.push(piVersionCheck);
 
 	if (!options.skipSourceCheck) {
-		const sourceCheck = await checkPiSources({ cwd, agentDir, settingsPaths, readText, pathExists });
+		const sourceCheck = await checkPiSources({
+			cwd,
+			agentDir,
+			settingsPaths,
+			readText,
+			pathExists,
+		});
 		checks.push(sourceCheck);
-		if (sourceCheck.status === "fail") failures.push(sourceCheck);
+
 		warnings.push(...(sourceCheck.warnings ?? []));
 	}
 
-	return { checks, failures, warnings };
+	return { checks, failures: checks.filter((check) => check.status === "fail"), warnings };
 }
 
+/** @param {DoctorReport} report @returns {string} */
 export function formatDoctorReport(report) {
 	const lines = ["pi-agent-browser-native doctor", ""];
 	for (const check of report.checks) {
-		const prefix = check.status === "pass" ? "✓" : check.status === "warn" ? "!" : "✗";
+		const prefix = { pass: "✓", warn: "!", fail: "✗" }[check.status];
 		lines.push(`${prefix} ${check.title}`);
 		for (const line of check.lines ?? []) {
 			lines.push(`  ${line}`);
@@ -475,7 +310,9 @@ export function formatDoctorReport(report) {
 	for (const warning of report.warnings ?? []) {
 		lines.push(`! ${warning}`);
 	}
-	if ((report.warnings ?? []).length > 0) lines.push("");
+	if ((report.warnings ?? []).length > 0) {
+		lines.push("");
+	}
 	lines.push(report.failures.length > 0 ? "Doctor found setup failures." : "Doctor passed.");
 	return lines.join("\n");
 }
@@ -502,8 +339,11 @@ export async function main(argv = process.argv.slice(2)) {
 	return 0;
 }
 
+/** @param {string} metaUrl @param {string | undefined} [argv1] @param {(path: string) => string} [resolveRealPath] @returns {boolean} */
 export function isDirectRun(metaUrl, argv1 = process.argv[1], resolveRealPath = realpathSync) {
-	if (!argv1) return false;
+	if (!argv1) {
+		return false;
+	}
 	try {
 		return resolveRealPath(argv1) === fileURLToPath(metaUrl);
 	} catch {
@@ -512,7 +352,12 @@ export function isDirectRun(metaUrl, argv1 = process.argv[1], resolveRealPath =
 }
 
 if (isDirectRun(import.meta.url)) {
-	main().then((exitCode) => {
-		process.exitCode = exitCode;
-	});
+	main()
+		.then((exitCode) => {
+			process.exitCode = exitCode;
+		})
+		.catch((error) => {
+			console.error(error instanceof Error ? error.message : error);
+			process.exitCode = 1;
+		});
 }