@cairn-tool/cli-schema 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan Stockus
+
+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

@@ -0,0 +1,7 @@
+Portable CLI-description types, JSON Schema, validator, usage string, and text renderer. No commander or System.CommandLine dependency.
+
+```js
+import { validate, cliSchema, buildUsage, renderText } from "@cairn-tool/cli-schema";
+```
+
+To walk a live commander tree, install `@cairn-tool/cli-schema-commander`.

package/dist/canonicalize.d.ts

@@ -0,0 +1,3 @@
+/** Drops `tool.version` and rewrites the payload in spec key order. */
+export declare function canonicalize(payload: unknown): unknown;
+export declare function canonicalizeJson(payload: unknown): string;

package/dist/canonicalize.js

@@ -0,0 +1,108 @@
+const OBJECT_KEYS = {
+    envelope: ["schemaVersion", "tool", "formatShorthands", "advisoryOutput", "schemas", "commands"],
+    tool: ["name", "version"],
+    advisoryOutput: ["description", "stream", "suppressedWhen", "optOutEnv"],
+    schemaRef: ["id", "uri", "title", "commands"],
+    command: [
+        "id",
+        "path",
+        "description",
+        "usage",
+        "arguments",
+        "options",
+        "subcommands",
+        "formats",
+        "defaultFormat",
+        "formatConfigurable",
+        "outputSchema",
+        "jsonlSchema",
+        "sarifSchema",
+        "exitCodes",
+        "exitCodePassthrough",
+        "stream",
+        "writes",
+        "stability",
+        "notes",
+    ],
+    argument: ["name", "description", "arity", "valueType", "allowedValues", "default"],
+    option: [
+        "name",
+        "aliases",
+        "description",
+        "valueName",
+        "arity",
+        "required",
+        "negatable",
+        "valueType",
+        "allowedValues",
+        "recursive",
+        "default",
+    ],
+    arity: ["min", "max"],
+    exitCode: ["code", "meaning"],
+    passthrough: ["min", "max", "description"],
+    stream: ["success", "findings"],
+};
+function reorder(value, keys) {
+    const ordered = {};
+    for (const key of keys) {
+        if (Object.prototype.hasOwnProperty.call(value, key))
+            ordered[key] = value[key];
+    }
+    for (const key of Object.keys(value)) {
+        if (!Object.prototype.hasOwnProperty.call(ordered, key))
+            ordered[key] = value[key];
+    }
+    return ordered;
+}
+function walk(value, kind) {
+    if (Array.isArray(value)) {
+        const itemKind = kind === "commands"
+            ? "command"
+            : kind === "arguments"
+                ? "argument"
+                : kind === "options"
+                    ? "option"
+                    : kind === "schemas"
+                        ? "schemaRef"
+                        : kind === "exitCodes"
+                            ? "exitCode"
+                            : "";
+        return value.map((item) => walk(item, itemKind));
+    }
+    if (value === null || typeof value !== "object")
+        return value;
+    const record = value;
+    const keys = OBJECT_KEYS[kind];
+    const ordered = keys ? reorder(record, keys) : record;
+    const next = {};
+    for (const [key, child] of Object.entries(ordered)) {
+        const childKind = key === "tool"
+            ? "tool"
+            : key === "advisoryOutput"
+                ? "advisoryOutput"
+                : key === "arity"
+                    ? "arity"
+                    : key === "exitCodePassthrough"
+                        ? "passthrough"
+                        : key === "stream"
+                            ? "stream"
+                            : key === "formatShorthands"
+                                ? ""
+                                : key;
+        next[key] = walk(child, childKind);
+    }
+    return next;
+}
+/** Drops `tool.version` and rewrites the payload in spec key order. */
+export function canonicalize(payload) {
+    const clone = structuredClone(payload);
+    const tool = clone.tool;
+    if (tool && typeof tool === "object")
+        delete tool.version;
+    return walk(clone, "envelope");
+}
+export function canonicalizeJson(payload) {
+    return JSON.stringify(canonicalize(payload), null, 2) + "\n";
+}
+//# sourceMappingURL=canonicalize.js.map

package/dist/canonicalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize.js","sourceRoot":"","sources":["../src/canonicalize.ts"],"names":[],"mappings":"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"}

