@clidoc/core 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,69 @@
+# @clidoc/core
+
+[![npm version](https://img.shields.io/npm/v/%40clidoc%2Fcore)](https://www.npmjs.com/package/@clidoc/core)
+[![npm downloads](https://img.shields.io/npm/dw/%40clidoc%2Fcore)](https://www.npmjs.com/package/@clidoc/core)
+[![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)
+
+TypeScript types, offline JSON Schema validation, YAML/JSON parsing, and Markdown documentation generation for [OpenCLI 1.0.0-alpha.14](https://github.com/bcdxn/opencli). The published package bundles the exact schema pinned in `upstream/opencli/spec.schema.json`.
+
+```ts
+import { parse, validate, renderMarkdown, generatePages } from '@clidoc/core';
+
+const document = parse(sourceText); // JSON or YAML; throws on invalid input
+const result = validate(document); // { valid, errors }
+const markdown = renderMarkdown(document);
+const pages = generatePages(document, { basePath: '/cli' });
+```
+
+`generatePages` returns a landing page and one page per visible command. Each command page includes a generated usage synopsis: required values use `<value>`, optional elements use `[element]`, and repeatable elements use `...`. The synopsis includes visible command flags and inherited global flags. Each page has `id`, `title`, `path`, and Markdown `content`. A command named `<binary> foo-bar` keeps the readable `/commands/foo-bar` route when its suffix is lowercase ASCII letters, digits, and single hyphens (up to 64 characters). Other names use a normalized readable prefix (up to 64 characters), a reserved `~`, and a SHA-256 digest of the full command name. Each route depends only on its command name, so adding unrelated commands does not change existing URLs. The generator rejects a digest collision before returning any pages. This replaces the previous collision-dependent hash suffixes, so URLs for names outside the readable form may change. Landing links use the generated base path. The bundled JSON Schema is also available at `@clidoc/core/schema`.
+
+`validate` checks documents against the vendored JSON Schema and, once that passes, against the logical rules ported from upstream's `validate/validate.go`: positional arguments must not place a required argument after an optional one, `minItems`/`maxItems` are only valid on variadic arguments and flags (with `minItems <= maxItems`), `$FILE` alternative sources must have a matching file declared in `global.config`, flag names and aliases must be unique per command, variadic flags cannot be `required`, and group commands cannot declare `args` or `flags`. Errors use the same `instancePath message` shape as schema errors.
+
+## Adding author-supplied metadata
+
+Adapters generate a document from what your CLI's argument parser already knows, so things like
+`examples`, `exitCodes`, `info.license`/`contact`, `install`, and `global` config are usually
+missing. Add them with `mergeDocument`, then re-validate:
+
+```ts
+import { mergeDocument } from '@clidoc/core';
+
+const documented = mergeDocument(document, {
+  info: { license: { name: 'MIT', spdxId: 'MIT' } },
+  install: [{ name: 'npm', command: 'npm i -g my-cli' }],
+  commands: {
+    'my-cli greet': {
+      examples: [{ title: 'Basic', content: 'my-cli greet Ada' }],
+      exitCodes: [{ code: 1, status: 'BAD_USER_INPUT_ERROR', summary: 'Missing name' }],
+      flags: [{ name: 'language', alternativeSources: [{ type: '$ENV', property: 'LANG' }] }],
+    },
+  },
+});
+```
+
+Plain objects (`info`, `global`, each command) merge recursively. Arrays replace the base array,
+except `examples` and `exitCodes`, which append, and `flags`/`args`, which are merged item-by-item
+matched by `name` &mdash; so you can add `alternativeSources` or a `summary` to one generated flag
+without repeating the rest of it. Commands not present in the generated document are added as-is.
+`mergeDocument` throws an `Error` listing every problem if the merged result fails schema
+validation.
+
+## Shell completion generation
+
+`generateCompletion(document, { shell: 'bash' | 'zsh' | 'fish', binary?: string })`
+validates an OpenCLI document and returns a standalone completion script. It
+supports nested commands, aliases, global/local flags, option and positional
+choices, and hidden entries, with no runtime dependency on Node or the target CLI.
+The optional `binary` overrides only the registered executable name. See the
+[completion guide](https://clidoc.dev/docs/guides/completion) for activation,
+supported syntax, and limitations.
+
+## License
+
+MIT. See [LICENSE](../../LICENSE).
+
+## Author
+
+[Ben Houston](https://ben3d.ca), Sponsored by [Land of Assets](https://landofassets.com).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,25 @@
+# Third-party notices
+
+The OpenCLI 1.0.0-alpha.14 JSON Schema in `schema/spec.schema.json` and the matching compiled schema in `src/schema.ts` are copied from [bcdxn/opencli](https://github.com/bcdxn/opencli), pinned at submodule commit `683d0ca92fc37ccc2626e64db0a8c32f3c4063c0`. They are distributed under the following license.
+
+MIT License
+
+Copyright (c) 2026 bcdxn
+
+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/dist/completion.d.ts

@@ -0,0 +1,10 @@
+import type { OpenCliDocument } from './types.js';
+/** Shells supported by standalone completion scripts. */
+export type CompletionShell = 'bash' | 'zsh' | 'fish';
+export type CompletionOptions = {
+    shell: CompletionShell;
+    binary?: string;
+};
+/** Generate a validated, deterministic script with no runtime dependency on clidoc or the target CLI. */
+export declare function generateCompletion(document: OpenCliDocument, options: CompletionOptions): string;
+//# sourceMappingURL=completion.d.ts.map

package/dist/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,YAAY,CAAC;AAErF,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AACtD,MAAM,MAAM,iBAAiB,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AA4E5E,yGAAyG;AACzG,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CA8BhG"}

package/dist/completion.js

@@ -0,0 +1,255 @@
+import { createHash } from 'node:crypto';
+import { validate } from './index.js';
+function compile(document) {
+    const binary = document.info.binary;
+    const nodes = [{ command: {}, children: new Map() }];
+    const paths = new Map([[binary, 0]]);
+    const commands = Object.entries(document.commands ?? {}).toSorted(([a], [b]) => a.localeCompare(b));
+    for (const [path, command] of commands) {
+        if (path !== binary && !path.startsWith(`${binary} `))
+            throw new Error(`Completion command must start with ${binary}: ${path}`);
+        let parent = 0;
+        let full = binary;
+        for (const part of path.slice(binary.length).trim().split(/\s+/).filter(Boolean)) {
+            full += ` ${part}`;
+            let id = paths.get(full);
+            if (id === undefined) {
+                id = nodes.length;
+                nodes.push({ command: {}, children: new Map() });
+                nodes[parent].children.set(part, id);
+                paths.set(full, id);
+            }
+            parent = id;
+        }
+        nodes[parent].command = command;
+    }
+    // Aliases identify a sibling command and share its complete descendant tree.
+    for (const node of nodes) {
+        for (const id of new Set(node.children.values())) {
+            for (const alias of nodes[id].command.aliases ?? []) {
+                if (!alias || /\s/.test(alias))
+                    throw new Error('Completion command aliases must be single words');
+                const existing = node.children.get(alias);
+                if (existing !== undefined && existing !== id)
+                    throw new Error(`Ambiguous completion alias: ${alias}`);
+                node.children.set(alias, id);
+            }
+        }
+    }
+    const table = new Map();
+    const put = (key, mode, values = []) => table.set(key, { mode, values });
+    for (const [id, node] of nodes.entries()) {
+        const children = [...node.children].filter(([, child]) => !nodes[child].command.hidden);
+        put(`s:${id}`, '', children.map(([name]) => name));
+        for (const [name, child] of children)
+            put(`c:${id}:${name}`, String(child));
+        const flags = new Map();
+        for (const flag of [...(document.global?.flags ?? []), ...(node.command.flags ?? [])]) {
+            flags.set(`--${flag.name}`, flag);
+            for (const alias of flag.aliases ?? [])
+                flags.set(`${alias.length === 1 ? '-' : '--'}${alias}`, flag);
+        }
+        put(`o:${id}`, '', [...flags].filter(([, flag]) => !flag.hidden).map(([name]) => name));
+        for (const [name, flag] of flags)
+            put(`f:${id}:${name}`, flag.type === 'boolean' ? 'boolean' : 'value', (flag.choices ?? []).map((choice) => String(choice.value)));
+        for (const [position, arg] of (node.command.args ?? []).entries())
+            put(`a:${id}:${position}`, arg.variadic ? 'repeat' : 'argument', (arg.choices ?? []).map((choice) => String(choice.value)));
+    }
+    return table;
+}
+/** Generate a validated, deterministic script with no runtime dependency on clidoc or the target CLI. */
+export function generateCompletion(document, options) {
+    const result = validate(document);
+    if (!result.valid)
+        throw new Error(`Invalid OpenCLI document: ${result.errors.join('; ')}`);
+    if (!['bash', 'zsh', 'fish'].includes(options.shell))
+        throw new Error(`Unsupported completion shell: ${options.shell}`);
+    const binary = options.binary ?? document.info.binary;
+    if (!/^[a-zA-Z0-9_][a-zA-Z0-9_.+-]*$/.test(binary))
+        throw new Error('Completion binary must be a single executable name (letters, digits, _, ., +, -)');
+    const table = compile(document);
+    const text = [
+        ...Object.keys(document.commands ?? {}),
+        ...[...table].flatMap(([key, entry]) => [key, ...entry.values]),
+    ];
+    // eslint-disable-next-line no-control-regex -- Shell completion data must not contain control characters.
+    if (text.some((value) => /[\x00-\x1f\x7f]/.test(value)))
+        throw new Error('Completion names and choices cannot contain control characters');
+    const name = `_clidoc_${createHash('sha256').update(binary).digest('hex').slice(0, 16)}`;
+    const shell = options.shell;
+    const fish = shell === 'fish';
+    const quote = (value) => `'${fish ? value.replace(/\\/g, '\\\\').replace(/'/g, "\\'") : value.replace(/'/g, "'\\''")}'`;
+    const cases = [...table]
+        .map(([key, { mode, values }]) => fish
+        ? `    case ${quote(key.replace(/[\\*?[\]]/g, '\\$&'))}\n      set mode ${quote(mode)}\n      set reply ${values.map(quote).join(' ')}`
+        : `    ${quote(key)}) mode=${quote(mode)}; reply=(${values.map(quote).join(' ')});;`)
+        .join('\n');
+    const header = '# Generated by clidoc. Regenerate after changing the CLI schema.\n';
+    return header + (fish ? fishScript(name, binary, cases) : shScript(name, binary, cases, shell));
+}
+function shScript(name, binary, cases, shell) {
+    const bash = shell === 'bash';
+    return `${name}_lookup() {
+  mode=''; reply=()
+  case "$1" in
+${cases}
+  esac
+}
+${name}() {
+  ${bash ? '' : 'emulate -L zsh'}
+  local state=0 pos=0 ended=0 pending='' cur word key mode prefix='' candidate i
+  local -a reply candidates tokens
+  ${bash
+        ? `COMPREPLY=()
+  # Bash splits '=' at COMP_WORDBREAKS; reconstruct tokens up to the cursor.
+  for ((i=1; i<=COMP_CWORD; i++)); do
+    word="\${COMP_WORDS[i]}"
+    if [[ "$word" == '=' && \${#tokens[@]} -gt 0 ]]; then
+      tokens[\${#tokens[@]}-1]+='='
+    elif [[ \${#tokens[@]} -gt 0 && "\${tokens[\${#tokens[@]}-1]}" == *= ]]; then
+      tokens[\${#tokens[@]}-1]+="$word"
+    else
+      tokens+=("$word")
+    fi
+  done
+  cur="\${tokens[\${#tokens[@]}-1]}"
+  unset "tokens[\${#tokens[@]}-1]"`
+        : `tokens=("\${(@)words[2,CURRENT-1]}")
+  (( CURRENT > 2 )) || tokens=()
+  cur="\${words[CURRENT]}"`}
+  for word in "\${tokens[@]}"; do
+    if [[ -n "$pending" ]]; then pending=''; continue; fi
+    if [[ "$ended" == 0 && "$word" == '--' ]]; then ended=1; continue; fi
+    if [[ "$ended" == 0 && "$word" == -* ]]; then
+      ${name}_lookup "f:$state:\${word%%=*}"
+      if [[ "$mode" == value && "$word" != *=* ]]; then pending="f:$state:$word"; fi
+      continue
+    fi
+    if [[ "$ended" == 0 && "$pos" == 0 ]]; then
+      ${name}_lookup "c:$state:$word"
+      if [[ -n "$mode" ]]; then state="$mode"; continue; fi
+    fi
+    ${name}_lookup "a:$state:$pos"
+    [[ "$mode" == repeat ]] || pos=$((pos + 1))
+  done
+  if [[ -n "$pending" ]]; then
+    ${name}_lookup "$pending"
+    candidates=("\${reply[@]}")
+  elif [[ "$ended" == 0 && "$cur" == --*=* ]]; then
+    key="\${cur%%=*}"
+    prefix="$key="
+    cur="\${cur#*=}"
+    ${name}_lookup "f:$state:$key"
+    candidates=("\${reply[@]}")
+  elif [[ "$ended" == 0 && "$cur" == -* ]]; then
+    ${name}_lookup "o:$state"
+    candidates=("\${reply[@]}")
+  else
+    ${name}_lookup "a:$state:$pos"
+    candidates=("\${reply[@]}")
+    if [[ "$ended" == 0 && "$pos" == 0 ]]; then
+      ${name}_lookup "s:$state"
+      candidates+=("\${reply[@]}")
+    fi
+  fi
+  ${bash
+        ? `for candidate in "\${candidates[@]}"; do
+    [[ "$candidate" == "$cur"* ]] && COMPREPLY+=("$prefix$candidate")
+  done
+  if [[ \${#candidates[@]} == 0 && "$cur" != -* ]]; then
+    while IFS= read -r candidate; do COMPREPLY+=("$prefix$candidate"); done < <(compgen -f -- "$cur")
+  fi
+  # Readline replaces only the value when '=' is a word break.
+  if [[ -n "$prefix" && "$COMP_WORDBREAKS" == *'='* ]]; then
+    for ((i=0; i<\${#COMPREPLY[@]}; i++)); do COMPREPLY[i]="\${COMPREPLY[i]#*=}"; done
+  fi`
+        : `if (( \${#candidates[@]} )); then
+    [[ -z "$prefix" ]] || compset -P '*='
+    compadd -- "\${candidates[@]}"
+  elif [[ "$cur" != -* ]]; then
+    [[ -z "$prefix" ]] || compset -P '*='
+    _files
+  fi`}
+  return 0
+}
+${bash ? `complete -o filenames -F ${name} -- '${binary}'` : `compdef ${name} '${binary}'`}
+`;
+}
+function fishScript(name, binary, cases) {
+    // Fish's no-scope-shadowing allows the helper to update caller-local reply/mode.
+    const lookup = (key) => `${name}_lookup ${key}`;
+    return `function ${name}_lookup --no-scope-shadowing
+  set mode ''; set reply
+  switch "$argv[1]"
+${cases}
+  end
+end
+function ${name}
+  set -l tokens (commandline -opc)
+  set -e tokens[1]
+  set -l cur (commandline -ct)
+  set -l state 0
+  set -l pos 0
+  set -l ended 0
+  set -l pending ''
+  set -l mode ''
+  set -l reply
+  set -l candidates
+  set -l prefix ''
+  for word in $tokens
+    if test -n "$pending"
+      set pending ''; continue
+    end
+    if test $ended = 0; and test "$word" = --
+      set ended 1; continue
+    end
+    if test $ended = 0; and string match -q -- '-*' "$word"
+      set -l flag (string split -m 1 '=' -- "$word")[1]
+      ${lookup('"f:$state:$flag"')}
+      if test "$mode" = value; and not string match -q '*=*' -- "$word"
+        set pending "f:$state:$word"
+      end
+      continue
+    end
+    if test $ended = 0; and test $pos = 0
+      ${lookup('"c:$state:$word"')}
+      if test -n "$mode"
+        set state $mode; continue
+      end
+    end
+    ${lookup('"a:$state:$pos"')}
+    if test "$mode" != repeat; set pos (math $pos + 1); end
+  end
+  if test -n "$pending"
+    ${lookup('"$pending"')}
+    set candidates $reply
+  else if test $ended = 0; and string match -q -- '--*=*' "$cur"
+    set -l pair (string split -m 1 '=' -- "$cur")
+    set prefix "$pair[1]="
+    set cur "$pair[2]"
+    ${lookup('"f:$state:$pair[1]"')}
+    set candidates $reply
+  else if test $ended = 0; and string match -q -- '-*' "$cur"
+    ${lookup('"o:$state"')}
+    set candidates $reply
+  else
+    ${lookup('"a:$state:$pos"')}
+    set candidates $reply
+    if test $ended = 0; and test $pos = 0
+      ${lookup('"s:$state"')}
+      set -a candidates $reply
+    end
+  end
+  for candidate in $candidates
+    printf '%s\\n' "$prefix$candidate"
+  end
+  if test (count $candidates) = 0; and not string match -q -- '-*' "$cur"
+    for candidate in (__fish_complete_path "$cur")
+      printf '%s\\n' "$prefix$candidate"
+    end
+  end
+end
+complete -c '${binary}' -f -a '(${name})'
+`;
+}
+//# sourceMappingURL=completion.js.map

package/dist/completion.js.map

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

package/dist/discovery.d.ts

@@ -0,0 +1,11 @@
+import type { OpenCliDocument } from './types.js';
+/** Hidden subcommand upstream OpenCLI adapters use for machine discovery. */
+export declare const OPENCLI_DISCOVERY_COMMAND: '__opencli';
+/**
+ * If argv requests the OpenCLI document (`__opencli` subcommand, optionally with upstream's
+ * `-o`/`--out <file>` flag), write it — JSON, 2-space indented, single trailing newline — to that
+ * file or to stdout, and return true. Otherwise return false without writing anything, so the
+ * caller can continue parsing argv as usual.
+ */
+export declare function handleOpenCliRequest(argv: readonly string[], document: () => OpenCliDocument, write?: (chunk: string) => void): Promise<boolean>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,EAAG,WAAoB,CAAC;AAoB9D;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,MAAM,eAAe,EAC/B,KAAK,GAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAA6C,GACtE,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/dist/discovery.js

@@ -0,0 +1,42 @@
+import { writeOpenCliDocument } from './docgen.js';
+/** Hidden subcommand upstream OpenCLI adapters use for machine discovery. */
+export const OPENCLI_DISCOVERY_COMMAND = '__opencli';
+/** Sentinel returned by {@link parseOutArg} for argv this module doesn't recognize. */
+const INVALID = Symbol('invalid');
+/**
+ * Parse `-o <file>` / `--out <file>` / `--out=<file>` from the args following `__opencli`,
+ * matching upstream OpenCLI's `ocobra` adapter flag. Returns `undefined` for no args (write to
+ * stdout), the file path for a recognized flag, or {@link INVALID} for anything else.
+ */
+function parseOutArg(args) {
+    if (args.length === 0)
+        return undefined;
+    if (args.length === 1) {
+        const match = /^(?:-o|--out)=(.+)$/.exec(args[0]);
+        return match ? match[1] : INVALID;
+    }
+    if (args.length === 2 && (args[0] === '-o' || args[0] === '--out'))
+        return args[1];
+    return INVALID;
+}
+/**
+ * If argv requests the OpenCLI document (`__opencli` subcommand, optionally with upstream's
+ * `-o`/`--out <file>` flag), write it — JSON, 2-space indented, single trailing newline — to that
+ * file or to stdout, and return true. Otherwise return false without writing anything, so the
+ * caller can continue parsing argv as usual.
+ */
+export async function handleOpenCliRequest(argv, document, write = (chunk) => process.stdout.write(chunk)) {
+    if (argv[0] !== OPENCLI_DISCOVERY_COMMAND)
+        return false;
+    const outFile = parseOutArg(argv.slice(1));
+    if (outFile === INVALID)
+        return false;
+    if (outFile === undefined) {
+        write(`${JSON.stringify(document(), null, 2)}\n`);
+    }
+    else {
+        await writeOpenCliDocument(document(), outFile);
+    }
+    return true;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,WAAoB,CAAC;AAE9D,uFAAuF;AACvF,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAElC;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAuB;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IACrC,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IACnF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAuB,EACvB,QAA+B,EAC/B,KAAK,GAA4B,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;IAEvE,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,yBAAyB;QAAE,OAAO,KAAK,CAAC;IACxD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;SAAM,CAAC;QACN,MAAM,oBAAoB,CAAC,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/docgen.d.ts

@@ -0,0 +1,22 @@
+import type { InfoObject, OpenCliDocument } from './types.js';
+/** The minimal shape of `package.json` used to derive an {@link InfoObject}. */
+export type PackageJsonLike = {
+    name?: string;
+    version?: string;
+    description?: string;
+    bin?: string | Record<string, string>;
+};
+/**
+ * Derive an {@link InfoObject} from a parsed `package.json`, so adapters don't each need their
+ * own `title`/`binary`/`version` bookkeeping. `overrides` wins over anything derived from `pkg`,
+ * and is required for whatever `pkg` cannot express (e.g. a package that exposes several binaries).
+ */
+export declare function infoFromPackageJson(pkg: PackageJsonLike, overrides?: Partial<InfoObject>): InfoObject;
+/** Output format for {@link writeOpenCliDocument}. */
+export type DocumentFormat = 'json' | 'yaml' | 'markdown';
+/**
+ * Render `document` (JSON, YAML, or Markdown) and write it to `output`, or to stdout if `output`
+ * is omitted. Shared by every adapter's docgen command and by `handleOpenCliRequest`.
+ */
+export declare function writeOpenCliDocument(document: OpenCliDocument, output?: string, format?: DocumentFormat): Promise<void>;
+//# sourceMappingURL=docgen.d.ts.map

package/dist/docgen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docgen.d.ts","sourceRoot":"","sources":["../src/docgen.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE9D,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC,CAAC;AAOF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,EAAE,SAAS,GAAE,OAAO,CAAC,UAAU,CAAM,GAAG,UAAU,CAYzG;AAED,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1D;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,GAAE,cAAuB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/docgen.js

@@ -0,0 +1,44 @@
+import { writeFile } from 'node:fs/promises';
+import { stringify as stringifyYaml } from 'yaml';
+import { renderMarkdown } from './index.js';
+/** Strip a npm scope (`@scope/name` -> `name`) for use as a default binary name. */
+function unscopedName(name) {
+    return name.replace(/^@[^/]+\//, '');
+}
+/**
+ * Derive an {@link InfoObject} from a parsed `package.json`, so adapters don't each need their
+ * own `title`/`binary`/`version` bookkeeping. `overrides` wins over anything derived from `pkg`,
+ * and is required for whatever `pkg` cannot express (e.g. a package that exposes several binaries).
+ */
+export function infoFromPackageJson(pkg, overrides = {}) {
+    const binary = overrides.binary ??
+        (typeof pkg.bin === 'object' && pkg.bin !== null ? Object.keys(pkg.bin)[0] : undefined) ??
+        (pkg.name ? unscopedName(pkg.name) : undefined);
+    if (!binary)
+        throw new Error('infoFromPackageJson: could not determine a binary name; pass overrides.binary');
+    const version = overrides.version ?? pkg.version;
+    if (!version)
+        throw new Error('infoFromPackageJson: package.json has no version; pass overrides.version');
+    const title = overrides.title ?? pkg.name ?? binary;
+    const info = { ...overrides, title, binary, version };
+    if (info.summary === undefined && pkg.description !== undefined)
+        info.summary = pkg.description;
+    return info;
+}
+/**
+ * Render `document` (JSON, YAML, or Markdown) and write it to `output`, or to stdout if `output`
+ * is omitted. Shared by every adapter's docgen command and by `handleOpenCliRequest`.
+ */
+export async function writeOpenCliDocument(document, output, format = 'json') {
+    const content = format === 'markdown'
+        ? renderMarkdown(document)
+        : format === 'yaml'
+            ? stringifyYaml(document)
+            : `${JSON.stringify(document, null, 2)}\n`;
+    if (output === undefined) {
+        process.stdout.write(content);
+        return;
+    }
+    await writeFile(output, content);
+}
+//# sourceMappingURL=docgen.js.map

package/dist/docgen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docgen.js","sourceRoot":"","sources":["../src/docgen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAW5C,oFAAoF;AACpF,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAoB,EAAE,SAAS,GAAwB,EAAE;IAC3F,MAAM,MAAM,GACV,SAAS,CAAC,MAAM;QAChB,CAAC,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACvF,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAC;IAC9G,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC;IACjD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;IAC1G,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,IAAI,GAAG,CAAC,IAAI,IAAI,MAAM,CAAC;IACpD,MAAM,IAAI,GAAe,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAClE,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS;QAAE,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,WAAW,CAAC;IAChG,OAAO,IAAI,CAAC;AACd,CAAC;AAKD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAyB,EACzB,MAAe,EACf,MAAM,GAAmB,MAAM;IAE/B,MAAM,OAAO,GACX,MAAM,KAAK,UAAU;QACnB,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC;QAC1B,CAAC,CAAC,MAAM,KAAK,MAAM;YACjB,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC;YACzB,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IACjD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,MAAM,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+export * from './discovery.js';
+export * from './merge.js';
+export * from './docgen.js';
+export * from './completion.js';
+import type { OpenCliDocument } from './types.js';
+export type * from './types.js';
+/** Supported version of the vendored OpenCLI schema. */
+export declare const OPENCLI_VERSION: '1.0.0-alpha.14';
+/** Vendored JSON Schema used to validate OpenCLI documents. */
+export declare const openCliSchema: object;
+/** Validate against the exact vendored upstream JSON Schema, plus upstream's logical checks. */
+export declare function validate(document: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/** Parse JSON or YAML and reject documents that do not match the specification. */
+export declare function parse(input: string, options?: {
+    format?: 'json' | 'yaml';
+}): OpenCliDocument;
+/** Render a complete Markdown reference, preserving spec-authored Markdown prose. */
+export declare function renderMarkdown(document: OpenCliDocument): string;
+export type GeneratedPage = {
+    id: string;
+    title: string;
+    path: string;
+    content: string;
+};
+/** Produce a landing page and one page per visible command with safe, stable routes. */
+export declare function generatePages(document: OpenCliDocument, options?: {
+    basePath?: string;
+}): GeneratedPage[];
+//# 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":"AACA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAMhC,OAAO,KAAK,EACV,eAAe,EAQhB,MAAM,YAAY,CAAC;AACpB,mBAAmB,YAAY,CAAC;AAEhC,wDAAwD;AACxD,eAAO,MAAM,eAAe,EAAG,gBAAyB,CAAC;AACzD,+DAA+D;AAC/D,eAAO,MAAM,aAAa,QAAS,CAAC;AAKpC,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAUhF;AAED,mFAAmF;AACnF,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAO,GAAG,eAAe,CAwBhG;AAyND,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAOhE;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AA4BzF,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,aAAa,EAAE,CAkC7G"}