@acid-cat/cli 0.1.0 → 0.3.0

package/dist/conform/properties.js

@@ -0,0 +1,98 @@
+import { Checks, expect } from "./check.js";
+import { mcpClient } from "./mcp.js";
+import fc from "fast-check";
+//#region src/conform/properties.ts
+const RULE = "spec/invocation.md#cancellation-and-concurrency";
+function httpInvoke(base) {
+	return async (id, input, signal) => {
+		return await (await fetch(`${base}/capabilities/${id}`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(input),
+			...signal ? { signal } : {}
+		})).json();
+	};
+}
+async function mcpInvoke(url) {
+	const client = await mcpClient(url);
+	return {
+		invoke: async (id, input, signal) => {
+			try {
+				const result = await client.callTool({
+					name: id,
+					arguments: input
+				}, signal ? { signal } : void 0);
+				const body = JSON.parse(result.content[0]?.text ?? "null");
+				if (result.isError !== true) return {
+					ok: true,
+					value: result.structuredContent ?? body
+				};
+				return body;
+			} catch (error) {
+				if (error.code === -32602) return {
+					kind: "unknown-capability",
+					message: String(error)
+				};
+				throw error;
+			}
+		},
+		close: () => client.close()
+	};
+}
+const operation = fc.oneof(fc.string({ maxLength: 40 }).map((text) => ({
+	kind: "echo",
+	text
+})), fc.constant({ kind: "refuse" }), fc.constant({ kind: "crash" }), fc.constant({ kind: "invalid" }));
+/** The outcome that an operation must have. */
+function agrees(operation, outcome) {
+	switch (operation.kind) {
+		case "echo": return "ok" in outcome && outcome.ok && JSON.stringify(outcome.value) === JSON.stringify({ text: operation.text });
+		case "refuse": return "ok" in outcome && !outcome.ok && outcome.error._tag === "Refused";
+		case "crash": return "kind" in outcome && outcome.kind === "internal";
+		case "invalid": return "kind" in outcome && outcome.kind === "invalid-input";
+	}
+}
+const callFor = (invoke, operation) => {
+	switch (operation.kind) {
+		case "echo": return invoke("fixture.echo", { text: operation.text });
+		case "refuse": return invoke("fixture.refuse", {});
+		case "crash": return invoke("fixture.crash", {});
+		case "invalid": return invoke("fixture.echo", { text: 0 });
+	}
+};
+async function checkProperties(binding, invoke) {
+	const checks = new Checks(`${binding} properties`);
+	await checks.run("concurrent calls each get exactly their own outcome", RULE, async () => {
+		await fc.assert(fc.asyncProperty(fc.array(operation, {
+			minLength: 1,
+			maxLength: 12
+		}), async (operations) => {
+			const outcomes = await Promise.all(operations.map((op) => callFor(invoke, op)));
+			operations.forEach((op, index) => expect(agrees(op, outcomes[index]), `${op.kind} gave ${JSON.stringify(outcomes[index])}`));
+		}), { numRuns: 25 });
+	});
+	await checks.run("cancelling a call affects only that call", RULE, async () => {
+		await fc.assert(fc.asyncProperty(fc.array(fc.boolean(), {
+			minLength: 2,
+			maxLength: 5
+		}), async (cancel) => {
+			const calls = cancel.map((cancelled) => {
+				const controller = new AbortController();
+				const outcome = invoke("fixture.slow", { milliseconds: 200 }, controller.signal).catch(() => "aborted");
+				if (cancelled) setTimeout(() => controller.abort(), 20);
+				return {
+					cancelled,
+					outcome
+				};
+			});
+			for (const call of calls) {
+				const outcome = await call.outcome;
+				if (!call.cancelled) expect(outcome !== "aborted" && "ok" in outcome && outcome.ok, `a call that was not cancelled gave ${JSON.stringify(outcome)}`);
+				else expect(outcome === "aborted" || "kind" in outcome && outcome.kind === "cancelled", `a cancelled call gave ${JSON.stringify(outcome)}`);
+			}
+		}), { numRuns: 5 });
+	});
+	return checks;
+}
+//#endregion
+export { checkProperties, httpInvoke, mcpInvoke };

package/dist/conform/serve.js

