experimental-a2 0.2.0 → 0.4.0

package/dist/cli-B3VuxoDe.js

@@ -0,0 +1,597 @@
+import { l as parseDevtoolsCapture, s as devtoolsSessionRevision, u as verifyDevtoolsCapture } from "./devtools-kJJaORn-.js";
+import { resolve } from "node:path";
+import { open, readFile } from "node:fs/promises";
+//#region src/cli.ts
+const DEVTOOLS_CLI_EXIT_ERROR = 1;
+const DEVTOOLS_CLI_EXIT_CHECK_FAILED = 2;
+var CliFailure = class extends Error {
+	exitCode;
+	constructor(message, exitCode = 1) {
+		super(message);
+		this.name = "CliFailure";
+		this.exitCode = exitCode;
+	}
+};
+var IntegrityFailure = class extends CliFailure {
+	constructor(message) {
+		super(message, 2);
+		this.name = "IntegrityFailure";
+	}
+};
+const USAGE = `Usage: a2 devtools <command> [options]
+
+Commands:
+  contracts                    List mounted contracts
+  sessions --contract NAME     List a contract's sessions
+  show --contract NAME --session ID
+                               Show one durable session
+  export --contract NAME --session ID [--output FILE]
+                               Save an integrity-protected .a2log capture
+  check --contract NAME --session ID [assertions]
+                               Verify a live session capture
+  verify FILE                  Verify a saved .a2log capture
+
+Connection:
+  --url URL                    Mounted devtools URL (or A2_DEVTOOLS_URL)
+  --bearer-env ENV             Read a bearer token from ENV
+  --header-env HEADER=ENV      Read a request header from ENV; repeatable
+
+Output:
+  --format human|json|ndjson   Human output is the default
+  --output FILE, -o FILE       Export destination
+  --force                      Allow export to replace FILE
+
+Check assertions:
+  --settled                    Require no pending events
+  --no-dead-letters            Require no dead-lettered events
+  --no-caught-failures         Require no caught handler failures
+  --max-redispatches N         Limit dispatches after each event's first claim
+`;
+const commandNames = /* @__PURE__ */ new Set([
+	"contracts",
+	"sessions",
+	"show",
+	"export",
+	"check",
+	"verify"
+]);
+const fail = (message) => {
+	throw new CliFailure(message);
+};
+const nextValue = (argv, index, option) => {
+	const token = argv[index];
+	const equals = token.indexOf("=");
+	if (equals !== -1) {
+		const value = token.slice(equals + 1);
+		if (value.length === 0) fail(`${option} requires a value`);
+		return {
+			value,
+			next: index
+		};
+	}
+	const value = argv[index + 1];
+	if (value === void 0 || value.startsWith("-")) fail(`${option} requires a value`);
+	return {
+		value,
+		next: index + 1
+	};
+};
+const nonNegativeInteger = (value, option) => {
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed < 0) fail(`${option} must be a non-negative integer`);
+	return parsed;
+};
+const positiveInteger = (value, option) => {
+	const parsed = nonNegativeInteger(value, option);
+	if (parsed === 0) fail(`${option} must be a positive integer`);
+	return parsed;
+};
+const parseArguments = (argv) => {
+	if (argv[0] !== "devtools") {
+		if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") return {
+			command: null,
+			help: true,
+			url: void 0,
+			format: "human",
+			contract: void 0,
+			session: void 0,
+			cursor: void 0,
+			limit: void 0,
+			output: void 0,
+			force: false,
+			bearerEnv: void 0,
+			headerEnvs: [],
+			settled: false,
+			noDeadLetters: false,
+			noCaughtFailures: false,
+			maxRedispatches: void 0,
+			positionals: []
+		};
+		fail("expected the 'devtools' command namespace");
+	}
+	const parsed = {
+		command: null,
+		help: false,
+		url: void 0,
+		format: "human",
+		contract: void 0,
+		session: void 0,
+		cursor: void 0,
+		limit: void 0,
+		output: void 0,
+		force: false,
+		bearerEnv: void 0,
+		headerEnvs: [],
+		settled: false,
+		noDeadLetters: false,
+		noCaughtFailures: false,
+		maxRedispatches: void 0,
+		positionals: []
+	};
+	for (let index = 1; index < argv.length; index += 1) {
+		const token = argv[index];
+		if (token === "--help" || token === "-h" || token === "help") {
+			parsed.help = true;
+			continue;
+		}
+		if (token === "--token" || token.startsWith("--token=") || token === "--bearer" || token.startsWith("--bearer=") || token === "--header" || token.startsWith("--header=")) fail("literal credential flags are not supported; use A2_DEVTOOLS_TOKEN, --bearer-env, or --header-env");
+		if (token === "--force") {
+			parsed.force = true;
+			continue;
+		}
+		if (token === "--settled") {
+			parsed.settled = true;
+			continue;
+		}
+		if (token === "--no-dead-letters") {
+			parsed.noDeadLetters = true;
+			continue;
+		}
+		if (token === "--no-caught-failures") {
+			parsed.noCaughtFailures = true;
+			continue;
+		}
+		const option = token.split("=", 1)[0];
+		if (option === "--url" || option === "--format" || option === "--contract" || option === "--session" || option === "--cursor" || option === "--limit" || option === "--output" || option === "-o" || option === "--bearer-env" || option === "--header-env" || option === "--max-redispatches") {
+			const result = nextValue(argv, index, option);
+			index = result.next;
+			switch (option) {
+				case "--url":
+					parsed.url = result.value;
+					break;
+				case "--format":
+					if (result.value !== "human" && result.value !== "json" && result.value !== "ndjson") fail("--format must be human, json, or ndjson");
+					parsed.format = result.value;
+					break;
+				case "--contract":
+					parsed.contract = result.value;
+					break;
+				case "--session":
+					parsed.session = result.value;
+					break;
+				case "--cursor":
+					parsed.cursor = result.value;
+					break;
+				case "--limit":
+					parsed.limit = positiveInteger(result.value, "--limit");
+					break;
+				case "--output":
+				case "-o":
+					parsed.output = result.value;
+					break;
+				case "--bearer-env":
+					parsed.bearerEnv = result.value;
+					break;
+				case "--header-env":
+					parsed.headerEnvs.push(result.value);
+					break;
+				case "--max-redispatches": parsed.maxRedispatches = nonNegativeInteger(result.value, "--max-redispatches");
+			}
+			continue;
+		}
+		if (token.startsWith("-")) fail(`unknown option '${token}'`);
+		if (parsed.command === null && commandNames.has(token)) {
+			parsed.command = token;
+			continue;
+		}
+		if (parsed.command === null) fail(`unknown devtools command '${token}'`);
+		parsed.positionals.push(token);
+	}
+	return parsed;
+};
+const required = (value, option) => {
+	if (value === void 0) fail(`${option} is required`);
+	return value;
+};
+const assertCommandArguments = (args) => {
+	if (args.command === null) return;
+	if (args.command === "verify") {
+		if (args.positionals.length !== 1) fail("verify requires exactly one capture file");
+		return;
+	}
+	if (args.positionals.length > 0) fail(`unexpected argument '${args.positionals[0]}'`);
+	if (args.command !== "contracts") required(args.contract, "--contract");
+	if (args.command === "show" || args.command === "export" || args.command === "check") required(args.session, "--session");
+};
+const baseUrl = (value) => {
+	const url = (() => {
+		try {
+			return new URL(value);
+		} catch {
+			return fail("--url must be an absolute HTTP(S) URL");
+		}
+	})();
+	if (url.protocol !== "http:" && url.protocol !== "https:") fail("--url must use HTTP or HTTPS");
+	if (url.username || url.password) fail("credentials must not be embedded in --url");
+	if (url.search || url.hash) fail("--url must not contain a query string or fragment");
+	url.pathname = `${url.pathname.replace(/\/+$/, "")}/`;
+	return url;
+};
+const environmentName = (value, option) => {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) fail(`${option} must reference a valid environment variable name`);
+	return value;
+};
+const requestHeaders = (args, env, accept) => {
+	const headers = new Headers({ accept });
+	const bearerName = args.bearerEnv === void 0 ? "A2_DEVTOOLS_TOKEN" : environmentName(args.bearerEnv, "--bearer-env");
+	const bearer = env[bearerName];
+	if (args.bearerEnv !== void 0 && !bearer) fail(`environment variable '${bearerName}' is not set`);
+	if (bearer) headers.set("authorization", `Bearer ${bearer}`);
+	for (const mapping of args.headerEnvs) {
+		const equals = mapping.indexOf("=");
+		if (equals < 1 || equals === mapping.length - 1) fail("--header-env must use HEADER=ENV");
+		const name = mapping.slice(0, equals);
+		const envName = environmentName(mapping.slice(equals + 1), "--header-env");
+		const value = env[envName];
+		if (!value) fail(`environment variable '${envName}' is not set`);
+		if (headers.has(name)) fail(`request header '${name}' was configured twice`);
+		try {
+			headers.set(name, value);
+		} catch {
+			fail(`--header-env contains an invalid header name or value`);
+		}
+	}
+	return headers;
+};
+const resourceUrl = (base, resource, params) => {
+	const url = new URL(`_a2/${resource}`, base);
+	for (const [name, value] of Object.entries(params)) if (value !== void 0) url.searchParams.set(name, String(value));
+	return url;
+};
+const terminalText = (value) => [...value].map((character) => {
+	const codePoint = character.codePointAt(0);
+	if (!(codePoint <= 31 || codePoint >= 127 && codePoint <= 159 || codePoint === 8232 || codePoint === 8233)) return character;
+	if (character === "\n") return "\\n";
+	if (character === "\r") return "\\r";
+	if (character === "	") return "\\t";
+	return codePoint <= 255 ? `\\x${codePoint.toString(16).padStart(2, "0")}` : `\\u${codePoint.toString(16).padStart(4, "0")}`;
+}).join("");
+const fetchResponse = async (fetcher, url, headers, resource) => {
+	let response;
+	try {
+		response = await fetcher(url, {
+			method: "GET",
+			headers,
+			redirect: "manual"
+		});
+	} catch (error) {
+		throw new CliFailure(`could not fetch ${resource}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!response.ok) {
+		let text = "";
+		try {
+			text = await response.text();
+		} catch {}
+		const detail = terminalText(text.trim().slice(0, 300));
+		throw new CliFailure(`${resource} returned ${response.status}${detail ? `: ${detail}` : ""}`);
+	}
+	return response;
+};
+const responseText = async (fetcher, url, headers, resource) => (await fetchResponse(fetcher, url, headers, resource)).text();
+const responseBytes = async (fetcher, url, headers, resource) => new Uint8Array(await (await fetchResponse(fetcher, url, headers, resource)).arrayBuffer());
+const objectValue = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+const parseJson = (text, resource) => {
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliFailure(`${resource} did not return valid JSON`);
+	}
+};
+const assertProtocol = (value, resource) => {
+	if (value["protocolVersion"] !== 1) throw new CliFailure(`${resource} returned an unsupported protocol version`);
+};
+const hasContractName = (value) => {
+	const object = objectValue(value);
+	return typeof object?.["name"] === "string" && object["name"].length > 0;
+};
+const contractsResponse = (value) => {
+	const object = objectValue(value);
+	if (!object) throw new CliFailure("contracts returned an invalid response");
+	assertProtocol(object, "contracts");
+	if (!Array.isArray(object["contracts"]) || !object["contracts"].every(hasContractName)) throw new CliFailure("contracts returned an invalid response");
+	return object;
+};
+const sessionsResponse = (value) => {
+	const object = objectValue(value);
+	if (!object) throw new CliFailure("sessions returned an invalid response");
+	assertProtocol(object, "sessions");
+	if (!Array.isArray(object["sessions"]) || object["cursor"] !== null && typeof object["cursor"] !== "string") throw new CliFailure("sessions returned an invalid response");
+	return object;
+};
+const sessionResponse = (value) => {
+	const object = objectValue(value);
+	if (!object) throw new CliFailure("session returned an invalid response");
+	assertProtocol(object, "session");
+	if (typeof object["contract"] !== "string" || typeof object["sessionId"] !== "string" || typeof object["revision"] !== "string" || !Array.isArray(object["events"]) || !Array.isArray(object["snapshots"])) throw new CliFailure("session returned an invalid response");
+	return object;
+};
+const sessionPageResponse = (value) => {
+	const object = objectValue(value);
+	if (!object) throw new CliFailure("session returned an invalid response");
+	assertProtocol(object, "session");
+	if (typeof object["contract"] !== "string" || typeof object["sessionId"] !== "string" || !Number.isSafeInteger(object["throughIndex"]) || object["throughIndex"] < 0 || object["cursor"] !== null && typeof object["cursor"] !== "string" || !Array.isArray(object["events"]) || !Array.isArray(object["snapshots"])) throw new CliFailure("session returned an invalid response");
+	return object;
+};
+const readSessionDetail = async (fetcher, base, headers, contract, session) => {
+	const events = [];
+	let snapshots = [];
+	let cursor;
+	let throughIndex;
+	const seenCursors = /* @__PURE__ */ new Set();
+	for (;;) {
+		const text = await responseText(fetcher, resourceUrl(base, "session", {
+			contract,
+			session,
+			limit: 250,
+			cursor
+		}), headers, "session");
+		const parsed = parseJson(text, "session");
+		const object = objectValue(parsed);
+		if (object && typeof object["revision"] === "string") {
+			if (events.length > 0) throw new CliFailure("session changed response shape between pages");
+			return sessionResponse(parsed);
+		}
+		const page = sessionPageResponse(parsed);
+		if (page.contract !== contract || page.sessionId !== session) throw new CliFailure("session page returned a different identity");
+		if (throughIndex === void 0) {
+			throughIndex = page.throughIndex;
+			snapshots = page.snapshots;
+		} else if (page.throughIndex !== throughIndex || page.snapshots.length > 0) throw new CliFailure("session page changed its frozen frontier");
+		for (const event of page.events) {
+			if (event.index !== events.length + 1 || event.index > throughIndex) throw new CliFailure("session event pages are not contiguous");
+			events.push(event);
+		}
+		if (page.cursor === null) break;
+		if (page.events.length === 0 || events.length === throughIndex || seenCursors.has(page.cursor)) throw new CliFailure("session cursor did not advance");
+		seenCursors.add(page.cursor);
+		cursor = page.cursor;
+	}
+	if (throughIndex !== events.length) throw new CliFailure("session ended before its frozen frontier");
+	return {
+		protocolVersion: 1,
+		contract,
+		sessionId: session,
+		revision: await devtoolsSessionRevision({
+			events,
+			snapshots
+		}),
+		events,
+		snapshots
+	};
+};
+const jsonText = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const ndjsonText = (values) => values.map((value) => JSON.stringify(value)).join("\n") + (values.length === 0 ? "" : "\n");
+const humanContracts = (response) => response.contracts.length === 0 ? "No contracts.\n" : `${response.contracts.map((contract) => terminalText(contract.name)).join("\n")}\n`;
+const humanSessions = (response) => {
+	if (response.sessions.length === 0) return "No sessions.\n";
+	return ["SESSION	EVENTS	PENDING	DEAD	ATTEMPTS	FAILURES	UPDATED", ...response.sessions.map((session) => [
+		terminalText(session.sessionId),
+		session.eventCount,
+		session.pendingCount,
+		session.failedCount,
+		session.attemptCount,
+		session.failureCount,
+		terminalText(session.updatedAt)
+	].join("	"))].join("\n") + "\n";
+};
+const humanSession = (detail) => {
+	const rows = detail.events.map((event) => {
+		const status = event.failedAt ? "dead-lettered" : event.processedAt ? "completed" : "pending";
+		return `${event.index}\t${status}\t${terminalText(event.type)}\t${terminalText(event.id)}`;
+	});
+	const heading = `${terminalText(detail.contract)}/${terminalText(detail.sessionId)}: ${detail.events.length} events, ${detail.snapshots.length} snapshots\n`;
+	return rows.length === 0 ? heading : `${heading}INDEX\tSTATUS\tTYPE\tID\n${rows.join("\n")}\n`;
+};
+const emitResponse = (format, value, ndjson, human, stdout) => {
+	if (format === "json") stdout(jsonText(value));
+	else if (format === "ndjson") stdout(ndjsonText(ndjson));
+	else stdout(human);
+};
+const parseAndVerifyCapture = async (bytes) => {
+	let text;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		throw new IntegrityFailure("capture is not valid UTF-8");
+	}
+	try {
+		const capture = parseDevtoolsCapture(text);
+		await verifyDevtoolsCapture(capture);
+		return capture;
+	} catch (error) {
+		throw new IntegrityFailure(error instanceof Error ? error.message : String(error));
+	}
+};
+const captureSummary = (capture) => {
+	let pendingCount = 0;
+	let deadLetterCount = 0;
+	let caughtFailureCount = 0;
+	let redispatchCount = 0;
+	for (const event of capture.events) {
+		if (event.processedAt === null && event.failedAt === null) pendingCount += 1;
+		if (event.failedAt !== null) deadLetterCount += 1;
+		if (!Number.isSafeInteger(event.failureCount) || event.failureCount < 0 || !Number.isSafeInteger(event.attemptCount) || event.attemptCount < 0) throw new IntegrityFailure(`event #${event.index} has invalid attempt or failure counts`);
+		caughtFailureCount += event.failureCount;
+		redispatchCount += Math.max(0, event.attemptCount - 1);
+	}
+	return {
+		ok: true,
+		contract: capture.contract,
+		sessionId: capture.sessionId,
+		revision: capture.revision,
+		eventCount: capture.events.length,
+		snapshotCount: capture.snapshots.length,
+		pendingCount,
+		deadLetterCount,
+		caughtFailureCount,
+		redispatchCount,
+		failures: []
+	};
+};
+const checkSummary = (capture, args) => {
+	const summary = captureSummary(capture);
+	if (capture.contract !== args.contract) summary.failures.push(`capture contract '${capture.contract}' does not match '${args.contract}'`);
+	if (capture.sessionId !== args.session) summary.failures.push(`capture session '${capture.sessionId}' does not match '${args.session}'`);
+	if (args.settled && summary.pendingCount > 0) summary.failures.push(`${summary.pendingCount} event(s) are pending`);
+	if (args.noDeadLetters && summary.deadLetterCount > 0) summary.failures.push(`${summary.deadLetterCount} event(s) are dead-lettered`);
+	if (args.noCaughtFailures && summary.caughtFailureCount > 0) summary.failures.push(`${summary.caughtFailureCount} caught handler failure(s) were recorded`);
+	if (args.maxRedispatches !== void 0 && summary.redispatchCount > args.maxRedispatches) summary.failures.push(`${summary.redispatchCount} redispatch(es) exceed the limit of ${args.maxRedispatches}`);
+	summary.ok = summary.failures.length === 0;
+	return summary;
+};
+const assertCaptureIdentity = (capture, contract, sessionId) => {
+	if (capture.contract !== contract) throw new IntegrityFailure(`capture contract '${capture.contract}' does not match '${contract}'`);
+	if (capture.sessionId !== sessionId) throw new IntegrityFailure(`capture session '${capture.sessionId}' does not match '${sessionId}'`);
+};
+const humanCheck = (summary, verb) => `${verb} ${terminalText(summary.contract)}/${terminalText(summary.sessionId)}: ${summary.eventCount} events, ${summary.snapshotCount} snapshots, ${summary.pendingCount} pending, ${summary.deadLetterCount} dead-lettered, ${summary.caughtFailureCount} caught failures, ${summary.redispatchCount} redispatches\n`;
+const defaultCaptureName = (contract, sessionId) => {
+	return `${`${contract}-${sessionId}`.replaceAll(/[^a-zA-Z0-9._-]/g, "_").slice(0, 160) || "a2-session"}.a2log`;
+};
+const errorCode = (error) => {
+	const object = objectValue(error);
+	return typeof object?.["code"] === "string" ? object["code"] : void 0;
+};
+const writeCaptureFile = async (path, data, options) => {
+	const file = await open(path, options.flag, options.mode);
+	try {
+		await file.chmod(options.mode);
+		await file.writeFile(data);
+	} finally {
+		await file.close();
+	}
+};
+/** Run the `a2 devtools` command namespace and return its process exit code. */
+async function runCli(argv, options = {}) {
+	const stdout = options.stdout ?? ((text) => process.stdout.write(text));
+	const stderr = options.stderr ?? ((text) => process.stderr.write(text));
+	const env = options.env ?? process.env;
+	const fetcher = options.fetch ?? globalThis.fetch;
+	const cwd = options.cwd ?? process.cwd();
+	const readFile$1 = options.readFile ?? readFile;
+	const writeFile = options.writeFile ?? writeCaptureFile;
+	try {
+		const args = parseArguments(argv);
+		if (args.help || args.command === null) {
+			stdout(USAGE);
+			return 0;
+		}
+		assertCommandArguments(args);
+		if (args.command === "verify") {
+			const path = resolve(cwd, args.positionals[0]);
+			let bytes;
+			try {
+				bytes = await readFile$1(path);
+			} catch (error) {
+				throw new CliFailure(`could not read '${path}': ${error instanceof Error ? error.message : String(error)}`);
+			}
+			const summary = captureSummary(await parseAndVerifyCapture(bytes));
+			emitResponse(args.format, summary, [summary], humanCheck(summary, "Verified"), stdout);
+			return 0;
+		}
+		const configuredUrl = args.url ?? env["A2_DEVTOOLS_URL"];
+		if (!configuredUrl) fail("--url or A2_DEVTOOLS_URL is required");
+		const base = baseUrl(configuredUrl);
+		const headers = requestHeaders(args, env, "application/json");
+		if (args.command === "contracts") {
+			const text = await responseText(fetcher, resourceUrl(base, "contracts", {}), headers, "contracts");
+			const response = contractsResponse(parseJson(text, "contracts"));
+			emitResponse(args.format, response, response.contracts, humanContracts(response), stdout);
+			return 0;
+		}
+		const contract = required(args.contract, "--contract");
+		if (args.command === "sessions") {
+			const text = await responseText(fetcher, resourceUrl(base, "sessions", {
+				contract,
+				cursor: args.cursor,
+				limit: args.limit
+			}), headers, "sessions");
+			const response = sessionsResponse(parseJson(text, "sessions"));
+			emitResponse(args.format, response, response.sessions, humanSessions(response), stdout);
+			return 0;
+		}
+		const session = required(args.session, "--session");
+		if (args.command === "show") {
+			const detail = await readSessionDetail(fetcher, base, headers, contract, session);
+			emitResponse(args.format, detail, [
+				{
+					kind: "session",
+					protocolVersion: detail.protocolVersion,
+					contract: detail.contract,
+					sessionId: detail.sessionId,
+					revision: detail.revision
+				},
+				...detail.events.map((event) => ({
+					...event,
+					kind: "event"
+				})),
+				...detail.snapshots.map((snapshot) => ({
+					...snapshot,
+					kind: "snapshot"
+				}))
+			], humanSession(detail), stdout);
+			return 0;
+		}
+		const exportHeaders = requestHeaders(args, env, "application/x-ndjson");
+		const captureBytes = await responseBytes(fetcher, resourceUrl(base, "export", {
+			contract,
+			session
+		}), exportHeaders, "export");
+		const capture = await parseAndVerifyCapture(captureBytes);
+		if (args.command === "check") {
+			const summary = checkSummary(capture, args);
+			emitResponse(args.format, summary, [summary], humanCheck(summary, summary.ok ? "Checked" : "Check failed for"), stdout);
+			if (!summary.ok) {
+				for (const failure of summary.failures) stderr(`a2 devtools: ${terminalText(failure)}\n`);
+				return 2;
+			}
+			return 0;
+		}
+		assertCaptureIdentity(capture, contract, session);
+		const output = resolve(cwd, args.output ?? defaultCaptureName(contract, session));
+		try {
+			await writeFile(output, captureBytes, {
+				flag: args.force ? "w" : "wx",
+				mode: 384
+			});
+		} catch (error) {
+			if (errorCode(error) === "EEXIST") throw new CliFailure(`'${output}' already exists; pass --force to replace it`);
+			throw new CliFailure(`could not write '${output}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const result = {
+			path: output,
+			contract: capture.contract,
+			sessionId: capture.sessionId,
+			eventCount: capture.events.length,
+			snapshotCount: capture.snapshots.length,
+			sha256: capture.footer.sha256
+		};
+		emitResponse(args.format, result, [result], `Exported ${terminalText(capture.contract)}/${terminalText(capture.sessionId)}: ${capture.events.length} events, ${capture.snapshots.length} snapshots -> ${terminalText(output)}\n`, stdout);
+		return 0;
+	} catch (error) {
+		const failure = error instanceof CliFailure ? error : new CliFailure(error instanceof Error ? error.message : String(error));
+		stderr(`a2 devtools: ${terminalText(failure.message)}\n`);
+		return failure.exitCode;
+	}
+}
+//#endregion
+export { DEVTOOLS_CLI_EXIT_ERROR as n, runCli as r, DEVTOOLS_CLI_EXIT_CHECK_FAILED as t };

package/dist/cli-bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli-bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { r as runCli } from "./cli-B3VuxoDe.js";
+//#region src/cli-bin.ts
+process.exitCode = await runCli(process.argv.slice(2));
+//#endregion

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+//#region src/cli.d.ts
+declare const DEVTOOLS_CLI_EXIT_ERROR: 1;
+declare const DEVTOOLS_CLI_EXIT_CHECK_FAILED: 2;
+type DevtoolsCliOptions = {
+  fetch?: typeof globalThis.fetch;
+  env?: Readonly<Record<string, string | undefined>>;
+  cwd?: string;
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+  readFile?: (path: string) => Promise<Uint8Array>;
+  writeFile?: (path: string, data: Uint8Array, options: {
+    flag: "w" | "wx";
+    mode: number;
+  }) => Promise<void>;
+};
+/** Run the `a2 devtools` command namespace and return its process exit code. */
+declare function runCli(argv: readonly string[], options?: DevtoolsCliOptions): Promise<number>;
+//#endregion
+export { DEVTOOLS_CLI_EXIT_CHECK_FAILED, DEVTOOLS_CLI_EXIT_ERROR, DevtoolsCliOptions, runCli };

package/dist/cli.js

@@ -0,0 +1,2 @@
+import { n as DEVTOOLS_CLI_EXIT_ERROR, r as runCli, t as DEVTOOLS_CLI_EXIT_CHECK_FAILED } from "./cli-B3VuxoDe.js";
+export { DEVTOOLS_CLI_EXIT_CHECK_FAILED, DEVTOOLS_CLI_EXIT_ERROR, runCli };