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

package/src/generate.ts

@@ -0,0 +1,218 @@
+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,
+  opts: { commandPlaceholder?: boolean } = {},
+): string {
+  const parts: string[] = [];
+
+  // Command path
+  parts.push(commandPath);
+
+  // A command that owns subcommands takes one as its next token. Opt-in, so
+  // consumers that render a command's own usage (e.g. opencli-remark) keep their
+  // output — only api.cli asks for the placeholder.
+  if (opts.commandPlaceholder && command.commands && command.commands.filter((c) => !c.hidden).length > 0) {
+    parts.push('<command>');
+  }
+
+  // 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;
+}