@@ -0,0 +1,62 @@
+import { createServer } from "node:http";
+//#region src/conform/serve.ts
+/**
+* Serve a web request handler, `(request: Request) => Promise<Response>`, on a local port. Implementations use it
+* to run `acid-cat conform` against their bindings in a test.
+*/
+/** Serve handlers by path prefix, for example `{ "/mcp": mcp, "/api": http }`. */
+function serve(routes) {
+	const prefixes = Object.keys(routes).sort((a, b) => b.length - a.length);
+	const server = createServer((incoming, outgoing) => {
+		answer(incoming, outgoing, prefixes, routes);
+	});
+	return new Promise((resolve) => {
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			resolve({
+				url: `http://127.0.0.1:${typeof address === "object" && address !== null ? address.port : 0}`,
+				close: () => new Promise((done) => server.close(() => done()))
+			});
+		});
+	});
+}
+async function answer(incoming, outgoing, prefixes, routes) {
+	const url = new URL(incoming.url ?? "/", `http://${incoming.headers.host ?? "127.0.0.1"}`);
+	const prefix = prefixes.find((candidate) => url.pathname === candidate || url.pathname.startsWith(`${candidate}/`));
+	if (prefix === void 0) {
+		outgoing.writeHead(404).end();
+		return;
+	}
+	const abort = new AbortController();
+	outgoing.on("close", () => {
+		if (!outgoing.writableFinished) abort.abort();
+	});
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(incoming.headers)) if (Array.isArray(value)) value.forEach((item) => headers.append(name, item));
+	else if (value !== void 0) headers.set(name, value);
+	const hasBody = incoming.method !== "GET" && incoming.method !== "HEAD";
+	const request = new Request(url, {
+		method: incoming.method ?? "GET",
+		headers,
+		signal: abort.signal,
+		...hasBody ? {
+			body: incoming,
+			duplex: "half"
+		} : {}
+	});
+	try {
+		const response = await routes[prefix](request);
+		outgoing.writeHead(response.status, Object.fromEntries(response.headers));
+		if (response.body === null) {
+			outgoing.end();
+			return;
+		}
+		for await (const chunk of response.body) outgoing.write(chunk);
+		outgoing.end();
+	} catch {
+		if (!outgoing.headersSent) outgoing.writeHead(500);
+		outgoing.end();
+	}
+}
+//#endregion
+export { serve };

package/dist/conform/webmcp.js

