@xyd-js/opencli 0.1.0-build.0

package/src/converters.test.ts

@@ -0,0 +1,68 @@
+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();
+    expect(titles).toEqual(['install', 'install dev', 'list']); // 'internal' (hidden) excluded
+  });
+
+  it('builds Arguments/Options/Commands definitions with required + alias info', () => {
+    const install = opencliToReferences(spec).find((r) => r.title === 'install')!;
+    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');
+    expect(install.examples).toEqual({ groups: [] });
+  });
+
+  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('returns [] for null spec', () => {
+    expect(opencliToReferences(null)).toEqual([]);
+  });
+});

package/src/converters.ts

@@ -0,0 +1,140 @@
+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[];
+}
+export interface OpencliReference {
+  title: string;
+  canonical: string;
+  description: string;
+  // `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[] };
+  examples: { groups: never[] };
+  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[];
+}
+
+/**
+ * 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 refs: OpencliReference[] = [];
+
+  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));
+      }
+      if (cmd.commands?.length) walk(cmd.commands, cmdPath);
+    }
+  };
+  walk(spec.commands, []);
+
+  return refs;
+}
+
+function commandToReference(
+  spec: OpencliSpecJson,
+  cmd: Command,
+  cmdPath: string[],
+  cliTitle: string,
+): 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 || '',
+      })),
+    });
+  }
+
+  // Sidebar grouping: top-level commands sit under "Commands"; a subcommand sits
+  // under a group named after its parent path (e.g. `auth login` → group "auth").
+  // (One group level is required — the docs engine drops references with an empty
+  // group — and a group must not mix direct pages with subgroups.)
+  const group = cmdPath.length === 1 ? ['Commands'] : [cmdPath.slice(0, -1).join(' ')];
+
+  return {
+    title: region || cliTitle,
+    canonical: cmdPath.join('/') || cliTitle,
+    description: cmd.description || '',
+    // 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.
+    context: { path: region, fullPath: generateUsage(spec, cmd, displayPath), group },
+    examples: { groups: [] },
+    definitions,
+  };
+}
+
+function argumentToProperty(arg: Argument): OpencliRefProperty {
+  const meta = arg.required ? [{ name: 'required', value: 'true' }] : undefined;
+  return {
+    name: arg.name,
+    type: arg.arity ? 'array' : 'string',
+    description: arg.description || '',
+    ...(meta ? { 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 } : {}),
+  };
+}

package/src/generate.ts

@@ -0,0 +1,206 @@
+import type { OpencliSpecJson, Command } from './types.js';
+
+export type IndentStyle = 'code' | 'list';
+
+/**
+ * Generate usage line for a command (like: "shadcn init [options] [components...]")
+ */
+export function generateUsage(_spec: OpencliSpecJson, command: Command, commandPath: string): string {
+  const parts: string[] = [];
+
+  // Command path
+  parts.push(commandPath);
+
+  // Options indicator
+  if (command.options && command.options.length > 0) {
+    const visibleOptions = command.options.filter((opt) => !opt.hidden);
+    if (visibleOptions.length > 0) {
+      parts.push('[options]');
+    }
+  }
+
+  // Arguments
+  if (command.arguments && command.arguments.length > 0) {
+    const visibleArgs = command.arguments.filter((arg) => !arg.hidden);
+    const argParts = visibleArgs.map((arg) => {
+      const name = arg.name.toLowerCase();
+      // Use ... suffix if argument can accept multiple values (variadic)
+      const suffix = arg.variadic ? '...' : '';
+      return arg.required ? `<${name}${suffix}>` : `[${name}${suffix}]`;
+    });
+    parts.push(...argParts);
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Generate description for a command
+ */
+export function generateDescription(command: Command): string {
+  return command.description || '';
+}
+
+/**
+ * Generate arguments documentation
+ * @param indentStyle - 'code' for tab-indented CLI style, 'list' for markdown list style
+ */
+export function generateArguments(command: Command, indentStyle: IndentStyle = 'code'): string {
+  if (!command.arguments || command.arguments.length === 0) {
+    return '';
+  }
+
+  const visibleArgs = command.arguments.filter((arg) => !arg.hidden);
+  if (visibleArgs.length === 0) {
+    return '';
+  }
+
+  const lines: string[] = [];
+
+  for (const arg of visibleArgs) {
+    const name = arg.name.toLowerCase();
+    const desc = arg.description || '';
+
+    if (indentStyle === 'list') {
+      // Markdown list format: - `package`         Package name
+      lines.push(`- \`${name}\`${desc ? `  ${desc}` : ''}`);
+    } else {
+      // Code/CLI format with tab indentation
+      const paddedName = name.padEnd(30);
+      lines.push(`\t${paddedName}${desc}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate options documentation
+ * @param indentStyle - 'code' for tab-indented CLI style, 'list' for markdown list style
+ */
+export function generateOptions(command: Command, indentStyle: IndentStyle = 'code'): string {
+  if (!command.options || command.options.length === 0) {
+    return '';
+  }
+
+  const visibleOptions = command.options.filter((opt) => !opt.hidden);
+  if (visibleOptions.length === 0) {
+    return '';
+  }
+
+  const lines: string[] = [];
+
+  for (const option of visibleOptions) {
+    // Build option signature
+    const aliases = option.aliases?.filter((a) => a.length === 1) || [];
+    const short = aliases.length > 0 ? `-${aliases[0]}` : '';
+    const long = `--${option.name}`;
+
+    // Add argument placeholder if option takes arguments
+    let argPlaceholder = '';
+    if (option.arguments && option.arguments.length > 0) {
+      const argNames = option.arguments.filter((arg) => !arg.hidden).map((arg) => `<${arg.name.toLowerCase()}>`);
+      argPlaceholder = ' ' + argNames.join(' ');
+    }
+
+    const desc = option.description || '';
+
+    if (indentStyle === 'list') {
+      // Markdown list format: - `-g`, `--global`   Install globally
+      const shortPart = short ? `\`${short}\`, ` : '';
+      lines.push(`- ${shortPart}\`${long}\`${argPlaceholder}${desc ? `  ${desc}` : ''}`);
+    } else {
+      // Code/CLI format with tab indentation
+      const signature = `${short ? `${short}, ` : ''}${long}${argPlaceholder}`;
+      const paddedSignature = signature.padEnd(30);
+      lines.push(`\t${paddedSignature}${desc}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * TODO: OPTIONS DO ALMOST THE SAME
+ * Generate flags/options documentation
+ */
+export function generateFlags(command: Command): string {
+  if (!command.options || command.options.length === 0) {
+    return 'No flags available.';
+  }
+
+  const visibleOptions = command.options.filter((opt) => !opt.hidden);
+  if (visibleOptions.length === 0) {
+    return 'No flags available.';
+  }
+
+  const lines: string[] = [];
+
+  for (const option of visibleOptions) {
+    const optionParts: string[] = [];
+
+    // Option name and aliases
+    const aliases = option.aliases?.filter((a) => a.length === 1) || [];
+    const short = aliases.length > 0 ? `-${aliases[0]}` : '';
+    const long = `--${option.name}`;
+    const name = short ? `\`${short}\`, \`${long}\`` : `\`${long}\``;
+    optionParts.push(name);
+
+    // Required indicator
+    if (option.required) {
+      optionParts.push('**(required)**');
+    }
+
+    lines.push(`- ${optionParts.join(' ')}`);
+
+    // Description
+    if (option.description) {
+      lines.push(`  ${option.description}`);
+    }
+
+    // Option arguments
+    if (option.arguments && option.arguments.length > 0) {
+      const argParts = option.arguments
+        .filter((arg) => !arg.hidden)
+        .map((arg) => {
+          const name = arg.name.toUpperCase();
+          return arg.required ? `<${name}>` : `[${name}]`;
+        });
+      if (argParts.length > 0) {
+        lines.push(`  Arguments: ${argParts.join(' ')}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate subcommands documentation
+ */
+export function generateCommands(command: Command): string {
+  if (!command.commands || command.commands.length === 0) {
+    return 'No subcommands available.';
+  }
+
+  const visibleCommands = command.commands.filter((cmd) => !cmd.hidden);
+  if (visibleCommands.length === 0) {
+    return 'No subcommands available.';
+  }
+
+  const lines: string[] = [];
+
+  for (const subcommand of visibleCommands) {
+    lines.push(`- \`${subcommand.name}\``);
+
+    if (subcommand.aliases && subcommand.aliases.length > 0) {
+      lines.push(`  Aliases: ${subcommand.aliases.map((a) => `\`${a}\``).join(', ')}`);
+    }
+
+    if (subcommand.description) {
+      lines.push(`  ${subcommand.description}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// OpenCLI core: the data model (generated from opencli-spec.json) plus the
+// pure spec/loader/generator helpers shared by opencli-remark and the
+// openapi2opencli / opencli2* code generators.
+export * from './types';
+
+export { loadOpencliSpec, findCommand } from './spec';
+export type { LoadOpencliSpecOptions } from './spec';
+
+export {
+  generateUsage,
+  generateDescription,
+  generateArguments,
+  generateOptions,
+  generateCommands,
+  generateFlags,
+} from './generate';
+export type { IndentStyle } from './generate';
+
+export { opencliToReferences } from './converters';
+export type { OpencliReference, OpencliToReferencesOptions } from './converters';

package/src/spec.ts

@@ -0,0 +1,106 @@
+import type { OpencliSpecJson, Command } from './types.js';
+
+export interface LoadOpencliSpecOptions {
+  /**
+   * Base directory used to resolve a relative file `source`.
+   * Defaults to `process.cwd()`. (The remark plugin passes the markdown file's dirname.)
+   */
+  cwd?: string;
+}
+
+/**
+ * Load an OpenCLI spec from a file path or an HTTP(S) URL.
+ *
+ * Returns `null` (and logs) on any failure so callers can leave placeholders
+ * untouched rather than throwing.
+ */
+export async function loadOpencliSpec(
+  source: string,
+  opts?: LoadOpencliSpecOptions,
+): Promise<OpencliSpecJson | null> {
+  try {
+    let content: string;
+
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+      // Load from URL
+      const response = await fetch(source);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch OpenCLI spec: ${response.statusText}`);
+      }
+      content = await response.text();
+    } else {
+      // Load from file
+      const fs = await import('node:fs/promises');
+      const path = await import('node:path');
+
+      // Resolve relative to the provided cwd (or process.cwd())
+      const base = opts?.cwd ?? process.cwd();
+      const resolvedPath = path.isAbsolute(source) ? source : path.resolve(base, source);
+
+      content = await fs.readFile(resolvedPath, 'utf-8');
+    }
+
+    return JSON.parse(content) as OpencliSpecJson;
+  } catch (error) {
+    console.error(`Error loading OpenCLI spec from ${source}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Find a command in the spec by path (e.g., "spice install").
+ * If the path is empty, returns a synthetic root command built from the spec root.
+ */
+export function findCommand(spec: OpencliSpecJson, commandPath: string): Command | null {
+  let parts = commandPath.trim().split(/\s+/).filter(Boolean);
+
+  // If no path specified, create a synthetic root command from spec root
+  if (parts.length === 0) {
+    return {
+      name: spec.info?.title || 'root',
+      description: spec.info?.description || spec.info?.summary,
+      options: spec.options || [],
+      arguments: spec.arguments || [],
+      commands: spec.commands || [],
+      examples: spec.examples || [],
+      exitCodes: spec.exitCodes || [],
+      interactive: spec.interactive,
+    };
+  }
+
+  // Skip the CLI name if it matches the first part (e.g., "spice install" -> "install")
+  if (parts.length > 0 && spec.info?.title && parts[0] === spec.info.title) {
+    parts = parts.slice(1);
+  }
+
+  // If only the CLI name was provided, return root command
+  if (parts.length === 0) {
+    return {
+      name: spec.info?.title || 'root',
+      description: spec.info?.description || spec.info?.summary,
+      options: spec.options || [],
+      arguments: spec.arguments || [],
+      commands: spec.commands || [],
+      examples: spec.examples || [],
+      exitCodes: spec.exitCodes || [],
+      interactive: spec.interactive,
+    };
+  }
+
+  // Start from root commands
+  let currentCommands = spec.commands || [];
+  let foundCommand: Command | null = null;
+
+  for (const part of parts) {
+    foundCommand = currentCommands.find((cmd) => cmd.name === part || cmd.aliases?.includes(part)) || null;
+
+    if (!foundCommand) {
+      return null;
+    }
+
+    // Move to subcommands for next iteration
+    currentCommands = foundCommand.commands || [];
+  }
+
+  return foundCommand;
+}