@xyd-js/opencli 0.0.0-build-b7bd05c-20260701151111

package/src/__tests__/opencli.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+
+import { findCommand, generateUsage, generateOptions, generateArguments } from '../index';
+import type { OpencliSpecJson } from '../index';
+
+const spec: OpencliSpecJson = {
+  opencli: '1.0.0',
+  info: { title: 'spice', version: '1.0.0', description: 'Spice CLI' },
+  commands: [
+    {
+      name: 'install',
+      aliases: ['i'],
+      description: 'Install a package',
+      options: [{ name: 'global', aliases: ['g'], description: 'Install globally' }],
+      arguments: [{ name: 'package', required: true, description: 'Package name' }],
+      commands: [{ name: 'dev', description: 'Install as dev dependency' }],
+    },
+  ],
+};
+
+describe('@xyd-js/opencli core', () => {
+  it('findCommand resolves a top-level command', () => {
+    const cmd = findCommand(spec, 'install');
+    expect(cmd?.name).toBe('install');
+  });
+
+  it('findCommand resolves via alias', () => {
+    const cmd = findCommand(spec, 'i');
+    expect(cmd?.name).toBe('install');
+  });
+
+  it('findCommand resolves a nested command', () => {
+    const cmd = findCommand(spec, 'install dev');
+    expect(cmd?.name).toBe('dev');
+  });
+
+  it('findCommand with empty path returns synthetic root', () => {
+    const cmd = findCommand(spec, '');
+    expect(cmd?.name).toBe('spice');
+    expect(cmd?.commands?.[0]?.name).toBe('install');
+  });
+
+  it('generateUsage renders the general form (options + required arg, no subcommand token)', () => {
+    const cmd = findCommand(spec, 'install')!;
+    expect(generateUsage(spec, cmd, 'spice install')).toBe('spice install [options] <package>');
+  });
+
+  it('generateUsage adds the <command> placeholder for a command group when opted in', () => {
+    const cmd = findCommand(spec, 'install')!;
+    expect(generateUsage(spec, cmd, 'spice install', { commandPlaceholder: true })).toBe(
+      'spice install <command> [options] <package>',
+    );
+  });
+
+  it('generateOptions / generateArguments render tab-indented code style', () => {
+    const cmd = findCommand(spec, 'install')!;
+    expect(generateOptions(cmd, 'code')).toContain('-g, --global');
+    expect(generateArguments(cmd, 'code')).toContain('package');
+  });
+
+  it('x-openapi binding survives on the model (typed extension)', () => {
+    const withBinding: OpencliSpecJson = {
+      ...spec,
+      'x-openapi': { servers: ['https://api.example.com/v1'] },
+    };
+    expect(withBinding['x-openapi']?.servers?.[0]).toBe('https://api.example.com/v1');
+  });
+});

package/src/converters.test.ts