@@ -0,0 +1,179 @@
+import { Checks, expect, expectEqual, fixture, idsOf, sorted } from "./check.js";
+import { REFERENCE, visitObjects } from "@acid-cat/spec-ts";
+//#region src/conform/webmcp.ts
+/**
+* Conformance checks for the WebMCP binding (spec/bindings/webmcp.md).
+*
+* The checks act as the WebMCP host: they give the page a `modelContext`, record the tools that the binding registers,
+* and call them. The page can run in a browser, or the implementation can install itself on the host in the same
+* process.
+*/
+const RULE = "spec/bindings/webmcp.md";
+/** The target of the fixture that has the WebMCP binding. */
+const TARGET = "app";
+/**
+* Make a test host. The function uses no imports and no outer variables, because the browser driver sends its
+* source text to the page.
+*/
+function createTestHost() {
+	const registered = /* @__PURE__ */ new Map();
+	return {
+		modelContext: { registerTool(tool, options) {
+			const recorded = tool;
+			registered.set(recorded.name, recorded);
+			options.signal.addEventListener("abort", () => {
+				if (registered.get(recorded.name) === recorded) registered.delete(recorded.name);
+			});
+		} },
+		tools: () => [...registered.values()].map((tool) => ({
+			name: tool.name,
+			description: tool.description,
+			inputSchema: tool.inputSchema
+		})),
+		async call(name, input, cancelAfter) {
+			const tool = registered.get(name);
+			if (tool === void 0) return { missing: true };
+			const controller = new AbortController();
+			if (cancelAfter !== void 0) setTimeout(() => controller.abort(), cancelAfter);
+			try {
+				return { resolved: await tool.execute(input, { signal: controller.signal }) };
+			} catch (error) {
+				const { name: errorName, kind, message } = error;
+				return { rejected: {
+					name: String(errorName),
+					kind,
+					message: String(message)
+				} };
+			}
+		}
+	};
+}
+/** A driver for an implementation in the same process. Values pass through JSON, as they do from a page. */
+async function processDriver(install) {
+	const host = createTestHost();
+	const remove = await install(host.modelContext);
+	const copy = (value) => JSON.parse(JSON.stringify(value));
+	return {
+		tools: async () => copy(host.tools()),
+		call: async (name, input, cancelAfter) => copy(await host.call(name, input, cancelAfter)),
+		close: async () => {
+			if (typeof remove === "function") await remove();
+		}
+	};
+}
+/** A driver for a page in Chromium, through Playwright. The page loads with the test host as its `modelContext`. */
+async function browserDriver(url) {
+	let playwright;
+	try {
+		playwright = await import("playwright");
+	} catch {
+		throw new Error("acid-cat conform --webmcp needs Playwright and Chromium: `pnpm add -D playwright`, then `pnpm exec playwright install chromium`.");
+	}
+	const browser = await playwright.chromium.launch();
+	const page = await browser.newPage();
+	const errors = [];
+	page.on("pageerror", (error) => errors.push(error.message));
+	await page.addInitScript(`
+    window.__acidCatConform = (${createTestHost.toString()})();
+    for (const scope of [document, navigator]) {
+      Object.defineProperty(scope, "modelContext", { value: window.__acidCatConform.modelContext, configurable: true });
+    }
+  `);
+	await page.goto(url);
+	return {
+		tools: async () => {
+			if (errors.length > 0) throw new Error(`The page has errors: ${errors.join("; ")}`);
+			return page.evaluate(() => window.__acidCatConform.tools());
+		},
+		call: (name, input, cancelAfter) => page.evaluate(([name, input, cancelAfter]) => window.__acidCatConform.call(name, input, cancelAfter), [
+			name,
+			input,
+			cancelAfter
+		]),
+		close: () => browser.close()
+	};
+}
+/** Wait until `condition` is true. Give up after `timeout` milliseconds. */
+async function eventually(condition, what, timeout = 5e3) {
+	const end = Date.now() + timeout;
+	for (;;) {
+		if (await condition()) return;
+		if (Date.now() > end) throw new Error(`after ${timeout} ms: ${what}`);
+		await new Promise((resolve) => setTimeout(resolve, 20));
+	}
+}
+/** True if each `$ref` of a schema refers to a type in its own `$defs` (spec/catalog.md#bundling). */
+function isBundled(schema) {
+	const types = schema.$defs ?? {};
+	let bundled = true;
+	visitObjects(schema, (node) => {
+		if (typeof node.$ref !== "string") return;
+		const name = REFERENCE.exec(node.$ref)?.[1];
+		if (name === void 0 || !(name in types)) bundled = false;
+	});
+	return bundled;
+}
+const names = async (driver) => sorted((await driver.tools()).map((tool) => tool.name));
+async function checkWebMcp(driver) {
+	const checks = new Checks("webmcp");
+	const view = fixture.capabilities;
+	const expected = idsOf(TARGET);
+	await checks.run("each available capability of the view is a tool", `${RULE}#tools`, async () => {
+		await eventually(async () => JSON.stringify(await names(driver)) === JSON.stringify(expected), `the tools must be ${expected.join(", ")}`);
+	});
+	await checks.run("a tool has the description and the bundled input schema of its capability", `${RULE}#tools`, async () => {
+		for (const tool of await driver.tools()) {
+			expectEqual(tool.description, view[tool.name]?.description, `description of ${tool.name}`);
+			const schema = tool.inputSchema;
+			const input = view[tool.name]?.input ?? {};
+			expectEqual(schema.type, "object", `type of the input schema of ${tool.name}`);
+			expectEqual(sorted(Object.keys(schema.properties ?? {})), sorted(Object.keys(input.properties ?? {})), `properties of ${tool.name}`);
+			expectEqual(sorted(schema.required ?? []), sorted(input.required ?? []), `required properties of ${tool.name}`);
+			expect(isBundled(schema), `the input schema of ${tool.name} must be bundled`);
+		}
+	});
+	await checks.run("a value resolves as a result", `${RULE}#tools`, async () => {
+		expectEqual(await driver.call("fixture.echo", { text: "hello" }), { resolved: {
+			ok: true,
+			value: { text: "hello" }
+		} }, "outcome");
+	});
+	await checks.run("a failure resolves as a result", `${RULE}#tools`, async () => {
+		const call = await driver.call("fixture.refuse", {});
+		expect("resolved" in call, `the call must resolve, got ${JSON.stringify(call)}`);
+		expectEqual(call.resolved.error?._tag, "Refused", "_tag");
+	});
+	for (const [name, capability, input, kind, errorName] of [[
+		"a defect rejects with the kind internal",
+		"fixture.crash",
+		{},
+		"internal",
+		void 0
+	], [
+		"invalid input rejects with the kind invalid-input, as a TypeError",
+		"fixture.echo",
+		{ text: 1 },
+		"invalid-input",
+		"TypeError"
+	]]) await checks.run(name, `${RULE}#tools`, async () => {
+		const call = await driver.call(capability, input);
+		expect("rejected" in call, `the call must reject, got ${JSON.stringify(call)}`);
+		expectEqual(call.rejected.kind, kind, "kind");
+		if (errorName !== void 0) expectEqual(call.rejected.name, errorName, "name");
+	});
+	await checks.run("the signal of the host cancels a call, as an AbortError", `${RULE}#tools`, async () => {
+		const call = await driver.call("fixture.slow", { milliseconds: 6e4 }, 50);
+		expect("rejected" in call, `the call must reject, got ${JSON.stringify(call)}`);
+		expectEqual(call.rejected.kind, "cancelled", "kind");
+		expectEqual(call.rejected.name, "AbortError", "name");
+	});
+	await checks.run("a tool is removed while its capability is unavailable, and registered again after", `${RULE}#tools`, async () => {
+		await driver.call("fixture.switch.set", { on: false });
+		await eventually(async () => !(await names(driver)).includes("fixture.toggle"), "fixture.toggle must be removed");
+		await driver.call("fixture.switch.set", { on: true });
+		await eventually(async () => (await names(driver)).includes("fixture.toggle"), "fixture.toggle must be registered again");
+	});
+	return checks;
+}
+//#endregion
+export { browserDriver, checkWebMcp, createTestHost, processDriver };

