@vostride/agent-qa-plugin-kit 0.0.1 → 0.3.1

package/dist/scripted-plugin.js

@@ -0,0 +1,985 @@
+import { appendFileSync, existsSync, readFileSync, realpathSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { z } from "zod";
+import { format, inspect } from "node:util";
+// src/protocol/messages.ts
+const PLUGIN_METHODS = [
+	"initialize",
+	"check",
+	"acquire",
+	"uploadApp",
+	"started",
+	"end",
+	"release",
+	"shutdown"
+];
+const OPTIONAL_PLUGIN_METHODS = [
+	"check",
+	"uploadApp",
+	"started",
+	"end"
+];
+const PLUGIN_SERVES = [
+	"playwright",
+	"cdp",
+	"appium"
+];
+const PLUGIN_RUN_FACTS = [
+	"testName",
+	"runId",
+	"failure"
+];
+const PLUGIN_FAILURE_KINDS = [
+	"unreachable",
+	"auth",
+	"capacity",
+	"timeout",
+	"version",
+	"refused",
+	"ended",
+	"lost"
+];
+const PLUGIN_ERROR_CODES = {
+	parse: -32700,
+	invalidRequest: -32600,
+	methodNotFound: -32601,
+	invalidParams: -32602,
+	plugin: -32e3,
+	cancelled: -32800
+};
+const PROGRESS_METHOD = "$/progress";
+const MAX_MESSAGE_BYTES = 1048576;
+const JsonObjectSchema = z.record(z.string(), z.unknown());
+const HandleSchema = z.json();
+const RequestIdSchema = z.union([z.string(), z.number()]);
+const InitializeParamsSchema = z.object({
+	protocolVersions: z.array(z.number().int()),
+	host: z.object({
+		pid: z.number().int(),
+		agentQaVersion: z.string(),
+		playwrightVersion: z.string(),
+		webdriverioVersion: z.string()
+	}),
+	entry: z.string(),
+	options: JsonObjectSchema,
+	runFacts: z.object({ runId: z.string().optional() }).optional()
+});
+z.object({
+	protocolVersion: z.number().int(),
+	plugin: z.object({
+		name: z.string(),
+		version: z.string()
+	}),
+	serves: z.array(z.enum(PLUGIN_SERVES)),
+	methods: z.array(z.enum(OPTIONAL_PLUGIN_METHODS))
+});
+const CheckParamsSchema = z.object({ remotes: z.array(z.object({
+	name: z.string(),
+	settings: JsonObjectSchema
+})) });
+const CheckResultSchema = z.object({
+	state: z.enum(["ok", "warn"]),
+	lines: z.array(z.string())
+});
+const WebSessionSchema = z.object({
+	platform: z.literal("web"),
+	engine: z.enum([
+		"chromium",
+		"firefox",
+		"webkit"
+	]),
+	context: z.enum(["new", "reuse"])
+});
+const DeviceSessionSchema = z.object({
+	platform: z.enum(["android", "ios"]),
+	capabilities: JsonObjectSchema
+});
+const AcquireParamsSchema = z.object({
+	remote: z.string(),
+	settings: JsonObjectSchema,
+	session: z.discriminatedUnion("platform", [WebSessionSchema, DeviceSessionSchema]),
+	run: z.object({ testName: z.string().optional() }).optional()
+});
+const AcquireResultSchema = z.object({
+	handle: HandleSchema,
+	protocol: z.enum(PLUGIN_SERVES),
+	url: z.string(),
+	headers: z.record(z.string(), z.string()).optional(),
+	capabilities: JsonObjectSchema.optional(),
+	mask: z.array(z.string()).optional(),
+	link: z.string().optional()
+});
+const UploadAppParamsSchema = z.object({
+	remote: z.string(),
+	settings: JsonObjectSchema,
+	platform: z.enum(["android", "ios"]),
+	path: z.string(),
+	sha256: z.string(),
+	size: z.number().int().nonnegative()
+});
+const UploadAppResultSchema = z.object({ ref: z.string() });
+const StartedParamsSchema = z.object({
+	handle: HandleSchema,
+	sessionId: z.string().optional()
+});
+const StartedResultSchema = z.object({
+	link: z.string().optional(),
+	appiumVersion: z.string().optional()
+});
+const EndParamsSchema = z.object({
+	handle: HandleSchema,
+	outcome: z.enum([
+		"passed",
+		"failed",
+		"error",
+		"cancelled"
+	]),
+	reason: z.string().optional()
+});
+const ReleaseParamsSchema = z.object({ handle: HandleSchema });
+const CancelParamsSchema = z.object({ id: RequestIdSchema });
+z.object({
+	id: RequestIdSchema,
+	message: z.string(),
+	queued: z.number().int().nonnegative().optional(),
+	percent: z.number().min(0).max(100).optional()
+});
+z.object({
+	kind: z.enum(PLUGIN_FAILURE_KINDS),
+	path: z.string().optional(),
+	handle: HandleSchema.optional(),
+	supported: z.array(z.number().int()).optional(),
+	requested: z.array(z.number().int()).optional()
+});
+// src/define-plugin.ts
+var PluginError = class extends Error {
+	kind;
+	path;
+	handle;
+	constructor(message, options) {
+		super(message);
+		this.name = "PluginError";
+		this.kind = options.kind;
+		this.path = options.path;
+		this.handle = options.handle;
+	}
+};
+function definePlugin(spec) {
+	const methods = OPTIONAL_PLUGIN_METHODS.filter((method) => typeof spec[method] === "function");
+	return {
+		...spec,
+		methods
+	};
+}
+// src/package-root.ts
+function findPackageRoot(fromDir) {
+	let dir = fromDir;
+	for (;;) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+function readPackageJson(packageRoot) {
+	const parsed = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	return typeof parsed === "object" && parsed !== null ? parsed : {};
+}
+// src/protocol/manifest.ts
+const PLUGIN_MANIFEST_FIELD = "agent-qa";
+const PackagePathSchema = z.string().min(1);
+const RemotePluginManifestSchema = z.strictObject({
+	kind: z.literal("remote"),
+	runs: z.literal("process"),
+	protocol: z.number().int().positive(),
+	entry: PackagePathSchema,
+	serves: z.array(z.enum(PLUGIN_SERVES)).nonempty(),
+	methods: z.array(z.enum(OPTIONAL_PLUGIN_METHODS)),
+	options: PackagePathSchema,
+	settings: PackagePathSchema,
+	runFacts: z.array(z.enum(PLUGIN_RUN_FACTS)).optional(),
+	skill: PackagePathSchema.optional()
+});
+const ModelAuthManifestSchema = z.strictObject({
+	kind: z.literal("model-auth"),
+	runs: z.literal("in-process"),
+	entry: PackagePathSchema,
+	options: PackagePathSchema.optional()
+});
+const ModelProviderManifestSchema = z.strictObject({
+	kind: z.literal("model-provider"),
+	runs: z.literal("in-process"),
+	entry: PackagePathSchema,
+	options: PackagePathSchema.optional()
+});
+const PluginManifestSchema = z.discriminatedUnion("kind", [
+	RemotePluginManifestSchema,
+	ModelAuthManifestSchema,
+	ModelProviderManifestSchema
+]);
+// src/protocol/framing.ts
+function encodeMessage(message) {
+	return `${JSON.stringify(message)}\n`;
+}
+const NEWLINE = 10;
+function createLineDecoder({ maxLineBytes, onLine, onOverflow }) {
+	const encoder = new TextEncoder();
+	const decoder = new TextDecoder();
+	let parts = [];
+	let size = 0;
+	let discarding = false;
+	const append = (segment) => {
+		if (discarding || segment.length === 0) return;
+		if (size + segment.length > maxLineBytes) {
+			discarding = true;
+			parts = [];
+			size = 0;
+			onOverflow();
+			return;
+		}
+		parts.push(new Uint8Array(segment));
+		size += segment.length;
+	};
+	const finishLine = () => {
+		const wasDiscarding = discarding;
+		const lineParts = parts;
+		const lineSize = size;
+		parts = [];
+		size = 0;
+		discarding = false;
+		if (wasDiscarding || lineSize === 0) return;
+		const bytes = new Uint8Array(lineSize);
+		let offset = 0;
+		for (const part of lineParts) {
+			bytes.set(part, offset);
+			offset += part.length;
+		}
+		const line = decoder.decode(bytes).replace(/\r$/, "");
+		if (line.trim() !== "") onLine(line);
+	};
+	return {
+		push(chunk) {
+			const bytes = typeof chunk === "string" ? encoder.encode(chunk) : chunk;
+			let start = 0;
+			while (start <= bytes.length) {
+				const newline = bytes.indexOf(NEWLINE, start);
+				if (newline === -1) {
+					append(bytes.subarray(start));
+					return;
+				}
+				append(bytes.subarray(start, newline));
+				finishLine();
+				start = newline + 1;
+			}
+		},
+		end() {
+			finishLine();
+		}
+	};
+}
+const RELEASE_ON_CLOSE_BOUND_MS = 3e4;
+const RELEASE_ON_SIGTERM_BOUND_MS = 4e3;
+const SUPPORTED_PROTOCOL_VERSIONS = [1];
+var ProtocolFailure = class extends Error {
+	code;
+	data;
+	constructor(code, message, data) {
+		super(message);
+		this.code = code;
+		this.data = data;
+	}
+};
+function resolveIo(io) {
+	return {
+		stdin: io.stdin ?? process.stdin,
+		stdout: io.stdout ?? process.stdout,
+		exit: io.exit ?? ((code) => process.exit(code)),
+		entryPath: io.entryPath ?? process.argv[1],
+		cancelAnswerGraceMs: io.cancelAnswerGraceMs ?? 4e3,
+		hostPidPollMs: io.hostPidPollMs ?? 1e3
+	};
+}
+function routeStrayOutputToStderr() {
+	const toLog = (...args) => {
+		process.stderr.write(`${format(...args)}\n`);
+	};
+	console.log = toLog;
+	console.info = toLog;
+	console.debug = toLog;
+	console.warn = toLog;
+	process.stdout.write = process.stderr.write.bind(process.stderr);
+}
+function hostGone(hostPid, startPpid) {
+	if (process.ppid !== startPpid) return true;
+	try {
+		process.kill(hostPid, 0);
+		return false;
+	} catch (error) {
+		return error.code === "ESRCH";
+	}
+}
+function handleKey(handle) {
+	const canonical = (value) => {
+		if (Array.isArray(value)) return value.map(canonical);
+		if (value === null || typeof value !== "object") return value;
+		return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+	};
+	return JSON.stringify(canonical(handle));
+}
+function within(work, boundMs) {
+	let timer;
+	const bound = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(void 0), boundMs);
+	});
+	return Promise.race([work, bound]).finally(() => clearTimeout(timer));
+}
+function firstLine(message) {
+	return message.split(/\r?\n/, 1)[0] ?? "";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRequestId(value) {
+	return typeof value === "string" || typeof value === "number";
+}
+function isPluginMethod(method) {
+	return PLUGIN_METHODS.includes(method);
+}
+function isOptionalMethod(method) {
+	return OPTIONAL_PLUGIN_METHODS.includes(method);
+}
+function issuePath(issue) {
+	return issue.path.map(String).join(".");
+}
+function parseParams(schema, params, method) {
+	const parsed = schema.safeParse(params ?? {});
+	if (parsed.success) return parsed.data;
+	const issue = parsed.error.issues[0];
+	const where = issue === void 0 ? "" : issuePath(issue);
+	throw new ProtocolFailure(PLUGIN_ERROR_CODES.invalidParams, `${method} params${where === "" ? "" : ` at ${where}`}: ${issue?.message ?? "invalid"}`);
+}
+function refuse(schema, value, prefix) {
+	const parsed = schema.safeParse(value);
+	if (parsed.success) return parsed.data;
+	const issue = parsed.error.issues[0];
+	const inner = issue === void 0 ? "" : issuePath(issue);
+	const path = inner === "" ? void 0 : `${prefix}.${inner}`;
+	throw new PluginError(`${path ?? prefix}: ${issue?.message ?? "invalid"}`, {
+		kind: "refused",
+		...path === void 0 ? {} : { path }
+	});
+}
+function checkedResult(schema, value, method) {
+	const parsed = schema.safeParse(value);
+	if (parsed.success) return value;
+	const issue = parsed.error.issues[0];
+	const where = issue === void 0 ? "" : issuePath(issue);
+	const handle = method === "acquire" && isRecord(value) && value.handle !== void 0 ? value.handle : void 0;
+	throw new PluginError(`${method} answered a malformed result${where === "" ? "" : ` at ${where}`}: ${issue?.message ?? "invalid"}`, {
+		kind: "refused",
+		...handle === void 0 ? {} : { handle }
+	});
+}
+function pluginIdentity(entryPath) {
+	const unknown = {
+		name: "unknown",
+		version: "unknown"
+	};
+	if (entryPath === void 0) return unknown;
+	try {
+		const root = findPackageRoot(dirname(realpathSync(entryPath)));
+		if (root === void 0) return unknown;
+		const pkg = readPackageJson(root);
+		return {
+			name: typeof pkg.name === "string" ? pkg.name : unknown.name,
+			version: typeof pkg.version === "string" ? pkg.version : unknown.version
+		};
+	} catch {
+		return unknown;
+	}
+}
+function runPlugin(definition, ioInput = {}) {
+	const io = resolveIo(ioInput);
+	const write = io.stdout.write.bind(io.stdout);
+	const ownsProcess = ioInput.stdout === void 0;
+	if (ownsProcess) {
+		routeStrayOutputToStderr();
+		process.stdout.on("error", () => {});
+		process.stderr.on("error", () => {});
+		process.on("SIGINT", () => {});
+		process.on("uncaughtException", (error) => {
+			try {
+				writeSync(2, `${inspect(error)}\n`);
+			} catch {}
+			process.exit(1);
+		});
+	}
+	const send = (message) => {
+		if (leaving) return;
+		write(encodeMessage(message));
+	};
+	const answer = (id, result) => send({
+		jsonrpc: "2.0",
+		id,
+		result
+	});
+	const fail = (id, code, message, data) => send({
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code,
+			message: firstLine(message),
+			...data === void 0 ? {} : { data }
+		}
+	});
+	let options;
+	let runFacts;
+	let initialized = false;
+	let initializing = false;
+	let shutdownRan = false;
+	let leaving = false;
+	let hostPoll;
+	const startPpid = process.ppid;
+	const pending = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Set();
+	const held = /* @__PURE__ */ new Map();
+	const releasing = /* @__PURE__ */ new Map();
+	const detachedContext = () => ({
+		signal: new AbortController().signal,
+		progress: () => {},
+		runFacts
+	});
+	const hold = (handle) => held.set(handleKey(handle), handle);
+	const releaseOnce = (handle, ctx) => {
+		const key = handleKey(handle);
+		const running = releasing.get(key);
+		if (running !== void 0) return running;
+		const work = (async () => {
+			try {
+				await definition.release({
+					handle,
+					options
+				}, ctx);
+				held.delete(key);
+			} finally {
+				releasing.delete(key);
+			}
+		})();
+		releasing.set(key, work);
+		return work;
+	};
+	const releaseHeld = (attempted) => Promise.allSettled([...held].filter(([key]) => !attempted.has(key)).map(([key, handle]) => {
+		attempted.add(key);
+		return releaseOnce(handle, detachedContext());
+	}));
+	const settings = (value) => refuse(definition.settings, value, "settings");
+	const leave = async (boundMs) => {
+		if (leaving) return;
+		leaving = true;
+		clearInterval(hostPoll);
+		const sequence = async () => {
+			if (!initialized) return;
+			for (const entry of pending.values()) if (entry.method !== "release" && entry.method !== "shutdown") entry.controller.abort();
+			const attempted = /* @__PURE__ */ new Set();
+			await Promise.allSettled([releaseHeld(attempted), ...inFlight]);
+			await releaseHeld(attempted);
+			if (shutdownRan) return;
+			shutdownRan = true;
+			await definition.shutdown?.({ options }, detachedContext());
+		};
+		await within(sequence().catch(() => {}), boundMs);
+		write("", () => io.exit(0));
+	};
+	const watchHost = (hostPid) => {
+		hostPoll = setInterval(() => {
+			if (hostGone(hostPid, startPpid)) leave(RELEASE_ON_CLOSE_BOUND_MS);
+		}, io.hostPidPollMs);
+		hostPoll.unref();
+	};
+	const initialize = async (params, ctx) => {
+		if (initialized || initializing) throw new ProtocolFailure(PLUGIN_ERROR_CODES.invalidRequest, "initialize was already called");
+		const input = parseParams(InitializeParamsSchema, params, "initialize");
+		const offered = input.protocolVersions.filter((version) => SUPPORTED_PROTOCOL_VERSIONS.includes(version));
+		if (offered.length === 0) throw new ProtocolFailure(PLUGIN_ERROR_CODES.plugin, `this plugin speaks protocol ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")}, and the host offered ${input.protocolVersions.join(", ") || "none"}`, {
+			kind: "version",
+			supported: SUPPORTED_PROTOCOL_VERSIONS,
+			requested: input.protocolVersions
+		});
+		const parsedOptions = refuse(definition.options, input.options, "options");
+		initializing = true;
+		try {
+			await definition.initialize?.({
+				options: parsedOptions,
+				host: input.host,
+				entry: input.entry,
+				runFacts: input.runFacts
+			}, {
+				...ctx,
+				runFacts: input.runFacts
+			});
+		} finally {
+			initializing = false;
+		}
+		options = parsedOptions;
+		runFacts = input.runFacts;
+		initialized = true;
+		watchHost(input.host.pid);
+		return {
+			protocolVersion: Math.max(...offered),
+			plugin: pluginIdentity(io.entryPath),
+			serves: [...definition.serves],
+			methods: [...definition.methods]
+		};
+	};
+	const call = async (method, params, ctx) => {
+		if (method === "initialize") return initialize(params, ctx);
+		if (!isPluginMethod(method) || isOptionalMethod(method) && (!definition.methods.includes(method) || typeof definition[method] !== "function")) throw new ProtocolFailure(PLUGIN_ERROR_CODES.methodNotFound, `${method} is not a method of this plugin`);
+		if (!initialized) throw new ProtocolFailure(PLUGIN_ERROR_CODES.invalidRequest, `${method} came before initialize`);
+		const current = options;
+		switch (method) {
+			case "acquire": {
+				const input = parseParams(AcquireParamsSchema, params, method);
+				const result = await definition.acquire({
+					...input,
+					settings: settings(input.settings),
+					options: current
+				}, ctx);
+				return checkedResult(AcquireResultSchema, result, method);
+			}
+			case "release": {
+				const input = parseParams(ReleaseParamsSchema, params, method);
+				await releaseOnce(input.handle, ctx);
+				return {};
+			}
+			case "shutdown":
+				shutdownRan = true;
+				await releaseHeld(/* @__PURE__ */ new Set());
+				await definition.shutdown?.({ options: current }, ctx);
+				return {};
+			case "check": {
+				const remotes = parseParams(CheckParamsSchema, params, method).remotes.map((remote) => ({
+					name: remote.name,
+					settings: settings(remote.settings)
+				}));
+				const result = await definition.check?.({
+					remotes,
+					options: current
+				}, ctx);
+				return checkedResult(CheckResultSchema, result, method);
+			}
+			case "uploadApp": {
+				const input = parseParams(UploadAppParamsSchema, params, method);
+				const result = await definition.uploadApp?.({
+					...input,
+					settings: settings(input.settings),
+					options: current
+				}, ctx);
+				return checkedResult(UploadAppResultSchema, result, method);
+			}
+			case "started": {
+				const input = parseParams(StartedParamsSchema, params, method);
+				const result = await definition.started?.({
+					...input,
+					options: current
+				}, ctx);
+				return checkedResult(StartedResultSchema, result, method);
+			}
+			case "end": {
+				const input = parseParams(EndParamsSchema, params, method);
+				await definition.end?.({
+					...input,
+					options: current
+				}, ctx);
+				return {};
+			}
+			default: throw new ProtocolFailure(PLUGIN_ERROR_CODES.methodNotFound, `${method} is not a method of this plugin`);
+		}
+	};
+	const createdHandle = (method, outcome) => {
+		if (outcome.ok) {
+			if (method !== "acquire" || !isRecord(outcome.value)) return void 0;
+			return outcome.value.handle;
+		}
+		return outcome.error instanceof PluginError ? outcome.error.handle : void 0;
+	};
+	const answerFailure = (id, error) => {
+		if (error instanceof ProtocolFailure) fail(id, error.code, error.message, error.data);
+		else if (error instanceof PluginError) fail(id, PLUGIN_ERROR_CODES.plugin, error.message, {
+			kind: error.kind,
+			...error.path === void 0 ? {} : { path: error.path },
+			...error.handle === void 0 ? {} : { handle: error.handle }
+		});
+		else {
+			const message = error instanceof Error ? error.message : String(error);
+			fail(id, PLUGIN_ERROR_CODES.plugin, message, { kind: "unreachable" });
+		}
+	};
+	const dispatch = async (id, method, params) => {
+		const entry = {
+			method,
+			controller: new AbortController(),
+			answered: false
+		};
+		pending.set(id, entry);
+		const ctx = {
+			signal: entry.controller.signal,
+			progress: (update) => {
+				if (entry.answered) return;
+				send({
+					jsonrpc: "2.0",
+					method: PROGRESS_METHOD,
+					params: {
+						id,
+						...update
+					}
+				});
+			},
+			runFacts
+		};
+		let outcome;
+		try {
+			outcome = {
+				ok: true,
+				value: await call(method, params, ctx)
+			};
+		} catch (error) {
+			outcome = {
+				ok: false,
+				error
+			};
+		}
+		clearTimeout(entry.graceTimer);
+		if (pending.get(id) === entry) pending.delete(id);
+		const handle = createdHandle(method, outcome);
+		const tracked = initialized ? handle : void 0;
+		if (tracked !== void 0) hold(tracked);
+		if (entry.answered) {
+			if (tracked !== void 0) await releaseOnce(tracked, detachedContext()).catch(() => {});
+			return;
+		}
+		if (leaving) return;
+		entry.answered = true;
+		if (outcome.ok) answer(id, outcome.value);
+		else if (entry.controller.signal.aborted) {
+			const message = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+			fail(id, PLUGIN_ERROR_CODES.cancelled, message, {
+				kind: "timeout",
+				...handle === void 0 ? {} : { handle }
+			});
+		} else answerFailure(id, outcome.error);
+	};
+	const cancel = (params) => {
+		const parsed = CancelParamsSchema.safeParse(params);
+		if (!parsed.success) return;
+		const { id } = parsed.data;
+		const entry = pending.get(id);
+		if (entry === void 0 || entry.controller.signal.aborted) return;
+		entry.controller.abort();
+		entry.graceTimer = setTimeout(() => {
+			if (entry.answered) return;
+			entry.answered = true;
+			fail(id, PLUGIN_ERROR_CODES.cancelled, `${entry.method} did not stop within ${io.cancelAnswerGraceMs} ms of its cancel`, { kind: "timeout" });
+		}, io.cancelAnswerGraceMs);
+	};
+	const handleLine = (line) => {
+		let message;
+		try {
+			message = JSON.parse(line);
+		} catch {
+			fail(null, PLUGIN_ERROR_CODES.parse, "the line is not JSON");
+			return;
+		}
+		if (!isRecord(message)) {
+			fail(null, PLUGIN_ERROR_CODES.invalidRequest, "a message must be a JSON-RPC 2.0 object");
+			return;
+		}
+		const id = isRequestId(message.id) ? message.id : null;
+		if (message.method === void 0 && ("result" in message || "error" in message)) return;
+		if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+			fail(id, PLUGIN_ERROR_CODES.invalidRequest, "a request needs jsonrpc \"2.0\" and a method");
+			return;
+		}
+		if (!("id" in message)) {
+			if (message.method === "$/cancel") cancel(message.params);
+			return;
+		}
+		if (id === null) {
+			fail(null, PLUGIN_ERROR_CODES.invalidRequest, "a request id is a string or a number");
+			return;
+		}
+		if (leaving) return;
+		const run = dispatch(id, message.method, message.params);
+		inFlight.add(run);
+		run.catch(() => {}).finally(() => inFlight.delete(run));
+	};
+	const decoder = createLineDecoder({
+		maxLineBytes: MAX_MESSAGE_BYTES,
+		onLine: handleLine,
+		onOverflow: () => fail(null, PLUGIN_ERROR_CODES.invalidRequest, `a message is longer than ${MAX_MESSAGE_BYTES} bytes`)
+	});
+	const stdinClosed = () => {
+		if (leaving) return;
+		decoder.end();
+		leave(RELEASE_ON_CLOSE_BOUND_MS);
+	};
+	if (ownsProcess) process.on("SIGTERM", () => void leave(RELEASE_ON_SIGTERM_BOUND_MS));
+	io.stdin.on("data", (chunk) => decoder.push(chunk));
+	io.stdin.on("end", stdinClosed);
+	io.stdin.on("error", stdinClosed);
+}
+// src/testing/scripted-plugin-main.ts
+const ScriptStepSchema = z.union([
+	z.enum([
+		"ok",
+		"hold",
+		"crash",
+		"uncaught",
+		"noise",
+		"consoleLog",
+		"ignoreCancel"
+	]),
+	z.object({ error: z.object({
+		kind: z.enum(PLUGIN_FAILURE_KINDS),
+		message: z.string(),
+		path: z.string().optional()
+	}) }),
+	z.object({
+		delayMs: z.number().int().nonnegative(),
+		ignoreCancel: z.boolean().optional()
+	}),
+	z.object({ errorAfterCreate: z.object({
+		kind: z.enum(PLUGIN_FAILURE_KINDS),
+		message: z.string()
+	}) })
+]);
+const ScriptSchema = z.union([ScriptStepSchema, z.array(ScriptStepSchema).min(1)]);
+const AnswerSchema = z.object({
+	protocol: z.enum(PLUGIN_SERVES),
+	url: z.string(),
+	headers: z.record(z.string(), z.string()).optional(),
+	capabilities: z.record(z.string(), z.unknown()).optional(),
+	mask: z.array(z.string()).optional(),
+	link: z.string().optional()
+});
+const ProgressSchema = z.object({
+	message: z.string(),
+	queued: z.number().int().nonnegative().optional(),
+	percent: z.number().min(0).max(100).optional()
+});
+const ScriptedOptionsSchema = z.looseObject({
+	ledgerFile: z.string().optional(),
+	recordProcess: z.boolean().optional(),
+	recordParams: z.boolean().optional(),
+	answer: AnswerSchema.optional(),
+	answerFile: z.string().optional(),
+	script: z.record(z.string(), ScriptSchema).optional(),
+	stderr: z.record(z.string(), z.string()).optional(),
+	progress: z.array(ProgressSchema).optional(),
+	progressByRemote: z.record(z.string(), z.array(ProgressSchema)).optional(),
+	progressEveryMs: z.number().int().positive().optional(),
+	started: StartedResultSchema.optional(),
+	upload: UploadAppResultSchema.optional(),
+	check: CheckResultSchema.optional()
+});
+function readOwnManifest() {
+	const entryPath = process.argv[1];
+	if (entryPath === void 0) throw new Error("the scripted plugin needs its entry path");
+	const root = findPackageRoot(dirname(realpathSync(entryPath)));
+	if (root === void 0) throw new Error(`no package.json above ${entryPath}`);
+	const field = readPackageJson(root)[PLUGIN_MANIFEST_FIELD];
+	const plugin = typeof field === "object" && field !== null ? Reflect.get(field, "plugin") : void 0;
+	const manifest = PluginManifestSchema.parse(plugin);
+	if (manifest.kind !== "remote") throw new Error("the scripted plugin is a remote plugin");
+	return manifest;
+}
+function ledger(options, entry) {
+	if (options.ledgerFile !== void 0) appendFileSync(options.ledgerFile, `${JSON.stringify(entry)}\n`);
+}
+function cancelled(method, handle) {
+	return new PluginError(`${method} was cancelled`, {
+		kind: "timeout",
+		...handle === void 0 ? {} : { handle }
+	});
+}
+const callsSoFar = /* @__PURE__ */ new Map();
+function reportProgress(options, remote, ctx) {
+	const updates = options.progressByRemote?.[remote] ?? options.progress ?? [];
+	for (const update of updates) ctx.progress(update);
+	if (options.progressEveryMs === void 0 || updates.length === 0) return () => {};
+	let next = 0;
+	const timer = setInterval(() => {
+		const update = updates[next % updates.length];
+		next += 1;
+		if (update !== void 0) ctx.progress(update);
+	}, options.progressEveryMs);
+	return () => clearInterval(timer);
+}
+function stepFor(options, method) {
+	const planned = options.script?.[method] ?? "ok";
+	if (!Array.isArray(planned)) return planned;
+	const call = callsSoFar.get(method) ?? 0;
+	callsSoFar.set(method, call + 1);
+	return planned[Math.min(call, planned.length - 1)] ?? "ok";
+}
+async function follow(options, method, ctx, handle) {
+	const logged = options.stderr?.[method];
+	if (logged !== void 0) writeSync(2, `${logged}\n`);
+	const step = stepFor(options, method);
+	switch (step) {
+		case "ok": return;
+		case "hold":
+			await new Promise((resolve) => {
+				ctx.signal.addEventListener("abort", () => resolve(), { once: true });
+			});
+			throw cancelled(method, handle);
+		case "ignoreCancel":
+			await new Promise(() => {});
+			return;
+		case "crash": process.exit(1);
+		case "uncaught":
+			process.emitWarning("a dependency used a deprecated API", "DeprecationWarning", "DEP0000");
+			setTimeout(() => {
+				throw new Error(`${method} threw where nothing catches it`);
+			}, 10);
+			await new Promise(() => {});
+			return;
+		case "noise":
+			writeSync(1, "noise\n");
+			return;
+		case "consoleLog":
+			console.log(`${method} logged to the console`);
+			return;
+	}
+	if ("delayMs" in step) {
+		try {
+			await setTimeout$1(step.delayMs, void 0, step.ignoreCancel ? {} : { signal: ctx.signal });
+		} catch {
+			throw cancelled(method, handle);
+		}
+		return;
+	}
+	if ("errorAfterCreate" in step) throw new PluginError(step.errorAfterCreate.message, {
+		kind: step.errorAfterCreate.kind,
+		...handle === void 0 ? {} : { handle }
+	});
+	throw new PluginError(step.error.message, {
+		kind: step.error.kind,
+		...step.error.path === void 0 ? {} : { path: step.error.path }
+	});
+}
+function startScriptedPlugin(timing = {}) {
+	const manifest = readOwnManifest();
+	const declares = (method) => manifest.methods.includes(method);
+	let issued = 0;
+	runPlugin(definePlugin({
+		options: ScriptedOptionsSchema,
+		settings: z.looseObject({}),
+		serves: manifest.serves,
+		...manifest.runFacts === void 0 ? {} : { runFacts: manifest.runFacts },
+		async initialize({ options, host, runFacts }, ctx) {
+			ledger(options, {
+				method: "initialize",
+				...options.recordProcess === true ? {
+					execPath: process.execPath,
+					pid: process.pid,
+					envKeys: Object.keys(process.env),
+					options,
+					host,
+					...runFacts === void 0 ? {} : { runFacts }
+				} : {}
+			});
+			await follow(options, "initialize", ctx);
+		},
+		async acquire({ options, remote, session, run }, ctx) {
+			issued += 1;
+			const handle = { n: issued };
+			ledger(options, {
+				method: "acquire",
+				handle,
+				remote,
+				...options.recordParams === true ? {
+					session,
+					...run === void 0 ? {} : { run }
+				} : {}
+			});
+			const stopProgress = reportProgress(options, remote, ctx);
+			try {
+				await follow(options, "acquire", ctx, handle);
+			} finally {
+				stopProgress();
+			}
+			const answer = options.answerFile === void 0 ? options.answer : AnswerSchema.parse(JSON.parse(readFileSync(options.answerFile, "utf8")));
+			if (answer === void 0) throw new PluginError("the scripted plugin has no answer option", {
+				kind: "refused",
+				path: "answer"
+			});
+			return {
+				handle,
+				...answer
+			};
+		},
+		async release({ options, handle }, ctx) {
+			ledger(options, {
+				method: "release",
+				handle
+			});
+			await follow(options, "release", ctx);
+		},
+		async shutdown({ options }, ctx) {
+			ledger(options, { method: "shutdown" });
+			await follow(options, "shutdown", ctx);
+		},
+		...declares("check") ? { async check({ options }, ctx) {
+			ledger(options, { method: "check" });
+			await follow(options, "check", ctx);
+			return options.check ?? {
+				state: "ok",
+				lines: []
+			};
+		} } : {},
+		...declares("uploadApp") ? { async uploadApp({ options, remote, settings, platform, path, sha256, size }, ctx) {
+			ledger(options, {
+				method: "uploadApp",
+				remote,
+				...options.recordParams === true ? {
+					settings,
+					platform,
+					path,
+					sha256,
+					size
+				} : {}
+			});
+			const stopProgress = reportProgress(options, remote, ctx);
+			try {
+				await follow(options, "uploadApp", ctx);
+			} finally {
+				stopProgress();
+			}
+			return options.upload ?? { ref: "scripted-app" };
+		} } : {},
+		...declares("started") ? { async started({ options, handle, sessionId }, ctx) {
+			ledger(options, {
+				method: "started",
+				handle,
+				...options.recordParams === true && sessionId !== void 0 ? { sessionId } : {}
+			});
+			await follow(options, "started", ctx);
+			return options.started ?? {};
+		} } : {},
+		...declares("end") ? { async end({ options, handle, outcome, reason }, ctx) {
+			ledger(options, {
+				method: "end",
+				handle,
+				...options.recordParams === true ? {
+					outcome,
+					...reason === void 0 ? {} : { reason }
+				} : {}
+			});
+			await follow(options, "end", ctx);
+		} } : {}
+	}), timing);
+}
+export { startScriptedPlugin };
+
+//# sourceMappingURL=scripted-plugin.js.map