@@ -0,0 +1,278 @@
+import { describe, expect, it } from 'vitest';
+
+import { opencliToReferences } from './converters';
+import type { OpencliSpecJson } from './types';
+
+const spec: OpencliSpecJson = {
+  opencli: '1.0.0',
+  info: { title: 'spice', version: '1.0.0' },
+  commands: [
+    {
+      name: 'install',
+      description: 'Install one or more packages.',
+      arguments: [{ name: 'packages', required: true, description: 'Packages to install.' }],
+      options: [
+        { name: 'global', aliases: ['g'], description: 'Install globally.' },
+        { name: 'save-dev', description: 'Add to devDependencies.' },
+        { name: 'secret', description: 'hidden', hidden: true },
+      ],
+      commands: [{ name: 'dev', description: 'Install as a dev dependency.' }],
+    },
+    { name: 'list', description: 'List installed packages.' },
+    { name: 'internal', description: 'hidden', hidden: true },
+  ],
+};
+
+describe('opencliToReferences', () => {
+  it('emits one reference per (visible) command, including nested', () => {
+    const refs = opencliToReferences(spec);
+    const titles = refs.map((r) => r.title).sort();
+    // 'install' owns a subcommand → "install <command>"; 'internal' (hidden) excluded
+    expect(titles).toEqual(['install <command>', 'install dev', 'list']);
+  });
+
+  it('builds Arguments/Options/Commands definitions with required + alias info', () => {
+    const install = opencliToReferences(spec).find((r) => r.title === 'install <command>')!;
+    expect(install.canonical).toBe('install');
+    expect(install.description).toBe('Install one or more packages.');
+
+    const byTitle = Object.fromEntries(install.definitions.map((d) => [d.title, d]));
+    expect(Object.keys(byTitle).sort()).toEqual(['Arguments', 'Commands', 'Options']);
+
+    // argument required meta
+    const packages = byTitle.Arguments.properties[0];
+    expect(packages.name).toBe('packages');
+    expect(packages.meta).toEqual([{ name: 'required', value: 'true' }]);
+
+    // options: kebab name with `--`, alias note, hidden one dropped
+    const optNames = byTitle.Options.properties.map((p) => p.name);
+    expect(optNames).toEqual(['--global', '--save-dev']); // 'secret' (hidden) excluded
+    expect(byTitle.Options.properties[0].description).toContain('alias: -g');
+
+    // nested subcommand listed
+    expect(byTitle.Commands.properties.map((p) => p.name)).toEqual(['dev']);
+
+    // context.path is the region key the engine round-trips
+    expect(install.context.path).toBe('install');
+
+    // a runnable CLI invocation is emitted as a "CLI Tool" code sample
+    const tab = install.examples.groups[0].examples[0].codeblock.tabs[0];
+    expect(tab.title).toBe('CLI Tool');
+    expect(tab.language).toBe('shell');
+    expect(tab.code).toContain('spice install');
+    // required positional arg filled with a value, no required options here
+    expect(tab.code).toContain("'Example data'");
+  });
+
+  it('fills required options with example/enum values', () => {
+    const cliSpec: OpencliSpecJson = {
+      opencli: '1.0.0',
+      info: { title: 'openai', version: '1.0.0' },
+      commands: [
+        {
+          name: 'transcribe',
+          description: 'Create a transcription.',
+          options: [
+            { name: 'file', required: true, arguments: [{ name: 'path', required: true }] },
+            { name: 'model', required: true, arguments: [{ name: 'id', required: true, acceptedValues: ['gpt-4o-transcribe', 'whisper-1'] }] },
+            { name: 'verbose', description: 'noise' },
+          ],
+        },
+      ],
+    };
+    const code = opencliToReferences(cliSpec)[0].examples.groups[0].examples[0].codeblock.tabs[0].code;
+    expect(code).toContain('openai transcribe');
+    expect(code).toContain("--file 'Example data'");
+    expect(code).toContain('--model gpt-4o-transcribe'); // enum value, unquoted (no spaces)
+    expect(code).not.toContain('--verbose'); // optional flag omitted
+  });
+
+  it('nests a subcommand under "Commands" > <parent>, keeping leaf commands direct', () => {
+    const refs = opencliToReferences(spec);
+    const groupOf = (title: string) => refs.find((r) => r.title === title)!.context.group;
+    // a leaf top-level command sits directly under "Commands"
+    expect(groupOf('list')).toEqual(['Commands']);
+    // a command that owns subcommands becomes a nested group named after itself...
+    expect(groupOf('install <command>')).toEqual(['Commands', 'install']);
+    // ...and its subcommand sits inside that same group
+    expect(groupOf('install dev')).toEqual(['Commands', 'install']);
+  });
+
+  it('renders one CLI Tool example per accepted value (an example-level switcher, not codeblock tabs)', () => {
+    const cliSpec: OpencliSpecJson = {
+      opencli: '1.0.0',
+      info: { title: 'xyd', version: '1.0.0' },
+      commands: [
+        {
+          name: 'completion',
+          description: 'Generate shell completions.',
+          arguments: [{ name: 'shell', required: true, acceptedValues: ['zsh', 'fish'] }],
+        },
+      ],
+    };
+    const group = opencliToReferences(cliSpec)[0].examples.groups[0];
+    // one example per value (labelled by codeblock.title) so Atlas renders an
+    // example switcher — not language tabs inside a single code block
+    expect(group.examples.map((e) => e.codeblock.title)).toEqual(['zsh', 'fish']);
+    expect(group.examples.map((e) => e.codeblock.tabs[0].code)).toEqual(['xyd completion zsh', 'xyd completion fish']);
+  });
+
+  it('labels the CLI Tool example with a single example value too (e.g. a [diagrams] tab)', () => {
+    const cliSpec: OpencliSpecJson = {
+      opencli: '1.0.0',
+      info: { title: 'xyd', version: '1.0.0' },
+      commands: [
+        {
+          name: 'install',
+          description: 'Install a component.',
+          arguments: [{ name: 'component', required: true, metadata: [{ name: 'example', value: 'diagrams' }] }],
+        },
+      ],
+    };
+    const examples = opencliToReferences(cliSpec)[0].examples.groups[0].examples;
+    expect(examples).toHaveLength(1);
+    expect(examples[0].codeblock.title).toBe('diagrams'); // rendered as a [diagrams] tab
+    expect(examples[0].codeblock.tabs[0].code).toBe('xyd install diagrams');
+  });
+
+  it('marks refs as the CLI category and surfaces an argument example/enum in its meta', () => {
+    const cliSpec: OpencliSpecJson = {
+      opencli: '1.0.0',
+      info: { title: 'xyd', version: '1.0.0' },
+      commands: [
+        {
+          name: 'components',
+          description: 'Manage components.',
+          commands: [
+            {
+              name: 'install',
+              description: 'Install a component.',
+              arguments: [{ name: 'component', required: true, metadata: [{ name: 'example', value: 'diagrams' }] }],
+            },
+          ],
+        },
+        {
+          name: 'completion',
+          description: 'Shell completions.',
+          arguments: [{ name: 'shell', required: true, acceptedValues: ['zsh', 'fish'] }],
+        },
+      ],
+    };
+    const refs = opencliToReferences(cliSpec);
+
+    // the parent (command group) reads as "components <command>" and keeps a stable URL
+    const parent = refs.find((r) => r.canonical === 'components')!;
+    expect(parent.title).toBe('components <command>');
+    expect(parent.context.fullPath).toBe('xyd components <command>');
+    // its CLI Tool sample shows the subcommand placeholder too (unquoted)
+    expect(parent.examples.groups[0].examples[0].codeblock.tabs[0].code).toBe('xyd components <command>');
+
+    const install = refs.find((r) => r.title === 'components install')!;
+    expect(install.category).toBe('cli');
+    expect(install.context.fullPath).toBe('xyd components install <component>'); // the usage formula
+    // example metadata → an "example" badge in the Arguments section
+    expect(install.definitions.find((d) => d.title === 'Arguments')!.properties[0].meta).toEqual([
+      { name: 'required', value: 'true' },
+      { name: 'example', value: 'diagrams' },
+    ]);
+    // acceptedValues → an "examples" badge list
+    const shell = refs.find((r) => r.title === 'completion')!;
+    expect(shell.definitions.find((d) => d.title === 'Arguments')!.properties[0].meta).toEqual([
+      { name: 'required', value: 'true' },
+      { name: 'examples', value: ['zsh', 'fish'] },
+    ]);
+  });
+
+  it('filters by region (command path)', () => {
+    const refs = opencliToReferences(spec, { regions: ['install dev'] });
+    expect(refs.map((r) => r.title)).toEqual(['install dev']);
+    expect(refs[0].context.path).toBe('install dev');
+  });
+
+  it('renders an "Example response" group from the x-openapi response binding', () => {
+    const withResponse: OpencliSpecJson = {
+      opencli: '1.0.0',
+      info: { title: 'openai', version: '1.0.0' },
+      commands: [
+        {
+          name: 'retrieve',
+          description: 'Retrieve a thing.',
+          'x-openapi': {
+            method: 'get',
+            path: '/things/{id}',
+            responses: [
+              { status: '200', contentType: 'application/json', example: { id: 'thing_123', object: 'thing' } },
+            ],
+          },
+        },
+      ],
+    };
+    const ref = opencliToReferences(withResponse)[0];
+
+    // the CLI Tool invocation stays at groups[0]
+    expect(ref.examples.groups[0].examples[0].codeblock.tabs[0].title).toBe('CLI Tool');
+
+    // the response sample becomes a second, separate group (status on the
+    // codeblock, contentType on the tab — mirrors the OpenAPI response track)
+    const responseGroup = ref.examples.groups[1];
+    expect(responseGroup.description).toBe('Example response');
+    expect(responseGroup.examples[0].codeblock.title).toBe('200');
+    const tab = responseGroup.examples[0].codeblock.tabs[0];
+    expect(tab.title).toBe('application/json');
+    expect(tab.language).toBe('json');
+    expect(JSON.parse(tab.code)).toEqual({ id: 'thing_123', object: 'thing' });
+  });
+
+  it('omits the response group when the command has no x-openapi response', () => {
+    // the spice fixture carries no x-openapi binding → only the CLI Tool group
+    for (const ref of opencliToReferences(spec)) {
+      expect(ref.examples.groups).toHaveLength(1);
+      expect(ref.examples.groups[0].examples[0].codeblock.tabs[0].title).toBe('CLI Tool');
+    }
+  });
+
+  const withGlobals: OpencliSpecJson = {
+    opencli: '1.0.0',
+    info: { title: 'demo', version: '1.0.0' },
+    options: [
+      { name: 'help', aliases: ['h'], description: 'Show help', recursive: true },
+      { name: 'cwd', description: 'Working dir', arguments: [{ name: 'path' }], recursive: true },
+      { name: 'secret', description: 'hidden', recursive: true, hidden: true },
+      { name: 'local', description: 'not a global flag' },
+    ],
+    commands: [{ name: 'build', description: 'Build it' }],
+  };
+
+  it('renders root recursive options on each command when globalOptionsPerCommand is true', () => {
+    const ref = opencliToReferences(withGlobals, { globalOptionsPerCommand: true })[0];
+    const byTitle = Object.fromEntries(ref.definitions.map((d) => [d.title, d]));
+    expect(Object.keys(byTitle)).toContain('Global options');
+    // recursive + visible only; the hidden one and the non-recursive one are excluded
+    expect(byTitle['Global options'].properties.map((p) => p.name)).toEqual(['--help', '--cwd']);
+    // no separate page in this mode
+    expect(opencliToReferences(withGlobals, { globalOptionsPerCommand: true }).some((r) => r.title === 'Global options')).toBe(false);
+  });
+
+  it('by default renders global options as a single dedicated page, not per command', () => {
+    const refs = opencliToReferences(withGlobals);
+    // no per-command "Global options" section
+    const build = refs.find((r) => r.title === 'build')!;
+    expect(build.definitions.map((d) => d.title)).not.toContain('Global options');
+    // a single "Global options" page instead, grouped on its own in the sidebar
+    const page = refs.find((r) => r.title === 'Global options')!;
+    expect(page).toBeTruthy();
+    expect(page.canonical).toBe('global-options');
+    expect(page.context.group).toEqual(['Global options']);
+    expect(page.definitions[0].properties.map((p) => p.name)).toEqual(['--help', '--cwd']);
+  });
+
+  it('emits no "Global options" section when there are no recursive root options', () => {
+    for (const ref of opencliToReferences(spec)) {
+      expect(ref.definitions.map((d) => d.title)).not.toContain('Global options');
+    }
+  });
+
+  it('returns [] for null spec', () => {
+    expect(opencliToReferences(null)).toEqual([]);
+  });
+});