package/dist/cli-schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/cairn-tool/cli-schema/v1/cli-schema.json",
+  "title": "CLI contract description",
+  "description": "The static contract of a command-line interface. Project configuration is not applied. Consumers must ignore properties they do not recognize.",
+  "type": "object",
+  "required": ["schemaVersion", "tool", "formatShorthands", "schemas", "commands"],
+  "properties": {
+    "schemaVersion": { "type": "string" },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" }
+      }
+    },
+    "formatShorthands": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "argv token to the --format value it expands to before parsing."
+    },
+    "advisoryOutput": {
+      "type": "object",
+      "description": "Machine-stream guarantees for an advisory notice. Omitted when the tool has none.",
+      "required": ["description", "stream", "suppressedWhen", "optOutEnv"],
+      "properties": {
+        "description": { "type": "string" },
+        "stream": { "enum": ["stdout", "stderr"] },
+        "suppressedWhen": { "type": "array", "items": { "type": "string" } },
+        "optOutEnv": { "type": "string" }
+      }
+    },
+    "schemas": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "uri", "title", "commands"],
+        "properties": {
+          "id": { "type": "string" },
+          "uri": { "type": "string" },
+          "title": { "type": "string" },
+          "commands": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "commands": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/command" }
+    }
+  },
+  "$defs": {
+    "arity": {
+      "type": "object",
+      "required": ["min", "max"],
+      "properties": {
+        "min": { "type": "integer", "minimum": 0 },
+        "max": { "type": ["integer", "null"], "minimum": 0 }
+      }
+    },
+    "valueType": {
+      "type": ["string", "null"],
+      "enum": ["boolean", "string", "integer", "number", null]
+    },
+    "command": {
+      "type": "object",
+      "required": [
+        "id",
+        "path",
+        "description",
+        "usage",
+        "arguments",
+        "options",
+        "subcommands",
+        "formats",
+        "defaultFormat",
+        "formatConfigurable",
+        "outputSchema",
+        "exitCodes",
+        "stream",
+        "writes",
+        "stability"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Space-joined command path, e.g. 'md graph'."
+        },
+        "path": { "type": "array", "items": { "type": "string" } },
+        "description": { "type": "string" },
+        "usage": { "type": "string" },
+        "arguments": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/argument" }
+        },
+        "options": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/option" }
+        },
+        "subcommands": { "type": "array", "items": { "type": "string" } },
+        "formats": { "type": ["array", "null"], "items": { "type": "string" } },
+        "defaultFormat": { "type": ["string", "null"] },
+        "formatConfigurable": { "type": "boolean" },
+        "outputSchema": { "type": ["string", "null"] },
+        "jsonlSchema": { "type": ["string", "null"] },
+        "sarifSchema": { "type": ["string", "null"] },
+        "exitCodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["code", "meaning"],
+            "properties": {
+              "code": { "type": "integer" },
+              "meaning": { "type": "string" }
+            }
+          }
+        },
+        "exitCodePassthrough": {
+          "type": "object",
+          "description": "Present only when the command forwards a child process's exit status verbatim.",
+          "required": ["min", "max", "description"],
+          "properties": {
+            "min": { "type": "integer" },
+            "max": { "type": "integer" },
+            "description": { "type": "string" }
+          }
+        },
+        "stream": {
+          "type": ["object", "null"],
+          "properties": {
+            "success": { "enum": ["stdout", "stderr"] },
+            "findings": { "enum": ["stdout", "stderr"] }
+          }
+        },
+        "writes": { "type": ["boolean", "null"] },
+        "stability": { "enum": ["stable", "experimental", "undeclared"] },
+        "notes": { "type": "string" }
+      }
+    },
+    "argument": {
+      "type": "object",
+      "required": ["name", "description", "arity", "valueType", "allowedValues"],
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "arity": { "$ref": "#/$defs/arity" },
+        "valueType": { "$ref": "#/$defs/valueType" },
+        "allowedValues": {
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        },
+        "default": true
+      }
+    },
+    "option": {
+      "type": "object",
+      "required": [
+        "name",
+        "aliases",
+        "description",
+        "valueName",
+        "arity",
+        "required",
+        "negatable",
+        "valueType",
+        "allowedValues",
+        "recursive"
+      ],
+      "properties": {
+        "name": { "type": "string" },
+        "aliases": { "type": "array", "items": { "type": "string" } },
+        "description": { "type": "string" },
+        "valueName": { "type": ["string", "null"] },
+        "arity": { "$ref": "#/$defs/arity" },
+        "required": { "type": "boolean" },
+        "negatable": { "type": "boolean" },
+        "valueType": { "$ref": "#/$defs/valueType" },
+        "allowedValues": {
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        },
+        "recursive": { "type": "boolean" },
+        "default": true
+      }
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { CONTRACT_VERSION, isRequired, isVariadic } from "./types.js";
+export type { AdvisoryOutput, Arity, CommandContract, CommandContractRegistry, ContractStream, DescribeResult, DescribedArgument, DescribedCommand, DescribedOption, ExitCodeMeaning, SchemaRef, Stability, ValueType, } from "./types.js";
+export { buildUsage } from "./usage.js";
+export { renderText } from "./render.js";
+export { cliSchema } from "./schema.js";
+export { validate } from "./validate.js";
+export type { ValidationResult } from "./validate.js";
+export { canonicalize, canonicalizeJson } from "./canonicalize.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { CONTRACT_VERSION, isRequired, isVariadic } from "./types.js";
+export { buildUsage } from "./usage.js";
+export { renderText } from "./render.js";
+export { cliSchema } from "./schema.js";
+export { validate } from "./validate.js";
+export { canonicalize, canonicalizeJson } from "./canonicalize.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgBtE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,3 @@
+import type { DescribeResult } from "./types.js";
+/** `llm` and `human` share one renderer; `human` adds ANSI bold and dim. */
+export declare function renderText(result: DescribeResult, human: boolean): string;

package/dist/render.js

@@ -0,0 +1,43 @@
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+function renderCommand(command, human) {
+    const name = human ? `${BOLD}${command.id}${RESET}` : command.id;
+    const lines = [name, `  ${command.description}`, `  usage: ${command.usage}`];
+    if (command.formats?.length)
+        lines.push(`  formats: ${command.formats.join(", ")} (default ${command.defaultFormat})`);
+    if (command.outputSchema)
+        lines.push(`  json schema: ${command.outputSchema}`);
+    if (command.jsonlSchema)
+        lines.push(`  jsonl schema: ${command.jsonlSchema}`);
+    if (command.stream)
+        lines.push(`  stream: ${command.stream.success} on success` +
+            (command.stream.findings ? `, ${command.stream.findings} on findings` : ""));
+    if (command.writes)
+        lines.push("  writes: may modify files");
+    for (const exit of command.exitCodes)
+        lines.push(`  exit ${exit.code}: ${exit.meaning}`);
+    if (command.stability === "undeclared")
+        lines.push(human ? `  ${DIM}contract: undeclared${RESET}` : "  contract: undeclared");
+    if (command.notes)
+        lines.push(`  note: ${command.notes}`);
+    return lines;
+}
+/** `llm` and `human` share one renderer; `human` adds ANSI bold and dim. */
+export function renderText(result, human) {
+    const lines = [
+        `${result.tool.name} ${result.tool.version}`,
+        `contract schema version: ${result.schemaVersion}`,
+        `format shorthands: ${Object.entries(result.formatShorthands)
+            .map(([flag, value]) => `${flag} = ${value}`)
+            .join(", ")}`,
+    ];
+    if (result.advisoryOutput) {
+        lines.push("", `update notice: ${result.advisoryOutput.description}`, ...result.advisoryOutput.suppressedWhen.map((condition) => `  suppressed when ${condition}`));
+    }
+    lines.push("", `commands (${result.commands.length}):`, "");
+    for (const command of result.commands)
+        lines.push(...renderCommand(command, human), "");
+    return lines.join("\n").trimEnd() + "\n";
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+/** Frozen JSON Schema 2020-12 document. `$id` is an identifier, not a URL. */
+export declare const cliSchema: Record<string, unknown>;

package/dist/schema.js

@@ -0,0 +1,7 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+/** Frozen JSON Schema 2020-12 document. `$id` is an identifier, not a URL. */
+export const cliSchema = Object.freeze(JSON.parse(readFileSync(join(here, "cli-schema.json"), "utf8")));
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAErD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,SAAS,GAA4B,MAAM,CAAC,MAAM,CAC7D,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAA4B,CAC3F,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+export declare const CONTRACT_VERSION = "1";
+export type ContractStream = "stdout" | "stderr";
+export type ValueType = "boolean" | "string" | "integer" | "number";
+export type Stability = "stable" | "experimental" | "undeclared";
+export interface Arity {
+    min: number;
+    /** `null` is unbounded. */
+    max: number | null;
+}
+export interface ExitCodeMeaning {
+    code: number;
+    meaning: string;
+}
+export interface AdvisoryOutput {
+    description: string;
+    stream: ContractStream;
+    suppressedWhen: string[];
+    optOutEnv: string;
+}
+export interface SchemaRef {
+    id: string;
+    uri: string;
+    title: string;
+    commands: string[];
+}
+export interface CommandContract {
+    formats: readonly string[] | null;
+    defaultFormat: string | null;
+    formatConfigurable: boolean;
+    outputSchema: string | null;
+    jsonlSchema?: string | null;
+    sarifSchema?: string | null;
+    exitCodes: ExitCodeMeaning[];
+    exitCodePassthrough?: {
+        min: number;
+        max: number;
+        description: string;
+    };
+    stream: {
+        success: ContractStream;
+        findings?: ContractStream;
+    } | null;
+    writes: boolean | null;
+    stability: "stable" | "experimental";
+    notes?: string;
+}
+export type CommandContractRegistry = Record<string, CommandContract>;
+export interface DescribedArgument {
+    name: string;
+    description: string;
+    arity: Arity;
+    valueType: ValueType | null;
+    allowedValues: string[] | null;
+    default?: unknown;
+}
+export interface DescribedOption {
+    name: string;
+    aliases: string[];
+    description: string;
+    valueName: string | null;
+    arity: Arity;
+    required: boolean;
+    negatable: boolean;
+    valueType: ValueType | null;
+    allowedValues: string[] | null;
+    recursive: boolean;
+    default?: unknown;
+}
+export interface DescribedCommand {
+    id: string;
+    path: string[];
+    description: string;
+    usage: string;
+    arguments: DescribedArgument[];
+    options: DescribedOption[];
+    subcommands: string[];
+    formats: string[] | null;
+    defaultFormat: string | null;
+    formatConfigurable: boolean;
+    outputSchema: string | null;
+    jsonlSchema?: string | null;
+    sarifSchema?: string | null;
+    exitCodes: ExitCodeMeaning[];
+    exitCodePassthrough?: {
+        min: number;
+        max: number;
+        description: string;
+    };
+    stream: {
+        success: ContractStream;
+        findings?: ContractStream;
+    } | null;
+    writes: boolean | null;
+    stability: Stability;
+    notes?: string;
+}
+export interface DescribeResult {
+    schemaVersion: string;
+    tool: {
+        name: string;
+        version: string;
+    };
+    formatShorthands: Record<string, string>;
+    advisoryOutput?: AdvisoryOutput;
+    schemas: SchemaRef[];
+    commands: DescribedCommand[];
+}
+export declare function isRequired(arity: Arity): boolean;
+export declare function isVariadic(arity: Arity): boolean;

package/dist/types.js

@@ -0,0 +1,8 @@
+export const CONTRACT_VERSION = "1";
+export function isRequired(arity) {
+    return arity.min >= 1;
+}
+export function isVariadic(arity) {
+    return arity.max === null || arity.max > 1;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAsGpC,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,OAAO,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,OAAO,KAAK,CAAC,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;AAC7C,CAAC"}

package/dist/usage.d.ts

@@ -0,0 +1,6 @@
+import { type DescribedArgument, type DescribedOption } from "./types.js";
+/**
+ * Spec-defined usage string. A pure function of the rest of the command, so two
+ * emitters cannot disagree on a required field.
+ */
+export declare function buildUsage(toolName: string, path: string[], options: readonly Pick<DescribedOption, "name">[], args: readonly DescribedArgument[]): string;

package/dist/usage.js

@@ -0,0 +1,21 @@
+import { isRequired, isVariadic } from "./types.js";
+/**
+ * Spec-defined usage string. A pure function of the rest of the command, so two
+ * emitters cannot disagree on a required field.
+ */
+export function buildUsage(toolName, path, options, args) {
+    const parts = [toolName, ...path];
+    const rest = [];
+    if (options.length)
+        rest.push("[options]");
+    for (const argument of args) {
+        const variadic = isVariadic(argument.arity);
+        const required = isRequired(argument.arity);
+        if (variadic)
+            rest.push(required ? `<${argument.name}...>` : `[${argument.name}...]`);
+        else
+            rest.push(required ? `<${argument.name}>` : `[${argument.name}]`);
+    }
+    return [...parts, ...rest].join(" ");
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAgD,MAAM,YAAY,CAAC;AAElG;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,IAAc,EACd,OAAiD,EACjD,IAAkC;IAElC,MAAM,KAAK,GAAG,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC;IAClC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,OAAO,CAAC,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3C,KAAK,MAAM,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,QAAQ;YAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,MAAM,CAAC,CAAC;;YACjF,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,6 @@
+import { type ErrorObject } from "ajv/dist/2020.js";
+export interface ValidationResult {
+    valid: boolean;
+    errors: ErrorObject[];
+}
+export declare function validate(payload: unknown): ValidationResult;

package/dist/validate.js

@@ -0,0 +1,9 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { cliSchema } from "./schema.js";
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const validateFn = ajv.compile(cliSchema);
+export function validate(payload) {
+    const valid = validateFn(payload);
+    return { valid: Boolean(valid), errors: validateFn.errors ? [...validateFn.errors] : [] };
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;AAC5D,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAO1C,MAAM,UAAU,QAAQ,CAAC,OAAgB;IACvC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAC5F,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@cairn-tool/cli-schema",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Portable CLI-description types, JSON Schema, validator, and text renderer",
+  "license": "MIT",
+  "author": "Bryan Stockus",
+  "keywords": [
+    "cli",
+    "schema",
+    "describe"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cairn-tool/cli-schema.git",
+    "directory": "packages/cli-schema"
+  },
+  "bugs": {
+    "url": "https://github.com/cairn-tool/cli-schema/issues"
+  },
+  "homepage": "https://github.com/cairn-tool/cli-schema#readme",
+  "engines": {
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc && cp src/cli-schema.json dist/cli-schema.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.7.0",
+    "vitest": "^5.0.0"
+  }
+}