@clidoc/core 0.1.0

package/src/index.ts

@@ -0,0 +1,359 @@
+import { createHash } from 'node:crypto';
+export * from './discovery.js';
+export * from './merge.js';
+export * from './docgen.js';
+export * from './completion.js';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import * as formatsModule from 'ajv-formats';
+import { parse as parseYaml } from 'yaml';
+import { schema } from './schema.js';
+import { logicalErrors } from './logical.js';
+import type {
+  OpenCliDocument,
+  CommandItemObject,
+  FlagItemObject,
+  LicenseObject,
+  ContactObject,
+  GlobalObject,
+  ChoiceObject,
+  AlternativeSource,
+} from './types.js';
+export type * from './types.js';
+
+/** Supported version of the vendored OpenCLI schema. */
+export const OPENCLI_VERSION = '1.0.0-alpha.14' as const;
+/** Vendored JSON Schema used to validate OpenCLI documents. */
+export const openCliSchema = schema;
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+(formatsModule.default as unknown as (instance: Ajv2020) => void)(ajv);
+const check = ajv.compile(schema);
+
+/** Validate against the exact vendored upstream JSON Schema, plus upstream's logical checks. */
+export function validate(document: unknown): { valid: boolean; errors: string[] } {
+  const schemaValid = check(document);
+  if (!schemaValid) {
+    return {
+      valid: false,
+      errors: (check.errors ?? []).map((error) => `${error.instancePath || '/'} ${error.message ?? 'is invalid'}`),
+    };
+  }
+  const errors = logicalErrors(document as OpenCliDocument);
+  return { valid: errors.length === 0, errors };
+}
+
+/** Parse JSON or YAML and reject documents that do not match the specification. */
+export function parse(input: string, options: { format?: 'json' | 'yaml' } = {}): OpenCliDocument {
+  const looksLikeJson = /^\s*[{[]/.test(input);
+  const format = options.format ?? (looksLikeJson ? 'json' : 'yaml');
+  let document: unknown;
+  if (format === 'json') {
+    try {
+      document = JSON.parse(input);
+    } catch (error) {
+      throw new Error(`Invalid OpenCLI JSON: ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error,
+      });
+    }
+  } else {
+    try {
+      document = parseYaml(input, { uniqueKeys: true });
+    } catch (error) {
+      throw new Error(`Invalid OpenCLI YAML: ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error,
+      });
+    }
+  }
+  const result = validate(document);
+  if (!result.valid) throw new Error(`Invalid OpenCLI document: ${result.errors.join('; ')}`);
+  return document as OpenCliDocument;
+}
+
+const heading = (level: number, text: string) => `${'#'.repeat(level)} ${text}\n\n`;
+const escapeCell = (value: unknown) => String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+function code(value: string): string {
+  const longest = Math.max(0, ...Array.from(value.matchAll(/`+/g), (match) => match[0].length));
+  const delim = '`'.repeat(longest + 1);
+  const padded = value.startsWith('`') || value.endsWith('`') ? ` ${value} ` : value;
+  return `${delim}${padded}${delim}`;
+}
+const values = (choices: ChoiceObject[]) =>
+  choices
+    .map((choice) => (choice.description ? `${choice.value} (${choice.description})` : String(choice.value)))
+    .join(', ');
+const details = (item: {
+  summary?: string;
+  description?: string;
+  choices?: ChoiceObject[];
+  variadic?: boolean;
+  minItems?: number;
+  maxItems?: number;
+  default?: string | number | boolean;
+  aliases?: string[];
+  hint?: string;
+  passthrough?: boolean;
+  alternativeSources?: AlternativeSource[];
+}) => {
+  const parts = [item.description ?? item.summary ?? ''];
+  if (item.aliases?.length) parts.push(`Aliases: ${item.aliases.map(code).join(', ')}`);
+  if (item.variadic)
+    parts.push(
+      `Variadic${item.minItems === undefined ? '' : ` (min ${item.minItems})`}${item.maxItems === undefined ? '' : ` (max ${item.maxItems})`}`,
+    );
+  if (item.choices?.length) parts.push(`Choices: ${values(item.choices)}`);
+  if (item.default !== undefined) parts.push(`Default: ${code(String(item.default))}`);
+  if (item.hint) parts.push(`Hint: ${item.hint}`);
+  if (item.passthrough) parts.push('Passthrough');
+  if (item.alternativeSources?.length)
+    parts.push(
+      item.alternativeSources
+        .map((source) => `${source.type === '$ENV' ? 'Env' : 'File'}: ${code(source.property)}`)
+        .join(', '),
+    );
+  return parts.filter(Boolean).join('; ');
+};
+function table(headers: string[], rows: unknown[][]): string {
+  if (!rows.length) return '';
+  return `| ${headers.join(' | ')} |\n| ${headers.map(() => '---').join(' | ')} |\n${rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`).join('\n')}\n\n`;
+}
+function fenced(content: string, language = 'sh'): string {
+  const longest = Math.max(0, ...Array.from(content.matchAll(/`+/g), (match) => match[0].length));
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+  return `${fence}${language}\n${content}\n${fence}\n\n`;
+}
+function placeholder(name: string, hint?: string): string {
+  const value = hint?.trim();
+  if (value?.startsWith('<') && value.endsWith('>')) return value;
+  return `<${value || name}>`;
+}
+function repeatable(token: string, required: boolean): string {
+  return required ? `${token} [${token}]...` : `[${token}]...`;
+}
+function renderArgumentUsage(arg: NonNullable<CommandItemObject['args']>[number]): string {
+  const token = placeholder(arg.name);
+  const required = Boolean(arg.required || (arg.minItems ?? 0) > 0);
+  if (arg.passthrough) {
+    const operand = `${token}${arg.variadic ? '...' : ''}`;
+    return required ? `-- ${operand}` : `[-- ${operand}]`;
+  }
+  if (arg.variadic) return required ? `${token}...` : `[${token}...]`;
+  return required ? token : `[${token}]`;
+}
+function renderFlagUsage(flag: FlagItemObject): string {
+  const token = `--${flag.name}${flag.type === 'boolean' ? '' : ` ${placeholder(flag.name, flag.hint)}`}`;
+  const required = Boolean(flag.required || (flag.minItems ?? 0) > 0);
+  if (flag.variadic) return repeatable(token, required);
+  return required ? token : `[${token}]`;
+}
+function commandInvocation(name: string, binary: string): { command: string; syntax: string[] } {
+  const parts: string[] = [];
+  const allParts = name.trim().split(/\s+/);
+  for (const part of allParts) {
+    if (part === '--' || ['<', '{', '['].some((marker) => part.includes(marker))) break;
+    parts.push(part);
+  }
+  const relative = parts.join(' ');
+  const command =
+    !binary || relative === binary || relative.startsWith(`${binary} `) ? relative : `${binary} ${relative}`;
+  return { command, syntax: allParts.slice(parts.length) };
+}
+function renderUsage(name: string, command: CommandItemObject, binary: string, globalFlags: FlagItemObject[]): string {
+  const combinedFlags = new Map(globalFlags.map((flag) => [flag.name, flag]));
+  for (const flag of command.flags ?? []) combinedFlags.set(flag.name, flag);
+  const flags = [...combinedFlags.values()].filter((flag) => !flag.hidden).map(renderFlagUsage);
+  const args = (command.args ?? []).map(renderArgumentUsage);
+  const invocation = commandInvocation(name, binary);
+  const legacyArgs = args.length
+    ? []
+    : invocation.syntax.filter((part) => !/^\[?flags\]?$/.test(part) && !/^\{commands?\}$/.test(part));
+  const legacyFlags = combinedFlags.size ? [] : invocation.syntax.filter((part) => /^\[?flags\]?$/.test(part));
+  const operands = [...legacyArgs, ...args];
+  const options = [...legacyFlags, ...flags];
+  const optionTerminated = (command.args ?? []).some((arg) => arg.passthrough) || legacyArgs.includes('--');
+  return (
+    heading(3, 'Usage') +
+    fenced(
+      [invocation.command, ...(optionTerminated ? options : operands), ...(optionTerminated ? operands : options)].join(
+        ' ',
+      ),
+    )
+  );
+}
+function renderCommand(
+  name: string,
+  command: CommandItemObject,
+  binary = '',
+  globalFlags: FlagItemObject[] = [],
+): string {
+  let out = heading(2, name);
+  if (command.summary) out += `${command.summary}\n\n`;
+  if (command.description) out += `${command.description}\n\n`;
+  if (command.aliases?.length) out += `Aliases: ${command.aliases.map(code).join(', ')}\n\n`;
+  if (command.kind === 'group') out += 'Command group\n\n';
+  out += renderUsage(name, command, binary, globalFlags);
+  out += table(
+    ['Argument', 'Type', 'Required', 'Description'],
+    (command.args ?? []).map((arg) => [
+      code(arg.name),
+      arg.type ?? 'string',
+      arg.required || (arg.minItems ?? 0) > 0 ? 'Yes' : 'No',
+      details(arg),
+    ]),
+  );
+  out += renderFlags(command.flags ?? []);
+  out += renderExitCodes(command.exitCodes ?? []);
+  if (command.examples?.length) {
+    out += heading(3, 'Examples');
+    for (const example of command.examples) {
+      if (example.title) out += heading(4, example.title);
+      out += fenced(example.content);
+    }
+  }
+  return out;
+}
+function renderFlags(flags: FlagItemObject[]): string {
+  return table(
+    ['Flag', 'Type', 'Required', 'Description'],
+    flags
+      .filter((flag) => !flag.hidden)
+      .map((flag) => [
+        code(`--${flag.name}`),
+        flag.type,
+        flag.required || (flag.minItems ?? 0) > 0 ? 'Yes' : 'No',
+        details(flag),
+      ]),
+  );
+}
+function renderExitCodes(codes: NonNullable<CommandItemObject['exitCodes']>): string {
+  return table(
+    ['Exit code', 'Status', 'Description'],
+    codes.map((item) => [item.code, item.status, item.description ?? item.summary]),
+  );
+}
+function renderLicense(license: LicenseObject): string {
+  const label = license.url ? `[${license.name}](${license.url})` : license.name;
+  return `License: ${label}${license.spdxId ? ` (${license.spdxId})` : ''}\n\n`;
+}
+function renderContact(contact: ContactObject): string {
+  const parts = [contact.name, contact.email, contact.url].filter(Boolean);
+  return `Contact: ${parts.join(' · ')}\n\n`;
+}
+function renderConfig(config: NonNullable<GlobalObject['config']>): string {
+  const rows: [string, string][] = [];
+  if (config.json) rows.push(['JSON', config.json]);
+  if (config.toml) rows.push(['TOML', config.toml]);
+  if (config.yaml) rows.push(['YAML', config.yaml]);
+  if (!rows.length) return '';
+  return (
+    heading(2, 'Configuration') +
+    table(
+      ['Format', 'Path'],
+      rows.map(([format, path]) => [format, code(path)]),
+    )
+  );
+}
+
+/** Render the shared header both `renderMarkdown` and `generatePages`' landing page use. */
+function renderDocumentHeader(document: OpenCliDocument): string {
+  let out = heading(1, document.info.title);
+  if (document.info.summary) out += `${document.info.summary}\n\n`;
+  if (document.info.description) out += `${document.info.description}\n\n`;
+  out += `Binary: ${code(document.info.binary)} · Version: ${code(document.info.version)}\n\n`;
+  if (document.info.license) out += renderLicense(document.info.license);
+  if (document.info.contact) out += renderContact(document.info.contact);
+  if (document.install?.length)
+    out +=
+      heading(2, 'Installation') +
+      table(
+        ['Method', 'Command or URL', 'Description'],
+        document.install.map((method) => [
+          method.name,
+          method.command ? code(method.command) : (method.url ?? ''),
+          method.description ?? '',
+        ]),
+      );
+  if (document.global?.config) out += renderConfig(document.global.config);
+  if (document.global?.flags?.length) out += heading(2, 'Global flags') + renderFlags(document.global.flags);
+  if (document.global?.exitCodes?.length)
+    out += heading(2, 'Global exit codes') + renderExitCodes(document.global.exitCodes);
+  return out;
+}
+
+function assertDocument(document: unknown): asserts document is OpenCliDocument {
+  const result = validate(document);
+  if (!result.valid) throw new Error(`Invalid OpenCLI document: ${result.errors.join('; ')}`);
+}
+
+/** Render a complete Markdown reference, preserving spec-authored Markdown prose. */
+export function renderMarkdown(document: OpenCliDocument): string {
+  assertDocument(document);
+  let out = renderDocumentHeader(document);
+  for (const [name, command] of Object.entries(document.commands ?? {}).toSorted(([a], [b]) => a.localeCompare(b))) {
+    if (!command.hidden) out += renderCommand(name, command, document.info.binary, document.global?.flags ?? []);
+  }
+  return out.trimEnd() + '\n';
+}
+
+export type GeneratedPage = { id: string; title: string; path: string; content: string };
+
+/** Strip the leading `<binary> ` prefix commands are keyed with, e.g. `acme run` -> `run`. */
+function withoutBinaryPrefix(name: string, binary: string): string {
+  if (binary && name.startsWith(`${binary} `)) {
+    const rest = name.slice(binary.length + 1).trim();
+    if (rest) return rest;
+  }
+  return name;
+}
+/** Reserve `~` for deterministic names outside the readable namespace. */
+function commandRoute(name: string, binary: string): string {
+  const display = withoutBinaryPrefix(name, binary);
+  const hasPrefix = !binary || name === `${binary} ${display}`;
+  if (hasPrefix && display.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(display)) return display;
+  // Hash UTF-16 code units to preserve distinctions even for lone surrogates.
+  const units = Buffer.allocUnsafe(name.length * 2);
+  for (let index = 0; index < name.length; index++) units.writeUInt16BE(name.charCodeAt(index), index * 2);
+  const readable =
+    display
+      .toLowerCase()
+      .normalize('NFKD')
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 64) || 'command';
+  return `${readable}~${createHash('sha256').update(units).digest('hex')}`;
+}
+
+/** Produce a landing page and one page per visible command with safe, stable routes. */
+export function generatePages(document: OpenCliDocument, options: { basePath?: string } = {}): GeneratedPage[] {
+  assertDocument(document);
+  const rawBase = (options.basePath ?? '').replace(/\\/g, '/');
+  const segments = rawBase.split('/').filter(Boolean);
+  if (segments.some((segment) => segment === '.' || segment === '..' || /%(?:2e|2f|5c)/i.test(segment)))
+    throw new Error('Invalid basePath segment');
+  const prefix = segments.length ? '/' + segments.map((segment) => encodeURIComponent(segment)).join('/') : '';
+  const pages: GeneratedPage[] = [];
+  const names = Object.keys(document.commands ?? {})
+    .filter((name) => !document.commands?.[name]?.hidden)
+    .toSorted((a, b) => a.localeCompare(b));
+  const routes = new Map(names.map((name) => [name, commandRoute(name, document.info.binary)]));
+  if (new Set(routes.values()).size !== routes.size) throw new Error('Generated command routes collide');
+  let landing = renderDocumentHeader(document);
+  if (names.length)
+    landing +=
+      heading(2, 'Commands') +
+      names
+        .map((name) => `- [${name.replace(/[[\]\\]/g, '\\$&')}](${`${prefix}/commands/${routes.get(name)}`})`)
+        .join('\n') +
+      '\n\n';
+  pages.push({ id: 'index', title: document.info.title, path: prefix || '/', content: landing.trimEnd() + '\n' });
+  for (const name of names) {
+    const route = routes.get(name)!;
+    pages.push({
+      id: `command-${route}`,
+      title: name,
+      path: `${prefix}/commands/${route}`,
+      content:
+        renderCommand(name, document.commands![name]!, document.info.binary, document.global?.flags ?? []).trimEnd() +
+        '\n',
+    });
+  }
+  return pages;
+}

