@acid-cat/cli 0.0.0-stage → 0.1.0

package/dist/conform/check.d.ts

@@ -0,0 +1,28 @@
+import type { CatalogDocument } from "@acid-cat/spec-ts";
+export interface Check {
+    readonly binding: string;
+    readonly name: string;
+    /** The part of the specification that the check tests, for example `spec/bindings/mcp.md#tools`. */
+    readonly rule: string;
+    readonly passed: boolean;
+    readonly detail?: string | undefined;
+}
+/** The conformance fixture: the catalog that each implementation serves. */
+export declare const fixture: CatalogDocument;
+/** The ids of the capabilities in the view of a target of the fixture. */
+export declare const idsOf: (target: string) => string[];
+/** Collects checks for one binding. */
+export declare class Checks {
+    readonly results: Check[];
+    readonly binding: string;
+    constructor(binding: string);
+    run(name: string, rule: string, body: () => Promise<void> | void): Promise<void>;
+}
+/** Fail a check unless `condition` is true. */
+export declare function expect(condition: unknown, message: string): asserts condition;
+/** Fail a check unless the two values have the same JSON. */
+export declare function expectEqual(actual: unknown, expected: unknown, what: string): void;
+/** A sorted copy of a list. */
+export declare const sorted: (values: Iterable<string>) => string[];
+/** An origin that no deployment allows. */
+export declare const FORBIDDEN_ORIGIN = "https://not-allowed.acid-cat.invalid";

package/dist/conform/cli.d.ts

@@ -0,0 +1,2 @@
+import { Checks } from "./check.js";
+export declare function checkCli(command: readonly string[]): Promise<Checks>;

package/dist/conform/http.d.ts

@@ -0,0 +1,5 @@
+/** 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;
+}): Promise<Checks>;

package/dist/conform/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `acid-cat conform`: test a running implementation through its bindings (spec/conformance.md). The implementation
+ * serves the conformance fixture (conformance/fixture.acidcat.json), with its switch on.
+ */
+import type { Check } from "./check.js";
+import type { WebMcpInstall } from "./webmcp.js";
+export type { Check } from "./check.js";
+export { fixture } from "./check.js";
+export { serve } from "./serve.js";
+export type { Served, WebHandler } from "./serve.js";
+export { createTestHost } from "./webmcp.js";
+export type { TestHost, WebMcpInstall } from "./webmcp.js";
+export interface ConformOptions {
+    /** The URL of the MCP server, for example `http://localhost:8787/mcp`. */
+    readonly mcp?: string | undefined;
+    /** The base URL of the HTTP API, before `/capabilities`. */
+    readonly http?: string | undefined;
+    /** The command that starts the command line, for example `["node", "fixture-cli.ts"]`. */
+    readonly cli?: readonly string[] | undefined;
+    /**
+     * The WebMCP binding: the URL of a page that serves the `app` target, or a function that installs the implementation
+     * on a host in the same process. A page runs in Chromium, through Playwright.
+     */
+    readonly webmcp?: string | WebMcpInstall | undefined;
+    /** The body limit of the remote bindings, in bytes. The default is 1 MiB. */
+    readonly maximumBytes?: number | undefined;
+}
+/** Run all checks for the bindings that the options give. */
+export declare function conform(options: ConformOptions): Promise<readonly Check[]>;

package/dist/conform/mcp.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Conformance checks for the MCP binding (spec/bindings/mcp.md). The protocol checks use the official MCP client,
+ * with revision 2026-07-28. The rejection checks send requests that a client never sends.
+ */
+import { Client } from "@modelcontextprotocol/client";
+import { Checks } from "./check.js";
+/** A connected MCP client. */
+export declare function mcpClient(url: string): Promise<Client>;
+export declare function checkMcp(url: string, options: {
+    readonly maximumBytes: number;
+}): Promise<Checks>;

