@acid-cat/spec-ts 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -58,6 +58,16 @@ export declare const CLI_EXIT_CODES: {
     readonly cancelled: 130;
 };
 export declare const cliExitCode: (outcome: Outcome<unknown, unknown>) => number;
+/**
+ * The flags of a command, as `usage` writes them (spec/bindings/cli.md#commands): required flags first, each group in
+ * code point order of the names. `input` is the bundled input schema.
+ */
+export declare function cliFlags(input: JsonObject): string[];
+/**
+ * The `usage` of a capability in `list` (spec/bindings/cli.md#commands). `input` is the bundled input schema, or
+ * `undefined` when the capability has no input.
+ */
+export declare function cliUsage(program: string, id: string, input: JsonObject | undefined): string;
 export declare const HTTP_STATUS: {
     readonly "unknown-capability": 404;
     readonly "invalid-input": 422;

package/dist/index.js

@@ -1,174 +1,249 @@
-// src/index.ts
-var CALL_FAILURE_KINDS = ["cancelled", "unknown-capability", "unavailable", "invalid-input", "internal"];
-var ok = (value) => ({ ok: true, value });
-var fail = (tag, data) => ({ ok: false, error: { _tag: tag, ...data ?? {} } });
-var callFailure = (kind, message) => ({ kind, message });
-var isCallFailure = (outcome) => !("ok" in outcome);
+//#region src/index.ts
+/**
+* The fixed details of the AcidCat specification, as TypeScript data and pure functions, for the TypeScript reference
+* implementation. This package has no dependencies.
+*
+* - Outcomes and call failures: spec/invocation.md
+* - Names, views and bundling: spec/catalog.md
+* - Exit codes, status codes and MCP results: spec/bindings/
+*/
+/** The kinds of call failure, in order of precedence: when more than one applies, the first one is used. */
+const CALL_FAILURE_KINDS = [
+	"cancelled",
+	"unknown-capability",
+	"unavailable",
+	"invalid-input",
+	"internal"
+];
+const ok = (value) => ({
+	ok: true,
+	value
+});
+/** A failure with its tag, as a result. */
+const fail = (tag, data) => ({
+	ok: false,
+	error: {
+		_tag: tag,
+		...data ?? {}
+	}
+});
+const callFailure = (kind, message) => ({
+	kind,
+	message
+});
+const isCallFailure = (outcome) => !("ok" in outcome);
+/** The JavaScript error for a call failure (spec/bindings/typescript.md#handles). */
 var CallFailureError = class extends Error {
-  kind;
-  constructor(failure) {
-    super(failure.message);
-    this.kind = failure.kind;
-    this.name = failure.kind === "cancelled" ? "AbortError" : failure.kind === "invalid-input" ? "TypeError" : "Error";
-  }
+	kind;
+	constructor(failure) {
+		super(failure.message);
+		this.kind = failure.kind;
+		this.name = failure.kind === "cancelled" ? "AbortError" : failure.kind === "invalid-input" ? "TypeError" : "Error";
+	}
 };
-var AVAILABLE = { available: true };
-var unavailable = (reason) => ({ available: false, reason });
-var ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*)+$/;
-var isId = (id) => id.length <= 128 && ID_PATTERN.test(id);
-var commandPath = (id) => id.split(".");
-var CLI_EXIT_CODES = {
-  value: 0,
-  failure: 1,
-  "unknown-capability": 2,
-  "invalid-input": 3,
-  unavailable: 4,
-  internal: 5,
-  cancelled: 130
+const AVAILABLE = { available: true };
+const unavailable = (reason) => ({
+	available: false,
+	reason
+});
+const ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*)+$/;
+const isId = (id) => id.length <= 128 && ID_PATTERN.test(id);
+/** The path of the CLI command for an id: `aircon.power.set` → `["aircon", "power", "set"]`. */
+const commandPath = (id) => id.split(".");
+const CLI_EXIT_CODES = {
+	value: 0,
+	failure: 1,
+	"unknown-capability": 2,
+	"invalid-input": 3,
+	unavailable: 4,
+	internal: 5,
+	cancelled: 130
 };
