@acid-cat/catalog 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hebilicious
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @acid-cat/catalog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The AcidCat catalog library for TypeScript. npm package: `@acid-cat/catalog`.
+
+Write a catalog in TypeScript, and write it in canonical form. The library has no dependencies. Use it at build time to write `acidcat.catalog.json`.
+
+```sh
+pnpm add -D @acid-cat/catalog
+```
+
+```ts
+import { Catalog } from "@acid-cat/catalog";
+
+const catalog = new Catalog({ title: "Living-room air conditioner" });
+catalog.target("cli", { bindings: ["cli"] });
+const offline = catalog.type("Offline", { type: "object" });
+catalog.capability("aircon.power.set", {
+  description: "Turn the unit on or off.",
+  audience: ["cli"],
+  input: { type: "object", required: ["on"], properties: { on: { type: "boolean" } } },
+  failures: { Offline: offline },
+});
+
+await writeFile("acidcat.catalog.json", catalog.render());
+```
+
+`validate()` lists the rules a catalog breaks, and `render()` refuses to render one that breaks any. The full example is [`examples/aircon.ts`](examples/aircon.ts). Test with `moon run catalog-typescript:test`.

package/dist/canonical.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The canonical form of a catalog (spec/catalog.md#canonical-form): the one way to write a catalog as text, so that
+ * every tool and every catalog library produces the same bytes for the same catalog.
+ */
+type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [key: string]: Json;
+};
+type JsonObject = {
+    readonly [key: string]: Json;
+};
+/** A catalog in canonical form, as text. */
+export declare function canonicalText(catalog: unknown): string;
+/** Put a catalog's members in canonical order. */
+export declare function canonicalCatalog(catalog: JsonObject): JsonObject;
+/** Order strings by Unicode code point, as Python, Go and Rust compare them. */
+export declare function byCodePoint(left: string, right: string): number;
+export {};

package/dist/canonical.js

