cli-forge 1.0.2 → 1.2.0

package/src/bin/commands/generate-documentation.ts

@@ -44,10 +44,16 @@ export function withGenerateDocumentationArgs<T extends ParsedArgs>(
       type: 'string',
       description:
         'Specifies the `tsconfig` used when loading typescript based CLIs.',
+    })
+    .option('llms', {
+      type: 'boolean',
+      description:
+        'Generate an llms.txt file describing the CLI for AI agents.',
+      default: true,
     });
 }
 
-export const generateDocumentationCommand: CLI<any, any, any> = cli('generate-documentation', {
+export const generateDocumentationCommand = cli('generate-documentation', {
   description: 'Generate documentation for the given CLI',
   examples: [
     'cli-forge generate-documentation ./bin/my-cli',
@@ -70,6 +76,10 @@ export const generateDocumentationCommand: CLI<any, any, any> = cli('generate-do
       ensureDirSync(outdir);
       writeFileSync(outfile, JSON.stringify(documentation, null, 2));
     }
+
+    if (args.llms) {
+      generateLlmsTxt(documentation, args);
+    }
   },
 });
 
@@ -81,6 +91,156 @@ async function generateMarkdownDocumentation(
   await generateMarkdownForSingleCommand(docs, args.output, args.output, md);
 }
 
+function generateLlmsTxt(docs: Documentation, args: GenerateDocsArgs) {
+  const content = generateLlmsTxtContent(docs);
+  const outfile = join(args.output, 'llms.txt');
+  ensureDirSync(args.output);
+  writeFileSync(outfile, content);
+}
+
+function generateLlmsTxtContent(
+  docs: Documentation,
+  depth = 0,
+  commandPath: string[] = []
+): string {
+  const lines: string[] = [];
+  const indent = '  '.repeat(depth);
+  const currentPath = [...commandPath, docs.name];
+  const fullCommand = currentPath.join(' ');
+
+  // Command header
+  if (depth === 0) {
+    lines.push(`# ${docs.name}`);
+    lines.push('');
+    if (docs.description) {
+      lines.push(docs.description);
+      lines.push('');
+    }
+    lines.push('This document describes the CLI commands and options for AI agent consumption.');
+    lines.push('');
+  } else {
+    lines.push(`${indent}## ${fullCommand}`);
+    if (docs.description) {
+      lines.push(`${indent}${docs.description}`);
+    }
+    lines.push('');
+  }
+
+  // Usage
+  lines.push(`${indent}Usage: ${docs.usage}`);
+  lines.push('');
+
+  // Positional arguments
+  if (docs.positionals.length > 0) {
+    lines.push(`${indent}Positional Arguments:`);
+    for (const pos of docs.positionals) {
+      const typeStr = formatOptionType(pos);
+      const reqStr = pos.required ? ' (required)' : ' (optional)';
+      lines.push(`${indent}  <${pos.key}> - ${typeStr}${reqStr}`);
+      if (pos.description) {
+        lines.push(`${indent}    ${pos.description}`);
+      }
+      if (pos.default !== undefined) {
+        lines.push(`${indent}    Default: ${JSON.stringify(pos.default)}`);
+      }
+    }
+    lines.push('');
+  }
+
+  // Options
+  const optionEntries = Object.entries(docs.options);
+  if (optionEntries.length > 0) {
+    lines.push(`${indent}Options:`);
+    for (const [, opt] of optionEntries) {
+      const typeStr = formatOptionType(opt);
+      const aliasStr = opt.alias?.length
+        ? ` (aliases: ${opt.alias.map((a) => (a.length === 1 ? `-${a}` : `--${a}`)).join(', ')})`
+        : '';
+      const reqStr =
+        opt.required && opt.default === undefined ? ' [required]' : '';
+      const deprecatedStr = opt.deprecated ? ' [deprecated]' : '';
+      lines.push(
+        `${indent}  --${opt.key}${aliasStr} <${typeStr}>${reqStr}${deprecatedStr}`
+      );
+      if (opt.description) {
+        lines.push(`${indent}    ${opt.description}`);
+      }
+      if (opt.default !== undefined) {
+        lines.push(`${indent}    Default: ${JSON.stringify(opt.default)}`);
+      }
+      if ('choices' in opt && opt.choices) {
+        const choicesList =
+          typeof opt.choices === 'function' ? opt.choices() : opt.choices;
+        lines.push(`${indent}    Valid values: ${choicesList.join(', ')}`);
+      }
+    }
+    lines.push('');
+  }
+
+  // Grouped options
+  for (const group of docs.groupedOptions) {
+    if (group.keys.length > 0) {
+      lines.push(`${indent}${group.label}:`);
+      for (const opt of group.keys) {
+        const typeStr = formatOptionType(opt);
+        const aliasStr = opt.alias?.length
+          ? ` (aliases: ${opt.alias.map((a) => (a.length === 1 ? `-${a}` : `--${a}`)).join(', ')})`
+          : '';
+        const reqStr =
+          opt.required && opt.default === undefined ? ' [required]' : '';
+        lines.push(`${indent}  --${opt.key}${aliasStr} <${typeStr}>${reqStr}`);
+        if (opt.description) {
+          lines.push(`${indent}    ${opt.description}`);
+        }
+        if (opt.default !== undefined) {
+          lines.push(`${indent}    Default: ${JSON.stringify(opt.default)}`);
+        }
+      }
+      lines.push('');
+    }
+  }
+
+  // Examples
+  if (docs.examples.length > 0) {
+    lines.push(`${indent}Examples:`);
+    for (const example of docs.examples) {
+      lines.push(`${indent}  $ ${example}`);
+    }
+    lines.push('');
+  }
+
+  // Subcommands
+  if (docs.subcommands.length > 0) {
+    lines.push(`${indent}Subcommands:`);
+    for (const sub of docs.subcommands) {
+      lines.push(
+        `${indent}  ${sub.name}${sub.description ? ` - ${sub.description}` : ''}`
+      );
+    }
+    lines.push('');
+
+    // Recursively document subcommands
+    for (const sub of docs.subcommands) {
+      lines.push(generateLlmsTxtContent(sub, depth + 1, currentPath));
+    }
+  }
+
+  // Epilogue
+  if (docs.epilogue && depth === 0) {
+    lines.push(`Note: ${docs.epilogue}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatOptionType(opt: Documentation['options'][string]): string {
+  if ('items' in opt && opt.type === 'array') {
+    return `${opt.items}[]`;
+  }
+  return opt.type;
+}
+
 async function generateMarkdownForSingleCommand(
   docs: Documentation,
   out: string,
@@ -367,7 +527,10 @@ async function loadCLIModule(
       });
     } else {
       const tsx = (await import('tsx/cjs/api')) as typeof import('tsx/cjs/api');
-      return tsx.require(cliPath, join(process.cwd(), 'fake-file-for-require.ts'));
+      return tsx.require(
+        cliPath,
+        join(process.cwd(), 'fake-file-for-require.ts')
+      );
     }
   } catch {
     try {

package/src/index.ts

@@ -10,3 +10,4 @@ export type {
 } from './lib/composable-builder';
 export type { ArgumentsOf } from './lib/utils';
 export { ConfigurationProviders } from './lib/configuration-providers';
+export type { LocalizationDictionary, LocalizationFunction } from '@cli-forge/parser';

package/src/lib/cli-localization.spec.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { cli } from './public-api';
+import { TestHarness } from './test-harness';
+import type { LocalizationDictionary } from '@cli-forge/parser';
+
+const ORIGINAL_CONSOLE_LOG = console.log;
+
+function mockConsoleLog() {
+  const lines: string[] = [];
+  console.log = (...contents) =>
+    lines.push(
+      contents
+        .map((s) => (typeof s === 'string' ? s : JSON.stringify(s)))
+        .join(' ')
+    );
+  return {
+    getOutput: () => lines.join('\n'),
+    restore: () => {
+      console.log = ORIGINAL_CONSOLE_LOG;
+    },
+  };
+}
+
+describe('CLI localization', () => {
+  afterEach(() => {
+    console.log = ORIGINAL_CONSOLE_LOG;
+    process.exitCode = undefined;
+  });
+
+  const dictionary: LocalizationDictionary = {
+    name: {
+      default: 'name',
+      'es-ES': 'nombre',
+    },
+    port: {
+      default: 'port',
+      'es-ES': 'puerto',
+    },
+    serve: {
+      default: 'serve',
+      'es-ES': 'servir',
+    },
+  };
+
+  it('should accept localized option keys', async () => {
+    const testCli = cli('test')
+      .localize(dictionary, 'es-ES')
+      .option('name', { type: 'string' })
+      .option('port', { type: 'number' })
+      .command('$0', {
+        handler: () => { /* noop */ },
+      });
+
+    const harness = new TestHarness(testCli);
+    const { args } = await harness.parse(['--nombre', 'test', '--puerto', '8080']);
+
+    expect(args.name).toBe('test');
+    expect(args.port).toBe(8080);
+  });
+
+  it('should accept default option keys as aliases', async () => {
+    const testCli = cli('test')
+      .localize(dictionary, 'es-ES')
+      .option('name', { type: 'string' })
+      .option('port', { type: 'number' })
+      .command('$0', {
+        handler: () => { /* noop */ },
+      });
+
+    const harness = new TestHarness(testCli);
+    const { args } = await harness.parse(['--name', 'test', '--port', '8080']);
+
+    expect(args.name).toBe('test');
+    expect(args.port).toBe(8080);
+  });
+
+  it('should display localized keys in help text', async () => {
+    const mock = mockConsoleLog();
+    try {
+      await cli('test')
+        .localize(dictionary, 'es-ES')
+        .option('name', { type: 'string', description: 'Name option' })
+        .option('port', { type: 'number', description: 'Port option' })
+        .forge(['--help']);
+
+      const output = mock.getOutput();
+      expect(output).toContain('--nombre');
+      expect(output).toContain('--puerto');
+      expect(output).not.toContain('--name '); // Should not show as primary
+      expect(output).not.toContain('--port '); // Should not show as primary
+    } finally {
+      mock.restore();
+    }
+  });
+
+  it('should display localized command names in help text', async () => {
+    const mock = mockConsoleLog();
+    try {
+      await cli('test')
+        .localize(dictionary, 'es-ES')
+        .command('serve', {
+          builder: (cmd) => cmd,
+          handler: () => { /* noop */ },
+          description: 'Start the server',
+        })
+        .forge(['--help']);
+
+      const output = mock.getOutput();
+      expect(output).toContain('servir');
+      expect(output).toContain('Start the server');
+    } finally {
+      mock.restore();
+    }
+  });
+
+  it('should work with subcommands', async () => {
+    const testCli = cli('test')
+      .localize(dictionary, 'es-ES')
+      .command('serve', {
+        builder: (cmd) =>
+          cmd
+            .option('port', { type: 'number' })
+            .option('name', { type: 'string' }),
+        handler: () => { /* noop */ },
+      });
+
+    const harness = new TestHarness(testCli);
+    const { args, commandChain } = await harness.parse(['servir', '--puerto', '8080', '--nombre', 'test']);
+
+    expect(args.port).toBe(8080);
+    expect(args.name).toBe('test');
+    expect(commandChain).toEqual(['servir']);
+  });
+
+  it('should work without localization', async () => {
+    const testCli = cli('test')
+      .option('name', { type: 'string' })
+      .option('port', { type: 'number' })
+      .command('$0', {
+        handler: () => { /* noop */ },
+      });
+
+    const harness = new TestHarness(testCli);
+    const { args } = await harness.parse(['--name', 'test', '--port', '8080']);
+
+    expect(args.name).toBe('test');
+    expect(args.port).toBe(8080);
+  });
+
+  it('should chain localize with other builder methods', async () => {
+    const testCli = cli('test')
+      .localize(dictionary, 'es-ES')
+      .option('name', { type: 'string' })
+      .option('port', { type: 'number' })
+      .env('TEST')
+      .command('$0', {
+        handler: () => { /* noop */ },
+      });
+
+    const harness = new TestHarness(testCli);
+    const { args } = await harness.parse(['--nombre', 'test', '--puerto', '8080']);
+
+    expect(args.name).toBe('test');
+    expect(args.port).toBe(8080);
+  });
+
+  it('should work with localization function', async () => {
+    const localizer = (key: string) => {
+      const translations: Record<string, string> = {
+        name: 'nombre',
+        port: 'puerto',
+        serve: 'servir',
+      };
+      return translations[key] || key;
+    };
+
+    const testCli = cli('test')
+      .localize(localizer)
+      .option('name', { type: 'string' })
+      .option('port', { type: 'number' })
+      .command('serve', {
+        builder: (cmd) => cmd,
+        handler: () => { /* noop */ },
+      });
+
+    const harness = new TestHarness(testCli);
+
+    // Test options with localized keys
+    const { args: args1 } = await harness.parse(['--nombre', 'test', '--puerto', '8080']);
+    expect(args1.name).toBe('test');
+    expect(args1.port).toBe(8080);
+
+    // Test command with localized name
+    const { commandChain } = await harness.parse(['servir']);
+    expect(commandChain).toEqual(['servir']);
+  });
+});

package/src/lib/composable-builder.spec.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { makeComposableBuilder } from './composable-builder';
+import cli from './public-api';
+import { chain } from '@cli-forge/parser';
+
+describe('makeComposableBuilder', () => {
+  describe('capture-and-replay', () => {
+    it('should produce stable middleware references across applications', () => {
+      const builder = makeComposableBuilder((cmd) =>
+        cmd
+          .option('verbose', { type: 'boolean' })
+          .middleware((args: any) => args)
+      );
+
+      const cli1 = builder(cli('test1'));
+      const cli2 = builder(cli('test2'));
+
+      const mw1 = [...(cli1 as any).registeredMiddleware];
+      const mw2 = [...(cli2 as any).registeredMiddleware];
+      expect(mw1.length).toBe(1);
+      expect(mw2.length).toBe(1);
+      expect(mw1[0]).toBe(mw2[0]);
+    });
+
+    it('should correctly replay option registrations', async () => {
+      const builder = makeComposableBuilder((cmd) =>
+        cmd.option('verbose', { type: 'boolean' })
+      );
+
+      let handlerArgs: any;
+      await chain(cli('test'), builder)
+        .command('$0', {
+          handler: (args) => {
+            handlerArgs = args;
+          },
+        })
+        .forge(['--verbose']);
+      expect(handlerArgs.verbose).toBe(true);
+    });
+
+    it('should deduplicate middleware when builder applied to parent and child', async () => {
+      let mwCallCount = 0;
+      const builder = makeComposableBuilder((cmd) =>
+        cmd.option('verbose', { type: 'boolean' }).middleware((args: any) => {
+          mwCallCount++;
+          return args;
+        })
+      );
+
+      await chain(cli('parent'), builder)
+        .command('child', {
+          builder: (cmd) =>
+            chain(cmd, builder).option('format', { type: 'string' }),
+          handler: () => { /* noop */ },
+        })
+        .forge(['child']);
+      expect(mwCallCount).toBe(1);
+    });
+
+    it('should replay commands registered by the builder', () => {
+      const builder = makeComposableBuilder((cmd) =>
+        cmd.command('sub', {
+          builder: (c) => c.option('flag', { type: 'boolean' }),
+          handler: () => { /* noop */ },
+        })
+      );
+
+      const myCli = builder(cli('test'));
+      const children = myCli.getChildren();
+      expect(children).toHaveProperty('sub');
+    });
+  });
+});

package/src/lib/composable-builder.ts

@@ -1,4 +1,4 @@
-import { ParsedArgs } from '@cli-forge/parser';
+import type { ParsedArgs } from '@cli-forge/parser';
 import { CLI } from './public-api';
 
 /**
@@ -30,6 +30,10 @@ export type ComposableBuilder<
  * Can be used to add options, commands, or any other CLI modifications.
  * Children added by the builder function are properly tracked in the type.
  *
+ * The builder function runs once at creation time against a recording Proxy.
+ * Subsequent applications replay the captured operations, ensuring inline
+ * middleware closures have stable references for Set-based deduplication.
+ *
  * @typeParam TArgs2 - The args type after the builder runs
  * @typeParam TChildren2 - The children type added by the builder
  */
@@ -43,15 +47,32 @@ export function makeComposableBuilder<
     init: CLI<ParsedArgs, any, {}, any>
   ) => CLI<TArgs2, any, TChildren2, any>
 ) {
+  // Run builder once against a recording proxy to capture operations.
+  // Replaying these ensures inline closures (e.g. middleware) keep stable
+  // references across applications, enabling Set-based deduplication.
+  const operations: { method: string; args: any[] }[] = [];
+  const proxy = new Proxy({} as CLI, {
+    get(_target, prop) {
+      return (...args: any[]) => {
+        operations.push({ method: prop as string, args });
+        return proxy;
+      };
+    },
+  });
+  fn(proxy);
+
   return <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
     init: CLI<TInit, THandlerReturn, TChildren, TParent>
-  ) =>
-    // eslint-disable-next-line @typescript-eslint/ban-types
-    fn(init as unknown as CLI<ParsedArgs, any, {}, any>) as unknown as CLI<
+  ) => {
+    let current: any = init;
+    for (const op of operations) {
+      current = current[op.method](...op.args);
+    }
+    return current as unknown as CLI<
       TInit & TArgs2,
       THandlerReturn,
       TChildren & TChildren2,
       TParent
     >;
+  };
 }
-

package/src/lib/documentation.ts

@@ -2,6 +2,7 @@ import {
   UnknownOptionConfig,
   OptionConfigToType,
   readDefaultValue,
+  LocalizationDictionary,
 } from '@cli-forge/parser';
 import { InternalCLI } from './internal-cli';
 import { CLI } from './public-api';
@@ -19,6 +20,11 @@ export type Documentation = {
     keys: Array<NormalizedOptionConfig>;
   }>;
   subcommands: Documentation[];
+  /**
+   * Localized keys for options and commands. Maps from default key to full localization entry.
+   * Only present if localization is configured.
+   */
+  localizedKeys?: LocalizationDictionary;
 };
 
 function normalizeOptionConfigForDocumentation<T extends UnknownOptionConfig>(
@@ -85,7 +91,42 @@ export function generateDocumentation(
     generateDocumentation(cmd.clone(), [...commandChain, cli.name])
   );
 
-  return {
+  // Get the localization dictionary if configured
+  const dictionary = parser.getLocalizationDictionary();
+  let localizedKeys: LocalizationDictionary | undefined;
+  
+  if (dictionary) {
+    // Filter to only include keys that are actually used in this CLI
+    const usedKeys: LocalizationDictionary = {};
+    let hasUsedKeys = false;
+    
+    for (const key in parser.configuredOptions) {
+      if (dictionary[key]) {
+        usedKeys[key] = dictionary[key];
+        hasUsedKeys = true;
+      }
+    }
+    
+    // Also include command names - track unique commands by instance to avoid duplicates
+    const seenCommands = new Set<InternalCLI<any, any, any, any>>();
+    for (const cmdKey in cli.getSubcommands()) {
+      const cmdInstance = cli.getSubcommands()[cmdKey];
+      if (!seenCommands.has(cmdInstance)) {
+        seenCommands.add(cmdInstance);
+        const defaultName = cmdInstance.name;
+        if (dictionary[defaultName]) {
+          usedKeys[defaultName] = dictionary[defaultName];
+          hasUsedKeys = true;
+        }
+      }
+    }
+    
+    if (hasUsedKeys) {
+      localizedKeys = usedKeys;
+    }
+  }
+
+  const result: Documentation = {
     name: cli.name,
     description: cli.configuration?.description,
     usage: cli.configuration?.usage
@@ -103,5 +144,11 @@ export function generateDocumentation(
     options,
     positionals,
     subcommands,
-  } as Documentation;
+  };
+
+  if (localizedKeys) {
+    result.localizedKeys = localizedKeys;
+  }
+
+  return result;
 }

package/src/lib/format-help.ts

@@ -24,9 +24,10 @@ export function formatHelp(parentCLI: InternalCLI<any>): string {
         : [
             parentCLI.name,
             ...parentCLI.commandChain,
-            ...command.parser.configuredPositionals.map((p) =>
-              p.required ? `<${p.key}>` : `[${p.key}]`
-            ),
+            ...command.parser.configuredPositionals.map((p) => {
+              const displayKey = command.parser.getDisplayKey(p.key);
+              return p.required ? `<${displayKey}>` : `[${displayKey}]`;
+            }),
           ].join(' ')
     }`
   );
@@ -37,10 +38,19 @@ export function formatHelp(parentCLI: InternalCLI<any>): string {
     help.push('');
     help.push('Commands:');
   }
+  // Track displayed commands by their actual CLI instance to avoid duplicates
+  const displayedCommands = new Set<InternalCLI<any, any, any, any>>();
   for (const key in command.registeredCommands) {
     const subcommand = command.registeredCommands[key];
+    // Skip if we've already displayed this command instance
+    if (displayedCommands.has(subcommand)) {
+      continue;
+    }
+    displayedCommands.add(subcommand);
+    // Use the localized command name for display based on the command's default name
+    const displayKey = command.getLocalizedCommandName(subcommand.name);
     help.push(
-      `  ${key}${
+      `  ${displayKey}${
         subcommand.configuration?.description
           ? ' - ' + subcommand.configuration.description
           : ''
@@ -52,10 +62,10 @@ export function formatHelp(parentCLI: InternalCLI<any>): string {
     command.parser.configuredOptions
   ).filter((c) => !c.positional);
 
-  help.push(...getOptionBlock('Options', nonpositionalOptions));
+  help.push(...getOptionBlock('Options', nonpositionalOptions, command.parser));
 
   for (const { label, keys } of groupedOptions) {
-    help.push(...getOptionBlock(label, keys));
+    help.push(...getOptionBlock(label, keys, command.parser));
   }
 
   if (command.configuration?.examples?.length) {
@@ -117,7 +127,11 @@ function removeTrailingAndLeadingQuotes(str: string) {
   return str.replace(/^['"]/, '').replace(/['"]$/, '');
 }
 
-function getOptionBlock(label: string, options: InternalOptionConfig[]) {
+function getOptionBlock(
+  label: string,
+  options: InternalOptionConfig[],
+  parser: import('@cli-forge/parser').ReadonlyArgvParser<any>
+) {
   const lines: string[] = [];
 
   if (options.length > 0) {
@@ -127,7 +141,9 @@ function getOptionBlock(label: string, options: InternalOptionConfig[]) {
 
   const allParts: Array<[key: string, ...parts: string[]]> = [];
   for (const option of options) {
-    allParts.push([option.key, ...getOptionParts(option)]);
+    // Use the display key (localized) instead of the storage key
+    const displayKey = parser.getDisplayKey(option.key);
+    allParts.push([displayKey, ...getOptionParts(option)]);
   }
   const paddingValues: number[] = [];
   for (let i = 0; i < allParts.length; i++) {

package/src/lib/interactive-shell.ts

@@ -58,6 +58,8 @@ export class InteractiveShell {
         process.emit('SIGINT');
       });
 
+    // Show the cursor (in case it was hidden)
+    process.stdout.write('\x1b[?25h');
     this.rl.prompt();
 
     this.registerLineListener(async (line) => {