package/dist/conform/properties.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Property-based checks for the guarantees of spec/invocation.md#cancellation-and-concurrency, through each remote
+ * binding. fast-check makes random sets of concurrent calls and cancellations.
+ */
+import type { Outcome } from "@acid-cat/spec-ts";
+import { Checks } from "./check.js";
+/** A call through one binding. A cancelled call can reject. */
+export type Invoke = (id: string, input: object, signal?: AbortSignal) => Promise<Outcome<unknown, unknown>>;
+export declare function httpInvoke(base: string): Invoke;
+export declare function mcpInvoke(url: string): Promise<{
+    readonly invoke: Invoke;
+    close(): Promise<void>;
+}>;
+export declare function checkProperties(binding: string, invoke: Invoke): Promise<Checks>;

package/dist/conform/serve.d.ts

@@ -0,0 +1,10 @@
+export interface Served {
+    /** The base URL, for example `http://127.0.0.1:40123`. */
+    readonly url: string;
+    close(): Promise<void>;
+}
+export type WebHandler = (request: Request) => Promise<Response>;
+/** Serve handlers by path prefix, for example `{ "/mcp": mcp, "/api": http }`. */
+export declare function serve(routes: {
+    readonly [prefix: string]: WebHandler;
+}): Promise<Served>;

package/dist/conform/webmcp.d.ts

