@clidoc/cli 0.1.0

package/dist/mcp/compile.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { validate } from '@clidoc/core';
+const required = (item) => item.required === true || (item.minItems ?? 0) > 0;
+const ownValue = (values, key) => values && Object.hasOwn(values, key) ? values[key] : undefined;
+const identifier = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+function objectSchema(items) {
+    const properties = Object.fromEntries(items.map((item) => {
+        if (item.name === '__proto__')
+            throw new Error('Unsupported parameter name __proto__');
+        const scalar = { type: item.type ?? 'string' };
+        if (item.choices?.length)
+            scalar.enum = item.choices.map((choice) => choice.value);
+        const schema = item.variadic
+            ? {
+                type: 'array',
+                items: scalar,
+                minItems: item.minItems ?? (required(item) ? 1 : 0),
+                ...(item.maxItems === undefined ? {} : { maxItems: item.maxItems }),
+            }
+            : scalar;
+        if (item.description ?? item.summary)
+            schema.description = item.description ?? item.summary;
+        // Defaults are descriptive only: the executable remains responsible for applying them.
+        if ('default' in item && item.default !== undefined && !item.variadic)
+            schema.default = item.default;
+        return [item.name, schema];
+    }));
+    return {
+        type: 'object',
+        properties,
+        required: items.filter(required).map((item) => item.name),
+        additionalProperties: false,
+    };
+}
+/** Compile the supported OpenCLI dialect to MCP tools without executing or modifying the spec. */
+export function compileMcpTools(source) {
+    const result = validate(source);
+    if (!result.valid)
+        throw new Error(`Invalid OpenCLI document: ${result.errors.join('; ')}`);
+    const document = structuredClone(source);
+    const ajv = new Ajv2020({ allErrors: true, strict: false, ownProperties: true });
+    const binary = document.info.binary;
+    const names = new Set();
+    return Object.entries(document.commands ?? {})
+        .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .filter(([, command]) => !command.hidden && command.kind !== 'group')
+        .map(([path, command]) => {
+        if (path !== binary && !path.startsWith(`${binary} `))
+            throw new Error(`${path}: command must start with binary ${binary}`);
+        const suffix = path.slice(binary.length).trim();
+        const words = suffix ? suffix.split(' ') : [];
+        if (words.some((word) => !identifier.test(word)))
+            throw new Error(`${path}: unsupported command path`);
+        const args = command.args ?? [];
+        const flagsByName = new Map();
+        for (const flag of document.global?.flags ?? []) {
+            if (flagsByName.has(flag.name))
+                throw new Error(`${path}: duplicate global flag ${flag.name}`);
+            flagsByName.set(flag.name, flag);
+        }
+        for (const flag of command.flags ?? [])
+            flagsByName.set(flag.name, flag);
+        const allFlags = [...flagsByName.values()];
+        for (const flag of allFlags) {
+            if (!identifier.test(flag.name))
+                throw new Error(`${path}: unsupported flag name ${flag.name}`);
+            if (flag.hidden && required(flag))
+                throw new Error(`${path}: hidden required flag ${flag.name} cannot be exposed`);
+            if (flag.variadic && flag.type === 'boolean')
+                throw new Error(`${path}: variadic boolean flag ${flag.name} is unsupported`);
+        }
+        const flags = allFlags.filter((flag) => !flag.hidden);
+        const argNames = new Set();
+        args.forEach((arg, index) => {
+            if (argNames.has(arg.name))
+                throw new Error(`${path}: duplicate argument ${arg.name}`);
+            argNames.add(arg.name);
+            if (arg.passthrough)
+                throw new Error(`${path}: passthrough argument ${arg.name} is unsupported`);
+            if (arg.variadic && index !== args.length - 1)
+                throw new Error(`${path}: variadic argument must be last`);
+        });
+        const inputSchema = {
+            type: 'object',
+            properties: { arguments: objectSchema(args), flags: objectSchema(flags) },
+            required: [...(args.some(required) ? ['arguments'] : []), ...(flags.some(required) ? ['flags'] : [])],
+            additionalProperties: false,
+        };
+        const check = ajv.compile(inputSchema);
+        const readable = path.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 43);
+        const name = `${readable}_${createHash('sha256').update(path).digest('hex').slice(0, 20)}`;
+        if (names.has(name))
+            throw new Error(`${path}: MCP tool name collision`);
+        names.add(name);
+        return {
+            tool: { name, title: path, description: command.description ?? command.summary ?? path, inputSchema },
+            argv(input) {
+                if (!check(input))
+                    throw new Error(`Invalid tool arguments: ${ajv.errorsText(check.errors)}`);
+                const values = input;
+                const argv = [...words];
+                for (const flag of flags) {
+                    const value = ownValue(values.flags, flag.name);
+                    if (value === undefined)
+                        continue;
+                    for (const entry of Array.isArray(value) ? value : [value]) {
+                        // Explicit false must override a CLI default of true.
+                        argv.push(flag.type === 'boolean' && entry === true ? `--${flag.name}` : `--${flag.name}=${String(entry)}`);
+                    }
+                }
+                const positional = [];
+                let gap = false;
+                for (const arg of args) {
+                    const value = ownValue(values.arguments, arg.name);
+                    if (value === undefined) {
+                        gap = true;
+                        continue;
+                    }
+                    if (gap)
+                        throw new Error(`Cannot supply ${arg.name} after an omitted positional argument`);
+                    positional.push(...(Array.isArray(value) ? value : [value]).map(String));
+                }
+                if (positional.length)
+                    argv.push('--', ...positional);
+                if (argv.some((value) => value.includes('\0')))
+                    throw new Error('CLI arguments cannot contain NUL bytes');
+                return argv;
+            },
+        };
+    });
+}
+//# sourceMappingURL=compile.js.map