package/src/converters.ts

@@ -0,0 +1,342 @@
+import { generateUsage } from './generate';
+import type { Argument, Command, OpencliSpecJson, Option } from './types';
+
+// Structural subset of @xyd-js/uniform's `Reference` — kept local so the OpenCLI
+// core stays free of the (React-typed) uniform package. The docs engine consumes
+// these as uniform References (api.cli → Atlas).
+interface OpencliRefProperty {
+  name: string;
+  type: string;
+  description: string;
+  meta?: { name: string; value: unknown }[];
+}
+interface OpencliRefDefinition {
+  title: string;
+  properties: OpencliRefProperty[];
+}
+interface OpencliRefCodeTab {
+  title: string;
+  code: string;
+  language: string;
+}
+interface OpencliRefExampleGroup {
+  description?: string;
+  examples: { description?: string; codeblock: { title?: string; tabs: OpencliRefCodeTab[] } }[];
+}
+export interface OpencliReference {
+  title: string;
+  canonical: string;
+  description: string;
+  // Marks these as CLI references so the docs engine / Atlas can render the
+  // usage-formula header (mirrors an OpenAPI page's method + path).
+  category: 'cli';
+  // `group` drives sidebar placement (the docs engine groups references by it);
+  // `path` is the region key round-tripped through the page frontmatter.
+  context: { path: string; fullPath: string; group: string[] };
+  // a runnable CLI invocation, rendered by Atlas as a code sample (like the
+  // request/response samples on an OpenAPI page).
+  examples: { groups: OpencliRefExampleGroup[] };
+  definitions: OpencliRefDefinition[];
+}
+
+export interface OpencliToReferencesOptions {
+  /**
+   * Restrict output to specific commands. Each region is a command path,
+   * space-joined from the CLI root (e.g. `"install"`, `"remote add"`).
+   */
+  regions?: string[];
+
+  /**
+   * Render the CLI's global (root recursive) options on every command page.
+   * When false (the default), a single "Global options" reference is emitted
+   * instead — so the options appear once in the sidebar rather than repeated
+   * on every command.
+   */
+  globalOptionsPerCommand?: boolean;
+}
+
+const GLOBAL_OPTIONS_REGION = 'global-options';
+
+/**
+ * Convert an OpenCLI document to uniform `Reference[]` — one Reference per
+ * command — so the docs engine can render CLI reference pages the same way it
+ * renders OpenAPI/GraphQL (`api.cli`). Mirrors `oapSchemaToReferences`.
+ */
+export function opencliToReferences(
+  spec: OpencliSpecJson | null | undefined,
+  options: OpencliToReferencesOptions = {},
+): OpencliReference[] {
+  if (!spec) return [];
+
+  const cliTitle = spec.info?.title || 'cli';
+  const regionSet = options.regions?.length ? new Set(options.regions) : null;
+  const perCommand = options.globalOptionsPerCommand ?? false;
+  const refs: OpencliReference[] = [];
+
+  // Root-level recursive options (e.g. a CLI's global flags) apply to every
+  // command. By default they get their own page; with `globalOptionsPerCommand`
+  // they're rendered as a "Global options" section on each command instead.
+  const globalOptions = (spec.options || []).filter((o) => o.recursive && !o.hidden);
+
+  const walk = (commands: Command[] | undefined, parentPath: string[]) => {
+    for (const cmd of commands || []) {
+      if (cmd.hidden) continue;
+      const cmdPath = [...parentPath, cmd.name];
+      const region = cmdPath.join(' ');
+      if (!regionSet || regionSet.has(region)) {
+        refs.push(commandToReference(spec, cmd, cmdPath, cliTitle, perCommand ? globalOptions : []));
+      }
+      if (cmd.commands?.length) walk(cmd.commands, cmdPath);
+    }
+  };
+  walk(spec.commands, []);
+
+  // Default: the global options live on a single dedicated page in the sidebar.
+  if (!perCommand && globalOptions.length && (!regionSet || regionSet.has(GLOBAL_OPTIONS_REGION))) {
+    refs.push(globalOptionsReference(globalOptions));
+  }
+
+  return refs;
+}
+
+function globalOptionsReference(globalOptions: Option[]): OpencliReference {
+  return {
+    title: 'Global options',
+    canonical: GLOBAL_OPTIONS_REGION,
+    description: 'Options available on every command.',
+    category: 'cli',
+    context: { path: GLOBAL_OPTIONS_REGION, fullPath: '', group: ['Global options'] },
+    examples: { groups: [] },
+    definitions: [{ title: 'Global options', properties: globalOptions.map(optionToProperty) }],
+  };
+}
+
+function commandToReference(
+  spec: OpencliSpecJson,
+  cmd: Command,
+  cmdPath: string[],
+  cliTitle: string,
+  globalOptions: Option[] = [],
+): OpencliReference {
+  const region = cmdPath.join(' ');
+  const displayPath = `${cliTitle} ${region}`.trim();
+
+  const definitions: OpencliRefDefinition[] = [];
+
+  const args = (cmd.arguments || []).filter((a) => !a.hidden);
+  if (args.length) {
+    definitions.push({ title: 'Arguments', properties: args.map(argumentToProperty) });
+  }
+
+  const opts = (cmd.options || []).filter((o) => !o.hidden);
+  if (opts.length) {
+    definitions.push({ title: 'Options', properties: opts.map(optionToProperty) });
+  }
+
+  const subs = (cmd.commands || []).filter((c) => !c.hidden);
+  if (subs.length) {
+    definitions.push({
+      title: 'Commands',
+      properties: subs.map((s) => ({
+        name: s.name,
+        type: 'command',
+        description: s.description || '',
+      })),
+    });
+  }
+
+  // Global flags (root-level recursive options) available on every command.
+  if (globalOptions.length) {
+    definitions.push({ title: 'Global options', properties: globalOptions.map(optionToProperty) });
+  }
+
+  // Sidebar grouping: a leaf top-level command sits directly under "Commands".
+  // A command that owns subcommands becomes a nested group (named after itself)
+  // under "Commands", and each of its subcommands sits inside that same group —
+  // e.g. `components` + `components install` → "Commands" › "components".
+  const hasSubcommands = (cmd.commands || []).some((c) => !c.hidden);
+  const group =
+    cmdPath.length === 1 && !hasSubcommands ? ['Commands'] : ['Commands', ...(hasSubcommands ? cmdPath : cmdPath.slice(0, -1))];
+
+  // The runnable invocation ("CLI Tool") at groups[0], plus — when the OpenAPI
+  // binding carried one — an "Example response" group rendered as a JSON sample.
+  // This mirrors an OpenAPI page's request + response code samples; Atlas stacks
+  // the groups vertically. Keep the CLI Tool group first.
+  const groups: OpencliRefExampleGroup[] = [{ examples: cliToolExamples(cliTitle, cmd, cmdPath) }];
+  const responseGroup = responseExampleGroup(cmd);
+  if (responseGroup) groups.push(responseGroup);
+
+  return {
+    // A command that owns subcommands reads as "<path> <command>" so it's
+    // distinct from its group and shows it takes a subcommand.
+    title: (hasSubcommands ? `${region} <command>` : region) || cliTitle,
+    canonical: cmdPath.join('/') || cliTitle,
+    description: cmd.description || '',
+    category: 'cli',
+    // context.path is the region key the docs engine writes into the page
+    // frontmatter (`cli: <spec>#<path>`) and reads back to re-resolve the command.
+    // api.cli shows the more specific form — a command group carries `<command>`.
+    context: { path: region, fullPath: generateUsage(spec, cmd, displayPath, { commandPlaceholder: true }), group },
+    examples: { groups },
+    definitions,
+  };
+}
+
+/** Map a response content type to a code-sample language. */
+function responseLanguage(contentType: string | undefined): string {
+  if (!contentType) return 'json';
+  if (/json/i.test(contentType)) return 'json';
+  if (/xml/i.test(contentType)) return 'xml';
+  return 'text';
+}
+
+/**
+ * The "Example response" group built from the command's `x-openapi.responses`
+ * binding (emitted by openapi2opencli) — one code sample per captured response,
+ * rendered alongside the "CLI Tool" invocation like an OpenAPI page's
+ * request/response samples. Returns null when no response example is available.
+ */
+function responseExampleGroup(cmd: Command): OpencliRefExampleGroup | null {
+  const responses = cmd['x-openapi']?.responses;
+  if (!responses?.length) return null;
+
+  const examples: OpencliRefExampleGroup['examples'] = [];
+  for (const res of responses) {
+    if (res.example == null) continue; // skip missing / null bodies (no useful sample)
+    const code = typeof res.example === 'string' ? res.example : JSON.stringify(res.example, null, 2);
+    examples.push({
+      codeblock: {
+        title: res.status || '200',
+        tabs: [{ title: res.contentType || 'application/json', language: responseLanguage(res.contentType), code }],
+      },
+    });
+  }
+  if (!examples.length) return null;
+  return { description: 'Example response', examples };
+}
+
+/** Shell-quote a value only when it needs it (spaces / special chars). */
+function shellQuote(value: string): string {
+  return /[\s'"$`\\<>|&;()]/.test(value) ? `'${value.replace(/'/g, "'\\''")}'` : value;
+}
+
+/** A representative value for an argument: an explicit example, an accepted/enum value, else a placeholder. */
+function exampleValue(arg: Argument | undefined): string {
+  const example = arg?.metadata?.find((m) => m.name === 'example')?.value;
+  if (typeof example === 'string' && example) return example;
+  if (arg?.acceptedValues?.length) return String(arg.acceptedValues[0]);
+  return 'Example data';
+}
+
+/**
+ * The "CLI Tool" example(s) for a command. When a required argument enumerates
+ * its accepted values (e.g. `completion <zsh|fish>`), each value becomes its own
+ * example (`codeblock.title` = the value) — so Atlas renders an example-level
+ * switcher (`[zsh] [fish]`) rather than language tabs inside a single code
+ * block. Otherwise a single "CLI Tool" example.
+ */
+function cliToolExamples(cliTitle: string, cmd: Command, cmdPath: string[]): OpencliRefExampleGroup['examples'] {
+  const reqArgs = (cmd.arguments || []).filter((a) => a.required && !a.hidden);
+  // The argument whose representative value(s) label the example(s): an enum
+  // (acceptedValues) gives one tab per value; a single example value gives one.
+  const variantArg = [...reqArgs].reverse().find((a) => a.acceptedValues?.length || argExampleValue(a) != null);
+  const values = variantArg?.acceptedValues?.length
+    ? variantArg.acceptedValues.map(String)
+    : variantArg
+      ? [String(argExampleValue(variantArg))]
+      : null;
+
+  if (variantArg && values) {
+    // Each value is its own example (`codeblock.title` = the value) so Atlas
+    // renders an example switcher — `[zsh] [fish]`, `[diagrams]`, etc.
+    return values.map((value) => ({
+      codeblock: {
+        title: value,
+        tabs: [
+          {
+            title: 'CLI Tool',
+            language: 'shell',
+            code: generateCliExample(cliTitle, cmd, cmdPath, { [variantArg.name]: value }),
+          },
+        ],
+      },
+    }));
+  }
+
+  return [{ codeblock: { tabs: [{ title: 'CLI Tool', language: 'shell', code: generateCliExample(cliTitle, cmd, cmdPath) }] } }];
+}
+
+/** An argument's explicit example value (from metadata), or null. */
+function argExampleValue(arg: Argument): string | null {
+  const example = arg.metadata?.find((m) => m.name === 'example')?.value;
+  return typeof example === 'string' && example ? example : null;
+}
+
+/**
+ * A runnable, concrete CLI invocation for a command — the command path plus its
+ * required arguments and options filled with example values, one option per line
+ * (the shape shown on an OpenAPI page's request sample). `overrides` pins a
+ * specific value for a named argument (used to render one tab per accepted value).
+ */
+function generateCliExample(
+  cliTitle: string,
+  cmd: Command,
+  cmdPath: string[],
+  overrides: Record<string, string> = {},
+): string {
+  let head = [cliTitle, ...cmdPath].join(' ');
+
+  // A command group takes a subcommand — shown as a placeholder (unquoted, like
+  // the usage formula), e.g. `xyd components <command>`.
+  if ((cmd.commands || []).some((c) => !c.hidden)) {
+    head += ' <command>';
+  }
+
+  for (const arg of (cmd.arguments || []).filter((a) => a.required && !a.hidden)) {
+    head += ` ${shellQuote(overrides[arg.name] ?? exampleValue(arg))}`;
+  }
+
+  const lines = [head];
+  for (const opt of (cmd.options || []).filter((o) => o.required && !o.hidden)) {
+    if (!opt.arguments?.length) {
+      lines.push(`--${opt.name}`); // boolean flag
+    } else {
+      lines.push(`--${opt.name} ${shellQuote(exampleValue(opt.arguments[0]))}`);
+    }
+  }
+
+  return lines.join(' \\\n  ');
+}
+
+function argumentToProperty(arg: Argument): OpencliRefProperty {
+  const meta: { name: string; value: unknown }[] = [];
+  if (arg.required) meta.push({ name: 'required', value: 'true' });
+  // Surface the argument's accepted values / example in the Arguments section
+  // (e.g. `component` → diagrams, `shell` → zsh, fish).
+  if (arg.acceptedValues?.length) {
+    meta.push({ name: 'examples', value: arg.acceptedValues });
+  } else {
+    const example = arg.metadata?.find((m) => m.name === 'example')?.value;
+    if (example != null && example !== '') meta.push({ name: 'example', value: example });
+  }
+  return {
+    name: arg.name,
+    type: arg.arity ? 'array' : 'string',
+    description: arg.description || '',
+    ...(meta.length ? { meta } : {}),
+  };
+}
+
+function optionToProperty(opt: Option): OpencliRefProperty {
+  const aliasNote = opt.aliases?.length
+    ? ` (alias: ${opt.aliases.map((a) => (a.length === 1 ? `-${a}` : `--${a}`)).join(', ')})`
+    : '';
+  const meta = opt.required ? [{ name: 'required', value: 'true' }] : undefined;
+  return {
+    name: `--${opt.name}`,
+    // an option that takes a value vs. a boolean flag
+    type: opt.arguments?.length ? 'string' : 'boolean',
+    description: `${opt.description || ''}${aliasNote}`,
+    ...(meta ? { meta } : {}),
+  };
+}