@clidoc/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Houston
+
+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,86 @@
+# @clidoc/cli
+
+[![npm version](https://img.shields.io/npm/v/%40clidoc%2Fcli)](https://www.npmjs.com/package/@clidoc/cli)
+[![npm downloads](https://img.shields.io/npm/dw/%40clidoc%2Fcli)](https://www.npmjs.com/package/@clidoc/cli)
+[![CI](https://github.com/bhouston/clidoc/actions/workflows/ci.yml/badge.svg)](https://github.com/bhouston/clidoc/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/bhouston/clidoc/graph/badge.svg)](https://codecov.io/gh/bhouston/clidoc)
+[![Documentation](https://img.shields.io/badge/docs-clidoc.dev-blue)](https://clidoc.dev)
+
+Generate OpenCLI JSON from framework metadata, validate JSON/YAML documents, and
+render Markdown. Node 22.12+; ESM only.
+
+The CLI being documented should provide its own `docgen` command, the human-facing
+entry point. Install clidoc globally to validate and render the resulting file:
+
+```sh
+npm install -g @clidoc/cli
+mycli docgen --output cli.json
+clidoc validate cli.json
+clidoc markdown cli.json --output reference.md
+```
+
+`mycli __opencli` is the hidden, machine-facing discovery subcommand, matching
+upstream OpenCLI's Go adapters, including its `-o`/`--out <file>` flag
+(`mycli __opencli --out cli.json`); omitted, it writes to stdout like
+`clidoc docgen`/`clidoc generate`/`clidoc markdown` do when their own
+`--output` is omitted. clidoc dogfoods this exact workflow on itself:
+`clidoc docgen` and `clidoc __opencli` both describe the `clidoc` binary. As a
+secondary option, trusted command definitions can be imported with
+`clidoc generate ./definition.mjs --adapter yargs --output cli.json`. Invalid
+input or command usage exits with status 1. `--help` describes command
+arguments, and `--version` prints the installed package version.
+
+The generation module must export `info` (`title`, `binary`, `version`) and a
+default value: Yargs command modules, a Commander `Command`, or an oclif manifest.
+Only import trusted modules: their top-level code and supported Yargs builder
+callbacks execute during generation. Command handlers are never invoked.
+
+Commands are separate files registered through `yargs-file-commands`, matching
+the `hdrify` approach. `cliDocument()` derives this tool's OpenCLI document from
+those same definitions. `runCli(argv)` supports embedding without exiting the
+calling process; it rejects on invalid input.
+
+See the [repository guide](../../README.md) and
+[generated command reference](../../docs/generated/cli.md).
+
+## Shell completion
+
+Generate standalone Bash, Zsh, and Fish scripts for clidoc or any validated OpenCLI
+JSON/YAML document:
+
+```sh
+clidoc completion bash                    # clidoc itself; script on stdout
+clidoc completion zsh -i mycli.json -o mycli.zsh
+clidoc completion fish -o ~/.config/fish/completions/clidoc.fish
+```
+
+For Bash, activate with `source <(clidoc completion bash)`. For Zsh, run
+`source <(clidoc completion zsh)` after `autoload -Uz compinit; compinit`.
+Use `--binary name` to register an alternative executable name. Generated scripts
+need neither Node nor clidoc at completion time. Regenerate them after CLI changes.
+See the [completion guide](https://clidoc.dev/docs/guides/completion) for
+persistent installation, supported syntax, and limitations.
+
+## MCP tools and stdio server
+
+```sh
+clidoc mcp cli.json --output tools.json
+clidoc mcp cli.json --serve --executable /absolute/path/to/mycli
+```
+
+Exporting does not execute the CLI. Serving requires an explicit trusted
+executable and validates every tool invocation. The bridge uses conventional
+long options and `--` before positional arguments; see the
+[MCP guide](../website/docs/guides/mcp.md) for the serialization contract,
+client configuration, limits, and supported spec features.
+
+Library users can import `compileMcpTools`, `createMcpServer`, and `serveMcp`
+from `@clidoc/cli/mcp`.
+
+## License
+
+MIT. See [LICENSE](../../LICENSE).
+
+## Author
+
+[Ben Houston](https://ben3d.ca), Sponsored by [Land of Assets](https://landofassets.com).

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

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

package/dist/bin.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { hideBin } from 'yargs/helpers';
+import { handleOpenCliRequest } from '@clidoc/core';
+import { cliDocument, runCli } from './index.js';
+try {
+    const argv = hideBin(process.argv);
+    if (!(await handleOpenCliRequest(argv, cliDocument)))
+        await runCli(argv);
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjD,IAAI,CAAC;IACH,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAAE,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;AAC3E,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/dist/commands/completion.d.ts

@@ -0,0 +1,10 @@
+export declare const command: import("yargs-file-commands").DefineCommandResult<{}, {
+    shell: "bash" | "fish" | "zsh";
+} & {
+    input: string | undefined;
+} & {
+    binary: string | undefined;
+} & {
+    output: string | undefined;
+}>;
+//# sourceMappingURL=completion.d.ts.map

package/dist/commands/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,OAAO;;;;;;;;EAqBlB,CAAC"}

package/dist/commands/completion.js

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import { generateCompletion, parse } from '@clidoc/core';
+import { defineCommand } from 'yargs-file-commands';
+import { cliDocument } from '../definition.js';
+import { output } from '../io.js';
+export const command = defineCommand({
+    command: 'completion <shell>',
+    describe: 'Generate a standalone shell completion script',
+    builder: (yargs) => yargs
+        .positional('shell', {
+        type: 'string',
+        choices: ['bash', 'zsh', 'fish'],
+        demandOption: true,
+        describe: 'Target shell',
+    })
+        .option('input', { type: 'string', alias: 'i', describe: 'OpenCLI JSON or YAML file; defaults to clidoc itself' })
+        .option('binary', { type: 'string', describe: 'Executable name override for completion registration' })
+        .option('output', { type: 'string', alias: 'o', describe: 'Output file; defaults to stdout' }),
+    handler: async (argv) => {
+        const document = argv.input ? parse(await readFile(argv.input, 'utf8')) : cliDocument();
+        await output(generateCompletion(document, { shell: argv.shell, binary: argv.binary }), argv.output);
+    },
+});
+//# sourceMappingURL=completion.js.map

package/dist/commands/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAwB,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;IACnC,OAAO,EAAE,oBAAoB;IAC7B,QAAQ,EAAE,+CAA+C;IACzD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,OAAO,EAAE;QACnB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAU;QACzC,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,cAAc;KACzB,CAAC;SACD,MAAM,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,sDAAsD,EAAE,CAAC;SACjH,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,sDAAsD,EAAE,CAAC;SACtG,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,iCAAiC,EAAE,CAAC;IAClG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACxF,MAAM,MAAM,CACV,kBAAkB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAwB,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,EAC3F,IAAI,CAAC,MAAM,CACZ,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/commands/docgen.d.ts

@@ -0,0 +1,6 @@
+export declare const command: import("yargs-file-commands").DefineCommandResult<{}, {
+    format: string;
+} & {
+    output: string | undefined;
+}>;
+//# sourceMappingURL=docgen.d.ts.map

package/dist/commands/docgen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docgen.d.ts","sourceRoot":"","sources":["../../src/commands/docgen.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,OAAO;;;;EAelB,CAAC"}

package/dist/commands/docgen.js

@@ -0,0 +1,19 @@
+import { writeOpenCliDocument } from '@clidoc/core';
+import { defineCommand } from 'yargs-file-commands';
+import { cliDocument } from '../definition.js';
+export const command = defineCommand({
+    command: 'docgen',
+    describe: 'Write clidoc’s own OpenCLI document',
+    builder: (yargs) => yargs
+        .option('format', {
+        type: 'string',
+        choices: ['json', 'yaml', 'markdown'],
+        default: 'json',
+        describe: 'Output format',
+    })
+        .option('output', { type: 'string', alias: 'o', describe: 'Output file; defaults to stdout' }),
+    handler: async (argv) => {
+        await writeOpenCliDocument(cliDocument(), argv.output, argv.format);
+    },
+});
+//# sourceMappingURL=docgen.js.map

package/dist/commands/docgen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docgen.js","sourceRoot":"","sources":["../../src/commands/docgen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;IACnC,OAAO,EAAE,QAAQ;IACjB,QAAQ,EAAE,qCAAqC;IAC/C,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,MAAM,CAAC,QAAQ,EAAE;QAChB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAU;QAC9C,OAAO,EAAE,MAAM;QACf,QAAQ,EAAE,eAAe;KAC1B,CAAC;SACD,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,iCAAiC,EAAE,CAAC;IAClG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACtB,MAAM,oBAAoB,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAwB,CAAC,CAAC;IACxF,CAAC;CACF,CAAC,CAAC"}

package/dist/commands/generate.d.ts

@@ -0,0 +1,8 @@
+export declare const command: import("yargs-file-commands").DefineCommandResult<{}, {
+    module: string;
+} & {
+    adapter: "commander" | "oclif" | "yargs";
+} & {
+    output: string | undefined;
+}>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,OAAO;;;;;;EAgClB,CAAC"}

package/dist/commands/generate.js

@@ -0,0 +1,40 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse } from '@clidoc/core';
+import { fromYargs } from '@clidoc/adapter-yargs';
+import { fromCommander } from '@clidoc/adapter-commander';
+import { fromOclif } from '@clidoc/adapter-oclif';
+import { defineCommand } from 'yargs-file-commands';
+import { output } from '../io.js';
+export const command = defineCommand({
+    command: 'generate <module>',
+    describe: 'Import a trusted framework definition module and generate OpenCLI JSON',
+    builder: (yargs) => yargs
+        .positional('module', {
+        type: 'string',
+        demandOption: true,
+        describe: 'Trusted JS module exporting default metadata and info',
+    })
+        .option('adapter', {
+        type: 'string',
+        choices: ['yargs', 'commander', 'oclif'],
+        demandOption: true,
+        describe: 'Framework adapter',
+    })
+        .option('output', { type: 'string', alias: 'o', describe: 'Output JSON file; defaults to stdout' }),
+    handler: async (argv) => {
+        // Importing code is intentional: this command accepts trusted local modules only.
+        const source = await import(pathToFileURL(resolve(argv.module)).href);
+        if (!source.default || !source.info)
+            throw new Error('Module must export default framework metadata and named info');
+        const document = argv.adapter === 'yargs'
+            ? fromYargs(source.default, source.info)
+            : argv.adapter === 'commander'
+                ? fromCommander(source.default, source.info)
+                : fromOclif(source.default, source.info);
+        const json = JSON.stringify(document, null, 2) + '\n';
+        parse(json);
+        await output(json, argv.output);
+    },
+});
+//# sourceMappingURL=generate.js.map

package/dist/commands/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;IACnC,OAAO,EAAE,mBAAmB;IAC5B,QAAQ,EAAE,wEAAwE;IAClF,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,QAAQ,EAAE;QACpB,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,uDAAuD;KAClE,CAAC;SACD,MAAM,CAAC,SAAS,EAAE;QACjB,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAU;QACjD,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,mBAAmB;KAC9B,CAAC;SACD,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,sCAAsC,EAAE,CAAC;IACvG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACtB,kFAAkF;QAClF,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtE,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI;YACjC,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QAClF,MAAM,QAAQ,GACZ,IAAI,CAAC,OAAO,KAAK,OAAO;YACtB,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC;YACxC,CAAC,CAAC,IAAI,CAAC,OAAO,KAAK,WAAW;gBAC5B,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC;gBAC5C,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;CACF,CAAC,CAAC"}

package/dist/commands/markdown.d.ts

@@ -0,0 +1,6 @@
+export declare const command: import("yargs-file-commands").DefineCommandResult<{}, {
+    input: string;
+} & {
+    output: string | undefined;
+}>;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/commands/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/commands/markdown.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,OAAO;;;;EAUlB,CAAC"}

package/dist/commands/markdown.js

@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises';
+import { parse, renderMarkdown } from '@clidoc/core';
+import { defineCommand } from 'yargs-file-commands';
+import { output } from '../io.js';
+export const command = defineCommand({
+    command: 'markdown <input>',
+    describe: 'Render an OpenCLI document as Markdown',
+    builder: (yargs) => yargs
+        .positional('input', { type: 'string', demandOption: true, describe: 'OpenCLI JSON or YAML filename' })
+        .option('output', { type: 'string', alias: 'o', describe: 'Output file; defaults to stdout' }),
+    handler: async (argv) => {
+        await output(renderMarkdown(parse(await readFile(argv.input, 'utf8'))), argv.output);
+    },
+});
+//# sourceMappingURL=markdown.js.map

package/dist/commands/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/commands/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;IACnC,OAAO,EAAE,kBAAkB;IAC3B,QAAQ,EAAE,wCAAwC;IAClD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,+BAA+B,EAAE,CAAC;SACtG,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,iCAAiC,EAAE,CAAC;IAClG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACtB,MAAM,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACvF,CAAC;CACF,CAAC,CAAC"}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,16 @@
+export declare const command: import("yargs-file-commands").DefineCommandResult<{}, {
+    input: string;
+} & {
+    output: string | undefined;
+} & {
+    serve: boolean;
+} & {
+    executable: string | undefined;
+} & {
+    cwd: string | undefined;
+} & {
+    "timeout-ms": number | undefined;
+} & {
+    "max-output-bytes": number | undefined;
+}>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/commands/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,OAAO;;;;;;;;;;;;;;EAmClB,CAAC"}

package/dist/commands/mcp.js

@@ -0,0 +1,39 @@
+import { readFile } from 'node:fs/promises';
+import { parse } from '@clidoc/core';
+import { defineCommand } from 'yargs-file-commands';
+import { compileMcpTools, serveMcp } from '../mcp/index.js';
+import { output } from '../io.js';
+export const command = defineCommand({
+    command: 'mcp <input>',
+    describe: 'Export MCP tools or serve a trusted CLI over MCP stdio',
+    builder: (yargs) => yargs
+        .positional('input', { type: 'string', demandOption: true, describe: 'OpenCLI JSON or YAML filename' })
+        .option('output', { type: 'string', alias: 'o', describe: 'Tool catalog output file; defaults to stdout' })
+        .option('serve', { type: 'boolean', default: false, describe: 'Serve MCP over stdin/stdout' })
+        .option('executable', { type: 'string', describe: 'Trusted executable to run; required with --serve' })
+        .option('cwd', { type: 'string', describe: 'Working directory for CLI invocations' })
+        .option('timeout-ms', { type: 'number', describe: 'Invocation timeout in milliseconds (default: 30000)' })
+        .option('max-output-bytes', { type: 'number', describe: 'Combined stdout/stderr limit (default: 1048576)' }),
+    handler: async (argv) => {
+        if (argv.serve && argv.output)
+            throw new Error('--output cannot be used with --serve');
+        if (argv.serve && !argv.executable)
+            throw new Error('--serve requires --executable');
+        if (!argv.serve &&
+            [argv.executable, argv.cwd, argv.timeoutMs, argv.maxOutputBytes].some((value) => value !== undefined))
+            throw new Error('Execution options require --serve');
+        const document = parse(await readFile(argv.input, 'utf8'));
+        if (argv.serve) {
+            await serveMcp(document, {
+                executable: argv.executable,
+                cwd: argv.cwd,
+                timeoutMs: argv.timeoutMs,
+                maxOutputBytes: argv.maxOutputBytes,
+            });
+        }
+        else {
+            await output(JSON.stringify({ tools: compileMcpTools(document).map((entry) => entry.tool) }, null, 2) + '\n', argv.output);
+        }
+    },
+});
+//# sourceMappingURL=mcp.js.map

package/dist/commands/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;IACnC,OAAO,EAAE,aAAa;IACtB,QAAQ,EAAE,wDAAwD;IAClE,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,+BAA+B,EAAE,CAAC;SACtG,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,8CAA8C,EAAE,CAAC;SAC1G,MAAM,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,6BAA6B,EAAE,CAAC;SAC7F,MAAM,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,kDAAkD,EAAE,CAAC;SACtG,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,uCAAuC,EAAE,CAAC;SACpF,MAAM,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,qDAAqD,EAAE,CAAC;SACzG,MAAM,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,iDAAiD,EAAE,CAAC;IAChH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACtB,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QACvF,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACrF,IACE,CAAC,IAAI,CAAC,KAAK;YACX,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;YAErG,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QAC3D,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,QAAQ,CAAC,QAAQ,EAAE;gBACvB,UAAU,EAAE,IAAI,CAAC,UAAW;gBAC5B,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,cAAc,EAAE,IAAI,CAAC,cAAc;aACpC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CACV,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAC/F,IAAI,CAAC,MAAM,CACZ,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}

package/dist/commands/validate.d.ts

@@ -0,0 +1,4 @@
+export declare const command: import("yargs-file-commands").DefineCommandResult<{}, {
+    input: string;
+}>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,OAAO;;EAalB,CAAC"}

package/dist/commands/validate.js

@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import { parse } from '@clidoc/core';
+import { defineCommand } from 'yargs-file-commands';
+export const command = defineCommand({
+    command: 'validate <input>',
+    describe: 'Validate an OpenCLI JSON or YAML document',
+    builder: (yargs) => yargs.positional('input', {
+        type: 'string',
+        demandOption: true,
+        describe: 'OpenCLI document filename',
+    }),
+    handler: async ({ input }) => {
+        parse(await readFile(input, 'utf8'));
+        process.stdout.write('Valid OpenCLI document\n');
+    },
+});
+//# sourceMappingURL=validate.js.map

package/dist/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;IACnC,OAAO,EAAE,kBAAkB;IAC3B,QAAQ,EAAE,2CAA2C;IACrD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE;QACxB,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,2BAA2B;KACtC,CAAC;IACJ,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,KAAK,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACnD,CAAC;CACF,CAAC,CAAC"}

package/dist/definition.d.ts

@@ -0,0 +1,48 @@
+export declare const info: {
+    title: string;
+    binary: string;
+    version: string;
+    summary: string;
+};
+export declare const commands: (import("yargs-file-commands").DefineCommandResult<{}, {
+    input: string;
+}> | import("yargs-file-commands").DefineCommandResult<{}, {
+    format: string;
+} & {
+    output: string | undefined;
+}> | import("yargs-file-commands").DefineCommandResult<{}, {
+    input: string;
+} & {
+    output: string | undefined;
+}> | import("yargs-file-commands").DefineCommandResult<{}, {
+    module: string;
+} & {
+    adapter: "commander" | "oclif" | "yargs";
+} & {
+    output: string | undefined;
+}> | import("yargs-file-commands").DefineCommandResult<{}, {
+    shell: "bash" | "fish" | "zsh";
+} & {
+    input: string | undefined;
+} & {
+    binary: string | undefined;
+} & {
+    output: string | undefined;
+}> | import("yargs-file-commands").DefineCommandResult<{}, {
+    input: string;
+} & {
+    output: string | undefined;
+} & {
+    serve: boolean;
+} & {
+    executable: string | undefined;
+} & {
+    cwd: string | undefined;
+} & {
+    "timeout-ms": number | undefined;
+} & {
+    "max-output-bytes": number | undefined;
+}>)[];
+/** Documentation and runtime share the exact same command definitions. */
+export declare function cliDocument(): import("@clidoc/core").OpenCliDocument;
+//# sourceMappingURL=definition.d.ts.map

package/dist/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,IAAI;IACf,KAAK;IACL,MAAM;IACN,OAAO;IACP,OAAO;CACR,CAAC;AACF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAA0D,CAAC;AAChF,0EAA0E;AAC1E,wBAAgB,WAAW,2CAS1B"}

package/dist/definition.js

@@ -0,0 +1,28 @@
+import { createRequire } from 'node:module';
+import { fromYargs } from '@clidoc/adapter-yargs';
+import { command as completion } from './commands/completion.js';
+import { command as docgen } from './commands/docgen.js';
+import { command as generate } from './commands/generate.js';
+import { command as mcp } from './commands/mcp.js';
+import { command as markdown } from './commands/markdown.js';
+import { command as validate } from './commands/validate.js';
+const packageJson = createRequire(import.meta.url)('../package.json');
+export const info = {
+    title: 'clidoc',
+    binary: 'clidoc',
+    version: packageJson.version,
+    summary: 'Generate, validate, and publish CLI documentation through OpenCLI.',
+};
+export const commands = [generate, markdown, validate, docgen, completion, mcp];
+/** Documentation and runtime share the exact same command definitions. */
+export function cliDocument() {
+    const document = fromYargs(commands, info);
+    document.global = {
+        flags: [
+            { name: 'help', type: 'boolean', summary: 'Show help' },
+            { name: 'version', type: 'boolean', summary: 'Show version number' },
+        ],
+    };
+    return document;
+}
+//# sourceMappingURL=definition.js.map

package/dist/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAwB,CAAC;AAE7F,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,WAAW,CAAC,OAAO;IAC5B,OAAO,EAAE,oEAAoE;CAC9E,CAAC;AACF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;AAChF,0EAA0E;AAC1E,MAAM,UAAU,WAAW;IACzB,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,GAAG;QAChB,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE;YACvD,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB,EAAE;SACrE;KACF,CAAC;IACF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { cliDocument } from './definition.js';
+/** Run without terminating the embedding process. Commands live in individual files. */
+export declare function runCli(argv: string[]): Promise<void>;
+//# 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":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,wFAAwF;AACxF,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1D"}

package/dist/index.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+import yargs from 'yargs';
+import { fileCommands } from 'yargs-file-commands';
+import { info } from './definition.js';
+export { cliDocument } from './definition.js';
+/** Run without terminating the embedding process. Commands live in individual files. */
+export async function runCli(argv) {
+    await yargs(argv)
+        .scriptName('clidoc')
+        .command(await fileCommands({ commandDirs: [fileURLToPath(new URL('./commands', import.meta.url))] }))
+        .demandCommand(1)
+        .strict()
+        .help()
+        .version(info.version)
+        .exitProcess(false)
+        .fail((message, error) => {
+        throw error ?? new Error(message);
+    })
+        .parseAsync();
+}
+//# 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,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAc;IACzC,MAAM,KAAK,CAAC,IAAI,CAAC;SACd,UAAU,CAAC,QAAQ,CAAC;SACpB,OAAO,CAAC,MAAM,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,YAAY,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SACrG,aAAa,CAAC,CAAC,CAAC;SAChB,MAAM,EAAE;SACR,IAAI,EAAE;SACN,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;SACrB,WAAW,CAAC,KAAK,CAAC;SAClB,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;QACvB,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC;SACD,UAAU,EAAE,CAAC;AAClB,CAAC"}

package/dist/io.d.ts

@@ -0,0 +1,2 @@
+export declare function output(content: string, filename?: string): Promise<void>;
+//# sourceMappingURL=io.d.ts.map

package/dist/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../src/io.ts"],"names":[],"mappings":"AAGA,wBAAsB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ9E"}

package/dist/io.js

@@ -0,0 +1,12 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+export async function output(content, filename) {
+    if (!filename) {
+        process.stdout.write(content);
+        return;
+    }
+    const destination = resolve(filename);
+    await mkdir(dirname(destination), { recursive: true });
+    await writeFile(destination, content);
+}
+//# sourceMappingURL=io.js.map

package/dist/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../src/io.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAe,EAAE,QAAiB;IAC7D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/dist/mcp/compile.d.ts

@@ -0,0 +1,10 @@
+import { type OpenCliDocument } from '@clidoc/core';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+/** A tool definition and its validated, shell-free argument encoder. */
+export type CompiledMcpTool = {
+    tool: Tool;
+    argv: (input: unknown) => string[];
+};
+/** Compile the supported OpenCLI dialect to MCP tools without executing or modifying the spec. */
+export declare function compileMcpTools(source: OpenCliDocument): CompiledMcpTool[];
+//# sourceMappingURL=compile.d.ts.map

package/dist/mcp/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/mcp/compile.ts"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,eAAe,EAAgD,MAAM,cAAc,CAAC;AAC5G,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE/D,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,EAAE,CAAA;CAAE,CAAC;AAmCjF,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,EAAE,CAmF1E"}