@acid-cat/spec-ts 0.0.0-stage → 0.1.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,20 @@
-# Temporary Holding Version
+# @acid-cat/spec-ts
 
-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 fixed details of the [AcidCat specification](../../spec/README.md), as TypeScript data and pure functions. npm package: `@acid-cat/spec-ts`. It has no dependencies.
+
+This package is part of the TypeScript reference implementation. [`@acid-cat/core-effect`](../core-effect) and [`@acid-cat/core-ts`](../core-ts) use it, so that both cores agree on each detail. An implementation in another language does not use it.
+
+```sh
+pnpm add @acid-cat/spec-ts
+```
+
+## Contents
+
+| Export | Use |
+| --- | --- |
+| `ok`, `fail`, `callFailure`, `isCallFailure` | Make and test [outcomes](../../spec/invocation.md#outcomes) |
+| `CALL_FAILURE_KINDS`, `CallFailureError` | The kinds of call failure, and the JavaScript error for one |
+| `AVAILABLE`, `unavailable` | Make [availability](../../spec/invocation.md#availability) values |
+| `viewOf`, `bundle` | The [view](../../spec/catalog.md#views) of a target, and a schema with its shared types |
+
+The other exports give the names, flags, exit codes and tool shapes of each [binding](../../spec/bindings/README.md).

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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. */
+export declare const CALL_FAILURE_KINDS: readonly ["cancelled", "unknown-capability", "unavailable", "invalid-input", "internal"];
+export type CallFailureKind = (typeof CALL_FAILURE_KINDS)[number];
+/** A call that did not give a result. */
+export interface CallFailure {
+    readonly kind: CallFailureKind;
+    readonly message: string;
+}
+/** A value or a failure. */
+export type Result<Value, Failure> = {
+    readonly ok: true;
+    readonly value: Value;
+} | {
+    readonly ok: false;
+    readonly error: Failure;
+};
+/** The end of a call: a value, a failure or a call failure. */
+export type Outcome<Value, Failure> = Result<Value, Failure> | CallFailure;
+export declare const ok: <Value>(value: Value) => Result<Value, never>;
+/** A failure with its tag, as a result. */
+export declare const fail: <Tag extends string, Data extends object = {}>(tag: Tag, data?: Data) => Result<never, {
+    readonly _tag: Tag;
+} & Data>;
+export declare const callFailure: (kind: CallFailureKind, message: string) => CallFailure;
+export declare const isCallFailure: (outcome: Outcome<unknown, unknown>) => outcome is CallFailure;
+/** The JavaScript error for a call failure (spec/bindings/typescript.md#handles). */
+export declare class CallFailureError extends Error {
+    readonly kind: CallFailureKind;
+    constructor(failure: CallFailure);
+}
+export type Availability = {
+    readonly available: true;
+} | {
+    readonly available: false;
+    readonly reason: string;
+};
+export declare const AVAILABLE: Availability;
+export declare const unavailable: (reason: string) => Availability;
+export declare const ID_PATTERN: RegExp;
+export declare const isId: (id: string) => boolean;
+/** The path of the CLI command for an id: `aircon.power.set` → `["aircon", "power", "set"]`. */
+export declare const commandPath: (id: string) => readonly string[];
+export declare const CLI_EXIT_CODES: {
+    readonly value: 0;
+    readonly failure: 1;
+    readonly "unknown-capability": 2;
+    readonly "invalid-input": 3;
+    readonly unavailable: 4;
+    readonly internal: 5;
+    readonly cancelled: 130;
+};
+export declare const cliExitCode: (outcome: Outcome<unknown, unknown>) => number;
+export declare const HTTP_STATUS: {
+    readonly "unknown-capability": 404;
+    readonly "invalid-input": 422;
+    readonly unavailable: 503;
+    readonly cancelled: 409;
+    readonly internal: 500;
+};
+export declare const httpStatus: (outcome: Outcome<unknown, unknown>) => number;
+export type Rejection = "method" | "origin" | "media-type" | "too-large" | "not-utf8";
+/**
+ * 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`.
+ */
+export declare function screenRequest(request: Request, rules: {
+    readonly methods: readonly string[];
+    readonly allowedOrigins: readonly string[];
+    readonly mediaType: string;
+    readonly maximumBytes: number;
+}): Rejection | undefined;
+/** Read a request body as UTF-8 text. Count the bytes as they arrive, and stop at the limit. */
+export declare function readBounded(request: Request, maximumBytes: number): Promise<{
+    readonly text: string;
+} | {
+    readonly rejection: Rejection;
+}>;
+export declare const MCP_PROTOCOL_VERSION = "2026-07-28";
+export declare const MCP_UNKNOWN_TOOL = -32602;
+/** The HTTP status and JSON-RPC error code for each rejected MCP request. */
+export declare const MCP_REJECTIONS: {
+    readonly [R in Rejection]: {
+        readonly status: number;
+        readonly code?: number;
+    };
+};
+export interface McpToolResult {
+    readonly content: readonly [{
+        readonly type: "text";
+        readonly text: string;
+    }];
+    readonly isError?: true;
+    readonly structuredContent?: unknown;
+}
+/** The MCP tool result for an outcome that is not `unknown-capability`. */
+export declare function mcpToolResult(outcome: Outcome<unknown, unknown>, hasOutputSchema: boolean): McpToolResult;
+export type JsonObject = {
+    readonly [key: string]: unknown;
+};
+export interface CatalogCapability extends JsonObject {
+    readonly description: string;
+    readonly audience?: readonly string[];
+    readonly input?: JsonObject;
+    readonly output?: JsonObject;
+    readonly failures?: {
+        readonly [tag: string]: JsonObject;
+    };
+    readonly readOnly?: boolean;
+    readonly state?: JsonObject;
+}
+export interface CatalogDocument extends JsonObject {
+    readonly acidcat: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly targets: {
+        readonly [name: string]: JsonObject & {
+            readonly bindings: readonly string[];
+        };
+    };
+    readonly $defs?: {
+        readonly [name: string]: JsonObject;
+    };
+    readonly capabilities: {
+        readonly [id: string]: CatalogCapability;
+    };
+}
+export declare const REFERENCE: RegExp;
+/** The schemas of a capability, each with the member that holds it. */
+export declare function schemasOf(capability: CatalogCapability): readonly (readonly [string, JsonObject])[];
+/** Every object in a JSON value, at all levels. */
+export declare function visitObjects(value: unknown, onObject: (node: JsonObject) => void): void;
+/** The types that a schema uses, directly or through other types. */
+export declare function typesUsedBy(schema: unknown, types: {
+    readonly [name: string]: JsonObject;
+}): Map<string, JsonObject>;
+/** Bundle a schema (spec/catalog.md#bundling). */
+export declare function bundle(schema: JsonObject, types: {
+    readonly [name: string]: JsonObject;
+}): JsonObject;
+/** The view of a target (spec/catalog.md#views). */
+export declare function viewOf(catalog: CatalogDocument, target: string): CatalogDocument;

package/dist/index.js

@@ -0,0 +1,174 @@
+// 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);
+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";
+  }
+};
+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
+};
+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
+};
+var httpStatus = (outcome) => isCallFailure(outcome) ? HTTP_STATUS[outcome.kind] : 200;
+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;
+}
+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" };
+  }
+}
+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 }
+};
+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) };
+}
+var REFERENCE = /^#\/\$defs\/([A-Za-z][A-Za-z0-9_]*)$/;
+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);
+}
+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));
+  }
+}
+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;
+}
+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) };
+}
+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
+  };
+}
+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
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@acid-cat/spec-ts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.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",
+    "specification"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hebilicious/acidcat.git",
+    "directory": "packages/spec-ts"
+  },
+  "homepage": "https://github.com/Hebilicious/acidcat/tree/main/packages/spec-ts#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"
+  }
 }