package/src/logical.ts

@@ -0,0 +1,158 @@
+import type { OpenCliDocument, CommandItemObject, AlternativeSource } from './types.js';
+
+/**
+ * Logical validations ported from upstream `validate/validate.go`, beyond what the JSON Schema
+ * can express: positional argument ordering, variadic/min/max constraints, `$FILE` alternative
+ * sources referencing a declared `global.config` file, duplicate flag names/aliases, and group
+ * commands carrying args or flags.
+ */
+export function logicalErrors(document: OpenCliDocument): string[] {
+  const errors: string[] = [];
+  const definedConfigFiles = new Set<string>();
+  if (document.global?.config?.json) definedConfigFiles.add('json');
+  if (document.global?.config?.toml) definedConfigFiles.add('toml');
+  if (document.global?.config?.yaml) definedConfigFiles.add('yaml');
+
+  for (const [name, command] of Object.entries(document.commands ?? {})) {
+    validateCommand(name, command, definedConfigFiles, errors);
+  }
+  return errors;
+}
+
+function validateCommand(
+  name: string,
+  command: CommandItemObject,
+  definedConfigFiles: Set<string>,
+  errors: string[],
+): void {
+  const base = `/commands/${name}`;
+  const args = command.args ?? [];
+  const flags = command.flags ?? [];
+
+  if (args.length > 0) {
+    validateArgumentOrdering(base, args, errors);
+    validateArgumentConstraints(base, args, errors);
+  }
+
+  if (flags.length > 0) {
+    validateFlagFileReferences(base, flags, definedConfigFiles, errors);
+    validateFlagConstraints(base, flags, errors);
+  }
+
+  if (command.kind === 'group') {
+    if (args.length > 0) errors.push(`${base} group command cannot have arguments`);
+    if (flags.length > 0) errors.push(`${base} group command cannot have flags`);
+  }
+}
+
+/** Ensures required positional args don't come after optional ones. */
+function validateArgumentOrdering(base: string, args: NonNullable<CommandItemObject['args']>, errors: string[]): void {
+  let seenOptional = false;
+  for (const [i, arg] of args.entries()) {
+    const isRequired = arg.required === true;
+    if (seenOptional && isRequired) {
+      errors.push(`${base}/args/${i} required positional argument '${arg.name}' cannot come after optional arguments`);
+    }
+    if (!isRequired) seenOptional = true;
+  }
+}
+
+/** Checks that minItems/maxItems are only used with variadic args, and min <= max. */
+function validateArgumentConstraints(
+  base: string,
+  args: NonNullable<CommandItemObject['args']>,
+  errors: string[],
+): void {
+  for (const [i, arg] of args.entries()) {
+    const path = `${base}/args/${i}`;
+    if ((arg.minItems !== undefined || arg.maxItems !== undefined) && !arg.variadic) {
+      const field = arg.minItems !== undefined ? 'minItems' : 'maxItems';
+      errors.push(`${path} argument '${arg.name}' has ${field} but is not variadic`);
+    }
+    if (arg.variadic && arg.minItems !== undefined && arg.maxItems !== undefined && arg.minItems > arg.maxItems) {
+      errors.push(
+        `${path} argument '${arg.name}' has minItems (${arg.minItems}) greater than maxItems (${arg.maxItems})`,
+      );
+    }
+  }
+}
+
+/** Checks that `$FILE` alternative sources reference a file declared in global.config. */
+function validateFlagFileReferences(
+  base: string,
+  flags: NonNullable<CommandItemObject['flags']>,
+  definedConfigFiles: Set<string>,
+  errors: string[],
+): void {
+  for (const [i, flag] of flags.entries()) {
+    validateFileReferences(
+      `${base}/flags/${i}`,
+      'flag',
+      flag.name,
+      flag.alternativeSources,
+      definedConfigFiles,
+      errors,
+    );
+  }
+}
+
+function validateFileReferences(
+  path: string,
+  itemType: string,
+  itemName: string,
+  altSources: AlternativeSource[] | undefined,
+  definedConfigFiles: Set<string>,
+  errors: string[],
+): void {
+  for (const [j, source] of (altSources ?? []).entries()) {
+    if (source.type === '$FILE' && definedConfigFiles.size === 0) {
+      errors.push(
+        `${path}/alternativeSources/${j} ${itemType} '${itemName}' references $FILE but no config files are defined in global.config`,
+      );
+    }
+  }
+}
+
+/** Checks for duplicate flag names/aliases and variadic+required/minItems/maxItems constraints. */
+function validateFlagConstraints(base: string, flags: NonNullable<CommandItemObject['flags']>, errors: string[]): void {
+  const seen = new Map<string, number>();
+
+  for (const [i, flag] of flags.entries()) {
+    const path = `${base}/flags/${i}`;
+    const flagName = flag.name;
+
+    if (flagName) {
+      const prevIdx = seen.get(flagName);
+      if (prevIdx !== undefined) {
+        errors.push(`${path} duplicate flag name '${flagName}' (also defined at index ${prevIdx})`);
+      }
+      seen.set(flagName, i);
+
+      for (const alias of flag.aliases ?? []) {
+        if (!alias) continue;
+        const prevAliasIdx = seen.get(alias);
+        if (prevAliasIdx !== undefined) {
+          errors.push(`${path}/aliases duplicate flag alias '${alias}' (already defined at index ${prevAliasIdx})`);
+        }
+        seen.set(alias, i);
+      }
+    }
+
+    if (flag.variadic && flag.required) {
+      errors.push(
+        `${path} variadic flag '${flagName}' cannot be marked as required (variadic flags can be provided 0 or more times)`,
+      );
+    }
+
+    if ((flag.minItems !== undefined || flag.maxItems !== undefined) && !flag.variadic) {
+      const field = flag.minItems !== undefined ? 'minItems' : 'maxItems';
+      errors.push(`${path} flag '${flagName}' has ${field} but is not variadic`);
+    }
+
+    if (flag.variadic && flag.minItems !== undefined && flag.maxItems !== undefined && flag.minItems > flag.maxItems) {
+      errors.push(
+        `${path} flag '${flagName}' has minItems (${flag.minItems}) greater than maxItems (${flag.maxItems})`,
+      );
+    }
+  }
+}