package/dist/index.js

@@ -1,16 +1,5 @@
-import {
-  bundle,
-  check,
-  conform,
-  fixture,
-  serve,
-  viewOf
-} from "./chunks/chunk-VZ6KDZEL.js";
-export {
-  bundle,
-  check,
-  conform,
-  fixture,
-  serve,
-  viewOf
-};
+import { bundle, check, viewOf } from "./catalog.js";
+import { fixture } from "./conform/check.js";
+import { serve } from "./conform/serve.js";
+import { conform } from "./conform/index.js";
+export { bundle, check, conform, fixture, serve, viewOf };

package/dist/json/catalog.schema.json.js

@@ -0,0 +1,117 @@
+//#region ../../schemas/catalog.schema.json
+var catalog_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://acid-cat.dev/schemas/0.1/catalog.schema.json",
+	title: "AcidCat catalog",
+	description: "One document that states what an application can do and which targets see it. See spec/catalog.md.",
+	type: "object",
+	required: [
+		"acidcat",
+		"targets",
+		"capabilities"
+	],
+	properties: {
+		"acidcat": {
+			"description": "The version of the AcidCat specification this catalog follows.",
+			"const": "0.1"
+		},
+		"title": { "type": "string" },
+		"description": { "type": "string" },
+		"targets": {
+			"description": "The targets, keyed by name.",
+			"type": "object",
+			"propertyNames": { "$ref": "#/$defs/targetName" },
+			"additionalProperties": { "$ref": "#/$defs/target" }
+		},
+		"$defs": {
+			"description": "Shared types, keyed by name. Capability schemas reference them as #/$defs/<Name>.",
+			"type": "object",
+			"propertyNames": { "$ref": "#/$defs/typeName" },
+			"additionalProperties": { "$ref": "#/$defs/schema" }
+		},
+		"capabilities": {
+			"description": "The capabilities, keyed by id.",
+			"type": "object",
+			"propertyNames": { "$ref": "#/$defs/id" },
+			"additionalProperties": { "$ref": "#/$defs/capability" }
+		}
+	},
+	$defs: {
+		"id": {
+			"type": "string",
+			"maxLength": 128,
+			"pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*(\\.[a-z][a-z0-9]*(-[a-z0-9]+)*)+$"
+		},
+		"targetName": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$"
+		},
+		"bindingName": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$"
+		},
+		"typeName": {
+			"type": "string",
+			"pattern": "^[A-Za-z][A-Za-z0-9_]*$"
+		},
+		"target": {
+			"type": "object",
+			"required": ["bindings"],
+			"properties": {
+				"bindings": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/bindingName" },
+					"minItems": 1,
+					"uniqueItems": true
+				},
+				"description": { "type": "string" },
+				"options": { "type": "object" }
+			}
+		},
+		"schema": {
+			"description": "A JSON Schema 2020-12 schema. Its $refs point into the catalog's $defs.",
+			"type": ["object", "boolean"]
+		},
+		"objectSchema": {
+			"description": "An input schema: it states that the input is an object, or it references a type.",
+			"type": "object",
+			"anyOf": [{
+				"required": ["type"],
+				"properties": { "type": { "const": "object" } }
+			}, {
+				"required": ["$ref"],
+				"properties": { "$ref": { "type": "string" } }
+			}]
+		},
+		"capability": {
+			"type": "object",
+			"required": ["description"],
+			"properties": {
+				"description": {
+					"type": "string",
+					"minLength": 1,
+					"pattern": "\\S"
+				},
+				"audience": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/targetName" },
+					"uniqueItems": true
+				},
+				"input": { "$ref": "#/$defs/objectSchema" },
+				"output": { "$ref": "#/$defs/schema" },
+				"failures": {
+					"type": "object",
+					"propertyNames": {
+						"type": "string",
+						"minLength": 1
+					},
+					"additionalProperties": { "$ref": "#/$defs/schema" }
+				},
+				"readOnly": { "type": "boolean" },
+				"state": { "$ref": "#/$defs/schema" }
+			}
+		}
+	}
+};
+//#endregion
+export { catalog_schema_default as default };

