@acid-cat/cli 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,56 @@
-# Temporary Holding Version
+# @acid-cat/cli
 
-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 command line. npm package: `@acid-cat/cli`. It gives the `acid-cat` command. Use it at build time, in CI or by hand, to check catalogs and to test implementations. Do not use it in an application at run time.
+
+```sh
+acid-cat check [--strict] <catalog.json ...>  # check catalogs
+acid-cat format [--write] <catalog.json ...>  # write catalogs in canonical form
+acid-cat view <catalog.json> <target>         # write the view of one target
+acid-cat conform --mcp <url> --http <url> --cli "<command>" --webmcp <url>  # test an implementation
+```
+
+Install it as a development dependency, and run it with `pnpm exec acid-cat …`:
+
+```sh
+pnpm add -D @acid-cat/cli
+```
+
+It needs Node.js 24 or later. `acid-cat conform --webmcp <url>` also needs [Playwright](https://playwright.dev) and Chromium.
+
+## check
+
+`check` tests a catalog against [`schemas/catalog.schema.json`](../../schemas/catalog.schema.json) and against the [catalog rules](../../spec/conformance.md#catalog) that the schema cannot express.
+
+- An **error** is a broken rule. Example: an audience that names an unknown target.
+- A **warning** is a broken recommendation. Examples: a file that is not in [canonical form](../../spec/catalog.md#canonical-form), or a member with no `x-` prefix.
+
+The exit code is 0 if there are no errors. It is 1 if there are errors. With `--strict`, warnings also give the exit code 1.
+
+## format
+
+`format` writes a catalog in canonical form. Use it for catalogs that a catalog library did not write: Pkl output, generated files, or files that you edit by hand.
+
+## conform
+
+`conform` tests a running implementation of the [conformance fixture](conformance/fixture.pkl) through its bindings (see [Conformance](../../spec/conformance.md#acid-cat-conform)):
+
+- **MCP:** the official MCP client, with revision `2026-07-28`, for tools and outcomes; raw requests for rejections.
+- **HTTP** and **CLI:** each outcome, each kind of call failure, availability, and rejections. For the CLI, an interrupt (`SIGINT`) during a call gives exit code 130.
+- **WebMCP:** the checks act as the WebMCP host. `--webmcp <url>` opens a page that serves the `app` target in Chromium, through [Playwright](https://playwright.dev), with a test `modelContext`. Install Playwright to use it: `pnpm add -D playwright`, then `pnpm exec playwright install chromium`. In code, `webmcp` can also be a function that installs the implementation on a host in the same process.
+- **Properties:** with fast-check, through each remote binding: concurrent calls each get exactly their own outcome, and a cancellation changes only its own call.
+
+The exit code is 1 if a check fails. Both AcidCat cores run `conform` in their tests. In code, use `conform()` and `serve()` from `@acid-cat/cli`. `createTestHost()` gives the WebMCP host of the checks.
+
+## Implementation
+
+The command line is an [Effect](https://effect.website) program that uses `effect/cli`. It validates catalogs with Effect Schema. It imports `schemas/catalog.schema.json` and each schema in the catalog as Effect schemas.
+
+| File | Contents |
+| --- | --- |
+| `src/catalog.ts` | The catalog rules, views and bundling |
+| `src/main.ts` | The commands |
+| `src/conform/` | The conformance checks, and `serve`, which serves web handlers on a local port |
+| `conformance/` | The conformance fixture, in Pkl and in JSON |
+| `test/` | Tests. Run them with `moon run cli:test` |
+
+The canonical writer comes from [`@acid-cat/catalog`](../catalog/typescript).

package/conformance/fixture.acidcat.json

@@ -0,0 +1,152 @@
+{
+  "acidcat": "0.1",
+  "title": "AcidCat conformance fixture",
+  "targets": {
+    "api": {
+      "bindings": [
+        "http"
+      ]
+    },
+    "app": {
+      "bindings": [
+        "typescript",
+        "webmcp"
+      ]
+    },
+    "cli": {
+      "bindings": [
+        "cli"
+      ]
+    },
+    "mcp": {
+      "bindings": [
+        "mcp"
+      ]
+    }
+  },
+  "capabilities": {
+    "fixture.crash": {
+      "description": "Always fail with a defect.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ]
+    },
+    "fixture.echo": {
+      "description": "Return the input text.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "input": {
+        "properties": {
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "text"
+        ],
+        "type": "object"
+      },
+      "output": {
+        "properties": {
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "text"
+        ],
+        "type": "object"
+      },
+      "readOnly": true
+    },
+    "fixture.hidden": {
+      "description": "Only the app target can use this capability.",
+      "audience": [
+        "app"
+      ]
+    },
+    "fixture.refuse": {
+      "description": "Always return the failure Refused.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "failures": {
+        "Refused": {
+          "properties": {
+            "_tag": {
+              "const": "Refused",
+              "type": "string"
+            },
+            "reason": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "_tag",
+            "reason"
+          ],
+          "type": "object"
+        }
+      }
+    },
+    "fixture.slow": {
+      "description": "Wait for some milliseconds, then return null.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "input": {
+        "properties": {
+          "milliseconds": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "milliseconds"
+        ],
+        "type": "object"
+      }
+    },
+    "fixture.switch.set": {
+      "description": "Turn the switch on or off. The switch controls the availability of fixture.toggle.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ],
+      "input": {
+        "properties": {
+          "on": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "on"
+        ],
+        "type": "object"
+      }
+    },
+    "fixture.toggle": {
+      "description": "Available only while the switch is on.",
+      "audience": [
+        "app",
+        "mcp",
+        "cli",
+        "api"
+      ]
+    }
+  }
+}

package/dist/catalog.d.ts

@@ -0,0 +1,11 @@
+import { bundle, viewOf } from "@acid-cat/spec-ts";
+import type { CatalogDocument as Catalog } from "@acid-cat/spec-ts";
+export { bundle, viewOf };
+export type { Catalog };
+/** The result of a check. An error breaks a rule. A warning breaks a recommendation. */
+export interface Report {
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+}
+/** Check a catalog. When `text` is given, the file must also be in canonical form. */
+export declare function check(document: unknown, text?: string): Report;