package/dist/mcp/compile.js.map

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

package/dist/mcp/index.d.ts

@@ -0,0 +1,15 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { OpenCliDocument } from '@clidoc/core';
+export { compileMcpTools, type CompiledMcpTool } from './compile.js';
+/** Executable and process limits are fixed by the host, never by tool inputs. */
+export type McpServerOptions = {
+    executable: string;
+    cwd?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+};
+/** Create an MCP server for a trusted local CLI. Connect it to a transport or call serveMcp. */
+export declare function createMcpServer(document: OpenCliDocument, options: McpServerOptions): Server;
+/** Connect a server to stdin/stdout; callers can close the returned server. */
+export declare function serveMcp(document: OpenCliDocument, options: McpServerOptions): Promise<Server>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAErE,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAyDF,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAyC5F;AAED,+EAA+E;AAC/E,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBpG"}

package/dist/mcp/index.js

@@ -0,0 +1,133 @@
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { compileMcpTools } from './compile.js';
+export { compileMcpTools } from './compile.js';
+const packageJson = createRequire(import.meta.url)('../../package.json');
+const failure = (text) => ({ content: [{ type: 'text', text }], isError: true });
+function execute(argv, options, signal) {
+    if (signal.aborted)
+        return Promise.resolve(failure('CLI invocation canceled'));
+    return new Promise((resolve) => {
+        const child = spawn(options.executable, argv, {
+            cwd: options.cwd,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        let size = 0;
+        let finished = false;
+        const finish = (result) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            signal.removeEventListener('abort', cancel);
+            resolve(result);
+        };
+        const stop = (message) => {
+            child.kill('SIGKILL');
+            child.stdout.destroy();
+            child.stderr.destroy();
+            finish(failure(message));
+        };
+        const cancel = () => stop('CLI invocation canceled');
+        const timer = setTimeout(() => stop(`CLI timed out after ${options.timeoutMs} ms`), options.timeoutMs);
+        signal.addEventListener('abort', cancel, { once: true });
+        const collect = (chunks, chunk) => {
+            if (finished)
+                return;
+            size += chunk.length;
+            if (size > options.maxOutputBytes)
+                stop(`CLI output exceeded ${options.maxOutputBytes} bytes`);
+            else
+                chunks.push(chunk);
+        };
+        child.stdout.on('data', (chunk) => collect(stdout, chunk));
+        child.stderr.on('data', (chunk) => collect(stderr, chunk));
+        child.on('error', (error) => finish(failure(`Cannot run CLI: ${error.message}`)));
+        child.on('close', (code, exitSignal) => {
+            const output = {
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+                exitCode: code,
+                signal: exitSignal,
+            };
+            finish({ content: [{ type: 'text', text: JSON.stringify(output) }], isError: code !== 0 });
+        });
+    });
+}
+/** Create an MCP server for a trusted local CLI. Connect it to a transport or call serveMcp. */
+export function createMcpServer(document, options) {
+    if (!options.executable || options.executable.includes('\0'))
+        throw new Error('An explicit executable is required');
+    const limits = {
+        ...options,
+        timeoutMs: options.timeoutMs ?? 30000,
+        maxOutputBytes: options.maxOutputBytes ?? 1048576,
+    };
+    for (const [name, value] of [
+        ['timeoutMs', limits.timeoutMs],
+        ['maxOutputBytes', limits.maxOutputBytes],
+    ])
+        if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647)
+            throw new Error(`${name} must be an integer between 1 and 2147483647`);
+    const compiled = compileMcpTools(document);
+    const tools = new Map(compiled.map((entry) => [entry.tool.name, entry]));
+    const server = new Server({ name: 'clidoc-mcp', version: packageJson.version }, { capabilities: { tools: {} } });
+    const active = new Set();
+    // The SDK exposes onclose as a callback, not an EventTarget.
+    // oxlint-disable-next-line unicorn/prefer-add-event-listener
+    server.onclose = () => {
+        for (const controller of active)
+            controller.abort();
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: compiled.map((entry) => entry.tool) }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const entry = tools.get(request.params.name);
+        if (!entry)
+            return failure(`Unknown tool: ${request.params.name}`);
+        const controller = new AbortController();
+        const cancel = () => controller.abort();
+        extra.signal.addEventListener('abort', cancel, { once: true });
+        if (extra.signal.aborted)
+            controller.abort();
+        active.add(controller);
+        try {
+            return await execute(entry.argv(request.params.arguments ?? {}), limits, controller.signal);
+        }
+        catch (error) {
+            return failure(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            extra.signal.removeEventListener('abort', cancel);
+            active.delete(controller);
+        }
+    });
+    return server;
+}
+/** Connect a server to stdin/stdout; callers can close the returned server. */
+export async function serveMcp(document, options) {
+    const server = createMcpServer(document, options);
+    await server.connect(new StdioServerTransport());
+    const onclose = server.onclose;
+    const shutdown = () => {
+        void server.close();
+    };
+    // The SDK exposes onclose as a callback, not an EventTarget.
+    // oxlint-disable-next-line unicorn/prefer-add-event-listener
+    server.onclose = () => {
+        process.stdin.removeListener('end', shutdown);
+        process.removeListener('SIGINT', shutdown);
+        process.removeListener('SIGTERM', shutdown);
+        onclose();
+    };
+    process.stdin.once('end', shutdown);
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    return server;
+}
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

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

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@clidoc/cli",
+  "version": "0.1.0",
+  "description": "Generate and validate OpenCLI documentation",
+  "keywords": [
+    "cli",
+    "docs",
+    "documentation",
+    "opencli",
+    "yargs"
+  ],
+  "homepage": "https://clidoc.dev",
+  "bugs": {
+    "url": "https://github.com/bhouston/clidoc/issues"
+  },
+  "license": "MIT",
+  "author": "Ben Houston <ben@ben3d.ca> (https://ben3d.ca)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhouston/clidoc.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "clidoc": "./dist/bin.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "tsc": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clidoc/adapter-commander": "^0.1.0",
+    "@clidoc/adapter-oclif": "^0.1.0",
+    "@clidoc/adapter-yargs": "^0.1.0",
+    "@clidoc/core": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ajv": "^8.20.0",
+    "yargs": "^18.1.0",
+    "yargs-file-commands": "^2.0.1"
+  },
+  "devDependencies": {
+    "@types/yargs": "^17.0.35"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,12 @@
+#!/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;
+}

package/src/commands/completion.ts

@@ -0,0 +1,28 @@
+import { readFile } from 'node:fs/promises';
+import { generateCompletion, parse, type CompletionShell } 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'] as const,
+        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 as CompletionShell, binary: argv.binary }),
+      argv.output,
+    );
+  },
+});

package/src/commands/docgen.ts

@@ -0,0 +1,21 @@
+import { writeOpenCliDocument } from '@clidoc/core';
+import type { DocumentFormat } 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'] as const,
+        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 as DocumentFormat);
+  },
+});

package/src/commands/generate.ts

@@ -0,0 +1,42 @@
+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'] as const,
+        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);
+  },
+});

package/src/commands/markdown.ts

@@ -0,0 +1,16 @@
+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);
+  },
+});

package/src/commands/mcp.ts

@@ -0,0 +1,42 @@
+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,
+      );
+    }
+  },
+});

package/src/commands/validate.ts

@@ -0,0 +1,18 @@
+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');
+  },
+});

package/src/definition.ts

@@ -0,0 +1,29 @@
+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') as { version: string };
+
+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;
+}

package/src/index.ts

@@ -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: string[]): Promise<void> {
+  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();
+}

package/src/io.ts

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