@acid-cat/spec-ts 0.2.0 → 0.3.1

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

@@ -60,6 +60,41 @@ const CLI_EXIT_CODES = {
 	cancelled: 130
 };
 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,
@@ -211,4 +246,4 @@ function viewOf(catalog, target) {
 	};
 }
 //#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, commandPath, fail, httpStatus, isCallFailure, isId, mcpToolResult, ok, readBounded, schemasOf, screenRequest, typesUsedBy, unavailable, viewOf, visitObjects };
+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.2.0",
+  "version": "0.3.1",
   "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",