@acid-cat/cli 0.4.0 → 0.5.0

package/README.md

@@ -54,5 +54,6 @@ The command line is an [Effect](https://effect.website) program that uses `effec
 | `src/conform/` | The conformance checks, and `serve`, which serves web handlers on a local port |
 | `conformance/` | The conformance fixture, in Pkl and in JSON |
 | `test/` | Tests. Run them with `moon run cli:test` |
+| `test/fixtures/` | The catalog of the tests: a bakery, in canonical form |
 
 The canonical writer comes from [`@acid-cat/catalog`](../catalog/typescript).

package/dist/catalog.d.ts

@@ -7,5 +7,10 @@ export interface Report {
     readonly errors: readonly string[];
     readonly warnings: readonly string[];
 }
+/**
+ * True if the value has the members and the member types of a catalog. It does not check the catalog rules: `check`
+ * does that.
+ */
+export declare const isCatalog: (value: unknown) => value is Catalog;
 /** Check a catalog. When `text` is given, the file must also be in canonical form. */
 export declare function check(document: unknown, text?: string): Report;

package/dist/catalog.js

@@ -1,4 +1,5 @@
 import catalog_schema_default from "./json/catalog.schema.json.js";
+import { isObject, isRecordOf, isStringArray } from "./json.js";
 import { canonicalText } from "@acid-cat/catalog";
 import { REFERENCE, bundle, schemasOf, viewOf as viewOf$1, visitObjects } from "@acid-cat/spec-ts";
 import { Result, Schema, SchemaIssue, SchemaRepresentation } from "effect";
@@ -34,13 +35,24 @@ const KNOWN_MEMBERS = {
 /** The catalog schema (schemas/catalog.schema.json), imported as an Effect schema. */
 const decodeCatalog = (() => {
 	const { $defs, $schema: _schema, $id: _id, ...root } = catalog_schema_default;
+	const definitions = $defs;
 	const schema = SchemaRepresentation.fromJsonSchemaDocument({
 		dialect: "draft-2020-12",
 		schema: root,
-		definitions: $defs ?? {}
+		definitions
 	}, { patterns: "apply" });
-	return Schema.decodeUnknownResult(schema);
+	return Schema.decodeUnknownResult(Schema.toType(schema));
 })();
+/** True if `key` is absent from the object, or if `isMember` is true for its value. */
+const optional = (object, key, isMember) => !(key in object) || isMember(object[key]);
+const isString = (value) => typeof value === "string";
+const isTarget = (value) => isObject(value) && isStringArray(value.bindings);
+const isCapability = (value) => isObject(value) && typeof value.description === "string" && optional(value, "audience", isStringArray) && optional(value, "input", isObject) && optional(value, "output", isObject) && optional(value, "state", isObject) && optional(value, "failures", (failures) => isRecordOf(failures, isObject)) && optional(value, "readOnly", (readOnly) => typeof readOnly === "boolean");
+/**
+* True if the value has the members and the member types of a catalog. It does not check the catalog rules: `check`
+* does that.
+*/
+const isCatalog = (value) => isObject(value) && typeof value.acidcat === "string" && optional(value, "title", isString) && optional(value, "description", isString) && isRecordOf(value.targets, isTarget) && optional(value, "$defs", (types) => isRecordOf(types, isObject)) && isRecordOf(value.capabilities, isCapability);
 const formatIssues = SchemaIssue.makeFormatterStandardSchemaV1();
 /** Check a catalog. When `text` is given, the file must also be in canonical form. */
 function check(document, text) {
@@ -49,6 +61,10 @@ function check(document, text) {
 		errors: formatIssues(decoded.failure.issue).issues.map((issue) => `${(issue.path ?? []).map((key) => `[${JSON.stringify(key)}]`).join("") || "the catalog"}: ${issue.message}`),
 		warnings: []
 	};
+	if (!isCatalog(document)) return {
+		errors: ["the catalog: the members do not have the types of a catalog"],
+		warnings: []
+	};
 	const catalog = document;
 	const errors = ruleErrors(catalog);
 	const warnings = [...unknownMembers(catalog), ...errors.length === 0 ? schemaWarnings(catalog) : []];
@@ -103,9 +119,12 @@ function referenceErrors(schema, types) {
 		if ("$defs" in node) errors.push("has its own $defs; put shared types in the catalog's $defs");
 		if (node.$ref === void 0) return;
 		const name = typeof node.$ref === "string" ? REFERENCE.exec(node.$ref)?.[1] : void 0;
-		if (name === void 0 || !(name in types)) errors.push(`references ${String(node.$ref)}, which is not a type`);
+		if (name === void 0 || !(name in types)) {
+			const reference = typeof node.$ref === "string" ? node.$ref : JSON.stringify(node.$ref);
+			errors.push(`references ${reference}, which is not a type`);
+		}
 	});
 	return errors;
 }
 //#endregion
-export { bundle, check, viewOf$1 as viewOf };
+export { bundle, check, isCatalog, viewOf$1 as viewOf };

package/dist/conform/check.d.ts

@@ -1,4 +1,4 @@
-import type { CatalogDocument } from "@acid-cat/spec-ts";
+import type { CatalogDocument, Outcome } from "@acid-cat/spec-ts";
 export interface Check {
     readonly binding: string;
     readonly name: string;
@@ -9,6 +9,11 @@ export interface Check {
 }
 /** The conformance fixture: the catalog that each implementation serves. */
 export declare const fixture: CatalogDocument;
+/**
+ * True if the value is an outcome (spec/invocation.md): `{ ok: true, value }`, `{ ok: false, error }`, or a call
+ * failure `{ kind, message }` with no `ok`.
+ */
+export declare const isOutcome: (value: unknown) => value is Outcome<unknown, unknown>;
 /** The ids of the capabilities in the view of a target of the fixture. */
 export declare const idsOf: (target: string) => string[];
 /** The time, in milliseconds, that each check has to settle when `conform` gets no other time. */

package/dist/conform/check.js

@@ -1,10 +1,21 @@
+import { isObject } from "../json.js";
 import fixture_acidcat_default from "../json/fixture.acidcat.json.js";
-import { viewOf } from "@acid-cat/spec-ts";
+import { CALL_FAILURE_KINDS, viewOf } from "@acid-cat/spec-ts";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 //#region src/conform/check.ts
 /** The result of one conformance check, and helpers to write checks. */
 /** The conformance fixture: the catalog that each implementation serves. */
 const fixture = fixture_acidcat_default;
+/**
+* True if the value is an outcome (spec/invocation.md): `{ ok: true, value }`, `{ ok: false, error }`, or a call
+* failure `{ kind, message }` with no `ok`.
+*/
+const isOutcome = (value) => {
+	if (!isObject(value)) return false;
+	if (value.ok === true) return "value" in value;
+	if (value.ok === false) return "error" in value;
+	return !("ok" in value) && CALL_FAILURE_KINDS.some((kind) => kind === value.kind) && typeof value.message === "string";
+};
 /** The ids of the capabilities in the view of a target of the fixture. */
 const idsOf = (target) => Object.keys(viewOf(fixture, target).capabilities).sort();
 /** The time, in milliseconds, that each check has to settle when `conform` gets no other time. */
@@ -88,4 +99,4 @@ const sorted = (values) => [...values].sort();
 /** An origin that no deployment allows. */
 const FORBIDDEN_ORIGIN = "https://not-allowed.acid-cat.invalid";
 //#endregion
-export { Checks, DEADLINE, FORBIDDEN_ORIGIN, abortable, expect, expectEqual, fixture, idsOf, sorted, until };
+export { Checks, DEADLINE, FORBIDDEN_ORIGIN, abortable, expect, expectEqual, fixture, idsOf, isOutcome, sorted, until };

package/dist/conform/cli.js

@@ -1,3 +1,4 @@
+import { isArrayOf, isObject, memberOf, parseJson } from "../json.js";
 import { Checks, expect, expectEqual, idsOf, sorted, until } from "./check.js";
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -19,13 +20,22 @@ const USAGES = {
 	"fixture.switch.set": "fixture switch set --on",
 	"fixture.toggle": "fixture toggle"
 };
+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. */
+function entriesOf(stdout) {
+	const list = parseJson(stdout);
+	if (!isArrayOf(list, isEntry)) throw new Error(`list must give a list of objects with an id, got ${JSON.stringify(list)}`);
+	return list;
+}
 /**
 * Start the command line. When the signal aborts, the process is killed, and its run rejects. The rejection is observed
 * here too, so that a check that stops waiting first, for example at the deadline, records a failure and does not end
 * the process with an unhandled rejection.
 */
 function start(command, args, signal) {
-	const child = spawn(command[0], [...command.slice(1), ...args], {
+	const [program, ...programArgs] = command;
+	if (program === void 0) throw new Error("the command that starts the command line is empty");
+	const child = spawn(program, [...programArgs, ...args], {
 		stdio: [
 			"ignore",
 			"pipe",
@@ -59,12 +69,12 @@ async function checkCli(command, options) {
 	await checks.run("a value goes to standard output with exit code 0", `${RULE}#outcomes`, async (signal) => {
 		const result = await run(signal, "fixture", "echo", "--text", "hello");
 		expectEqual(result.code, 0, "exit code");
-		expectEqual(JSON.parse(result.stdout), { text: "hello" }, "standard output");
+		expectEqual(parseJson(result.stdout), { text: "hello" }, "standard output");
 	});
 	await checks.run("a failure goes to standard output with exit code 1", `${RULE}#outcomes`, async (signal) => {
 		const result = await run(signal, "fixture", "refuse");
 		expectEqual(result.code, 1, "exit code");
-		expectEqual(JSON.parse(result.stdout)._tag, "Refused", "_tag");
+		expectEqual(memberOf(parseJson(result.stdout), "_tag"), "Refused", "_tag");
 	});
 	await checks.run("a defect goes to standard error with exit code 5", `${RULE}#outcomes`, async (signal) => {
 		const result = await run(signal, "fixture", "crash");
@@ -141,14 +151,14 @@ async function checkCli(command, options) {
 	await checks.run("call gives the value of a capability", `${RULE}#commands`, async (signal) => {
 		const result = await run(signal, "call", "fixture.echo", "{\"text\":\"hello\"}");
 		expectEqual(result.code, 0, "exit code");
-		expectEqual(JSON.parse(result.stdout), { text: "hello" }, "standard output");
+		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(JSON.parse(result.stdout).map((entry) => entry.id)), idsOf("cli"), "ids");
+		expectEqual(sorted(entriesOf(result.stdout).map((entry) => entry.id)), idsOf("cli"), "ids");
 	});
 	await checks.run("list gives the usage of each capability, with its flags", `${RULE}#commands`, async (signal) => {
-		const entries = JSON.parse((await run(signal, "list")).stdout);
+		const entries = entriesOf((await run(signal, "list")).stdout);
 		for (const { id, usage } of entries) {
 			expect(typeof usage === "string", `${id} must have a usage`);
 			const [program, ...rest] = usage.split(" ");

package/dist/conform/http.d.ts

@@ -1,4 +1,3 @@
-/** Conformance checks for the HTTP binding (spec/bindings/http.md). */
 import { Checks } from "./check.js";
 export declare function checkHttp(base: string, options: {
     readonly maximumBytes: number;

package/dist/conform/http.js

@@ -1,7 +1,15 @@
+import { isArrayOf, isObject, memberOf, readJson } from "../json.js";
 import { Checks, FORBIDDEN_ORIGIN, expect, expectEqual, idsOf, sorted } from "./check.js";
 //#region src/conform/http.ts
 /** Conformance checks for the HTTP binding (spec/bindings/http.md). */
 const RULE = "spec/bindings/http.md";
+const isEntry = (value) => isObject(value) && typeof value.id === "string";
+/** The list that `GET /capabilities` gives. The check fails when it is not a list of entries. */
+async function entriesOf(response) {
+	const list = await readJson(response);
+	if (!isArrayOf(list, isEntry)) throw new Error(`GET /capabilities must give a list of objects with an id, got ${JSON.stringify(list)}`);
+	return list;
+}
 async function checkHttp(base, options) {
 	const checks = new Checks("http", options.deadline);
 	const post = (signal, id, body, headers = {}) => fetch(`${base}/capabilities/${id}`, {
@@ -10,28 +18,28 @@ async function checkHttp(base, options) {
 			"Content-Type": "application/json",
 			...headers
 		},
-		body: typeof body === "string" ? body : body instanceof Uint8Array ? new Blob([body]) : JSON.stringify(body),
+		body: typeof body === "string" ? body : body instanceof Uint8Array ? new Blob([new Uint8Array(body)]) : JSON.stringify(body),
 		signal
 	});
-	const json = async (response) => await response.json();
+	const kindOf = async (response) => memberOf(await readJson(response), "kind");
 	await checks.run("GET /capabilities lists the view with availability", `${RULE}#requests`, async (signal) => {
-		const list = await (await fetch(`${base}/capabilities`, { signal })).json();
+		const list = await entriesOf(await fetch(`${base}/capabilities`, { signal }));
 		expectEqual(sorted(list.map((entry) => entry.id)), idsOf("api"), "ids");
 		expect(list.every((entry) => typeof entry.available === "boolean"), "each entry must have available");
 	});
 	await checks.run("a value has the status 200", `${RULE}#requests`, async (signal) => {
 		const response = await post(signal, "fixture.echo", { text: "hello" });
 		expectEqual(response.status, 200, "status");
-		expectEqual(await json(response), {
+		expectEqual(await readJson(response), {
 			ok: true,
 			value: { text: "hello" }
 		}, "body");
 	});
 	await checks.run("a failure has the status 200 and ok: false", `${RULE}#requests`, async (signal) => {
 		const response = await post(signal, "fixture.refuse", {});
-		const body = await json(response);
+		const body = await readJson(response);
 		expectEqual(response.status, 200, "status");
-		expect(body.ok === false && body.error?._tag === "Refused", `got ${JSON.stringify(body)}`);
+		expect(memberOf(body, "ok") === false && memberOf(memberOf(body, "error"), "_tag") === "Refused", `got ${JSON.stringify(body)}`);
 	});
 	for (const [name, id, input, status, kind] of [
 		[
@@ -58,16 +66,16 @@ async function checkHttp(base, options) {
 	]) await checks.run(name, `${RULE}#requests`, async (signal) => {
 		const response = await post(signal, id, input);
 		expectEqual(response.status, status, "status");
-		expectEqual((await json(response)).kind, kind, "kind");
+		expectEqual(await kindOf(response), kind, "kind");
 	});
 	await checks.run("an unavailable capability has the status 503", `${RULE}#requests`, async (signal) => {
 		await post(signal, "fixture.switch.set", { on: false });
 		try {
-			const toggle = (await (await fetch(`${base}/capabilities`, { signal })).json()).find((entry) => entry.id === "fixture.toggle");
+			const toggle = (await entriesOf(await fetch(`${base}/capabilities`, { signal }))).find((entry) => entry.id === "fixture.toggle");
 			expect(toggle?.available === false && typeof toggle.reason === "string", "fixture.toggle must be unavailable, with a reason");
 			const response = await post(signal, "fixture.toggle", {});
 			expectEqual(response.status, 503, "status");
-			expectEqual((await json(response)).kind, "unavailable", "kind");
+			expectEqual(await kindOf(response), "unavailable", "kind");
 		} finally {
 			await post(AbortSignal.timeout(options.deadline), "fixture.switch.set", { on: true });
 		}

package/dist/conform/mcp.js

@@ -1,3 +1,4 @@
+import { isObject, memberOf, parseJson, readJson } from "../json.js";
 import { Checks, FORBIDDEN_ORIGIN, expect, expectEqual, fixture, idsOf, sorted } from "./check.js";
 import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 //#region src/conform/mcp.ts
@@ -15,7 +16,11 @@ async function mcpClient(url, signal) {
 	await client.connect(new StreamableHTTPClientTransport(new URL(url)), signal ? { signal } : void 0);
 	return client;
 }
-const textOf = (result) => JSON.parse(result.content?.[0]?.text ?? "null");
+/** The JSON value in the first text content of a tool result, or `null` when there is no text content. */
+const textOf = (result) => {
+	const first = result.content[0];
+	return parseJson(first?.type === "text" ? first.text : "null");
+};
 async function checkMcp(url, options) {
 	const checks = new Checks("mcp", options.deadline);
 	let client;
@@ -41,9 +46,9 @@ async function checkMcp(url, options) {
 		const refuse = tools.find((tool) => tool.name === "fixture.refuse");
 		expect(echo?.annotations?.readOnlyHint === true, "fixture.echo must have readOnlyHint: true");
 		expect(refuse?.annotations?.readOnlyHint !== true, "fixture.refuse must not have readOnlyHint: true");
-		expect((echo?.outputSchema)?.type === "object", "fixture.echo must have an object outputSchema");
+		expect(echo?.outputSchema?.type === "object", "fixture.echo must have an object outputSchema");
 		expect(refuse?.outputSchema === void 0, "fixture.refuse has no object output, so it must have no outputSchema");
-		expect((echo?.inputSchema).type === "object", "an inputSchema must be an object");
+		expect(echo?.inputSchema.type === "object", "an inputSchema must be an object");
 	});
 	await checks.run("a value is a tool result with structured content", `${RULE}#tools`, async (signal) => {
 		const result = await call(signal, "fixture.echo", { text: "hello" });
@@ -55,21 +60,23 @@ async function checkMcp(url, options) {
 		const result = await call(signal, "fixture.refuse", {});
 		expect(result.isError === true, "a failure must be an error result");
 		const body = textOf(result);
-		expect(body.ok === false && body.error?._tag === "Refused", `expected { ok: false, error: { _tag: "Refused" } }, got ${JSON.stringify(body)}`);
+		expect(memberOf(body, "ok") === false && memberOf(memberOf(body, "error"), "_tag") === "Refused", `expected { ok: false, error: { _tag: "Refused" } }, got ${JSON.stringify(body)}`);
 	});
 	await checks.run("a defect is an internal call failure with no internal details", `${RULE}#tools`, async (signal) => {
 		const result = await call(signal, "fixture.crash", {});
 		const body = textOf(result);
+		expect(isObject(body), `expected an object, got ${JSON.stringify(body)}`);
 		expect(result.isError === true && body.kind === "internal" && !("ok" in body), `expected { kind: "internal" }, got ${JSON.stringify(body)}`);
-		expect(!/\n\s+at /.test(body.message ?? ""), "the message must not contain a stack trace");
+		const message = typeof body.message === "string" ? body.message : "";
+		expect(!/\n\s+at /.test(message), "the message must not contain a stack trace");
 	});
 	await checks.run("an input that does not agree with its schema is invalid-input", `${RULE}#tools`, async (signal) => {
 		const result = await call(signal, "fixture.echo", { text: 1 });
-		expectEqual(textOf(result).kind, "invalid-input", "kind");
+		expectEqual(memberOf(textOf(result), "kind"), "invalid-input", "kind");
 	});
 	await checks.run("a capability outside the view is an unknown tool", `${RULE}#tools`, async (signal) => {
 		const error = await call(signal, "fixture.hidden", {}).then(() => void 0, (caught) => caught);
-		expect(error?.code === -32602, `expected the JSON-RPC error -32602, got ${JSON.stringify(error)}`);
+		expect(memberOf(error, "code") === -32602, `expected the JSON-RPC error -32602, got ${JSON.stringify(error)}`);
 	});
 	await checks.run("an unavailable capability is not listed", `${RULE}#tools`, async (signal) => {
 		await call(signal, "fixture.switch.set", { on: false });
@@ -81,19 +88,19 @@ async function checkMcp(url, options) {
 		}
 	});
 	await mcp.close();
-	const post = (signal, init) => fetch(url, {
+	const post = (signal, { headers = {}, body }) => fetch(url, {
 		method: "POST",
-		...init,
+		body,
 		headers: {
 			"Content-Type": "application/json",
-			...init.headers
+			...headers
 		},
 		signal
 	});
 	const rejection = async (response, status, code) => {
 		expectEqual(response.status, status, "status");
 		expectEqual(response.headers.get("Cache-Control"), "no-store", "Cache-Control");
-		if (code !== void 0) expectEqual((await response.json()).error?.code, code, "JSON-RPC error code");
+		if (code !== void 0) expectEqual(memberOf(memberOf(await readJson(response), "error"), "code"), code, "JSON-RPC error code");
 	};
 	await checks.run("a method other than POST is rejected with 405", `${RULE}#server`, async (signal) => {
 		const response = await fetch(url, { signal });

package/dist/conform/properties.d.ts

@@ -1,7 +1,8 @@
 import type { Outcome } from "@acid-cat/spec-ts";
+import type { JsonObject } from "../json.js";
 import { Checks } from "./check.js";
 /** A call through one binding. When the signal aborts, the client stops the call and rejects with the reason of the signal. */
-export type Invoke = (id: string, input: object, signal?: AbortSignal) => Promise<Outcome<unknown, unknown>>;
+export type Invoke = (id: string, input: JsonObject, signal?: AbortSignal) => Promise<Outcome<unknown, unknown>>;
 export declare function httpInvoke(base: string): Invoke;
 export declare function mcpInvoke(url: string, signal: AbortSignal): Promise<{
     readonly invoke: Invoke;

package/dist/conform/properties.js

@@ -1,4 +1,5 @@
-import { Checks, expect, until } from "./check.js";
+import { isStringArray, memberOf, parseJson, readJson } from "../json.js";
+import { Checks, expect, isOutcome, until } from "./check.js";
 import { mcpClient } from "./mcp.js";
 import { SdkError } from "@modelcontextprotocol/client";
 import { randomUUID } from "node:crypto";
@@ -11,12 +12,15 @@ import fc from "fast-check";
 const RULE = "spec/invocation.md#cancellation-and-concurrency";
 function httpInvoke(base) {
 	return async (id, input, signal) => {
-		return await (await fetch(`${base}/capabilities/${id}`, {
+		const response = await fetch(`${base}/capabilities/${id}`, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
 			body: JSON.stringify(input),
 			...signal ? { signal } : {}
-		})).json();
+		});
+		const outcome = await readJson(response);
+		if (!isOutcome(outcome)) throw new Error(`POST /capabilities/${id} gave ${JSON.stringify(outcome)}, which is not an outcome`);
+		return outcome;
 	};
 }
 async function mcpInvoke(url, signal) {
@@ -28,15 +32,17 @@ async function mcpInvoke(url, signal) {
 					name: id,
 					arguments: input
 				}, signal ? { signal } : void 0);
-				const body = JSON.parse(result.content[0]?.text ?? "null");
+				const first = result.content[0];
+				const body = parseJson(first?.type === "text" ? first.text : "null");
 				if (result.isError !== true) return {
 					ok: true,
 					value: result.structuredContent ?? body
 				};
+				if (!isOutcome(body)) throw new Error(`the error result of ${id} gave ${JSON.stringify(body)}, which is not an outcome`);
 				return body;
 			} catch (error) {
 				if (signal?.aborted && error instanceof SdkError && error.message === String(signal.reason)) throw signal.reason;
-				if (error.code === -32602) return {
+				if (memberOf(error, "code") === -32602) return {
 					kind: "unknown-capability",
 					message: String(error)
 				};
@@ -54,7 +60,7 @@ const operation = fc.oneof(fc.string({ maxLength: 40 }).map((text) => ({
 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 "refuse": return "ok" in outcome && !outcome.ok && memberOf(outcome.error, "_tag") === "Refused";
 		case "crash": return "kind" in outcome && outcome.kind === "internal";
 		case "invalid": return "kind" in outcome && outcome.kind === "invalid-input";
 	}
@@ -78,7 +84,9 @@ const isCancellation = (settled, reason) => "outcome" in settled ? "kind" in set
 async function heldKeys(invoke, signal) {
 	const outcome = await invoke("fixture.held", {}, signal);
 	expect("ok" in outcome && outcome.ok, `fixture.held gave ${JSON.stringify(outcome)}`);
-	return outcome.value.keys;
+	const keys = memberOf(outcome.value, "keys");
+	expect(isStringArray(keys), `fixture.held gave ${JSON.stringify(outcome)}, with no list of keys`);
+	return keys;
 }
 /**
 * Start one call to fixture.hold for each flag, and wait until each call holds. Then cancel each call whose flag is
@@ -138,8 +146,10 @@ async function checkProperties(binding, invoke, deadline) {
 			maxLength: 12
 		}), async (operations) => {
 			fc.pre(!signal.aborted);
-			const outcomes = await Promise.all(operations.map((op) => callFor(invoke, op, signal)));
-			operations.forEach((op, index) => expect(agrees(op, outcomes[index]), `${op.kind} gave ${JSON.stringify(outcomes[index])}`));
+			(await Promise.all(operations.map(async (op) => ({
+				op,
+				outcome: await callFor(invoke, op, signal)
+			})))).forEach(({ op, outcome }) => expect(agrees(op, outcome), `${op.kind} gave ${JSON.stringify(outcome)}`));
 		}), {
 			numRuns: 25,
 			includeErrorInReport: true

package/dist/conform/serve.js

@@ -23,7 +23,8 @@ function serve(routes) {
 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) {
+	const handler = prefix === void 0 ? void 0 : routes[prefix];
+	if (handler === void 0) {
 		outgoing.writeHead(404).end();
 		return;
 	}
@@ -35,17 +36,19 @@ async function answer(incoming, outgoing, prefixes, routes) {
 	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, {
+	const init = {
 		method: incoming.method ?? "GET",
 		headers,
-		signal: abort.signal,
-		...hasBody ? {
-			body: incoming,
-			duplex: "half"
-		} : {}
+		signal: abort.signal
+	};
+	const withBody = () => ({
+		...init,
+		body: bodyOf(incoming),
+		duplex: "half"
 	});
+	const request = new Request(url, hasBody ? withBody() : init);
 	try {
-		const response = await routes[prefix](request);
+		const response = await handler(request);
 		outgoing.writeHead(response.status, Object.fromEntries(response.headers));
 		if (response.body === null) {
 			outgoing.end();
@@ -58,5 +61,39 @@ async function answer(incoming, outgoing, prefixes, routes) {
 		outgoing.end();
 	}
 }
+/**
+* The body of an incoming request, as a web stream. The stream reads the request only when the handler reads the body,
+* and the request pauses after each chunk until the handler reads again. A request that the handler does not read stays
+* unread, so that Node.js discards it after the response. When the handler cancels the stream, the request discards the
+* rest of its body.
+*/
+function bodyOf(incoming) {
+	let open = true;
+	let reading = false;
+	const close = (end) => {
+		if (open) end();
+		open = false;
+	};
+	return new ReadableStream({
+		pull(controller) {
+			if (!reading) {
+				reading = true;
+				incoming.on("data", (chunk) => {
+					if (!open) return;
+					if (!(chunk instanceof Uint8Array)) return close(() => controller.error(/* @__PURE__ */ new TypeError("a chunk of the request body is not bytes")));
+					controller.enqueue(chunk);
+					incoming.pause();
+				});
+				incoming.on("end", () => close(() => controller.close()));
+				incoming.on("error", (error) => close(() => controller.error(error)));
+			}
+			incoming.resume();
+		},
+		cancel() {
+			open = false;
+			incoming.resume();
+		}
+	}, { highWaterMark: 0 });
+}
 //#endregion
 export { serve };

package/dist/conform/webmcp.d.ts

@@ -5,6 +5,12 @@ export interface RecordedTool {
     readonly description: string;
     readonly inputSchema: unknown;
 }
+/** A tool, as a page gives it to `registerTool`. */
+export interface HostTool extends RecordedTool {
+    execute(input: unknown, options: {
+        readonly signal: AbortSignal;
+    }): Promise<unknown>;
+}
 /** What a call to a tool gives: the value that `execute` resolves with, or the error that it rejects with. */
 export type ToolCall = {
     readonly resolved: unknown;
@@ -20,7 +26,7 @@ export type ToolCall = {
 /** The host that the checks give to the page. */
 export interface TestHost {
     readonly modelContext: {
-        registerTool(tool: object, options: {
+        registerTool(tool: HostTool, options: {
             readonly signal: AbortSignal;
         }): void;
     };

package/dist/conform/webmcp.js

@@ -1,3 +1,4 @@
+import { isArrayOf, isObject, isStringArray, memberOf, parseJson } from "../json.js";
 import { Checks, abortable, expect, expectEqual, fixture, idsOf, sorted, until } from "./check.js";
 import { REFERENCE, visitObjects } from "@acid-cat/spec-ts";
 //#region src/conform/webmcp.ts
@@ -20,10 +21,9 @@ function createTestHost() {
 	const calls = /* @__PURE__ */ new Map();
 	return {
 		modelContext: { registerTool(tool, options) {
-			const recorded = tool;
-			registered.set(recorded.name, recorded);
+			registered.set(tool.name, tool);
 			options.signal.addEventListener("abort", () => {
-				if (registered.get(recorded.name) === recorded) registered.delete(recorded.name);
+				if (registered.get(tool.name) === tool) registered.delete(tool.name);
 			});
 		} },
 		tools: () => [...registered.values()].map((tool) => ({
@@ -39,7 +39,10 @@ function createTestHost() {
 			try {
 				return { resolved: await tool.execute(input, { signal: controller.signal }) };
 			} catch (error) {
-				const { name: errorName, kind, message } = error;
+				const hasMembers = typeof error === "object" && error !== null;
+				const errorName = hasMembers && "name" in error ? error.name : void 0;
+				const kind = hasMembers && "kind" in error ? error.kind : void 0;
+				const message = hasMembers && "message" in error ? error.message : void 0;
 				return { rejected: {
 					name: String(errorName),
 					kind,
@@ -54,6 +57,30 @@ function createTestHost() {
 		}
 	};
 }
+/** The tools that a host gives, after they pass through JSON. The check fails when the value is not a list of tools. */
+function toolsOf(value) {
+	const isTool = (tool) => isObject(tool) && typeof tool.name === "string" && typeof tool.description === "string";
+	if (!isArrayOf(value, isTool)) throw new Error(`the host must give a list of tools, got ${JSON.stringify(value)}`);
+	return value.map((tool) => ({
+		name: tool.name,
+		description: tool.description,
+		inputSchema: tool.inputSchema
+	}));
+}
+/** A tool call that a host gives, after it passes through JSON. The check fails when the value is not a tool call. */
+function toolCallOf(value) {
+	if (isObject(value)) {
+		if (value.missing === true) return { missing: true };
+		if ("resolved" in value) return { resolved: value.resolved };
+		const rejected = value.rejected;
+		if (isObject(rejected) && typeof rejected.name === "string" && typeof rejected.message === "string") return { rejected: {
+			name: rejected.name,
+			kind: rejected.kind,
+			message: rejected.message
+		} };
+	}
+	throw new Error(`the host must give a tool call, got ${JSON.stringify(value)}`);
+}
 let lastCall = 0;
 function driverOf(host) {
 	return {
@@ -76,10 +103,10 @@ function driverOf(host) {
 async function processDriver(install) {
 	const host = createTestHost();
 	const remove = await install(host.modelContext);
-	const copy = (value) => JSON.parse(JSON.stringify(value));
+	const copy = (value) => parseJson(JSON.stringify(value));
 	return driverOf({
-		tools: async () => copy(host.tools()),
-		call: async (name, input, id) => copy(await host.call(name, input, id)),
+		tools: async () => toolsOf(copy(host.tools())),
+		call: async (name, input, id) => toolCallOf(copy(await host.call(name, input, id))),
 		cancel: async (id) => host.cancel(id),
 		close: async () => {
 			if (typeof remove === "function") await remove();
@@ -105,23 +132,22 @@ async function browserDriver(url) {
     }
   `);
 	await page.goto(url);
+	const host = (method, ...args) => page.evaluate(`window.__acidCatConform.${method}(${args.map((arg) => JSON.stringify(arg) ?? "undefined").join(", ")})`);
 	return driverOf({
 		tools: async () => {
 			if (errors.length > 0) throw new Error(`The page has errors: ${errors.join("; ")}`);
-			return page.evaluate(() => window.__acidCatConform.tools());
+			return toolsOf(await host("tools"));
+		},
+		call: async (name, input, id) => toolCallOf(await host("call", name, input, id)),
+		cancel: async (id) => {
+			await host("cancel", id);
 		},
-		call: (name, input, id) => page.evaluate(([name, input, id]) => window.__acidCatConform.call(name, input, id), [
-			name,
-			input,
-			id
-		]),
-		cancel: (id) => page.evaluate((id) => window.__acidCatConform.cancel(id), id),
 		close: () => browser.close()
 	});
 }
 /** 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 ?? {};
+	const types = isObject(schema.$defs) ? schema.$defs : {};
 	let bundled = true;
 	visitObjects(schema, (node) => {
 		if (typeof node.$ref !== "string") return;
@@ -135,7 +161,9 @@ const names = async (driver, signal) => sorted((await driver.tools(signal)).map(
 async function heldKeys(driver, signal) {
 	const call = await driver.call("fixture.held", {}, { signal });
 	expect("resolved" in call, `fixture.held gave ${JSON.stringify(call)}`);
-	return call.resolved.value.keys;
+	const keys = memberOf(memberOf(call.resolved, "value"), "keys");
+	expect(isStringArray(keys), `fixture.held gave ${JSON.stringify(call)}, with no list of keys`);
+	return keys;
 }
 async function checkWebMcp(driver, options) {
 	const checks = new Checks("webmcp", options.deadline);
@@ -148,10 +176,12 @@ async function checkWebMcp(driver, options) {
 		for (const tool of await driver.tools(signal)) {
 			expectEqual(tool.description, view[tool.name]?.description, `description of ${tool.name}`);
 			const schema = tool.inputSchema;
+			expect(isObject(schema), `the input schema of ${tool.name} must be an object`);
 			const input = view[tool.name]?.input ?? {};
+			const required = (object) => isStringArray(object.required) ? object.required : [];
 			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}`);
+			expectEqual(sorted(required(schema)), sorted(required(input)), `required properties of ${tool.name}`);
 			expect(isBundled(schema), `the input schema of ${tool.name} must be bundled`);
 		}
 	});
@@ -164,7 +194,7 @@ async function checkWebMcp(driver, options) {
 	await checks.run("a failure resolves as a result", `${RULE}#tools`, async (signal) => {
 		const call = await driver.call("fixture.refuse", {}, { signal });
 		expect("resolved" in call, `the call must resolve, got ${JSON.stringify(call)}`);
-		expectEqual(call.resolved.error?._tag, "Refused", "_tag");
+		expectEqual(memberOf(memberOf(call.resolved, "error"), "_tag"), "Refused", "_tag");
 	});
 	for (const [name, capability, input, kind, errorName] of [[
 		"a defect rejects with the kind internal",

package/dist/json/package.json.js

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

package/dist/json.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Checks of JSON values at run time. A value from a file, a process or a network is not trusted. These checks give it a
+ * type only after they examine it.
+ */
+import type { JsonObject } from "@acid-cat/spec-ts";
+export type { JsonObject };
+/** True if the value is a JSON object: not `null`, and not an array. */
+export declare const isObject: (value: unknown) => value is JsonObject;
+/** True if the value is an array of strings. */
+export declare const isStringArray: (value: unknown) => value is readonly string[];
+/** True if the value is a JSON object, and `isMember` is true for each of its member values. */
+export declare const isRecordOf: <T>(value: unknown, isMember: (member: unknown) => member is T) => value is {
+    readonly [key: string]: T;
+};
+/** The member `key` of a value, or `undefined` when the value is not an object. */
+export declare const memberOf: (value: unknown, key: string) => unknown;
+/** Parse JSON text. The value is not trusted, so its type is `unknown`. */
+export declare function parseJson(text: string): unknown;
+/** Read the body of a response as JSON. The value is not trusted, so its type is `unknown`. */
+export declare function readJson(response: Response): Promise<unknown>;
+/** True if the value is an array, and `isItem` is true for each of its items. */
+export declare const isArrayOf: <T>(value: unknown, isItem: (item: unknown) => item is T) => value is readonly T[];

package/dist/json.js

@@ -0,0 +1,21 @@
+//#region src/json.ts
+/** True if the value is a JSON object: not `null`, and not an array. */
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** True if the value is an array of strings. */
+const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+/** True if the value is a JSON object, and `isMember` is true for each of its member values. */
+const isRecordOf = (value, isMember) => isObject(value) && Object.values(value).every(isMember);
+/** The member `key` of a value, or `undefined` when the value is not an object. */
+const memberOf = (value, key) => isObject(value) ? value[key] : void 0;
+/** Parse JSON text. The value is not trusted, so its type is `unknown`. */
+function parseJson(text) {
+	return JSON.parse(text);
+}
+/** Read the body of a response as JSON. The value is not trusted, so its type is `unknown`. */
+async function readJson(response) {
+	return await response.json();
+}
+/** True if the value is an array, and `isItem` is true for each of its items. */
+const isArrayOf = (value, isItem) => Array.isArray(value) && value.every(isItem);
+//#endregion
+export { isArrayOf, isObject, isRecordOf, isStringArray, memberOf, parseJson, readJson };

package/dist/main.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { check, viewOf } from "./catalog.js";
+import { parseJson } from "./json.js";
+import { check, isCatalog, viewOf } from "./catalog.js";
 import { DEADLINE } from "./conform/check.js";
 import { conform } from "./conform/index.js";
 import { version } from "./json/package.json.js";
@@ -17,7 +18,7 @@ const readCatalog = Effect.fn("readCatalog")(function* (file) {
 	const text = yield* (yield* FileSystem.FileSystem).readFileString(file);
 	return {
 		text,
-		document: JSON.parse(text)
+		document: parseJson(text)
 	};
 });
 const fail = Effect.sync(() => {
@@ -55,8 +56,11 @@ const viewCommand = Command.make("view", {
 	file: Argument.String("catalog").pipe(Argument.withDescription("A catalog file")),
 	target: Argument.String("target").pipe(Argument.withDescription("The name of a target in the catalog"))
 }, Effect.fn(function* ({ file, target }) {
-	const { document } = yield* readCatalog(file);
-	const catalog = document;
+	const { document: catalog } = yield* readCatalog(file);
+	if (!isCatalog(catalog)) {
+		yield* Console.error(`${file}: error: the file is not a catalog; run \`acid-cat check ${file}\``);
+		return yield* fail;
+	}
 	if (!(target in catalog.targets)) {
 		yield* Console.error(`${file}: error: there is no target ${target}`);
 		return yield* fail;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The AcidCat command line: check, format and view catalogs, and test implementations.",
   "keywords": [
     "acidcat",
@@ -37,12 +37,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.4.0",
-    "@acid-cat/spec-ts": "0.4.0",
-    "@effect/platform-node": "4.0.5",
-    "@effect/platform-node-shared": "4.0.5",
+    "@acid-cat/catalog": "0.5.0",
+    "@acid-cat/spec-ts": "0.5.0",
+    "@effect/platform-node": "4.0.6",
+    "@effect/platform-node-shared": "4.0.6",
     "@modelcontextprotocol/client": "2.3.1",
-    "effect": "4.0.5",
+    "effect": "4.0.6",
     "fast-check": "4.10.2"
   },
   "peerDependencies": {