-var cliExitCode = (outcome) => isCallFailure(outcome) ? CLI_EXIT_CODES[outcome.kind] : outcome.ok ? CLI_EXIT_CODES.value : CLI_EXIT_CODES.failure;
-var HTTP_STATUS = {
-  "unknown-capability": 404,
-  "invalid-input": 422,
-  unavailable: 503,
-  cancelled: 409,
-  internal: 500
+const cliExitCode = (outcome) => isCallFailure(outcome) ? CLI_EXIT_CODES[outcome.kind] : outcome.ok ? CLI_EXIT_CODES.value : CLI_EXIT_CODES.failure;
+/**
+* The flags of a command, as `usage` writes them (spec/bindings/cli.md#commands): required flags first, each group in
+* code point order of the names. `input` is the bundled input schema.
+*/
+function cliFlags(input) {
+	const properties = input.properties ?? {};
+	const definitions = input.$defs ?? {};
+	const required = new Set(input.required ?? []);
+	const byName = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+	const names = Object.keys(properties).sort(byName);
+	return [...names.filter((name) => required.has(name)), ...names.filter((name) => !required.has(name))].map((name) => {
+		const reference = properties[name].$ref;
+		const target = typeof reference === "string" ? REFERENCE.exec(reference)?.[1] : void 0;
+		const property = (target === void 0 ? void 0 : definitions[target]) ?? properties[name];
+		const flag = property.type === "boolean" ? `--${name}` : `--${name} <${flagValue(property)}>`;
+		return required.has(name) ? flag : `[${flag}]`;
+	});
+}
+function flagValue(property) {
+	if (Array.isArray(property.enum) && property.enum.every((value) => typeof value === "string")) return property.enum.join("|");
+	if (property.type === "integer" || property.type === "number" || property.type === "string") return property.type;
+	return "json";
+}
+/**
+* The `usage` of a capability in `list` (spec/bindings/cli.md#commands). `input` is the bundled input schema, or
+* `undefined` when the capability has no input.
+*/
+function cliUsage(program, id, input) {
+	if (input !== void 0 && input.properties === void 0) return `${program} call ${id} '<json>'`;
+	return [
+		program,
+		...commandPath(id),
+		...input === void 0 ? [] : cliFlags(input)
+	].join(" ");
+}
+const HTTP_STATUS = {
+	"unknown-capability": 404,
+	"invalid-input": 422,
+	unavailable: 503,
+	cancelled: 409,
+	internal: 500
 };
-var httpStatus = (outcome) => isCallFailure(outcome) ? HTTP_STATUS[outcome.kind] : 200;
+const httpStatus = (outcome) => isCallFailure(outcome) ? HTTP_STATUS[outcome.kind] : 200;
+/**
+* The first rule that a request breaks, before its body is read: method, origin, media type, declared length.
+* The body itself is checked as it arrives, with `readBounded`.
+*/
 function screenRequest(request, rules) {
-  if (!rules.methods.includes(request.method)) return "method";
-  const origin = request.headers.get("Origin");
-  if (origin !== null && !rules.allowedOrigins.includes(origin)) return "origin";
-  if (request.method === "GET" || request.method === "HEAD") return void 0;
-  const mediaType = (request.headers.get("Content-Type") ?? "").split(";")[0].trim().toLowerCase();
-  if (mediaType !== rules.mediaType) return "media-type";
-  const declared = Number(request.headers.get("Content-Length") ?? "");
-  if (Number.isFinite(declared) && declared > rules.maximumBytes) return "too-large";
-  return void 0;
+	if (!rules.methods.includes(request.method)) return "method";
+	const origin = request.headers.get("Origin");
+	if (origin !== null && !rules.allowedOrigins.includes(origin)) return "origin";
+	if (request.method === "GET" || request.method === "HEAD") return void 0;
+	if ((request.headers.get("Content-Type") ?? "").split(";")[0].trim().toLowerCase() !== rules.mediaType) return "media-type";
+	const declared = Number(request.headers.get("Content-Length") ?? "");
+	if (Number.isFinite(declared) && declared > rules.maximumBytes) return "too-large";
 }
+/** Read a request body as UTF-8 text. Count the bytes as they arrive, and stop at the limit. */
 async function readBounded(request, maximumBytes) {
-  if (request.body === null) return { text: "" };
-  const reader = request.body.getReader();
-  const chunks = [];
-  let length = 0;
-  for (; ; ) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    length += value.byteLength;
-    if (length > maximumBytes) {
-      await reader.cancel().catch(() => void 0);
-      return { rejection: "too-large" };
-    }
-    chunks.push(value);
-  }
-  const bytes = new Uint8Array(length);
-  let offset = 0;
-  for (const chunk of chunks) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  try {
-    return { text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
-  } catch {
-    return { rejection: "not-utf8" };
-  }
+	if (request.body === null) return { text: "" };
+	const reader = request.body.getReader();
+	const chunks = [];
+	let length = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		length += value.byteLength;
+		if (length > maximumBytes) {
+			await reader.cancel().catch(() => void 0);
+			return { rejection: "too-large" };
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	try {
+		return { text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+	} catch {
+		return { rejection: "not-utf8" };
+	}
 }
-var MCP_PROTOCOL_VERSION = "2026-07-28";
-var MCP_UNKNOWN_TOOL = -32602;
-var MCP_REJECTIONS = {
-  method: { status: 405 },
-  origin: { status: 403 },
-  "media-type": { status: 415 },
-  "too-large": { status: 413, code: -32600 },
-  "not-utf8": { status: 400, code: -32700 }
+const MCP_PROTOCOL_VERSION = "2026-07-28";
+const MCP_UNKNOWN_TOOL = -32602;
+/** The HTTP status and JSON-RPC error code for each rejected MCP request. */
+const MCP_REJECTIONS = {
+	method: { status: 405 },
+	origin: { status: 403 },
+	"media-type": { status: 415 },
+	"too-large": {
+		status: 413,
+		code: -32600
+	},
+	"not-utf8": {
+		status: 400,
+		code: -32700
+	}
 };
+/** The MCP tool result for an outcome that is not `unknown-capability`. */
 function mcpToolResult(outcome, hasOutputSchema) {
-  const text = (value) => [{ type: "text", text: JSON.stringify(value) }];
-  if (isCallFailure(outcome)) return { content: text({ kind: outcome.kind, message: outcome.message }), isError: true };
-  if (!outcome.ok) return { content: text({ ok: false, error: outcome.error }), isError: true };
-  return hasOutputSchema ? { content: text(outcome.value), structuredContent: outcome.value } : { content: text(outcome.value) };
+	const text = (value) => [{
+		type: "text",
+		text: JSON.stringify(value)
+	}];
+	if (isCallFailure(outcome)) return {
+		content: text({
+			kind: outcome.kind,
+			message: outcome.message
+		}),
+		isError: true
+	};
+	if (!outcome.ok) return {
+		content: text({
+			ok: false,
+			error: outcome.error
+		}),
+		isError: true
+	};
+	return hasOutputSchema ? {
+		content: text(outcome.value),
+		structuredContent: outcome.value
+	} : { content: text(outcome.value) };
 }
-var REFERENCE = /^#\/\$defs\/([A-Za-z][A-Za-z0-9_]*)$/;
+const REFERENCE = /^#\/\$defs\/([A-Za-z][A-Za-z0-9_]*)$/;
+/** The schemas of a capability, each with the member that holds it. */
 function schemasOf(capability) {
-  const members = [
-    ["input", capability.input],
-    ["output", capability.output],
-    ["state", capability.state],
-    ...Object.entries(capability.failures ?? {}).map(([tag, schema]) => [`failure ${tag}`, schema])
-  ];
-  return members.filter((entry) => entry[1] !== void 0);
+	return [
+		["input", capability.input],
+		["output", capability.output],
+		["state", capability.state],
+		...Object.entries(capability.failures ?? {}).map(([tag, schema]) => [`failure ${tag}`, schema])
+	].filter((entry) => entry[1] !== void 0);
 }
+/** Every object in a JSON value, at all levels. */
 function visitObjects(value, onObject) {
-  if (Array.isArray(value)) {
-    value.forEach((item) => visitObjects(item, onObject));
-  } else if (value !== null && typeof value === "object") {
-    onObject(value);
-    Object.values(value).forEach((item) => visitObjects(item, onObject));
-  }
+	if (Array.isArray(value)) value.forEach((item) => visitObjects(item, onObject));
+	else if (value !== null && typeof value === "object") {
+		onObject(value);
+		Object.values(value).forEach((item) => visitObjects(item, onObject));
+	}
 }
+/** The types that a schema uses, directly or through other types. */
 function typesUsedBy(schema, types) {
-  const used = /* @__PURE__ */ new Map();
-  const collect = (node) => visitObjects(node, (inner) => {
-    const name = typeof inner.$ref === "string" ? REFERENCE.exec(inner.$ref)?.[1] : void 0;
-    const type = name === void 0 ? void 0 : types[name];
-    if (name !== void 0 && type !== void 0 && !used.has(name)) {
-      used.set(name, type);
-      collect(type);
-    }
-  });
-  collect(schema);
-  return used;
+	const used = /* @__PURE__ */ new Map();
+	const collect = (node) => visitObjects(node, (inner) => {
+		const name = typeof inner.$ref === "string" ? REFERENCE.exec(inner.$ref)?.[1] : void 0;
+		const type = name === void 0 ? void 0 : types[name];
+		if (name !== void 0 && type !== void 0 && !used.has(name)) {
+			used.set(name, type);
+			collect(type);
+		}
+	});
+	collect(schema);
+	return used;
 }
+/** Bundle a schema (spec/catalog.md#bundling). */
 function bundle(schema, types) {
-  const only = Object.keys(schema).length === 1 ? REFERENCE.exec(String(schema.$ref))?.[1] : void 0;
-  const base = only === void 0 ? schema : types[only] ?? schema;
-  const used = typesUsedBy(base, types);
-  return used.size === 0 ? base : { ...base, $defs: Object.fromEntries(used) };
+	const only = Object.keys(schema).length === 1 ? REFERENCE.exec(String(schema.$ref))?.[1] : void 0;
+	const base = only === void 0 ? schema : types[only] ?? schema;
+	const used = typesUsedBy(base, types);
+	return used.size === 0 ? base : {
+		...base,
+		$defs: Object.fromEntries(used)
+	};
 }
+/** The view of a target (spec/catalog.md#views). */
 function viewOf(catalog, target) {
-  const types = catalog.$defs ?? {};
-  const capabilities = Object.fromEntries(
-    Object.entries(catalog.capabilities).filter(([, capability]) => (capability.audience ?? []).includes(target)).map(([id, capability]) => [id, { ...capability, audience: [target] }])
-  );
-  const used = /* @__PURE__ */ new Map();
-  for (const capability of Object.values(capabilities)) {
-    for (const [, schema] of schemasOf(capability)) for (const [name, type] of typesUsedBy(schema, types)) used.set(name, type);
-  }
-  const { $defs: _, ...rest } = catalog;
-  const declared = catalog.targets[target];
-  return {
-    ...rest,
-    targets: declared === void 0 ? {} : { [target]: declared },
-    ...used.size > 0 ? { $defs: Object.fromEntries(used) } : {},
-    capabilities
-  };
+	const types = catalog.$defs ?? {};
+	const capabilities = Object.fromEntries(Object.entries(catalog.capabilities).filter(([, capability]) => (capability.audience ?? []).includes(target)).map(([id, capability]) => [id, {
+		...capability,
+		audience: [target]
+	}]));
+	const used = /* @__PURE__ */ new Map();
+	for (const capability of Object.values(capabilities)) for (const [, schema] of schemasOf(capability)) for (const [name, type] of typesUsedBy(schema, types)) used.set(name, type);
+	const { $defs: _, ...rest } = catalog;
+	const declared = catalog.targets[target];
+	return {
+		...rest,
+		targets: declared === void 0 ? {} : { [target]: declared },
+		...used.size > 0 ? { $defs: Object.fromEntries(used) } : {},
+		capabilities
+	};
 }
-export {
-  AVAILABLE,
-  CALL_FAILURE_KINDS,
-  CLI_EXIT_CODES,
-  CallFailureError,
-  HTTP_STATUS,
-  ID_PATTERN,
-  MCP_PROTOCOL_VERSION,
-  MCP_REJECTIONS,
-  MCP_UNKNOWN_TOOL,
-  REFERENCE,
-  bundle,
-  callFailure,
-  cliExitCode,
-  commandPath,
-  fail,
-  httpStatus,
-  isCallFailure,
-  isId,
-  mcpToolResult,
-  ok,
-  readBounded,
-  schemasOf,
-  screenRequest,
-  typesUsedBy,
-  unavailable,
-  viewOf,
-  visitObjects
-};
+//#endregion
+export { AVAILABLE, CALL_FAILURE_KINDS, CLI_EXIT_CODES, CallFailureError, HTTP_STATUS, ID_PATTERN, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, REFERENCE, bundle, callFailure, cliExitCode, cliFlags, cliUsage, commandPath, fail, httpStatus, isCallFailure, isId, mcpToolResult, ok, readBounded, schemasOf, screenRequest, typesUsedBy, unavailable, viewOf, visitObjects };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/spec-ts",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The fixed details of the AcidCat specification as TypeScript data and pure functions, with no dependencies. Part of the TypeScript reference implementation.",
   "keywords": [
     "acidcat",