pi-agent-browser-native 0.9.3 → 0.9.5

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)), "..");
 
-export function normalizeAgentBrowserVersion(output) {
-	return String(output ?? "").trim().replace(/^agent-browser\s+/, "");
+/** @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 */
+
+function normalizeAgentBrowserVersion(output) {
+	return String(output ?? "")
+		.trim()
+		.replace(/^agent-browser\s+/, "");
 }
 
-export function normalizePiVersion(output) {
-	return String(output ?? "").trim().replace(/^pi\s+/, "");
+function normalizePiVersion(output) {
+	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;
+		});
 }

package/scripts/platform-smoke/artifacts.mjs

@@ -18,7 +18,10 @@ export function writeExitCode(dir, code, signal) {
 }
 
 export function writeSummary(dir, data) {
-	writeFileSync(resolve(dir, "summary.json"), JSON.stringify({ ...data, writtenAt: new Date().toISOString() }, null, 2));
+	writeFileSync(
+		resolve(dir, "summary.json"),
+		JSON.stringify({ ...data, writtenAt: new Date().toISOString() }, null, 2),
+	);
 }
 
 export function writeManifest(dir, expectedFiles) {
@@ -26,11 +29,16 @@ export function writeManifest(dir, expectedFiles) {
 	function walk(current) {
 		for (const entry of readdirSync(current, { withFileTypes: true })) {
 			const path = resolve(current, entry.name);
-			if (entry.isDirectory()) walk(path);
-			else if (entry.isFile()) present.push(relative(dir, path));
+			if (entry.isDirectory()) {
+				walk(path);
+			} else if (entry.isFile()) {
+				present.push(relative(dir, path));
+			}
 		}
 	}
-	if (existsSync(dir)) walk(dir);
+	if (existsSync(dir)) {
+		walk(dir);
+	}
 	const allPresent = [...new Set([...present, "artifact-manifest.json"])].sort();
 	const manifest = {
 		expected: expectedFiles,
@@ -43,7 +51,13 @@ export function writeManifest(dir, expectedFiles) {
 }
 
 export function collectSecretValues(envNames, env = process.env) {
-	return [...new Set(envNames.map((name) => env[name]).filter((value) => typeof value === "string" && value.length >= 8))];
+	return [
+		...new Set(
+			envNames
+				.map((name) => env[name])
+				.filter((value) => typeof value === "string" && value.length >= 8),
+		),
+	];
 }
 
 export function redactSecrets(text, secretValues = []) {
@@ -58,14 +72,21 @@ export function scanForSecrets(text, secretValues = []) {
 	const content = String(text ?? "");
 	const violations = [];
 	for (const secret of secretValues) {
-		if (secret && content.includes(secret)) violations.push("raw forwarded secret value");
+		if (secret && content.includes(secret)) {
+			violations.push("raw forwarded secret value");
+		}
 	}
 	for (const [pattern, label] of [
 		[/bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/gi, "bearer token"],
 		[/Authorization:\s*Bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/gi, "authorization header"],
-		[/(?:api[_-]?key|access[_-]?token|refresh[_-]?token|cookie)\s*[:=]\s*["']?[A-Za-z0-9_./+\-=]{20,}/gi, "token-like field"],
+		[
+			/(?:api[_-]?key|access[_-]?token|refresh[_-]?token|cookie)\s*[:=]\s*["']?[A-Za-z0-9_./+\-=]{20,}/gi,
+			"token-like field",
+		],
 	]) {
-		if (pattern.test(content)) violations.push(label);
+		if (pattern.test(content)) {
+			violations.push(label);
+		}
 	}
 	return [...new Set(violations)];
 }
@@ -79,11 +100,17 @@ export function scanArtifactTextFiles(dir, secretValues = []) {
 				walk(path);
 				continue;
 			}
-			if (!entry.isFile()) continue;
-			if (!/\.(?:txt|json|jsonl|md|log|ps1|mjs|js)$/i.test(entry.name)) continue;
+			if (!entry.isFile()) {
+				continue;
+			}
+			if (!/\.(?:txt|json|jsonl|md|log|ps1|mjs|js)$/i.test(entry.name)) {
+				continue;
+			}
 			try {
 				const text = readFileSync(path, "utf8");
-				for (const violation of scanForSecrets(text, secretValues)) findings.push({ file: relative(dir, path), violation });
+				for (const violation of scanForSecrets(text, secretValues)) {
+					findings.push({ file: relative(dir, path), violation });
+				}
 			} catch {
 				// Ignore unreadable or non-text files.
 			}

package/scripts/platform-smoke/commands.mjs

@@ -0,0 +1,104 @@
+/** Native POSIX/PowerShell platform command rendering; every required gate contributes to the final exit. */
+import { CAPABILITY_BASELINE } from "../agent-browser-capability-baseline.mjs";
+import { platformFor } from "./suite-evidence.mjs";
+
+function shellQuote(value) {
+	return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function psSingleQuote(value) {
+	return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+export function buildPlatformBuildCommand(targetName, packageName, nodeValidationVersion) {
+	if (platformFor(targetName) === "powershell") {
+		return `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\\scripts\\platform-smoke\\platform-build-windows.ps1 -PackageName ${psSingleQuote(packageName)} -NodeValidationVersion ${psSingleQuote(nodeValidationVersion)}`;
+	}
+	return [
+		`echo "Starting platform-build in $(pwd) at $(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
+		`RUN_ROOT=".platform-smoke-runs/platform-build-$(date -u +%Y%m%dT%H%M%SZ)-$$"`,
+		`SOURCE_ROOT="$(pwd)"`,
+		`PACK_DIR="$SOURCE_ROOT/$RUN_ROOT/pack"`,
+		`PI_PROJECT="$SOURCE_ROOT/$RUN_ROOT/pi-project"`,
+		`mkdir -p "$PACK_DIR" "$PI_PROJECT"`,
+		`echo "PLATFORM_RUN_ROOT=$RUN_ROOT"`,
+		`NODE_VERSION=$(node --version)`,
+		`echo "PLATFORM_NODE_VERSION=$NODE_VERSION"`,
+		`if node -e 'process.exit(process.versions.node.localeCompare(process.argv[1], undefined, { numeric: true }) < 0 ? 1 : 0)' ${shellQuote(nodeValidationVersion)}; then NODE_VERSION_EXIT=0; else NODE_VERSION_EXIT=1; fi`,
+		`echo "PLATFORM_NODE_VERSION_EXIT=$NODE_VERSION_EXIT"`,
+		`npm ci 2>&1`,
+		`NPM_CI_EXIT=$?`,
+		`echo "PLATFORM_NPM_CI_EXIT=$NPM_CI_EXIT"`,
+		`npm run verify -- platform-target 2>&1`,
+		`VERIFY_EXIT=$?`,
+		`echo "PLATFORM_VERIFY_EXIT=$VERIFY_EXIT"`,
+		`PACK_TARBALL=$(npm pack --silent --pack-destination "$PACK_DIR" 2>"$PACK_DIR/npm-pack.stderr.txt")`,
+		`PACK_EXIT=$?`,
+		`cat "$PACK_DIR/npm-pack.stderr.txt"`,
+		`PACK_FILE="$PACK_DIR/$PACK_TARBALL"`,
+		`echo "PLATFORM_NPM_PACK_EXIT=$PACK_EXIT"`,
+		`echo "PLATFORM_PACKED_TARBALL=$PACK_FILE"`,
+		`PI_CLI="$SOURCE_ROOT/node_modules/.bin/pi"`,
+		`if [ ! -x "$PI_CLI" ]; then PI_CLI="$(command -v pi || true)"; fi`,
+		`echo "PLATFORM_PI_CLI=$PI_CLI"`,
+		`if [ -n "$PACK_TARBALL" ] && [ -f "$PACK_FILE" ]; then (cd "$PI_PROJECT" && npm init -y >"$PACK_DIR/packed-node-install.stdout.txt" 2>"$PACK_DIR/packed-node-install.stderr.txt" && npm install --no-save "$PACK_FILE" >>"$PACK_DIR/packed-node-install.stdout.txt" 2>>"$PACK_DIR/packed-node-install.stderr.txt"); PACKED_NODE_INSTALL_EXIT=$?; else echo "missing tarball" >"$PACK_DIR/packed-node-install.stderr.txt"; PACKED_NODE_INSTALL_EXIT=1; fi`,
+		`echo "PLATFORM_PACKED_NODE_INSTALL_EXIT=$PACKED_NODE_INSTALL_EXIT"`,
+		`echo "--- PACKED_NODE_INSTALL_STDOUT START ---"; cat "$PACK_DIR/packed-node-install.stdout.txt" 2>/dev/null || true; echo "--- PACKED_NODE_INSTALL_STDOUT END ---"`,
+		`echo "--- PACKED_NODE_INSTALL_STDERR START ---"; cat "$PACK_DIR/packed-node-install.stderr.txt" 2>/dev/null || true; echo "--- PACKED_NODE_INSTALL_STDERR END ---"`,
+		`if [ "$PACKED_NODE_INSTALL_EXIT" -eq 0 ] && [ -n "$PI_CLI" ]; then (cd "$PI_PROJECT" && PI_OFFLINE=1 "$PI_CLI" install -l --approve ./node_modules/${packageName} >"$PACK_DIR/pi-install.stdout.txt" 2>"$PACK_DIR/pi-install.stderr.txt"); PI_INSTALL_EXIT=$?; else echo "missing pi cli or packed install" >"$PACK_DIR/pi-install.stderr.txt"; PI_INSTALL_EXIT=1; fi`,
+		`echo "PLATFORM_PI_INSTALL_EXIT=$PI_INSTALL_EXIT"`,
+		`echo "--- PI_INSTALL_STDOUT START ---"; cat "$PACK_DIR/pi-install.stdout.txt" 2>/dev/null || true; echo "--- PI_INSTALL_STDOUT END ---"`,
+		`echo "--- PI_INSTALL_STDERR START ---"; cat "$PACK_DIR/pi-install.stderr.txt" 2>/dev/null || true; echo "--- PI_INSTALL_STDERR END ---"`,
+		`if [ -n "$PI_CLI" ]; then (cd "$PI_PROJECT" && PI_OFFLINE=1 "$PI_CLI" list --approve >"$PACK_DIR/pi-list.stdout.txt" 2>"$PACK_DIR/pi-list.stderr.txt"); PI_LIST_EXIT=$?; else echo "missing pi cli" >"$PACK_DIR/pi-list.stderr.txt"; PI_LIST_EXIT=1; fi`,
+		`echo "PLATFORM_PI_LIST_EXIT=$PI_LIST_EXIT"`,
+		`echo "--- PI_LIST_STDOUT START ---"; cat "$PACK_DIR/pi-list.stdout.txt" 2>/dev/null || true; echo "--- PI_LIST_STDOUT END ---"`,
+		`echo "--- PI_LIST_STDERR START ---"; cat "$PACK_DIR/pi-list.stderr.txt" 2>/dev/null || true; echo "--- PI_LIST_STDERR END ---"`,
+		`if [ "$NODE_VERSION_EXIT" -ne 0 ] || [ "$NPM_CI_EXIT" -ne 0 ] || [ "$VERIFY_EXIT" -ne 0 ] || [ "$PACK_EXIT" -ne 0 ] || [ "$PACKED_NODE_INSTALL_EXIT" -ne 0 ] || [ "$PI_INSTALL_EXIT" -ne 0 ] || [ "$PI_LIST_EXIT" -ne 0 ]; then echo "PLATFORM_BUILD_FAILED"; exit 1; fi`,
+		`echo "PLATFORM_BUILD_OK"`,
+	].join("\n");
+}
+
+export function buildBrowserDogfoodCommand(
+	targetName,
+	agentBrowserVersion = CAPABILITY_BASELINE.targetVersion,
+	dependenciesReady = false,
+) {
+	if (platformFor(targetName) === "powershell") {
+		return `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\\scripts\\platform-smoke\\browser-dogfood-windows.ps1 -AgentBrowserVersion ${psSingleQuote(agentBrowserVersion)}${dependenciesReady ? " -SkipNpmCi" : ""}`;
+	}
+	return [
+		`echo "Starting browser-dogfood-smoke in $(pwd) at $(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
+		`RUN_ROOT=".platform-smoke-runs/browser-dogfood-$(date -u +%Y%m%dT%H%M%SZ)-$$"`,
+		`SOURCE_ROOT="$(pwd)"`,
+		`DOGFOOD_DIR="$SOURCE_ROOT/$RUN_ROOT/dogfood"`,
+		`DOGFOOD_ARTIFACT_DIR="$DOGFOOD_DIR/artifacts"`,
+		`mkdir -p "$DOGFOOD_ARTIFACT_DIR"`,
+		`echo "PLATFORM_RUN_ROOT=$RUN_ROOT"`,
+		`echo "PLATFORM_DOGFOOD_ARTIFACT_DIR=$DOGFOOD_ARTIFACT_DIR"`,
+		`NODE_VERSION=$(node --version)`,
+		`NODE_MAJOR="${"${NODE_VERSION#v}"}"`,
+		`NODE_MAJOR="${"${NODE_MAJOR%%.*}"}"`,
+		`echo "PLATFORM_NODE_VERSION=$NODE_VERSION"`,
+		`EXPECTED_AGENT_BROWSER_VERSION=${shellQuote(`agent-browser ${agentBrowserVersion}`)}`,
+		`AGENT_BROWSER_VERSION_OUTPUT=$(agent-browser --version 2>&1)`,
+		`AGENT_BROWSER_VERSION_COMMAND_EXIT=$?`,
+		`echo "PLATFORM_AGENT_BROWSER_VERSION=$AGENT_BROWSER_VERSION_OUTPUT"`,
+		`if [ "$AGENT_BROWSER_VERSION_COMMAND_EXIT" -eq 0 ] && [ "$AGENT_BROWSER_VERSION_OUTPUT" = "$EXPECTED_AGENT_BROWSER_VERSION" ]; then AGENT_BROWSER_READY_EXIT=0; else AGENT_BROWSER_READY_EXIT=1; fi`,
+		`echo "PLATFORM_AGENT_BROWSER_READY_EXIT=$AGENT_BROWSER_READY_EXIT"`,
+		...(dependenciesReady
+			? [
+					`if [ -d node_modules ]; then echo "PLATFORM_NPM_CI_SKIPPED=1"; NPM_CI_EXIT=0; else npm ci 2>&1; NPM_CI_EXIT=$?; fi`,
+				]
+			: [`npm ci 2>&1`, `NPM_CI_EXIT=$?`]),
+		`echo "PLATFORM_NPM_CI_EXIT=$NPM_CI_EXIT"`,
+		`TSX_CLI="$SOURCE_ROOT/node_modules/.bin/tsx"`,
+		`if [ ! -x "$TSX_CLI" ]; then TSX_CLI="$(command -v tsx || true)"; fi`,
+		`echo "PLATFORM_TSX_CLI=$TSX_CLI"`,
+		`if [ "$NPM_CI_EXIT" -eq 0 ] && [ "$AGENT_BROWSER_READY_EXIT" -eq 0 ] && [ -n "$TSX_CLI" ]; then "$TSX_CLI" scripts/verify-agent-browser-dogfood.ts --artifact-dir "$DOGFOOD_ARTIFACT_DIR" --json >"$DOGFOOD_DIR/dogfood.stdout.txt" 2>"$DOGFOOD_DIR/dogfood.stderr.txt"; DOGFOOD_EXIT=$?; else echo "missing tsx, npm ci failed, or agent-browser baseline mismatch" >"$DOGFOOD_DIR/dogfood.stderr.txt"; DOGFOOD_EXIT=1; fi`,
+		`echo "PLATFORM_DOGFOOD_EXIT=$DOGFOOD_EXIT"`,
+		`echo "--- DOGFOOD_STDOUT START ---"; cat "$DOGFOOD_DIR/dogfood.stdout.txt" 2>/dev/null || true; echo "--- DOGFOOD_STDOUT END ---"`,
+		`echo "--- DOGFOOD_STDERR START ---"; cat "$DOGFOOD_DIR/dogfood.stderr.txt" 2>/dev/null || true; echo "--- DOGFOOD_STDERR END ---"`,
+		`if [ "$NPM_CI_EXIT" -ne 0 ] || [ "$AGENT_BROWSER_READY_EXIT" -ne 0 ] || [ "$DOGFOOD_EXIT" -ne 0 ]; then echo "PLATFORM_BROWSER_DOGFOOD_FAILED"; exit 1; fi`,
+		`echo "PLATFORM_BROWSER_DOGFOOD_OK"`,
+	].join("\n");
+}