package/dist/json/fixture.acidcat.json.js

@@ -0,0 +1,140 @@
+//#region conformance/fixture.acidcat.json
+var fixture_acidcat_default = {
+	acidcat: "0.1",
+	title: "AcidCat conformance fixture",
+	description: "One capability for each behavior that acid-cat conform tests.",
+	targets: {
+		"api": { "bindings": ["http"] },
+		"app": { "bindings": ["typescript", "webmcp"] },
+		"cli": { "bindings": ["cli"] },
+		"mcp": { "bindings": ["mcp"] }
+	},
+	capabilities: {
+		"fixture.crash": {
+			"description": "Always fail with a defect.",
+			"audience": [
+				"app",
+				"mcp",
+				"cli",
+				"api"
+			]
+		},
+		"fixture.echo": {
+			"description": "Return the input text.",
+			"audience": [
+				"app",
+				"mcp",
+				"cli",
+				"api"
+			],
+			"input": {
+				"properties": { "text": { "type": "string" } },
+				"required": ["text"],
+				"type": "object"
+			},
+			"output": {
+				"properties": { "text": { "type": "string" } },
+				"required": ["text"],
+				"type": "object"
+			},
+			"readOnly": true
+		},
+		"fixture.flags": {
+			"description": "Return the input. The input has one property for each kind of command-line flag.",
+			"audience": ["cli"],
+			"input": {
+				"properties": {
+					"count": { "type": "integer" },
+					"extra": { "type": "object" },
+					"label": { "type": "string" },
+					"mode": {
+						"enum": ["fast", "slow"],
+						"type": "string"
+					},
+					"ratio": { "type": "number" },
+					"verbose": { "type": "boolean" }
+				},
+				"required": ["mode"],
+				"type": "object"
+			},
+			"output": {
+				"properties": {
+					"count": { "type": "integer" },
+					"extra": { "type": "object" },
+					"label": { "type": "string" },
+					"mode": {
+						"enum": ["fast", "slow"],
+						"type": "string"
+					},
+					"ratio": { "type": "number" },
+					"verbose": { "type": "boolean" }
+				},
+				"required": ["mode"],
+				"type": "object"
+			}
+		},
+		"fixture.hidden": {
+			"description": "Only the app target can use this capability.",
+			"audience": ["app"]
+		},
+		"fixture.refuse": {
+			"description": "Always return the failure Refused.",
+			"audience": [
+				"app",
+				"mcp",
+				"cli",
+				"api"
+			],
+			"failures": { "Refused": {
+				"properties": {
+					"_tag": {
+						"const": "Refused",
+						"type": "string"
+					},
+					"reason": { "type": "string" }
+				},
+				"required": ["_tag", "reason"],
+				"type": "object"
+			} }
+		},
+		"fixture.slow": {
+			"description": "Wait for some milliseconds, then return null.",
+			"audience": [
+				"app",
+				"mcp",
+				"cli",
+				"api"
+			],
+			"input": {
+				"properties": { "milliseconds": { "type": "number" } },
+				"required": ["milliseconds"],
+				"type": "object"
+			}
+		},
+		"fixture.switch.set": {
+			"description": "Turn the switch on or off. The switch controls the availability of fixture.toggle.",
+			"audience": [
+				"app",
+				"mcp",
+				"cli",
+				"api"
+			],
+			"input": {
+				"properties": { "on": { "type": "boolean" } },
+				"required": ["on"],
+				"type": "object"
+			}
+		},
+		"fixture.toggle": {
+			"description": "Available only while the switch is on.",
+			"audience": [
+				"app",
+				"mcp",
+				"cli",
+				"api"
+			]
+		}
+	}
+};
+//#endregion
+export { fixture_acidcat_default as default };

package/dist/json/package.json.js

@@ -0,0 +1,4 @@
+//#region package.json
+var version = "0.3.0";
+//#endregion
+export { version };