package/src/merge.ts

@@ -0,0 +1,96 @@
+import { validate } from './index.js';
+import type {
+  ArgumentItemObject,
+  CommandItemObject,
+  FlagItemObject,
+  GlobalObject,
+  InfoObject,
+  InstallMethodItemObject,
+  OpenCliDocument,
+} from './types.js';
+
+/** A named array entry merged with a generated entry of the same name. */
+export type NamedOverride<T extends { name: string }> = Pick<T, 'name'> & Partial<Omit<T, 'name'>>;
+/** Metadata layered onto a generated command. */
+export type CommandOverride = Omit<Partial<CommandItemObject>, 'args' | 'flags'> & {
+  args?: NamedOverride<ArgumentItemObject>[];
+  flags?: NamedOverride<FlagItemObject>[];
+};
+/** Metadata layered onto the generated global settings. */
+export type GlobalOverride = Omit<Partial<GlobalObject>, 'config' | 'flags'> & {
+  config?: Partial<NonNullable<GlobalObject['config']>>;
+  flags?: NamedOverride<FlagItemObject>[];
+};
+/** Metadata layered onto the generated CLI identity. */
+export type InfoOverride = Omit<Partial<InfoObject>, 'license' | 'contact'> & {
+  license?: Partial<NonNullable<InfoObject['license']>>;
+  contact?: Partial<NonNullable<InfoObject['contact']>>;
+};
+
+/**
+ * Author-supplied additions layered onto a generated OpenCLI document by {@link mergeDocument}.
+ * Named flags and arguments require a name for matching, but their remaining fields may be
+ * supplied by the generated document. The merged result is validated before it is returned.
+ */
+export type DocumentOverrides = {
+  info?: InfoOverride;
+  install?: InstallMethodItemObject[];
+  global?: GlobalOverride;
+  commands?: Record<string, CommandOverride>;
+  [key: `x-${string}`]: unknown;
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Arrays under these keys are appended rather than replaced. */
+const APPEND_KEYS = new Set(['examples', 'exitCodes']);
+/** Arrays under these keys are merged item-by-item, matched by `name`. */
+const NAME_MERGE_KEYS = new Set(['flags', 'args']);
+
+/** Merge two arrays of `{ name: ... }` items (flags/args): match by `name`, append the rest. */
+function mergeNamedArray(base: unknown[], override: unknown[]): unknown[] {
+  const result = (base as Record<string, unknown>[]).map((item) => ({ ...item }));
+  for (const item of override as Record<string, unknown>[]) {
+    const index = result.findIndex((entry) => entry.name === item.name);
+    if (index >= 0) result[index] = mergeObjects(result[index]!, item);
+    else result.push(item);
+  }
+  return result;
+}
+
+function mergeValue(key: string, base: unknown, override: unknown): unknown {
+  if (override === undefined) return base;
+  if (Array.isArray(base) && Array.isArray(override)) {
+    if (APPEND_KEYS.has(key)) return [...base, ...override];
+    if (NAME_MERGE_KEYS.has(key)) return mergeNamedArray(base, override);
+    return override;
+  }
+  if (isPlainObject(base) && isPlainObject(override)) return mergeObjects(base, override);
+  return override;
+}
+
+function mergeObjects(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...base };
+  for (const key of Object.keys(override)) result[key] = mergeValue(key, base[key], override[key]);
+  return result;
+}
+
+/**
+ * Return a new document with `overrides` deep-merged onto `base`. Plain objects merge
+ * recursively (so `info.license`, `global`, and individual commands can be extended without
+ * repeating the rest). Arrays in `overrides` replace the base array, except `examples` and
+ * `exitCodes`, which append, and `flags`/`args`, which are merged item-by-item matched by
+ * `name` (so an author can add e.g. `alternativeSources` to one generated flag without
+ * repeating the whole flag list). Commands not present in `base` are added as-is.
+ *
+ * Throws if the merged result fails OpenCLI schema validation, listing every problem found.
+ */
+export function mergeDocument(base: OpenCliDocument, overrides: DocumentOverrides): OpenCliDocument {
+  const merged = mergeObjects(base as unknown as Record<string, unknown>, overrides as Record<string, unknown>);
+  const result = merged as unknown as OpenCliDocument;
+  const { valid, errors } = validate(result);
+  if (!valid) throw new Error(`Invalid OpenCLI document after merge: ${errors.join('; ')}`);
+  return result;
+}