@cairn-tool/cli-schema 1.0.0 → 1.1.0

package/dist/cli-schema.json

@@ -6,56 +6,98 @@
   "type": "object",
   "required": ["schemaVersion", "tool", "formatShorthands", "schemas", "commands"],
   "properties": {
-    "schemaVersion": { "type": "string" },
+    "schemaVersion": {
+      "type": "string"
+    },
     "tool": {
+      "title": "ToolInfo",
       "type": "object",
       "required": ["name", "version"],
       "properties": {
-        "name": { "type": "string" },
-        "version": { "type": "string" }
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
       }
     },
     "formatShorthands": {
       "type": "object",
-      "additionalProperties": { "type": "string" },
+      "additionalProperties": {
+        "type": "string"
+      },
       "description": "argv token to the --format value it expands to before parsing."
     },
     "advisoryOutput": {
+      "title": "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" }
+        "description": {
+          "type": "string"
+        },
+        "stream": {
+          "enum": ["stdout", "stderr"]
+        },
+        "suppressedWhen": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "optOutEnv": {
+          "type": "string"
+        }
       }
     },
     "schemas": {
       "type": "array",
       "items": {
+        "title": "SchemaRef",
         "type": "object",
         "required": ["id", "uri", "title", "commands"],
         "properties": {
-          "id": { "type": "string" },
-          "uri": { "type": "string" },
-          "title": { "type": "string" },
-          "commands": { "type": "array", "items": { "type": "string" } }
+          "id": {
+            "type": "string"
+          },
+          "uri": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "commands": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
         }
       }
     },
     "commands": {
       "type": "array",
-      "items": { "$ref": "#/$defs/command" }
+      "items": {
+        "$ref": "#/$defs/command"
+      }
     }
   },
   "$defs": {
     "arity": {
+      "title": "Arity",
       "type": "object",
       "required": ["min", "max"],
       "properties": {
-        "min": { "type": "integer", "minimum": 0 },
-        "max": { "type": ["integer", "null"], "minimum": 0 }
+        "min": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "max": {
+          "type": ["integer", "null"],
+          "minimum": 0
+        }
       }
     },
     "valueType": {
@@ -63,6 +105,7 @@
       "enum": ["boolean", "string", "integer", "number", null]
     },
     "command": {
+      "title": "DescribedCommand",
       "type": "object",
       "required": [
         "id",
@@ -86,73 +129,236 @@
           "type": "string",
           "description": "Space-joined command path, e.g. 'md graph'."
         },
-        "path": { "type": "array", "items": { "type": "string" } },
-        "description": { "type": "string" },
-        "usage": { "type": "string" },
+        "path": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "description": {
+          "type": "string"
+        },
+        "usage": {
+          "type": "string"
+        },
         "arguments": {
           "type": "array",
-          "items": { "$ref": "#/$defs/argument" }
+          "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"] },
+          "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": {
+            "title": "ExitCodeMeaning",
             "type": "object",
             "required": ["code", "meaning"],
             "properties": {
-              "code": { "type": "integer" },
-              "meaning": { "type": "string" }
+              "code": {
+                "type": "integer"
+              },
+              "meaning": {
+                "type": "string"
+              }
             }
           }
         },
         "exitCodePassthrough": {
+          "title": "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" }
+            "min": {
+              "type": "integer"
+            },
+            "max": {
+              "type": "integer"
+            },
+            "description": {
+              "type": "string"
+            }
           }
         },
         "stream": {
+          "title": "CommandStream",
           "type": ["object", "null"],
+          "required": ["success"],
           "properties": {
-            "success": { "enum": ["stdout", "stderr"] },
-            "findings": { "enum": ["stdout", "stderr"] }
+            "success": {
+              "enum": ["stdout", "stderr"]
+            },
+            "findings": {
+              "enum": ["stdout", "stderr"]
+            }
           }
         },
