@acid-cat/cli 0.8.0 → 0.10.0

package/dist/conform/cli.js

@@ -1,5 +1,5 @@
 import { isArrayOf, isObject, memberOf, parseJson } from "../json.js";
-import { Checks, expect, expectEqual, idsOf, sorted, until } from "./check.js";
+import { Checks, eventIdsOf, expect, expectEqual, expectOccurrence, idsOf, sorted, until } from "./check.js";
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdtemp, rm } from "node:fs/promises";
@@ -19,7 +19,15 @@ const USAGES = {
 	"fixture.refuse": "fixture refuse",
 	"fixture.release": "fixture release --key <string>",
 	"fixture.switch.set": "fixture switch set --on",
-	"fixture.toggle": "fixture toggle"
+	"fixture.toggle": "fixture toggle",
+	"fixture.signal": "fixture signal --key <string> --value <string>",
+	"fixture.watching": "fixture watching"
+};
+/** The `usage` of each event in the view of the fixture, after the name of the program. */
+const EVENT_USAGES = {
+	"fixture.broken": "watch fixture.broken [--cursor <string>] [--max-age-ms <integer>]",
+	"fixture.ticks": "watch fixture.ticks --count <integer> [--gap <integer>] [--key <string>] [--cursor <string>] [--max-age-ms <integer>]",
+	"fixture.watch": "watch fixture.watch --key <string> [--marker <string>] [--cursor <string>] [--max-age-ms <integer>]"
 };
 const isEntry = (value) => isObject(value) && typeof value.id === "string";
 /** The list that the `list` command writes to standard output. The check fails when it is not a list of entries. */
@@ -229,20 +237,135 @@ async function checkCli(command, options) {
 		expectEqual(result.code, 0, "exit code");
 		expectEqual(parseJson(result.stdout), { text: "hello" }, "standard output");
 	});