@@ -0,0 +1,51 @@
+import { Checks } from "./check.js";
+/** A tool as the host records it. */
+export interface RecordedTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: 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;
+} | {
+    readonly rejected: {
+        readonly name: string;
+        readonly kind: unknown;
+        readonly message: string;
+    };
+} | {
+    readonly missing: true;
+};
+/** The host that the checks give to the page. */
+export interface TestHost {
+    readonly modelContext: {
+        registerTool(tool: object, options: {
+            readonly signal: AbortSignal;
+        }): void;
+    };
+    tools(): RecordedTool[];
+    /** Call a tool. If `cancelAfter` is given, abort the signal of the call after that many milliseconds. */
+    call(name: string, input: unknown, cancelAfter?: number): Promise<ToolCall>;
+}
+/**
+ * Make a test host. The function uses no imports and no outer variables, because the browser driver sends its
+ * source text to the page.
+ */
+export declare function createTestHost(): TestHost;
+/** The view from the checks: the tools of the page, and calls to them. */
+export interface WebMcpDriver {
+    tools(): Promise<RecordedTool[]>;
+    call(name: string, input: unknown, cancelAfter?: number): Promise<ToolCall>;
+    close(): Promise<void>;
+}
+/**
+ * Install the implementation on a host in the same process. Return a function that removes it, or nothing. The
+ * implementation serves the `app` target of the fixture, with its switch on.
+ */
+export type WebMcpInstall = (modelContext: TestHost["modelContext"]) => void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+/** A driver for an implementation in the same process. Values pass through JSON, as they do from a page. */
+export declare function processDriver(install: WebMcpInstall): Promise<WebMcpDriver>;
+/** A driver for a page in Chromium, through Playwright. The page loads with the test host as its `modelContext`. */
+export declare function browserDriver(url: string): Promise<WebMcpDriver>;
+export declare function checkWebMcp(driver: WebMcpDriver): Promise<Checks>;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/** The library of `@acid-cat/cli`: catalog checks, and the conformance tests. */
+export { bundle, check, viewOf } from "./catalog.js";
+export type { Catalog, Report } from "./catalog.js";
+export { conform, fixture, serve } from "./conform/index.js";
+export type { Check, ConformOptions, Served, WebHandler } from "./conform/index.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+import {
+  bundle,
+  check,
+  conform,
+  fixture,
+  serve,
+  viewOf
+} from "./chunks/chunk-VZ6KDZEL.js";
+export {
+  bundle,
+  check,
+  conform,
+  fixture,
+  serve,
+  viewOf
+};

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import {
+  check,
+  conform,
+  viewOf
+} from "./chunks/chunk-VZ6KDZEL.js";
+
+// src/main.ts
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { canonicalText } from "@acid-cat/catalog";
+import { Console, Effect, FileSystem, Option } from "effect";
+import { Argument, Command, Flag } from "effect/cli";
+
+// package.json
+var package_default = {
+  name: "@acid-cat/cli",
+  version: "0.1.0",
+  description: "The AcidCat command line: check, format and view catalogs, and test implementations.",
+  keywords: [
+    "acidcat",
+    "cli",
+    "conformance"
+  ],
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/Hebilicious/acidcat.git",
+    directory: "packages/cli"
+  },
+  homepage: "https://github.com/Hebilicious/acidcat/tree/main/packages/cli#readme",
+  bugs: "https://github.com/Hebilicious/acidcat/issues",
+  type: "module",
+  engines: {
+    node: ">=24"
+  },
+  files: [
+    "dist",
+    "conformance/fixture.acidcat.json"
+  ],
+  bin: {
+    "acid-cat": "./src/main.ts"
+  },
+  exports: {
+    ".": "./src/index.ts",
+    "./conformance/fixture.acidcat.json": "./conformance/fixture.acidcat.json"
+  },
+  publishConfig: {
+    access: "public",
+    exports: {
+      ".": {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js"
+      },
+      "./conformance/fixture.acidcat.json": "./conformance/fixture.acidcat.json"
+    },
+    bin: {
+      "acid-cat": "./dist/main.js"
+    }
+  },
+  dependencies: {
+    "@acid-cat/catalog": "workspace:*",
+    "@acid-cat/spec-ts": "workspace:*",
+    "@effect/platform-node": "catalog:",
+    "@modelcontextprotocol/client": "catalog:",
+    effect: "catalog:",
+    "fast-check": "catalog:"
+  },
+  peerDependencies: {
+    playwright: "catalog:peers"
+  },
+  peerDependenciesMeta: {
+    playwright: {
+      optional: true
+    }
+  },
+  devDependencies: {
+    "@types/node": "catalog:",
+    playwright: "catalog:",
+    typescript: "catalog:"
+  }
+};
+
+// src/main.ts
+var readCatalog = Effect.fn("readCatalog")(function* (file) {
+  const fs = yield* FileSystem.FileSystem;
+  const text = yield* fs.readFileString(file);
+  return { text, document: JSON.parse(text) };
+});
+var fail = Effect.sync(() => {
+  process.exitCode = 1;
+});
+var files = Argument.String("catalog").pipe(
+  Argument.withDescription("A catalog file, such as acidcat.catalog.json"),
+  Argument.variadic({ min: 1 })
+);
+var checkCommand = Command.make(
+  "check",
+  {
+    files,
+    strict: Flag.Boolean("strict").pipe(Flag.withDescription("Fail on warnings too"), Flag.withDefault(false))
+  },
+  Effect.fn(function* ({ files: files2, strict }) {
+    let failed = false;
+    for (const file of files2) {
+      const { text, document } = yield* readCatalog(file);
+      const report = check(document, text);
+      for (const error of report.errors) yield* Console.error(`${file}: error: ${error}`);
+      for (const warning of report.warnings) yield* Console.error(`${file}: warning: ${warning}`);
+      failed ||= report.errors.length > 0 || strict && report.warnings.length > 0;
+    }
+    if (failed) return yield* fail;
+    yield* Console.log(files2.length === 1 ? "The catalog conforms." : "Every catalog conforms.");
+  })
+).pipe(Command.withDescription("Check that catalogs conform to the specification."));
+var formatCommand = Command.make(
+  "format",
+  {
+    files,
+    write: Flag.Boolean("write").pipe(Flag.withDescription("Rewrite each file instead of printing it"), Flag.withDefault(false))
+  },
+  Effect.fn(function* ({ files: files2, write }) {
+    const fs = yield* FileSystem.FileSystem;
+    for (const file of files2) {
+      const { document } = yield* readCatalog(file);
+      const text = canonicalText(document);
+      if (write) yield* fs.writeFileString(file, text);
+      else yield* Effect.sync(() => process.stdout.write(text));
+    }
+  })
+).pipe(Command.withDescription("Write catalogs in canonical form."));
+var 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;
+    if (!(target in catalog.targets)) {
+      yield* Console.error(`${file}: error: there is no target ${target}`);
+      return yield* fail;
+    }
+    yield* Effect.sync(() => process.stdout.write(canonicalText(viewOf(catalog, target))));
+  })
+).pipe(Command.withDescription("Print the view of one target."));
+var url = (name, description) => Flag.String(name).pipe(Flag.withDescription(description), Flag.optional);
+var conformCommand = Command.make(
+  "conform",
+  {
+    mcp: url("mcp", "The URL of the MCP server"),
+    http: url("http", "The base URL of the HTTP API, before /capabilities"),
+    cli: url("cli", 'The command that starts the command line, for example "node fixture-cli.ts"'),
+    webmcp: url("webmcp", "The URL of a web page that serves the app target. It runs in Chromium, through Playwright"),
+    maximumBytes: Flag.Int("max-bytes").pipe(Flag.withDescription("The body limit of the remote bindings"), Flag.withDefault(1048576))
+  },
+  Effect.fn(function* (options) {
+    const value = (option) => Option.isSome(option) ? option.value : void 0;
+    const command = value(options.cli)?.split(/\s+/).filter((word) => word !== "");
+    const results = yield* Effect.promise(
+      () => conform({
+        mcp: value(options.mcp),
+        http: value(options.http),
+        cli: command,
+        webmcp: value(options.webmcp),
+        maximumBytes: options.maximumBytes
+      })
+    );
+    if (results.length === 0) {
+      yield* Console.error("Give at least one binding: --mcp, --http, --cli or --webmcp.");
+      return yield* fail;
+    }
+    for (const result of results) {
+      yield* Console.log(`${result.passed ? "\u2713" : "\u2717"} ${result.binding}: ${result.name} (${result.rule})${result.detail ? `
+    ${result.detail}` : ""}`);
+    }
+    const failed = results.filter((result) => !result.passed).length;
+    yield* Console.log(`
+${results.length - failed} passed, ${failed} failed.`);
+    if (failed > 0) return yield* fail;
+  })
+).pipe(Command.withDescription("Test a running implementation of the conformance fixture through its bindings."));
+var acidCat = Command.make("acid-cat").pipe(
+  Command.withDescription("Check, format and view AcidCat catalogs, and test implementations."),
+  Command.withSubcommands([checkCommand, formatCommand, viewCommand, conformCommand])
+);
+acidCat.pipe(
+  Command.run({ version: package_default.version }),
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain
+);

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@acid-cat/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The AcidCat command line: check, format and view catalogs, and test implementations.",
+  "keywords": [
+    "acidcat",
+    "cli",
+    "conformance"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hebilicious/acidcat.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Hebilicious/acidcat/tree/main/packages/cli#readme",
+  "bugs": "https://github.com/Hebilicious/acidcat/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "conformance/fixture.acidcat.json"
+  ],
+  "bin": {
+    "acid-cat": "./dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./conformance/fixture.acidcat.json": "./conformance/fixture.acidcat.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@acid-cat/catalog": "0.1.0",
+    "@acid-cat/spec-ts": "0.1.0",
+    "@effect/platform-node": "4.0.3",
+    "@modelcontextprotocol/client": "2.3.1",
+    "effect": "4.0.3",
+    "fast-check": "4.10.2"
+  },
+  "peerDependencies": {
+    "playwright": "^1.64.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "playwright": "1.64.0",
+    "typescript": "7.0.2"
+  }
 }