-        "writes": { "type": ["boolean", "null"] },
-        "stability": { "enum": ["stable", "experimental", "undeclared"] },
-        "notes": { "type": "string" }
+        "writes": {
+          "type": ["boolean", "null"]
+        },
+        "stability": {
+          "enum": ["stable", "experimental", "undeclared"]
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "commandContract": {
+      "title": "CommandContract",
+      "type": "object",
+      "description": "What a host declares about one command: the facts a CLI framework cannot know. A framework supplies the command tree, the options and their arity; everything here has to be stated. An emitter merges this with what it walked to produce a `command`. A command with no contract is emitted with `stability: \"undeclared\"` rather than rejected, so a missing row is a visible gap and not a crash.",
+      "required": [
+        "formats",
+        "defaultFormat",
+        "formatConfigurable",
+        "outputSchema",
+        "exitCodes",
+        "stream",
+        "writes",
+        "stability"
+      ],
+      "properties": {
+        "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": {
+            "title": "ExitCodeMeaning",
+            "type": "object",
+            "required": ["code", "meaning"],
+            "properties": {
+              "code": {
+                "type": "integer"
+              },
+              "meaning": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "exitCodePassthrough": {
+          "title": "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": {
+          "title": "CommandStream",
+          "type": ["object", "null"],
+          "required": ["success"],
+          "properties": {
+            "success": {
+              "enum": ["stdout", "stderr"]
+            },
+            "findings": {
+              "enum": ["stdout", "stderr"]
+            }
+          }
+        },
+        "writes": {
+          "type": ["boolean", "null"]
+        },
+        "stability": {
+          "enum": ["stable", "experimental"],
+          "description": "Deliberately narrower than a command's. `undeclared` is what an emitter assigns to a command with no contract, so it is never a value a host declares."
+        },
+        "notes": {
+          "type": "string"
+        }
       }
     },
     "argument": {
+      "title": "DescribedArgument",
       "type": "object",
       "required": ["name", "description", "arity", "valueType", "allowedValues"],
       "properties": {
-        "name": { "type": "string" },
-        "description": { "type": "string" },
-        "arity": { "$ref": "#/$defs/arity" },
-        "valueType": { "$ref": "#/$defs/valueType" },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "arity": {
+          "$ref": "#/$defs/arity"
+        },
+        "valueType": {
+          "$ref": "#/$defs/valueType"
+        },
         "allowedValues": {
           "type": ["array", "null"],
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "default": true
       }
     },
     "option": {
+      "title": "DescribedOption",
       "type": "object",
       "required": [
         "name",
@@ -167,19 +373,42 @@
         "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" },
+        "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" }
+          "items": {
+            "type": "string"
+          }
+        },
+        "recursive": {
+          "type": "boolean"
         },
-        "recursive": { "type": "boolean" },
         "default": true
       }
     }

package/dist/generated/types.d.ts

@@ -0,0 +1,118 @@
+export type ValueType = "boolean" | "string" | "integer" | "number" | null;
+export type CommandStream = {
+    success: "stdout" | "stderr";
+    findings?: "stdout" | "stderr";
+} | null;
+/**
+ * The static contract of a command-line interface. Project configuration is not applied. Consumers must ignore properties they do not recognize.
+ */
+export interface DescribeResult {
+    schemaVersion: string;
+    tool: ToolInfo;
+    /**
+     * argv token to the --format value it expands to before parsing.
+     */
+    formatShorthands: {
+        [k: string]: string;
+    };
+    advisoryOutput?: AdvisoryOutput;
+    schemas: SchemaRef[];
+    commands: DescribedCommand[];
+}
+export interface ToolInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Machine-stream guarantees for an advisory notice. Omitted when the tool has none.
+ */
+export interface AdvisoryOutput {
+    description: string;
+    stream: "stdout" | "stderr";
+    suppressedWhen: string[];
+    optOutEnv: string;
+}
+export interface SchemaRef {
+    id: string;
+    uri: string;
+    title: string;
+    commands: string[];
+}
+export interface DescribedCommand {
+    /**
+     * Space-joined command path, e.g. 'md graph'.
+     */
+    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?: ExitCodePassthrough;
+    stream: CommandStream;
+    writes: boolean | null;
+    stability: "stable" | "experimental" | "undeclared";
+    notes?: string;
+}
+export interface DescribedArgument {
+    name: string;
+    description: string;
+    arity: Arity;
+    valueType: ValueType;
+    allowedValues: string[] | null;
+    default?: unknown;
+}
+export interface Arity {
+    min: number;
+    max: number | null;
+}
+export interface DescribedOption {
+    name: string;
+    aliases: string[];
+    description: string;
+    valueName: string | null;
+    arity: Arity;
+    required: boolean;
+    negatable: boolean;
+    valueType: ValueType;
+    allowedValues: string[] | null;
+    recursive: boolean;
+    default?: unknown;
+}
+export interface ExitCodeMeaning {
+    code: number;
+    meaning: string;
+}
+/**
+ * Present only when the command forwards a child process's exit status verbatim.
+ */
+export interface ExitCodePassthrough {
+    min: number;
+    max: number;
+    description: string;
+}
+export interface CommandContract {
+    formats: string[] | null;
+    defaultFormat: string | null;
+    formatConfigurable: boolean;
+    outputSchema: string | null;
+    jsonlSchema?: string | null;
+    sarifSchema?: string | null;
+    exitCodes: ExitCodeMeaning[];
+    exitCodePassthrough?: ExitCodePassthrough;
+    stream: CommandStream;
+    writes: boolean | null;
+    /**
+     * Deliberately narrower than a command's. `undeclared` is what an emitter assigns to a command with no contract, so it is never a value a host declares.
+     */
+    stability: "stable" | "experimental";
+    notes?: string;
+}

package/dist/generated/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/generated/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/generated/types.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -1,109 +1,27 @@
+/**
+ * The public model surface.
+ *
+ * Every shape is generated from `spec/v1/cli-schema.json` and re-exported here. What stays
+ * hand-written is what the spec does not describe as a shape: the contract version, the three
+ * string-union aliases the payload uses at its leaves, the registry map a host builds, and two
+ * predicates over arity.
+ */
+export type { Arity, AdvisoryOutput, CommandContract, CommandStream, DescribeResult, DescribedArgument, DescribedCommand, DescribedOption, ExitCodeMeaning, ExitCodePassthrough, SchemaRef, ToolInfo, } from "./generated/types.js";
+import type { Arity, CommandContract } from "./generated/types.js";
+/** Hand-owned, and independent of the npm and NuGet package versions. */
 export declare const CONTRACT_VERSION = "1";
+/**
+ * The three leaf unions.
+ *
+ * Kept by hand rather than taken from the generated file because the generated `ValueType` folds
+ * `null` into the union, where the published one has always been the non-null set with nullability
+ * expressed at each use site. Changing that would be a breaking change to a published package for
+ * no gain.
+ */
 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;
-}
+/** What a host hands an emitter, keyed by space-joined command id, e.g. `"md graph"`. */
 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

@@ -1,3 +1,4 @@
+/** Hand-owned, and independent of the npm and NuGet package versions. */
 export const CONTRACT_VERSION = "1";
 export function isRequired(arity) {
     return arity.min >= 1;

package/dist/types.js.map

@@ -1 +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"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAyBA,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAiBpC,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairn-tool/cli-schema",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Portable CLI-description types, JSON Schema, validator, and text renderer",
   "license": "MIT",