-	await checks.run("list gives the view", `${RULE}#commands`, async (signal) => {
-		const result = await run(signal, "list");
-		expectEqual(sorted(entriesOf(result.stdout).map((entry) => entry.id)), idsOf("cli"), "ids");
+	await checks.run("list gives the view: the capabilities, then the events", `${RULE}#commands`, async (signal) => {
+		const entries = entriesOf((await run(signal, "list")).stdout);
+		const ids = (kind) => entries.filter((entry) => entry.kind === kind).map((entry) => entry.id);
+		expectEqual(sorted(ids("capability")), idsOf("cli"), "the ids of the items with kind: capability");
+		expectEqual(sorted(ids("event")), eventIdsOf("cli"), "the ids of the items with kind: event");
+		expectEqual(entries.length, ids("capability").length + ids("event").length, "the number of items with a kind");
+		const firstEvent = entries.findIndex((entry) => entry.kind === "event");
+		expect(firstEvent === -1 || entries.slice(firstEvent).every((entry) => entry.kind === "event"), "the events must come after the capabilities");
 	});
-	await checks.run("list gives the usage of each capability, with its flags", `${RULE}#commands`, async (signal) => {
+	await checks.run("list gives the usage of each capability and each event, with its flags", `${RULE}#commands`, async (signal) => {
 		const entries = entriesOf((await run(signal, "list")).stdout);
-		for (const { id, usage } of entries) {
+		for (const { id, kind, usage } of entries) {
 			expect(typeof usage === "string", `${id} must have a usage`);
 			const [program, ...rest] = usage.split(" ");
 			expect(program !== "" && rest.length > 0, `the usage of ${id} must start with the name of the program, got ${JSON.stringify(usage)}`);
-			expectEqual(rest.join(" "), USAGES[id], `usage of ${id} after the name of the program`);
+			expectEqual(rest.join(" "), kind === "event" ? EVENT_USAGES[id] : USAGES[id], `usage of ${id} after the name of the program`);
 		}
 	});
+	await checkWatch(checks, command);
 	return checks;
 }
+const EVENTS = `${RULE}#events`;
+/** The checks of `watch` (spec/bindings/cli.md#events). */
+async function checkWatch(checks, command) {
+	const run = (signal, ...args) => start(command, args, signal).run;
+	/** The lines of standard output, each one an occurrence of the event. */
+	const occurrences = (stdout, id) => stdout.split("\n").filter((line) => line !== "").map((line) => expectOccurrence(parseJson(line), id));
+	await checks.run("watch writes each occurrence as one line of JSON, and exits with 0 when the subscription is complete", EVENTS, async (signal) => {
+		const result = await run(signal, "watch", "fixture.ticks", "--count", "2");
+		expectEqual(result.code, 0, "exit code");
+		expectEqual(occurrences(result.stdout, "fixture.ticks").map((occurrence) => occurrence.data), [{ n: 1 }, { n: 2 }], "the data of the occurrences");
+		expectEqual(result.stderr, "", "standard error");
+	});
+	await checks.run("watch with --cursor starts after the cursor", EVENTS, async (signal) => {
+		const result = await run(signal, "watch", "fixture.ticks", "--count", "3", "--cursor", "1", "--max-age-ms", "60000");
+		expectEqual(result.code, 0, "exit code");
+		expectEqual(occurrences(result.stdout, "fixture.ticks").map((occurrence) => [occurrence.data, occurrence.cursor]), [[{ n: 2 }, "2"], [{ n: 3 }, "3"]], "the data and the cursor of the occurrences");
+	});
+	await checks.run("watch writes an occurrence after a gap with truncated: true", EVENTS, async (signal) => {
+		const result = await run(signal, "watch", "fixture.ticks", "--count", "3", "--gap", "2");
+		expectEqual(result.code, 0, "exit code");
+		expectEqual(occurrences(result.stdout, "fixture.ticks").map((occurrence) => [occurrence.data, occurrence.truncated ?? null]), [
+			[{ n: 1 }, null],
+			[{ n: 2 }, true],
+			[{ n: 3 }, null]
+		], "the data and truncated of the occurrences");
+	});
+	await checks.run("watch writes internal to standard error with exit code 5 after a defect", EVENTS, async (signal) => {
+		const result = await run(signal, "watch", "fixture.broken");
+		expectEqual(result.code, 5, "exit code");
+		expectEqual(occurrences(result.stdout, "fixture.broken").map((occurrence) => occurrence.data), [{ n: 1 }], "the data of the occurrences");
+		expect(/"kind":"internal"/.test(result.stderr), `standard error must contain the call failure internal, got ${JSON.stringify(result.stderr)}`);
+	});
+	for (const [name, args, code] of [
+		[
+			"watch with invalid input has exit code 3",
+			[
+				"watch",
+				"fixture.ticks",
+				"--count",
+				"101"
+			],
+			3
+		],
+		[
+			"watch with a missing required flag has exit code 3",
+			["watch", "fixture.ticks"],
+			3
+		],
+		[
+			"watch of an event outside the view has exit code 2",
+			["watch", "fixture.secret"],
+			2
+		],
+		[
+			"watch with a --max-age-ms that is not an integer has exit code 3",
+			[
+				"watch",
+				"fixture.ticks",
+				"--count",
+				"1",
+				"--max-age-ms",
+				"soon"
+			],
+			3
+		],
+		[
+			"watch with a --max-age-ms that is a fraction has exit code 3",
+			[
+				"watch",
+				"fixture.ticks",
+				"--count",
+				"1",
+				"--max-age-ms",
+				"1.5"
+			],
+			3
+		]
+	]) await checks.run(name, EVENTS, async (signal) => {
+		expectEqual((await run(signal, ...args)).code, code, "exit code");
+	});
+	await checks.run("an interrupt cancels watch with exit code 130", EVENTS, async (signal) => {
+		const directory = await mkdtemp(join(tmpdir(), "acid-cat-conform-"));
+		const marker = join(directory, "watching");
+		try {
+			const { child, run: watched } = start(command, [
+				"watch",
+				"fixture.watch",
+				"--key",
+				"interrupt",
+				"--marker",
+				marker
+			], signal);
+			const ended = () => child.exitCode !== null || child.signalCode !== null;
+			await until("the subscription writes its marker file", async () => existsSync(marker) || ended(), (ready) => ready, signal);
+			if (!ended()) child.kill("SIGINT");
+			const result = await watched;
+			expect(existsSync(marker), `the subscription must start before the interrupt, but the command line ended with ${result.code}: ${result.stderr}`);
+			expect(result.signal === null, `the process must exit, not end by the signal ${result.signal}`);
+			expectEqual(result.code, 130, "exit code");
+			expectEqual(result.stdout, "", "standard output");
+			expectEqual(result.stderr, "", "standard error");
+		} finally {
+			await rm(directory, {
+				recursive: true,
+				force: true
+			});
+		}
+	});
+}
 //#endregion
 export { checkCli };

package/dist/conform/http.js

@@ -1,5 +1,7 @@
-import { isArrayOf, isObject, memberOf, readJson } from "../json.js";
-import { Checks, FORBIDDEN_ORIGIN, expect, expectEqual, idsOf, sorted } from "./check.js";
+import { isArrayOf, isObject, isStringArray, memberOf, parseJson, readJson } from "../json.js";
+import { Checks, FORBIDDEN_ORIGIN, eventIdsOf, expect, expectEqual, expectOccurrence, idsOf, sorted, until } from "./check.js";
+import { sseReader } from "./sse.js";
+import { randomUUID } from "node:crypto";
 //#region src/conform/http.ts
 /** Conformance checks for the HTTP binding (spec/bindings/http.md). */
 const RULE = "spec/bindings/http.md";
@@ -103,7 +105,210 @@ async function checkHttp(base, options) {
 			125
 		])), 400);
 	});
