cli-forge 1.2.3 → 1.4.0

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

@@ -7,8 +7,8 @@ import { pathToFileURL } from 'node:url';
 
 import cli, { ArgumentsOf, CLI } from '../..';
 import { Documentation, generateDocumentation } from '../../lib/documentation';
-import { ensureDirSync } from '../utils/fs';
 import { InternalCLI } from '../../lib/internal-cli';
+import { ensureDirSync } from '../utils/fs';
 
 type mdfactory = typeof import('markdown-factory');
 
@@ -68,6 +68,10 @@ export const generateDocumentationCommand = cli('generate-documentation', {
     const documentation = generateDocumentation(cli);
     if (args.format === 'md') {
       await generateMarkdownDocumentation(documentation, args);
+
+      if (args.llms) {
+        generateLlmsTxt(documentation, args);
+      }
     } else if (args.format === 'json') {
       const outfile = args.output.endsWith('json')
         ? args.output
@@ -76,10 +80,6 @@ export const generateDocumentationCommand = cli('generate-documentation', {
       ensureDirSync(outdir);
       writeFileSync(outfile, JSON.stringify(documentation, null, 2));
     }
-
-    if (args.llms) {
-      generateLlmsTxt(documentation, args);
-    }
   },
 });
 
@@ -116,7 +116,9 @@ function generateLlmsTxtContent(
       lines.push(docs.description);
       lines.push('');
     }
-    lines.push('This document describes the CLI commands and options for AI agent consumption.');
+    lines.push(
+      'This document describes the CLI commands and options for AI agent consumption.'
+    );
     lines.push('');
   } else {
     lines.push(`${indent}## ${fullCommand}`);
@@ -154,7 +156,9 @@ function generateLlmsTxtContent(
     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(', ')})`
+        ? ` (aliases: ${opt.alias
+            .map((a) => (a.length === 1 ? `-${a}` : `--${a}`))
+            .join(', ')})`
         : '';
       const reqStr =
         opt.required && opt.default === undefined ? ' [required]' : '';
@@ -184,7 +188,9 @@ function generateLlmsTxtContent(
       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(', ')})`
+          ? ` (aliases: ${opt.alias
+              .map((a) => (a.length === 1 ? `-${a}` : `--${a}`))
+              .join(', ')})`
           : '';
         const reqStr =
           opt.required && opt.default === undefined ? ' [required]' : '';
@@ -200,6 +206,16 @@ function generateLlmsTxtContent(
     }
   }
 
+  // Configuration sources
+  if (docs.configurationSources && docs.configurationSources.length > 0) {
+    lines.push(`${indent}Configuration:`);
+    for (const section of docs.configurationSources) {
+      lines.push(`${indent}  ${section.heading}`);
+      lines.push(`${indent}    ${section.body}`);
+    }
+    lines.push('');
+  }
+
   // Examples
   if (docs.examples.length > 0) {
     lines.push(`${indent}Examples:`);
@@ -214,7 +230,9 @@ function generateLlmsTxtContent(
     lines.push(`${indent}Subcommands:`);
     for (const sub of docs.subcommands) {
       lines.push(
-        `${indent}  ${sub.name}${sub.description ? ` - ${sub.description}` : ''}`
+        `${indent}  ${sub.name}${
+          sub.description ? ` - ${sub.description}` : ''
+        }`
       );
     }
     lines.push('');
@@ -269,12 +287,19 @@ async function generateMarkdownForSingleCommand(
             md
           )
         ),
+        getConfigurationSourcesLink(
+          docs.configurationSources,
+          outdir,
+          docsRoot,
+          md
+        ),
         getSubcommandsFragment(docs.subcommands, outdir, docsRoot, md),
         getExamplesFragment(docs.examples, md),
         getEpilogueFragment(docs.epilogue, md),
       ].filter(isTruthy)
     )
   );