@@ -0,0 +1,84 @@
+//#region src/canonical.ts
+const CATALOG_ORDER = [
+	"acidcat",
+	"title",
+	"description",
+	"targets",
+	"$defs",
+	"capabilities"
+];
+const TARGET_ORDER = [
+	"bindings",
+	"description",
+	"options"
+];
+const CAPABILITY_ORDER = [
+	"description",
+	"audience",
+	"input",
+	"output",
+	"failures",
+	"readOnly",
+	"state"
+];
+/** A catalog in canonical form, as text. */
+function canonicalText(catalog) {
+	return `${write(canonicalCatalog(catalog), "")}\n`;
+}
+/** Put a catalog's members in canonical order. */
+function canonicalCatalog(catalog) {
+	return ordered(catalog, CATALOG_ORDER, (key, value) => {
+		if (key === "targets") return byKey(value, (target) => ordered(target, TARGET_ORDER, sortedMember));
+		if (key === "$defs") return byKey(value, sorted);
+		if (key === "capabilities") return byKey(value, (capability) => ordered(capability, CAPABILITY_ORDER, (member, inner) => member === "failures" ? byKey(inner, sorted) : sortedMember(member, inner)));
+		return sortedMember(key, value);
+	});
+}
+/** The known members in their order, then every other member sorted by key. */
+function ordered(value, order, each) {
+	const known = order.filter((key) => key in value);
+	const others = Object.keys(value).filter((key) => !order.includes(key)).sort(byCodePoint);
+	return Object.fromEntries([...known, ...others].map((key) => [key, each(key, value[key])]));
+}
+/** A map keyed by name or id: its keys sorted, each value shaped by `each`. */
+function byKey(value, each) {
+	const object = value;
+	return Object.fromEntries(Object.keys(object).sort(byCodePoint).map((key) => [key, each(object[key])]));
+}
+function sortedMember(_key, value) {
+	return sorted(value);
+}
+/** Every object's keys sorted, at every depth. Arrays keep their order. */
+function sorted(value) {
+	if (Array.isArray(value)) return value.map(sorted);
+	if (value !== null && typeof value === "object") return byKey(value, sorted);
+	return value;
+}
+/** Order strings by Unicode code point, as Python, Go and Rust compare them. */
+function byCodePoint(left, right) {
+	const a = [...left];
+	const b = [...right];
+	for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+		const difference = a[i].codePointAt(0) - b[i].codePointAt(0);
+		if (difference !== 0) return difference;
+	}
+	return a.length - b.length;
+}
+/** Write a JSON value with two-space indentation, one member or item per line. */
+function write(value, indent) {
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		const inner = `${indent}  `;
+		return `[\n${value.map((item) => inner + write(item, inner)).join(",\n")}\n${indent}]`;
+	}
+	if (value !== null && typeof value === "object") {
+		const keys = Object.keys(value);
+		if (keys.length === 0) return "{}";
+		const inner = `${indent}  `;
+		return `{\n${keys.map((key) => `${inner}${JSON.stringify(key)}: ${write(value[key], inner)}`).join(",\n")}\n${indent}}`;
+	}
+	if (typeof value === "number" && !Number.isFinite(value)) throw new TypeError("A catalog holds only finite numbers");
+	return JSON.stringify(value);
+}
+//#endregion
+export { byCodePoint, canonicalCatalog, canonicalText };

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Write an AcidCat catalog in TypeScript, and render it to the JSON document the toolchain checks.
+ *
+ * This is an authoring library, not a runtime: a program uses it to produce `acidcat.catalog.json`, and nothing
+ * reads the catalog through it at runtime. See spec/catalog.md.
+ */
+export { canonicalText } from "./canonical.js";
+/** A JSON Schema 2020-12 schema, written as a plain object. */
+export type Schema = {
+    readonly [keyword: string]: unknown;
+};
+export interface TargetOptions {
+    /** The bindings that serve the target, such as `"typescript"` and `"webmcp"`. */
+    readonly bindings: readonly string[];
+    readonly description?: string;
+    /** Settings for the bindings, in a form each binding defines. */
+    readonly options?: Schema;
+}
+export interface CapabilityOptions {
+    /** What the capability does for its caller, written for people and agents. */
+    readonly description: string;
+    /** The targets the capability is offered to. Empty means no target. */
+    readonly audience?: readonly string[];
+    /** The input schema. It must describe an object. Absent means an empty object. */
+    readonly input?: Schema;
+    /** The schema of a successful call's value. Absent means `null`. */
+    readonly output?: Schema;
+    /** The failures, keyed by tag. */
+    readonly failures?: Readonly<Record<string, Schema>>;
+    /** `true` when a call changes nothing anyone can observe. A hint for clients. */
+    readonly readOnly?: boolean;
+    /** The schema of a value that clients can observe. */
+    readonly state?: Schema;
+}
+export declare class Catalog {
+    #private;
+    constructor(options?: {
+        readonly title?: string;
+        readonly description?: string;
+    });
+    /** Declare a target. */
+    target(name: string, options: TargetOptions): this;
+    /** Declare a shared type, and get the schema that references it. */
+    type(name: string, schema: Schema): Schema;
+    /** Declare a capability. */
+    capability(id: string, options: CapabilityOptions): this;
+    /** The catalog rules this catalog breaks. Empty when it conforms. */
+    validate(): string[];
+    /** The catalog as a JSON value. Throws when the catalog breaks a rule. */
+    toJSON(): Schema;
+    /** The catalog as JSON text in canonical form, ready to write to `acidcat.catalog.json`. */
+    render(): string;
+}

package/dist/index.js