+	await checkEvents(checks, base);
 	return checks;
 }
+const EVENTS = `${RULE}#events`;
+/** The checks of the events (spec/bindings/http.md#events). */
+async function checkEvents(checks, base) {
+	const subscribe = (signal, id, input, headers = {}) => fetch(`${base}/events/${id}`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			...headers
+		},
+		body: JSON.stringify(input),
+		signal
+	});
+	/** Subscribe, and check that the stream starts. `signal` and `close` both close the stream. */
+	const open = async (signal, id, input, headers = {}) => {
+		const controller = new AbortController();
+		const response = await subscribe(AbortSignal.any([signal, controller.signal]), id, input, headers);
+		if (response.status !== 200) {
+			controller.abort();
+			throw new Error(`POST /events/${id} must start a stream with the status 200, got ${response.status}`);
+		}
+		expect(response.headers.get("Content-Type")?.startsWith("text/event-stream") === true, `the media type must be text/event-stream, got ${response.headers.get("Content-Type")}`);
+		expectEqual(response.headers.get("Cache-Control"), "no-store", "Cache-Control");
+		return {
+			response,
+			reader: sseReader(response),
+			close: () => controller.abort()
+		};
+	};
+	/** The next message of a stream, which must be an occurrence of the event with the cursor as its SSE id. */
+	const nextOccurrence = async (stream, id) => {
+		const message = await stream.reader.next();
+		expect(message?.event === "next", `expected event: next, got ${JSON.stringify(message)}`);
+		const occurrence = expectOccurrence(parseJson(message.data), id);
+		expectEqual(message.id, occurrence.cursor, "the SSE id of the message, which is the cursor of the occurrence");
+		return occurrence;
+	};
+	const expectComplete = async (stream) => {
+		const message = await stream.reader.next();
+		expect(message?.event === "complete", `expected event: complete, got ${JSON.stringify(message)}`);
+		expectEqual(message.data, "", "the data of event: complete");
+		expectEqual(await stream.reader.next(), void 0, "the stream after event: complete");
+	};
+	const watching = async (signal) => {
+		const response = await fetch(`${base}/capabilities/fixture.watching`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: "{}",
+			signal
+		});
+		const keys = memberOf(memberOf(await readJson(response), "value"), "keys");
+		expect(isStringArray(keys), `fixture.watching must give a list of keys, got ${JSON.stringify(keys)}`);
+		return keys;
+	};
+	const count = (keys, key) => keys.filter((each) => each === key).length;
+	const signalKey = async (signal, key, value) => {
+		const response = await fetch(`${base}/capabilities/fixture.signal`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				key,
+				value
+			}),
+			signal
+		});
+		const delivered = memberOf(memberOf(await readJson(response), "value"), "delivered");
+		expect(typeof delivered === "number", `fixture.signal must give the number of subscriptions, got ${JSON.stringify(delivered)}`);
+		return delivered;
+	};
+	await checks.run("GET /events lists the events of the view", `${RULE}#requests`, async (signal) => {
+		const list = await readJson(await fetch(`${base}/events`, { signal }));
+		if (!isArrayOf(list, isEntry)) throw new Error(`GET /events must give a list of objects with an id, got ${JSON.stringify(list)}`);
+		expectEqual(sorted(list.map((entry) => entry.id)), eventIdsOf("api"), "ids");
+	});
+	for (const [name, id, input, status, kind] of [
+		[
+			"a subscription to an event outside the view has the status 404",
+			"fixture.secret",
+			{},
+			404,
+			"unknown-capability"
+		],
+		[
+			"a subscription to the id of a capability has the status 404",
+			"fixture.echo",
+			{ text: "x" },
+			404,
+			"unknown-capability"
+		],
+		[
+			"a subscription with invalid input has the status 422",
+			"fixture.ticks",
+			{ count: 101 },
+			422,
+			"invalid-input"
+		]
+	]) await checks.run(name, EVENTS, async (signal) => {
+		const response = await subscribe(signal, id, input);
+		expectEqual(response.status, status, "status");
+		const body = await readJson(response);
+		expectEqual(memberOf(body, "kind"), kind, "kind");
+		expect(typeof memberOf(body, "message") === "string", `the call failure must have a message, got ${JSON.stringify(body)}`);
+	});
+	await checks.run("a subscription gives each occurrence as event: next, in order, then event: complete", EVENTS, async (signal) => {
+		const stream = await open(signal, "fixture.ticks", { count: 3 });
+		try {
+			for (const n of [
+				1,
+				2,
+				3
+			]) {
+				const occurrence = await nextOccurrence(stream, "fixture.ticks");
+				expectEqual(occurrence.data, { n }, "data");
+				expectEqual([occurrence.eventId, occurrence.cursor], [String(n), String(n)], "the eventId and the cursor");
+			}
+			await expectComplete(stream);
+		} finally {
+			stream.close();
+		}
+	});
+	await checks.run("an occurrence after a gap has truncated: true, and the other occurrences have no truncated", EVENTS, async (signal) => {
+		const stream = await open(signal, "fixture.ticks", {
+			count: 3,
+			gap: 2
+		});
+		try {
+			for (const n of [
+				1,
+				2,
+				3
+			]) {
+				const occurrence = await nextOccurrence(stream, "fixture.ticks");
+				expectEqual([occurrence.data, occurrence.truncated], [{ n }, n === 2 ? true : void 0], "the data and truncated");
+			}
+			await expectComplete(stream);
+		} finally {
+			stream.close();
+		}
+	});
+	await checks.run("Last-Event-ID gives the cursor, and the subscription starts after it", EVENTS, async (signal) => {
+		const stream = await open(signal, "fixture.ticks", { count: 3 }, { "Last-Event-ID": "1" });
+		try {
+			for (const n of [2, 3]) expectEqual((await nextOccurrence(stream, "fixture.ticks")).data, { n }, "data");
+			await expectComplete(stream);
+		} finally {
+			stream.close();
+		}
+	});
+	await checks.run("a defect after an occurrence ends the stream with event: error and internal", EVENTS, async (signal) => {
+		const stream = await open(signal, "fixture.broken", {});
+		try {
+			expectEqual((await nextOccurrence(stream, "fixture.broken")).data, { n: 1 }, "data");
+			const message = await stream.reader.next();
+			expect(message?.event === "error", `expected event: error, got ${JSON.stringify(message)}`);
+			const failure = parseJson(message.data);
+			expect(memberOf(failure, "kind") === "internal" && typeof memberOf(failure, "message") === "string", `expected { kind: "internal", message }, got ${message.data}`);
+			expect(!/\n\s+at /.test(String(memberOf(failure, "message"))), "the message must not contain a stack trace");
+			expectEqual(await stream.reader.next(), void 0, "the stream after event: error");
+		} finally {
+			stream.close();
+		}
+	});
+	await checks.run("a subscription gets the things that happen, and closing the stream cancels it", EVENTS, async (signal) => {
+		const key = randomUUID();
+		const pending = open(signal, "fixture.watch", { key });
+		pending.catch(() => void 0);
+		let stream;
+		try {
+			await until("fixture.watching gives the key", () => watching(signal), (keys) => keys.includes(key), signal);
+			stream = await pending;
+			expectEqual(await signalKey(signal, key, "first"), 1, "the subscriptions that fixture.signal reached");
+			expectEqual((await nextOccurrence(stream, "fixture.watch")).data, {
+				key,
+				value: "first"
+			}, "data");
+			stream.close();
+			await until("the key leaves fixture.watching", () => watching(signal), (keys) => !keys.includes(key), signal);
+		} finally {
+			stream?.close();
+			pending.then((opened) => opened.close(), () => void 0);
+		}
+	});
+	await checks.run("cancelling one subscription leaves the other subscriptions running", EVENTS, async (signal) => {
+		const key = randomUUID();
+		const first = open(signal, "fixture.watch", { key });
+		const second = open(signal, "fixture.watch", { key });
+		first.catch(() => void 0);
+		second.catch(() => void 0);
+		try {
+			await until("fixture.watching gives the key of both subscriptions", () => watching(signal), (keys) => count(keys, key) === 2, signal);
+			const [cancelled, kept] = [await first, await second];
+			cancelled.close();
+			await until("the cancelled subscription leaves fixture.watching", () => watching(signal), (keys) => count(keys, key) === 1, signal);
+			expectEqual(await signalKey(signal, key, "after"), 1, "the subscriptions that fixture.signal reached");
+			expectEqual((await nextOccurrence(kept, "fixture.watch")).data, {
+				key,
+				value: "after"
+			}, "data");
+		} finally {
+			for (const stream of [first, second]) stream.then((opened) => opened.close(), () => void 0);
+		}
+	});
+}
 //#endregion
 export { checkHttp };