+  writeConfigurationSourcesFile(docs.configurationSources, outdir, md);
   for (const subcommand of docs.subcommands) {
     await generateMarkdownForSingleCommand(
       subcommand,
@@ -347,6 +372,42 @@ function getFlagArgsFragment(
   );
 }
 
+function getConfigurationSourcesLink(
+  sources: Documentation['configurationSources'],
+  outdir: string,
+  docsRoot: string,
+  md: mdfactory
+) {
+  if (!sources || sources.length === 0) {
+    return undefined;
+  }
+  const linkPath =
+    './' +
+    joinPathFragments(
+      normalize(relative(docsRoot, outdir)),
+      'configuration.md'
+    );
+  return md.h2('Configuration', md.link(linkPath, 'Configuration'));
+}
+
+function writeConfigurationSourcesFile(
+  sources: Documentation['configurationSources'],
+  outdir: string,
+  md: mdfactory
+) {
+  if (!sources || sources.length === 0) {
+    return;
+  }
+  ensureDirSync(outdir);
+  writeFileSync(
+    join(outdir, 'configuration.md'),
+    md.h1(
+      'Configuration',
+      ...sources.map((section) => md.h2(section.heading, section.body))
+    )
+  );
+}
+
 function getSubcommandsFragment(
   subcommands: Documentation['subcommands'],
   outdir: string,

package/src/index.ts

@@ -9,5 +9,6 @@ export type {
   ExtractChildren,
 } from './lib/composable-builder';
 export type { ArgumentsOf } from './lib/utils';
+export type { PromptConfig, PromptOptionConfig, PromptOption, PromptProvider } from './lib/prompt-types';
 export { ConfigurationProviders } from './lib/configuration-providers';
 export type { LocalizationDictionary, LocalizationFunction } from '@cli-forge/parser';

package/src/lib/composable-builder.ts

@@ -19,7 +19,7 @@ export type ExtractArgs<T> = T extends CLI<infer A, any, any, any> ? A : never;
  */
 export type ComposableBuilder<
   TArgs2 extends ParsedArgs,
-  // eslint-disable-next-line @typescript-eslint/ban-types
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   TAddedChildren = {}
 > = <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
   init: CLI<TInit, THandlerReturn, TChildren, TParent>
@@ -39,11 +39,11 @@ export type ComposableBuilder<
  */
 export function makeComposableBuilder<
   TArgs2 extends ParsedArgs,
-  // eslint-disable-next-line @typescript-eslint/ban-types
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
   TChildren2 = {}
 >(
   fn: (
-    // eslint-disable-next-line @typescript-eslint/ban-types
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
     init: CLI<ParsedArgs, any, {}, any>
   ) => CLI<TArgs2, any, TChildren2, any>
 ) {

package/src/lib/configuration-providers.ts

@@ -1,5 +1,13 @@
 import { ConfigurationFiles } from '@cli-forge/parser';
 
+let md: typeof import('markdown-factory') | undefined;
+try {
+  // markdown-factory is an optional peer dependency
+  md = require('markdown-factory');
+} catch {
+  // not available
+}
+
 /**
  * A collection of built-in configuration provider factories. These should be invoked and passed to
  * {@link CLI.config} to load configuration from various sources. For custom configuration providers, see
@@ -25,12 +33,53 @@ export const ConfigurationProviders = {
   /**
    * Load configuration from a JSON file.
    *
-   * @param filename The filename of the JSON file to load.
+   * @param filename The filename (or array of possible filenames) of the JSON file to load.
+   *   When an array is provided, the nearest matching file wins.
    * @param key The key in the JSON file to load as configuration. By default, the entire JSON object is loaded.
    */
-  JsonFile<T>(filename: string, key?: string) {
-    return ConfigurationFiles.getJsonFileConfigLoader<T>(filename, (json) =>
-      key ? json[key] : json
+  JsonFile<T>(filename: string | string[], key?: string) {
+    const loader = ConfigurationFiles.getJsonFileConfigLoader<T>(
+      filename,
+      key ? (json) => json[key] : undefined,
+      key ? (json, config) => ({ ...json, [key]: config }) : undefined
     );
+    if (key) {
+      const filenames = Array.isArray(filename) ? filename : [filename];
+      const fileList = filenames.join(', ');
+      loader.describeConfig = () => {
+        const heading = `JSON File: ${fileList} (key: "${key}")`;
+        if (md) {
+          return {
+            heading,
+            body: md.lines(
+              filenames.length > 1
+                ? `Searches for one of: ${filenames.map((f) => md.code(f)).join(', ')}`
+                : `Searches for ${md.code(filenames[0])}`,
+              'Resolution walks up the directory tree from the working directory, using the nearest match.',
+              `Reads the ${md.code(`"${key}"`)} key from the JSON file.`,
+              `Supports ${md.code('"extends"')} for configuration inheritance.`,
+              '',
+              md.bold('Example:'),
+              md.codeBlock(
+                JSON.stringify({ [key]: { option: 'value' } }, null, 2),
+                'json'
+              )
+            ),
+          };
+        }
+        return {
+          heading,
+          body: [
+            filenames.length > 1
+              ? `Searches for one of: ${fileList}`
+              : `Searches for ${filenames[0]}`,
+            'Resolution walks up the directory tree from the working directory, using the nearest match.',
+            `Reads the "${key}" key from the JSON file.`,
+            'Supports "extends" for configuration inheritance.',
+          ].join('\n\n'),
+        };
+      };
+    }
+    return loader;
   },
 };

package/src/lib/documentation.ts

@@ -3,6 +3,7 @@ import {
   OptionConfigToType,
   readDefaultValue,
   LocalizationDictionary,
+  ConfigurationFiles,
 } from '@cli-forge/parser';
 import { InternalCLI } from './internal-cli';
 import { CLI } from './public-api';
@@ -20,6 +21,11 @@ export type Documentation = {
     keys: Array<NormalizedOptionConfig>;
   }>;
   subcommands: Documentation[];
+  /**
+   * Describes how configuration is loaded for this command.
+   * Each section is produced by a provider's `describeConfig` method.
+   */
+  configurationSources?: ConfigurationFiles.ConfigurationDocSection[];
   /**
    * Localized keys for options and commands. Maps from default key to full localization entry.
    * Only present if localization is configured.
@@ -146,6 +152,11 @@ export function generateDocumentation(
     subcommands,
   };
 
+  const configDocs = parser.getConfigurationDocs();
+  if (configDocs.length > 0) {
+    result.configurationSources = configDocs;
+  }
+
   if (localizedKeys) {
     result.localizedKeys = localizedKeys;
   }

package/src/lib/format-help.ts

@@ -76,6 +76,16 @@ export function formatHelp(parentCLI: InternalCLI<any>): string {
     }
   }
 
+  const configDocs = command.parser.getConfigurationDocs();
+  if (configDocs.length > 0) {
+    help.push('');
+    help.push('Configuration:');
+    for (const section of configDocs) {
+      help.push(`  ${section.heading}`);
+      help.push(`    ${section.body}`);
+    }
+  }
+
   if (Object.keys(command.registeredCommands).length > 0) {
     help.push(' ');
     help.push(

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it } from 'vitest';
 import { InternalCLI } from './internal-cli';
 import { cli } from './public-api';
+import type { PromptProvider } from './prompt-types';
 
 const ORIGINAL_CONSOLE_LOG = console.log;
 
@@ -1250,4 +1251,303 @@ describe('cliForge', () => {
       expect(result.watch).toBe(true);
     });
   });
+
+  describe('prompt providers', () => {
+    it('should register a prompt provider via withPromptProvider', () => {
+      const provider: PromptProvider = {
+        prompt: async () => 'test-value',
+      };
+      const app = cli('test').withPromptProvider(provider);
+      // Should return CLI for chaining
+      expect(app).toBeDefined();
+    });
+
+    it('should throw if provider has neither prompt nor promptBatch', () => {
+      expect(() => {
+        cli('test').withPromptProvider({} as any);
+      }).toThrow(/must implement at least one of/);
+    });
+
+    it('should store prompt config from option registration', () => {
+      const app = cli('test')
+        .option('name', { type: 'string', prompt: true })
+        .option('age', { type: 'number', prompt: 'How old are you?' })
+        .option('debug', { type: 'boolean' });
+
+      const internal = app as unknown as InternalCLI;
+      expect(internal.promptConfigs.get('name')).toBe(true);
+      expect(internal.promptConfigs.get('age')).toBe('How old are you?');
+      expect(internal.promptConfigs.has('debug')).toBe(false);
+    });
+
+    it('should store prompt config from positional registration', () => {
+      const app = cli('test')
+        .positional('file', { type: 'string', prompt: 'Which file?' });
+
+      const internal = app as unknown as InternalCLI;
+      expect(internal.promptConfigs.get('file')).toBe('Which file?');
+    });
+
+    it('should not store prompt config when prompt is not provided', () => {
+      const app = cli('test')
+        .option('name', { type: 'string' });
+
+      const internal = app as unknown as InternalCLI;
+      expect(internal.promptConfigs.size).toBe(0);
+    });
+
+    it('should store prompt callback config', () => {
+      const promptFn = () => 'Enter value';
+      const app = cli('test')
+        .option('token', { type: 'string', prompt: promptFn });
+
+      const internal = app as unknown as InternalCLI;
+      expect(internal.promptConfigs.get('token')).toBe(promptFn);
+    });
+
+    it('should propagate prompt providers to subcommands', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test')
+        .withPromptProvider(provider)
+        .command('sub', {
+          builder: (cmd) =>
+            cmd.option('name', { type: 'string', required: true }),
+          handler: () => {},
+        });
+
+      await app.forge(['sub']);
+      expect(prompted).toContain('name');
+    });
+  });
+
+  describe('prompt resolution in forge', () => {
+    it('should prompt for required options with no value when provider exists', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return option.name === 'name' ? 'Alice' : 42;
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', required: true })
+        .option('age', { type: 'number', required: true })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+      expect(prompted).toContain('name');
+      expect(prompted).toContain('age');
+    });
+
+    it('should not prompt for options with values already provided', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', required: true })
+        .withPromptProvider(provider);
+
+      await app.forge(['--name', 'Bob']);
+      expect(prompted).not.toContain('name');
+    });
+
+    it('should prompt when prompt is true even if not required', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', prompt: true })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+      expect(prompted).toContain('name');
+    });
+
+    it('should still prompt when prompt is true even if value already provided', async () => {
+      const prompted: string[] = [];
+      let handlerArgs: any;
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'prompted-value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: (args) => {
+          handlerArgs = args;
+        },
+      })
+        .option('name', { type: 'string', prompt: true })
+        .withPromptProvider(provider);
+
+      await app.forge(['--name', 'cli-value']);
+      expect(prompted).toContain('name');
+      expect(handlerArgs.name).toBe('prompted-value');
+    });
+
+    it('should not prompt when prompt is false even if required', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', required: true, prompt: false })
+        .withPromptProvider(provider);
+
+      // This will throw due to required validation, but should not prompt
+      await expect(app.forge([])).rejects.toThrow();
+      expect(prompted).not.toContain('name');
+    });
+
+    it('should use prompt callback to resolve config', async () => {
+      const prompted: string[] = [];
+      const provider: PromptProvider = {
+        prompt: async (option) => {
+          prompted.push(option.name);
+          return 'value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('token', {
+          type: 'string',
+          prompt: (args: any) => (args.authFile ? false : 'Enter token'),
+        })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+      expect(prompted).toContain('token');
+    });
+
+    it('should throw when prompting needed but no provider registered', async () => {
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', prompt: true });
+
+      await expect(app.forge([])).rejects.toThrow(/no prompt provider/i);
+    });
+
+    it('should use filtered providers before fallback providers', async () => {
+      const calls: Array<{ provider: string; option: string }> = [];
+      const filteredProvider: PromptProvider = {
+        filter: (name) => name === 'secret',
+        prompt: async (option) => {
+          calls.push({ provider: 'filtered', option: option.name });
+          return 'secret-value';
+        },
+      };
+      const fallbackProvider: PromptProvider = {
+        prompt: async (option) => {
+          calls.push({ provider: 'fallback', option: option.name });
+          return 'fallback-value';
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('name', { type: 'string', prompt: true })
+        .option('secret', { type: 'string', prompt: true })
+        .withPromptProvider(filteredProvider)
+        .withPromptProvider(fallbackProvider);
+
+      await app.forge([]);
+      expect(calls).toContainEqual({ provider: 'filtered', option: 'secret' });
+      expect(calls).toContainEqual({ provider: 'fallback', option: 'name' });
+    });
+
+    it('should prefer promptBatch over prompt when available', async () => {
+      let batchCalled = false;
+      const provider: PromptProvider = {
+        promptBatch: async (options) => {
+          batchCalled = true;
+          const result: Record<string, unknown> = {};
+          for (const opt of options) {
+            result[opt.name] = 'batch-value';
+          }
+          return result;
+        },
+        prompt: async () => {
+          throw new Error('Should not be called when promptBatch exists');
+        },
+      };
+
+      const app = cli('test', {
+        handler: () => {},
+      })
+        .option('a', { type: 'string', prompt: true })
+        .option('b', { type: 'string', prompt: true })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+      expect(batchCalled).toBe(true);
+    });
+
+    it('should prompt, inject values, and pass validation', async () => {
+      let handlerArgs: any;
+      const provider: PromptProvider = {
+        promptBatch: async (options) => {
+          const results: Record<string, unknown> = {};
+          for (const opt of options) {
+            if (opt.config.type === 'number') {
+              results[opt.name] = 42;
+            } else {
+              results[opt.name] = 'prompted-' + opt.name;
+            }
+          }
+          return results;
+        },
+      };
+
+      const app = cli('test', {
+        handler: (args) => {
+          handlerArgs = args;
+        },
+      })
+        .option('name', { type: 'string', required: true })
+        .option('port', { type: 'number', prompt: 'Which port?' })
+        .option('verbose', { type: 'boolean', default: false })
+        .withPromptProvider(provider);
+
+      await app.forge([]);
+
+      expect(handlerArgs.name).toBe('prompted-name');
+      expect(handlerArgs.port).toBe(42);
+      expect(handlerArgs.verbose).toBe(false); // default, not prompted
+    });
+  });
 });