@@ -0,0 +1,126 @@
+import { canonicalText } from "./canonical.js";
+//#region src/index.ts
+/**
+* Write an AcidCat catalog in TypeScript, and render it to the JSON document the toolchain checks.
+*
+* This is an authoring library, not a runtime: a program uses it to produce `acidcat.catalog.json`, and nothing
+* reads the catalog through it at runtime. See spec/catalog.md.
+*/
+const ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*)+$/;
+const NAME = /^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$/;
+const TYPE_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+const REFERENCE = /^#\/\$defs\/([A-Za-z][A-Za-z0-9_]*)$/;
+var Catalog = class {
+	#title;
+	#description;
+	#targets = /* @__PURE__ */ new Map();
+	#types = /* @__PURE__ */ new Map();
+	#capabilities = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.#title = options.title;
+		this.#description = options.description;
+	}
+	/** Declare a target. */
+	target(name, options) {
+		if (this.#targets.has(name)) throw new Error(`The target ${name} is declared twice`);
+		this.#targets.set(name, options);
+		return this;
+	}
+	/** Declare a shared type, and get the schema that references it. */
+	type(name, schema) {
+		if (this.#types.has(name)) throw new Error(`The type ${name} is declared twice`);
+		this.#types.set(name, schema);
+		return { $ref: `#/$defs/${name}` };
+	}
+	/** Declare a capability. */
+	capability(id, options) {
+		if (this.#capabilities.has(id)) throw new Error(`The capability ${id} is declared twice`);
+		this.#capabilities.set(id, options);
+		return this;
+	}
+	/** The catalog rules this catalog breaks. Empty when it conforms. */
+	validate() {
+		const problems = [];
+		for (const [name, target] of this.#targets) {
+			if (!NAME.test(name)) problems.push(`the target name ${name} is malformed`);
+			if (target.bindings.length === 0) problems.push(`the target ${name} has no bindings`);
+			if (new Set(target.bindings).size !== target.bindings.length) problems.push(`the target ${name} repeats a binding`);
+			for (const binding of target.bindings) if (!NAME.test(binding)) problems.push(`the target ${name} names the malformed binding ${binding}`);
+		}
+		for (const [name, schema] of this.#types) {
+			if (!TYPE_NAME.test(name)) problems.push(`the type name ${name} is malformed`);
+			problems.push(...this.#referenceProblems(schema).map((problem) => `the type ${name} ${problem}`));
+		}
+		for (const [id, capability] of this.#capabilities) {
+			if (id.length > 128 || !ID.test(id)) problems.push(`the id ${id} is malformed`);
+			if (capability.description.trim() === "") problems.push(`${id} has no description`);
+			const audience = capability.audience ?? [];
+			if (new Set(audience).size !== audience.length) problems.push(`${id} repeats a target in its audience`);
+			for (const target of audience) if (!this.#targets.has(target)) problems.push(`${id} names the undeclared target ${target}`);
+			if (capability.input !== void 0 && this.#resolve(capability.input).type !== "object") problems.push(`${id} input does not describe an object`);
+			const schemas = [
+				capability.input,
+				capability.output,
+				capability.state,
+				...Object.values(capability.failures ?? {})
+			];
+			for (const schema of schemas) if (schema !== void 0) problems.push(...this.#referenceProblems(schema).map((problem) => `${id} ${problem}`));
+		}
+		return problems;
+	}
+	/** The catalog as a JSON value. Throws when the catalog breaks a rule. */
+	toJSON() {
+		const problems = this.validate();
+		if (problems.length > 0) throw new Error(`The catalog does not conform:\n${problems.join("\n")}`);
+		return compact({
+			acidcat: "0.1",
+			title: this.#title,
+			description: this.#description,
+			targets: Object.fromEntries([...this.#targets].map(([name, target]) => [name, compact({
+				bindings: target.bindings,
+				description: target.description,
+				options: target.options
+			})])),
+			$defs: this.#types.size === 0 ? void 0 : Object.fromEntries(this.#types),
+			capabilities: Object.fromEntries([...this.#capabilities].map(([id, capability]) => [id, compact({
+				description: capability.description,
+				audience: capability.audience ?? [],
+				input: capability.input,
+				output: capability.output,
+				failures: Object.keys(capability.failures ?? {}).length === 0 ? void 0 : capability.failures,
+				readOnly: capability.readOnly,
+				state: capability.state
+			})]))
+		});
+	}
+	/** The catalog as JSON text in canonical form, ready to write to `acidcat.catalog.json`. */
+	render() {
+		return canonicalText(this.toJSON());
+	}
+	#resolve(schema) {
+		const name = typeof schema.$ref === "string" ? REFERENCE.exec(schema.$ref)?.[1] : void 0;
+		return name === void 0 ? schema : this.#types.get(name) ?? schema;
+	}
+	#referenceProblems(schema) {
+		const problems = [];
+		visit(schema, (node) => {
+			if ("$defs" in node) problems.push("carries its own $defs; declare shared types with type()");
+			if (node.$ref === void 0) return;
+			const name = typeof node.$ref === "string" ? REFERENCE.exec(node.$ref)?.[1] : void 0;
+			if (name === void 0 || !this.#types.has(name)) problems.push(`references ${String(node.$ref)}, which is not a type`);
+		});
+		return problems;
+	}
+};
+function compact(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, member]) => member !== void 0));
+}
+function visit(value, onObject) {
+	if (Array.isArray(value)) value.forEach((item) => visit(item, onObject));
+	else if (value !== null && typeof value === "object") {
+		onObject(value);
+		Object.values(value).forEach((item) => visit(item, onObject));
+	}
+}
+//#endregion
+export { Catalog, canonicalText };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@acid-cat/catalog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Write an AcidCat catalog in TypeScript and render it in canonical form.",
+  "keywords": [
+    "acidcat",
+    "catalog"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hebilicious/acidcat.git",
+    "directory": "packages/catalog/typescript"
+  },
+  "homepage": "https://github.com/Hebilicious/acidcat/tree/main/packages/catalog/typescript#readme",
+  "bugs": "https://github.com/Hebilicious/acidcat/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2"
+  }
 }