package/dist/conform/index.d.ts

@@ -1,14 +1,28 @@
 import type { Check } from "./check.js";
 import type { WebMcpInstall } from "./webmcp.js";
+import type { PollSettings } from "./poll.js";
+import type { WebhookSettings } from "./webhook.js";
 export type { Check } from "./check.js";
 export { DEADLINE, fixture } from "./check.js";
 export { serve } from "./serve.js";
 export type { Routes, Served, WebHandler } from "./serve.js";
 export { createTestHost } from "./webmcp.js";
 export type { TestHost, WebMcpInstall } from "./webmcp.js";
+export type { PollSettings } from "./poll.js";
+export type { WebhookSettings } from "./webhook.js";
 export interface ConformOptions {
     /** The URL of the MCP server, for example `http://localhost:8787/mcp`. */
     readonly mcp?: string | undefined;
+    /**
+     * Check the `initialize` handshake of revision 2025-11-25 through the MCP server too
+     * (spec/bindings/mcp.md#earlier-revisions-through-http). The default is `false`.
+     */
+    readonly mcpHandshake?: boolean | undefined;
+    /**
+     * The command that starts the MCP server through standard input and standard output, for example
+     * `["node", "fixture-mcp-stdio.ts"]`. Each check starts its own process.
+     */
+    readonly mcpStdio?: readonly string[] | undefined;
     /** The base URL of the HTTP API, before `/capabilities`. */
     readonly http?: string | undefined;
     /** The command that starts the command line, for example `["node", "fixture-cli.ts"]`. */
@@ -18,6 +32,17 @@ export interface ConformOptions {
      * on a host in the same process. A page runs in Chromium, through Playwright.
      */
     readonly webmcp?: string | WebMcpInstall | undefined;
+    /**
+     * The poll settings of the deployment, for MCP through HTTP and through stdio. With `bufferLimit`, conform tests a
+     * cursor older than the buffer. With `leaseMs`, it tests that a lease with no poll ends.
+     */
+    readonly poll?: PollSettings | undefined;
+    /**
+     * Test webhook delivery through `mcp`. conform runs an HTTPS receiver on 127.0.0.1 with this certificate and key. The
+     * deployment trusts the certificate, allows deliveries to 127.0.0.1, and gives the principal to each request with the
+     * header `Authorization: Bearer <principal>`.
+     */
+    readonly webhook?: WebhookSettings | undefined;
     /** The body limit of the remote bindings, in bytes. The default is 1 MiB. */
     readonly maximumBytes?: number | undefined;
     /**

package/dist/conform/index.js

@@ -3,6 +3,7 @@ import { checkCli } from "./cli.js";
 import { checkHttp } from "./http.js";
 import { checkMcp } from "./mcp.js";
 import { checkProperties, httpInvoke, mcpInvoke } from "./properties.js";
+import { checkMcpStdio } from "./mcp-stdio.js";
 import { browserDriver, checkWebMcp, processDriver } from "./webmcp.js";
 import { serve } from "./serve.js";
 //#region src/conform/index.ts
@@ -14,11 +15,15 @@ import { serve } from "./serve.js";
 async function conform(options) {
 	const maximumBytes = options.maximumBytes ?? 1048576;
 	const deadline = options.deadline ?? 3e4;
+	const poll = options.poll ?? {};
 	const results = [];
 	if (options.mcp !== void 0) {
 		results.push(...(await checkMcp(options.mcp, {
 			maximumBytes,
-			deadline
+			deadline,
+			handshake: options.mcpHandshake === true,
+			poll,
+			webhook: options.webhook
 		})).results);
 		const mcp = await mcpInvoke(options.mcp, AbortSignal.timeout(deadline)).catch(() => void 0);
 		if (mcp !== void 0) {
@@ -26,6 +31,10 @@ async function conform(options) {
 			await mcp.close();
 		}
 	}
+	if (options.mcpStdio !== void 0) for (const checks of await checkMcpStdio(options.mcpStdio, {
+		deadline,
+		poll
+	})) results.push(...checks.results);
 	if (options.http !== void 0) {
 		results.push(...(await checkHttp(options.http, {
 			maximumBytes,

package/dist/conform/mcp-stdio.d.ts

@@ -0,0 +1,6 @@
+import { Checks } from "./check.js";
+import type { PollSettings } from "./poll.js";
+export declare function checkMcpStdio(command: readonly string[], options: {
+    readonly deadline: number;
+    readonly poll: PollSettings;
+}): Promise<readonly Checks[]>;