@cli-schema/spec 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# @cli-schema/spec
+
+TypeScript types, the vendored meta-schema, and a validator for the
+[CLI Schema specification](https://github.com/cli-schema/cli-schema) v1 — the open standard for
+describing command-line interfaces in a language-agnostic, machine-readable way.
+
+This is the only package in the [`cli-schema-js`](https://github.com/cli-schema/cli-schema-js)
+monorepo with no CLI-framework dependency. It defines the *shape* of a CLI Schema document;
+[`@cli-schema/commander`](https://www.npmjs.com/package/@cli-schema/commander) is what actually
+produces one from a real CLI.
+
+## Quickstart
+
+```sh
+npm install @cli-schema/spec
+```
+
+```ts
+import { validate, SCHEMA_VERSION, type CliSchema } from '@cli-schema/spec'
+
+const doc: CliSchema = {
+  schemaVersion: SCHEMA_VERSION,
+  name: 'mytool',
+  version: '1.0.0',
+}
+
+const result = validate(doc)
+if (!result.valid) throw new Error(JSON.stringify(result.errors, null, 2))
+```
+
+That's the minimum: a document only needs `schemaVersion`, `name`, and `version` to be valid —
+everything else (commands, parameters, environment, intent, ...) is optional enrichment.
+
+## Purpose
+
+CLI help text is written for humans, completion scripts are hand-authored per shell, and AI
+agents guess flags. CLI Schema fixes this by defining one JSON document format that describes a
+program's commands, parameters, intent, auth requirements, environment dependencies, and output
+capabilities — so agents, IDEs, shell-completion generators, and docs tooling can all read the
+same document instead of re-deriving it.
+
+`@cli-schema/spec` is the compile-time and runtime contract for that format: the types you build
+a document against, and the validator you check it with before trusting it.
+
+## Features
+
+- **Full v1 type coverage** — every object in the spec has a corresponding TypeScript interface:
+  `CliSchema` (root), `Command`, `Namespace`, `Parameter`, `Constraint`, `Intent`, `Output`,
+  `Environment`, `EnvVar`, `ConfigFile`, `DefaultHandler`, `Shortcut`, `Deprecation`.
+- **The normative meta-schema, vendored** — `schema/cli-schema.meta-schema.json` from the spec
+  repo, re-exported at `@cli-schema/spec/meta-schema.json` for tools that want the raw JSON
+  Schema directly (e.g. to validate in a non-JS pipeline, or feed to a codegen tool).
+- **A ready-to-use validator** — `validate()` / `assertValid()`, backed by
+  [ajv](https://ajv.js.org)'s 2020-12 dialect support. No need to wire up ajv yourself.
+- **`inferIntentFromHttp`** — a small pure helper for CLIs that wrap HTTP APIs: derives a
+  reasonable {@link Intent} from an HTTP verb (`GET`/`HEAD` → safe & idempotent, `PUT` →
+  idempotent, `DELETE` → destructive & idempotent, `POST`/`PATCH` → unset, since their semantics
+  are endpoint-specific).
+- **Vendor extensions typed** — every object that permits `x-` prefixed fields (spec §14) is
+  typed to accept them (`[extension: \`x-${string}\`]: unknown`), so `x-my-tool: {...}` type-checks
+  without `as any`.
+
+## Usage
+
+### Building a document by hand
+
+The types double as documentation of the format — reach for the [spec
+itself](https://github.com/cli-schema/cli-schema/blob/main/spec/v1/README.md) for full field
+semantics, but a well-populated document looks like:
+
+```ts
+import type { CliSchema } from '@cli-schema/spec'
+
+const doc: CliSchema = {
+  schemaVersion: 1,
+  name: 'gh',
+  version: '2.45.0',
+  description: 'GitHub CLI — bring GitHub to your terminal',
+  requiresAuth: true,
+  authCommands: ['auth login', 'auth logout'],
+  reservedMetaCommands: ['__schema'],
+  commands: [
+    {
+      name: 'status',
+      summary: 'Print information about relevant issues, pull requests, and notifications',
+      intent: { destructive: false, idempotent: true, requiresAuth: true },
+    },
+  ],
+  namespaces: [
+    {
+      segment: 'repo',
+      commands: [
+        {
+          name: 'delete',
+          path: ['repo'],
+          parameters: [
+            { role: 'positional', name: 'repository', type: 'string', required: true },
+            { role: 'confirmationSkip', name: 'yes', type: 'boolean', required: false },
+          ],
+          intent: { destructive: true, idempotent: true, scope: 'global', requiresConfirmation: true },
+        },
+      ],
+    },
+  ],
+}
+```
+
+In practice you'll usually generate this from a live CLI rather than write it by hand — see
+[`@cli-schema/commander`](https://www.npmjs.com/package/@cli-schema/commander).
+
+### Validating an untrusted document
+
+Per spec §15, consumers should treat schema documents as untrusted input:
+
+```ts
+import { validate, assertValid } from '@cli-schema/spec'
+
+const { valid, errors } = validate(untrustedDoc)
+// errors is an ajv ErrorObject[] — empty when valid
+
+assertValid(untrustedDoc) // throws with a formatted message if invalid
+```
+
+### Reading the raw meta-schema
+
+```ts
+import metaSchema from '@cli-schema/spec/meta-schema.json' with { type: 'json' }
+```
+
+Useful if you want to validate documents with your own ajv instance, a different validator
+entirely, or a non-JS tool.
+
+### Deriving intent from an HTTP verb
+
+```ts
+import { inferIntentFromHttp } from '@cli-schema/spec'
+
+inferIntentFromHttp('DELETE') // { destructive: true, idempotent: true, scope: 'global' }
+inferIntentFromHttp('POST')   // undefined — annotate explicitly, semantics vary per endpoint
+```
+
+## Related packages
+
+- [`@cli-schema/zod`](https://www.npmjs.com/package/@cli-schema/zod) — derive `Parameter`s from Zod schemas
+- [`@cli-schema/commander`](https://www.npmjs.com/package/@cli-schema/commander) — generate a full `CliSchema` from a live Commander tree
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.ts';
+export * from './validate.ts';
+export * from './intent.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./validate.js";
+export * from "./intent.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":"AAKA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA"}

package/dist/intent.d.ts

@@ -0,0 +1,3 @@
+import type { Intent } from './types.ts';
+export declare function inferIntentFromHttp(method: string): Intent | undefined;
+//# sourceMappingURL=intent.d.ts.map

package/dist/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAWxC,wBAAgB,mBAAmB,CAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYvE"}

package/dist/intent.js

@@ -0,0 +1,14 @@
+export function inferIntentFromHttp(method) {
+    switch (method.toUpperCase()) {
+        case 'GET':
+        case 'HEAD':
+            return { destructive: false, idempotent: true, scope: 'global' };
+        case 'PUT':
+            return { destructive: false, idempotent: true, scope: 'global' };
+        case 'DELETE':
+            return { destructive: true, idempotent: true, scope: 'global' };
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=intent.js.map

package/dist/intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.js","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAgBA,MAAM,UAAU,mBAAmB,CAAE,MAAc;IACjD,QAAQ,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;QAC7B,KAAK,KAAK,CAAC;QACX,KAAK,MAAM;YACT,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;QAClE,KAAK,KAAK;YACR,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;QAClE,KAAK,QAAQ;YACX,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;QACjE;YACE,OAAO,SAAS,CAAA;IACpB,CAAC;AACH,CAAC"}

package/dist/meta-schema.json

@@ -0,0 +1,213 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://cli-schema.github.io/cli-schema/schema/cli-schema.meta-schema.json",
+    "title": "CLI Schema",
+    "description": "Meta-schema for CLI Schema documents (specification v1)",
+    "type": "object",
+    "$defs": {
+        "deprecation": {
+            "oneOf": [
+                { "type": "boolean", "const": true },
+                {
+                    "type": "object",
+                    "properties": {
+                        "message": { "type": "string" },
+                        "since": { "type": "string" },
+                        "removedIn": { "type": "string" }
+                    },
+                    "additionalProperties": false
+                }
+            ]
+        },
+        "constraint": {
+            "type": "object",
+            "required": ["kind"],
+            "properties": {
+                "kind": {
+                    "type": "string",
+                    "enum": [
+                        "range", "timeSpanRange", "length", "count", "regex",
+                        "allowed", "denied", "email", "url", "uriScheme",
+                        "fileExtensions", "existing", "nonExisting", "rejectSymbolicLinks"
+                    ]
+                },
+                "min": { "type": "string" },
+                "max": { "type": "string" },
+                "pattern": { "type": "string" },
+                "values": { "type": "array", "items": { "type": "string" } }
+            },
+            "additionalProperties": false
+        },
+        "parameter": {
+            "type": "object",
+            "required": ["role", "name", "type", "required"],
+            "properties": {
+                "role": {
+                    "type": "string",
+                    "enum": ["flag", "positional", "confirmationSkip", "dryRun"]
+                },
+                "name": { "type": "string" },
+                "shortName": { "type": "string", "maxLength": 1 },
+                "type": {
+                    "type": "string",
+                    "enum": ["string", "integer", "number", "boolean", "array", "enum"]
+                },
+                "required": { "type": "boolean" },
+                "summary": { "type": "string" },
+                "defaultValue": { "type": "string" },
+                "repeatable": { "type": "boolean", "default": false },
+                "separator": { "type": "string" },
+                "aliases": { "type": "array", "items": { "type": "string" } },
+                "enumValues": { "type": "array", "items": { "type": "string" } },
+                "elementType": {
+                    "type": "string",
+                    "enum": ["string", "integer", "number", "boolean"]
+                },
+                "hidden": { "type": "boolean", "default": false },
+                "variadic": { "type": "boolean", "default": false },
+                "deprecated": { "$ref": "#/$defs/deprecation" },
+                "validations": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/constraint" }
+                }
+            },
+            "patternProperties": { "^x-": {} },
+            "additionalProperties": false
+        },
+        "intent": {
+            "type": "object",
+            "properties": {
+                "destructive": { "type": "boolean" },
+                "idempotent": { "type": "boolean" },
+                "scope": {
+                    "type": "string",
+                    "enum": ["file", "directory", "global"]
+                },
+                "requiresConfirmation": { "type": "boolean" },
+                "requiresAuth": { "type": "boolean" }
+            },
+            "additionalProperties": false
+        },
+        "output": {
+            "type": "object",
+            "properties": {
+                "formats": { "type": "array", "items": { "type": "string" } },
+                "formatFlag": { "type": "string" }
+            },
+            "additionalProperties": false
+        },
+        "envVar": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+                "name": { "type": "string" },
+                "required": { "type": "boolean", "default": false },
+                "description": { "type": "string" },
+                "defaultValue": { "type": "string" }
+            },
+            "additionalProperties": false
+        },
+        "configFile": {
+            "type": "object",
+            "required": ["path"],
+            "properties": {
+                "path": { "type": "string" },
+                "description": { "type": "string" },
+                "required": { "type": "boolean", "default": false }
+            },
+            "additionalProperties": false
+        },
+        "environment": {
+            "type": "object",
+            "properties": {
+                "variables": { "type": "array", "items": { "$ref": "#/$defs/envVar" } },
+                "configFiles": { "type": "array", "items": { "$ref": "#/$defs/configFile" } }
+            },
+            "additionalProperties": false
+        },
+        "defaultHandler": {
+            "type": "object",
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "enum": ["root", "namespace"] },
+                "summary": { "type": "string" },
+                "notes": { "type": "string" },
+                "usage": { "type": "string" },
+                "examples": { "type": "array", "items": { "type": "string" } },
+                "parameters": { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
+                "hidden": { "type": "boolean", "default": false }
+            },
+            "patternProperties": { "^x-": {} },
+            "additionalProperties": false
+        },
+        "command": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+                "path": { "type": "array", "items": { "type": "string" } },
+                "name": { "type": "string" },
+                "summary": { "type": "string" },
+                "notes": { "type": "string" },
+                "usage": { "type": "string" },
+                "examples": { "type": "array", "items": { "type": "string" } },
+                "parameters": { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
+                "aliases": { "type": "array", "items": { "type": "string" } },
+                "hidden": { "type": "boolean", "default": false },
+                "tags": { "type": "array", "items": { "type": "string" } },
+                "deprecated": { "$ref": "#/$defs/deprecation" },
+                "intent": { "$ref": "#/$defs/intent" },
+                "output": { "$ref": "#/$defs/output" },
+                "streaming": { "type": "boolean", "default": false },
+                "longRunning": { "type": "boolean", "default": false }
+            },
+            "patternProperties": { "^x-": {} },
+            "additionalProperties": false
+        },
+        "namespace": {
+            "type": "object",
+            "required": ["segment"],
+            "properties": {
+                "segment": { "type": "string" },
+                "summary": { "type": "string" },
+                "notes": { "type": "string" },
+                "options": { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
+                "defaultCommand": { "$ref": "#/$defs/defaultHandler" },
+                "commands": { "type": "array", "items": { "$ref": "#/$defs/command" } },
+                "namespaces": { "type": "array", "items": { "$ref": "#/$defs/namespace" } }
+            },
+            "patternProperties": { "^x-": {} },
+            "additionalProperties": false
+        },
+        "shortcut": {
+            "type": "object",
+            "required": ["from", "to"],
+            "properties": {
+                "from": { "type": "string" },
+                "to": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+            },
+            "additionalProperties": false
+        }
+    },
+    "required": ["schemaVersion", "name", "version"],
+    "properties": {
+        "schemaVersion": {
+            "type": "integer",
+            "const": 1
+        },
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "description": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "requiresAuth": { "type": "boolean" },
+        "authCommands": { "type": "array", "items": { "type": "string" } },
+        "environment": { "$ref": "#/$defs/environment" },
+        "reservedMetaCommands": { "type": "array", "items": { "type": "string" } },
+        "globalOptions": { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
+        "rootDefault": { "$ref": "#/$defs/defaultHandler" },
+        "commands": { "type": "array", "items": { "$ref": "#/$defs/command" } },
+        "namespaces": { "type": "array", "items": { "$ref": "#/$defs/namespace" } },
+        "shortcuts": { "type": "array", "items": { "$ref": "#/$defs/shortcut" } }
+    },
+    "patternProperties": { "^x-": {} },
+    "additionalProperties": false
+}

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+export declare const SCHEMA_VERSION: 1;
+export type ParameterType = 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'enum';
+export type ParameterElementType = 'string' | 'integer' | 'number' | 'boolean';
+export type ParameterRole = 'flag' | 'positional' | 'confirmationSkip' | 'dryRun';
+export type ConstraintKind = 'range' | 'timeSpanRange' | 'length' | 'count' | 'regex' | 'allowed' | 'denied' | 'email' | 'url' | 'uriScheme' | 'fileExtensions' | 'existing' | 'nonExisting' | 'rejectSymbolicLinks';
+export interface Constraint {
+    kind: ConstraintKind;
+    min?: string;
+    max?: string;
+    pattern?: string;
+    values?: string[];
+}
+export type Deprecation = true | {
+    message?: string;
+    since?: string;
+    removedIn?: string;
+};
+export interface Parameter {
+    role: ParameterRole;
+    name: string;
+    type: ParameterType;
+    required: boolean;
+    shortName?: string;
+    summary?: string;
+    defaultValue?: string;
+    repeatable?: boolean;
+    separator?: string;
+    aliases?: string[];
+    enumValues?: string[];
+    elementType?: ParameterElementType;
+    hidden?: boolean;
+    variadic?: boolean;
+    deprecated?: Deprecation;
+    validations?: Constraint[];
+    [extension: `x-${string}`]: unknown;
+}
+export interface Intent {
+    destructive?: boolean;
+    idempotent?: boolean;
+    scope?: 'file' | 'directory' | 'global';
+    requiresConfirmation?: boolean;
+    requiresAuth?: boolean;
+}
+export interface Output {
+    formats?: string[];
+    formatFlag?: string;
+}
+export interface DefaultHandler {
+    kind: 'root' | 'namespace';
+    summary?: string;
+    notes?: string;
+    usage?: string;
+    examples?: string[];
+    parameters?: Parameter[];
+    hidden?: boolean;
+    [extension: `x-${string}`]: unknown;
+}
+export interface Command {
+    name: string;
+    path?: string[];
+    summary?: string;
+    notes?: string;
+    usage?: string;
+    examples?: string[];
+    parameters?: Parameter[];
+    aliases?: string[];
+    hidden?: boolean;
+    tags?: string[];
+    deprecated?: Deprecation;
+    intent?: Intent;
+    output?: Output;
+    streaming?: boolean;
+    longRunning?: boolean;
+    [extension: `x-${string}`]: unknown;
+}
+export interface Namespace {
+    segment: string;
+    summary?: string;
+    notes?: string;
+    options?: Parameter[];
+    defaultCommand?: DefaultHandler;
+    commands?: Command[];
+    namespaces?: Namespace[];
+    [extension: `x-${string}`]: unknown;
+}
+export interface EnvVar {
+    name: string;
+    required?: boolean;
+    description?: string;
+    defaultValue?: string;
+}
+export interface ConfigFile {
+    path: string;
+    description?: string;
+    required?: boolean;
+}
+export interface Environment {
+    variables?: EnvVar[];
+    configFiles?: ConfigFile[];
+}
+export interface Shortcut {
+    from: string;
+    to: string[];
+}
+export interface CliSchema {
+    schemaVersion: typeof SCHEMA_VERSION;
+    name: string;
+    version: string;
+    description?: string;
+    tags?: string[];
+    requiresAuth?: boolean;
+    authCommands?: string[];
+    environment?: Environment;
+    reservedMetaCommands?: string[];
+    globalOptions?: Parameter[];
+    rootDefault?: DefaultHandler;
+    commands?: Command[];
+    namespaces?: Namespace[];
+    shortcuts?: Shortcut[];
+    [extension: `x-${string}`]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export const SCHEMA_VERSION = 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":"AAeA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAU,CAAA"}

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+import type { ErrorObject } from 'ajv';
+export interface ValidationResult {
+    valid: boolean;
+    errors: ErrorObject[];
+}
+export declare function validate(doc: unknown): ValidationResult;
+export declare function assertValid(doc: unknown): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAA;AAGtC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,WAAW,EAAE,CAAA;CACtB;AAkBD,wBAAgB,QAAQ,CAAE,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAIxD;AAGD,wBAAgB,WAAW,CAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CAM/C"}

package/dist/validate.js

@@ -0,0 +1,23 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import metaSchema from './meta-schema.json' with { type: 'json' };
+let compiled;
+function getValidator() {
+    if (compiled == null) {
+        const ajv = new Ajv2020({ allErrors: true, strict: false });
+        compiled = ajv.compile(metaSchema);
+    }
+    return compiled;
+}
+export function validate(doc) {
+    const validator = getValidator();
+    const valid = validator(doc);
+    return { valid, errors: valid ? [] : [...(validator.errors ?? [])] };
+}
+export function assertValid(doc) {
+    const result = validate(doc);
+    if (!result.valid) {
+        const details = result.errors.map((e) => `  - ${e.instancePath || '/'}: ${e.message ?? 'invalid'}`).join('\n');
+        throw new Error(`Invalid CLI Schema document:\n${details}`);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAE1C,OAAO,UAAU,MAAM,oBAAoB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAOjE,IAAI,QAAoD,CAAA;AAExD,SAAS,YAAY;IACnB,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;QAC3D,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAQD,MAAM,UAAU,QAAQ,CAAE,GAAY;IACpC,MAAM,SAAS,GAAG,YAAY,EAAE,CAAA;IAChC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAY,CAAA;IACvC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,EAAE,CAAA;AACtE,CAAC;AAGD,MAAM,UAAU,WAAW,CAAE,GAAY;IACvC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,YAAY,IAAI,GAAG,KAAK,CAAC,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC9G,MAAM,IAAI,KAAK,CAAC,iCAAiC,OAAO,EAAE,CAAC,CAAA;IAC7D,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@cli-schema/spec",
+  "version": "0.1.0",
+  "description": "TypeScript types, meta-schema, and validator for the CLI Schema specification (https://github.com/cli-schema/cli-schema)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./meta-schema.json": "./dist/meta-schema.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --import tsx/esm --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cli-schema/cli-schema-js.git",
+    "directory": "packages/spec"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright cli-schema contributors
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './types.ts'
+export * from './validate.ts'
+export * from './intent.ts'

package/src/intent.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright cli-schema contributors
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { Intent } from './types.ts'
+
+/**
+ * Derives an {@link Intent} from an HTTP method, for CLIs that wrap HTTP APIs.
+ *
+ * GET and HEAD are safe and idempotent.
+ * PUT is idempotent (upsert semantics).
+ * DELETE is destructive and idempotent.
+ * POST and PATCH are left `undefined` — their semantics depend on the specific endpoint
+ * and should be annotated explicitly by the caller.
+ */
+export function inferIntentFromHttp (method: string): Intent | undefined {
+  switch (method.toUpperCase()) {
+    case 'GET':
+    case 'HEAD':
+      return { destructive: false, idempotent: true, scope: 'global' }
+    case 'PUT':
+      return { destructive: false, idempotent: true, scope: 'global' }
+    case 'DELETE':
+      return { destructive: true, idempotent: true, scope: 'global' }
+    default:
+      return undefined
+  }
+}

package/src/meta-schema.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cli-schema.github.io/cli-schema/schema/cli-schema.meta-schema.json",
+  "title": "CLI Schema",
+  "description": "Meta-schema for CLI Schema documents (specification v1)",
+  "type": "object",
+  "$defs": {
+    "deprecation": {
+      "oneOf": [
+        { "type": "boolean", "const": true },
+        {
+          "type": "object",
+          "properties": {
+            "message": { "type": "string" },
+            "since": { "type": "string" },
+            "removedIn": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "constraint": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "range", "timeSpanRange", "length", "count", "regex",
+            "allowed", "denied", "email", "url", "uriScheme",
+            "fileExtensions", "existing", "nonExisting", "rejectSymbolicLinks"
+          ]
+        },
+        "min": { "type": "string" },
+        "max": { "type": "string" },
+        "pattern": { "type": "string" },
+        "values": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "parameter": {
+      "type": "object",
+      "required": ["role", "name", "type", "required"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "enum": ["flag", "positional", "confirmationSkip", "dryRun"]
+        },
+        "name": { "type": "string" },
+        "shortName": { "type": "string", "maxLength": 1 },
+        "type": {
+          "type": "string",
+          "enum": ["string", "integer", "number", "boolean", "array", "enum"]
+        },
+        "required": { "type": "boolean" },
+        "summary": { "type": "string" },
+        "defaultValue": { "type": "string" },
+        "repeatable": { "type": "boolean", "default": false },
+        "separator": { "type": "string" },
+        "aliases": { "type": "array", "items": { "type": "string" } },
+        "enumValues": { "type": "array", "items": { "type": "string" } },
+        "elementType": {
+          "type": "string",
+          "enum": ["string", "integer", "number", "boolean"]
+        },
+        "hidden": { "type": "boolean", "default": false },
+        "variadic": { "type": "boolean", "default": false },
+        "deprecated": { "$ref": "#/$defs/deprecation" },
+        "validations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/constraint" }
+        }
+      },
+      "patternProperties": { "^x-": {} },
+      "additionalProperties": false
+    },
+    "intent": {
+      "type": "object",
+      "properties": {
+        "destructive": { "type": "boolean" },
+        "idempotent": { "type": "boolean" },
+        "scope": {
+          "type": "string",
+          "enum": ["file", "directory", "global"]
+        },
+        "requiresConfirmation": { "type": "boolean" },
+        "requiresAuth": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "output": {
+      "type": "object",
+      "properties": {
+        "formats": { "type": "array", "items": { "type": "string" } },
+        "formatFlag": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "envVar": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "required": { "type": "boolean", "default": false },
+        "description": { "type": "string" },
+        "defaultValue": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "configFile": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "path": { "type": "string" },
+        "description": { "type": "string" },
+        "required": { "type": "boolean", "default": false }
+      },
+      "additionalProperties": false
+    },
+    "environment": {
+      "type": "object",
+      "properties": {
+        "variables": { "type": "array", "items": { "$ref": "#/$defs/envVar" } },
+        "configFiles": { "type": "array", "items": { "$ref": "#/$defs/configFile" } }
+      },
+      "additionalProperties": false
+    },
+    "defaultHandler": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "type": "string", "enum": ["root", "namespace"] },
+        "summary": { "type": "string" },
+        "notes": { "type": "string" },
+        "usage": { "type": "string" },
+        "examples": { "type": "array", "items": { "type": "string" } },
+        "parameters": { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
+        "hidden": { "type": "boolean", "default": false }
+      },
+      "patternProperties": { "^x-": {} },
+      "additionalProperties": false
+    },
+    "command": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "path": { "type": "array", "items": { "type": "string" } },
+        "name": { "type": "string" },
+        "summary": { "type": "string" },
+        "notes": { "type": "string" },
+        "usage": { "type": "string" },
+        "examples": { "type": "array", "items": { "type": "string" } },
+        "parameters": { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
+        "aliases": { "type": "array", "items": { "type": "string" } },
+        "hidden": { "type": "boolean", "default": false },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "deprecated": { "$ref": "#/$defs/deprecation" },
+        "intent": { "$ref": "#/$defs/intent" },
+        "output": { "$ref": "#/$defs/output" },
+        "streaming": { "type": "boolean", "default": false },
+        "longRunning": { "type": "boolean", "default": false }
+      },
+      "patternProperties": { "^x-": {} },
+      "additionalProperties": false
+    },
+    "namespace": {
+      "type": "object",
+      "required": ["segment"],
+      "properties": {
+        "segment": { "type": "string" },
+        "summary": { "type": "string" },
+        "notes": { "type": "string" },
+        "options": { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
+        "defaultCommand": { "$ref": "#/$defs/defaultHandler" },
+        "commands": { "type": "array", "items": { "$ref": "#/$defs/command" } },
+        "namespaces": { "type": "array", "items": { "$ref": "#/$defs/namespace" } }
+      },
+      "patternProperties": { "^x-": {} },
+      "additionalProperties": false
+    },
+    "shortcut": {
+      "type": "object",
+      "required": ["from", "to"],
+      "properties": {
+        "from": { "type": "string" },
+        "to": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["schemaVersion", "name", "version"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "description": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "requiresAuth": { "type": "boolean" },
+    "authCommands": { "type": "array", "items": { "type": "string" } },
+    "environment": { "$ref": "#/$defs/environment" },
+    "reservedMetaCommands": { "type": "array", "items": { "type": "string" } },
+    "globalOptions": { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
+    "rootDefault": { "$ref": "#/$defs/defaultHandler" },
+    "commands": { "type": "array", "items": { "$ref": "#/$defs/command" } },
+    "namespaces": { "type": "array", "items": { "$ref": "#/$defs/namespace" } },
+    "shortcuts": { "type": "array", "items": { "$ref": "#/$defs/shortcut" } }
+  },
+  "patternProperties": { "^x-": {} },
+  "additionalProperties": false
+}

package/src/types.ts

@@ -0,0 +1,184 @@
+/*
+ * Copyright cli-schema contributors
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * TypeScript types for CLI Schema specification v1
+ * (https://github.com/cli-schema/cli-schema/blob/main/spec/v1/README.md).
+ *
+ * Field-for-field mirror of the meta-schema (`meta-schema.json`, vendored from the spec
+ * repo). Keep both in sync — the meta-schema is the normative source of truth; these types
+ * exist purely for compile-time ergonomics.
+ */
+
+/** Always `1` for specification v1. */
+export const SCHEMA_VERSION = 1 as const
+
+/** JSON Schema primitive type names used by {@link Parameter.type} and {@link Parameter.elementType}. */
+export type ParameterType = 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'enum'
+
+/** Element type names for array-typed parameters (scalars only — see spec §6). */
+export type ParameterElementType = 'string' | 'integer' | 'number' | 'boolean'
+
+/** See spec §6.1 Roles. */
+export type ParameterRole = 'flag' | 'positional' | 'confirmationSkip' | 'dryRun'
+
+/** See spec §6.2 Constraints. */
+export type ConstraintKind =
+  | 'range'
+  | 'timeSpanRange'
+  | 'length'
+  | 'count'
+  | 'regex'
+  | 'allowed'
+  | 'denied'
+  | 'email'
+  | 'url'
+  | 'uriScheme'
+  | 'fileExtensions'
+  | 'existing'
+  | 'nonExisting'
+  | 'rejectSymbolicLinks'
+
+/** A validation rule applied to a parameter's value (spec §6.2). */
+export interface Constraint {
+  kind: ConstraintKind
+  min?: string
+  max?: string
+  pattern?: string
+  values?: string[]
+}
+
+/** Structured deprecation metadata (spec §11.1). `true` signals deprecation without version detail. */
+export type Deprecation = true | {
+  message?: string
+  since?: string
+  removedIn?: string
+}
+
+/** A single flag or positional argument (spec §6 Parameter Object). */
+export interface Parameter {
+  role: ParameterRole
+  name: string
+  type: ParameterType
+  required: boolean
+  shortName?: string
+  summary?: string
+  defaultValue?: string
+  repeatable?: boolean
+  separator?: string
+  aliases?: string[]
+  enumValues?: string[]
+  elementType?: ParameterElementType
+  hidden?: boolean
+  variadic?: boolean
+  deprecated?: Deprecation
+  validations?: Constraint[]
+  [extension: `x-${string}`]: unknown
+}
+
+/** A command's side-effect profile, for agent risk reasoning (spec §11 Intent Object). */
+export interface Intent {
+  destructive?: boolean
+  idempotent?: boolean
+  scope?: 'file' | 'directory' | 'global'
+  requiresConfirmation?: boolean
+  requiresAuth?: boolean
+}
+
+/** Machine-readable output formats a command supports (spec §12 Output Object). */
+export interface Output {
+  formats?: string[]
+  formatFlag?: string
+}
+
+/** A handler invoked when a program or namespace is called with no subcommand (spec §10). */
+export interface DefaultHandler {
+  kind: 'root' | 'namespace'
+  summary?: string
+  notes?: string
+  usage?: string
+  examples?: string[]
+  parameters?: Parameter[]
+  hidden?: boolean
+  [extension: `x-${string}`]: unknown
+}
+
+/** A single executable command (spec §7 Command Object). */
+export interface Command {
+  name: string
+  path?: string[]
+  summary?: string
+  notes?: string
+  usage?: string
+  examples?: string[]
+  parameters?: Parameter[]
+  aliases?: string[]
+  hidden?: boolean
+  tags?: string[]
+  deprecated?: Deprecation
+  intent?: Intent
+  output?: Output
+  streaming?: boolean
+  longRunning?: boolean
+  [extension: `x-${string}`]: unknown
+}
+
+/** A named grouping of commands; namespaces may be nested arbitrarily (spec §8). */
+export interface Namespace {
+  segment: string
+  summary?: string
+  notes?: string
+  options?: Parameter[]
+  defaultCommand?: DefaultHandler
+  commands?: Command[]
+  namespaces?: Namespace[]
+  [extension: `x-${string}`]: unknown
+}
+
+/** A single environment variable dependency (spec §9.1). */
+export interface EnvVar {
+  name: string
+  required?: boolean
+  description?: string
+  defaultValue?: string
+}
+
+/** A single configuration file dependency (spec §9.2). */
+export interface ConfigFile {
+  path: string
+  description?: string
+  required?: boolean
+}
+
+/** External context the program depends on (spec §9 Environment Object). */
+export interface Environment {
+  variables?: EnvVar[]
+  configFiles?: ConfigFile[]
+}
+
+/** A root-level alias that transparently resolves to a deeper namespace or command path (spec §5.1). */
+export interface Shortcut {
+  from: string
+  to: string[]
+}
+
+/** The root of a CLI Schema document (spec §5 Root Object). */
+export interface CliSchema {
+  schemaVersion: typeof SCHEMA_VERSION
+  name: string
+  version: string
+  description?: string
+  tags?: string[]
+  requiresAuth?: boolean
+  authCommands?: string[]
+  environment?: Environment
+  reservedMetaCommands?: string[]
+  globalOptions?: Parameter[]
+  rootDefault?: DefaultHandler
+  commands?: Command[]
+  namespaces?: Namespace[]
+  shortcuts?: Shortcut[]
+  [extension: `x-${string}`]: unknown
+}

package/src/validate.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright cli-schema contributors
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Ajv2020 } from 'ajv/dist/2020.js'
+import type { ErrorObject } from 'ajv'
+import metaSchema from './meta-schema.json' with { type: 'json' }
+
+export interface ValidationResult {
+  valid: boolean
+  errors: ErrorObject[]
+}
+
+let compiled: ReturnType<Ajv2020['compile']> | undefined
+
+function getValidator (): ReturnType<Ajv2020['compile']> {
+  if (compiled == null) {
+    const ajv = new Ajv2020({ allErrors: true, strict: false })
+    compiled = ajv.compile(metaSchema)
+  }
+  return compiled
+}
+
+/**
+ * Validates a candidate document against the CLI Schema v1 meta-schema.
+ *
+ * Per spec §15 (Security Considerations), consumers should treat schema documents as
+ * untrusted input and validate them before acting on their contents.
+ */
+export function validate (doc: unknown): ValidationResult {
+  const validator = getValidator()
+  const valid = validator(doc) as boolean
+  return { valid, errors: valid ? [] : [...(validator.errors ?? [])] }
+}
+
+/** Throws with a formatted message if `doc` does not conform to the meta-schema. */
+export function assertValid (doc: unknown): void {
+  const result = validate(doc)
+  if (!result.valid) {
+    const details = result.errors.map((e) => `  - ${e.instancePath || '/'}: ${e.message ?? 'invalid'}`).join('\n')
+    throw new Error(`Invalid CLI Schema document:\n${details}`)
+  }
+}