Composable Builders

import { makeComposableBuilder } from 'cli-forge';

/**
 * Adds a --verbose flag for detailed output.
 * This option is shared across many commands.
 */
export const withVerbose = makeComposableBuilder((args) =>
  args.option('verbose', {
    type: 'boolean',
    alias: ['v'],
    description: 'Enable verbose output',
    default: false,
  })
);

/**
 * Adds a --config option for specifying a config file path.
 */
export const withConfig = makeComposableBuilder((args) =>
  args.option('config', {
    type: 'string',
    alias: ['c'],
    description: 'Path to configuration file',
  })
);

/**
 * Adds a --dry-run flag for preview mode.
 */
export const withDryRun = makeComposableBuilder((args) =>
  args.option('dryRun', {
    type: 'boolean',
    description: 'Preview changes without executing',
    default: false,
  })
);

import { makeComposableBuilder } from 'cli-forge';

/**
 * Output format choices. Using a const array allows TypeScript
 * to infer the literal union type.
 */
export const OUTPUT_FORMATS = ['json', 'yaml', 'table', 'plain'] as const;
export type OutputFormat = (typeof OUTPUT_FORMATS)[number];

/**
 * Adds a --format option for controlling output format.
 * The choices are constrained to the OUTPUT_FORMATS array.
 */
export const withFormat = makeComposableBuilder((args) =>
  args.option('format', {
    type: 'string',
    alias: ['f'],
    description: 'Output format',
    choices: OUTPUT_FORMATS,
    default: 'plain' as OutputFormat,
  })
);

/**
 * Adds a --output option for specifying output file path.
 */
export const withOutputFile = makeComposableBuilder((args) =>
  args.option('output', {
    type: 'string',
    alias: ['o'],
    description: 'Write output to file instead of stdout',
  })
);

import { chain, makeComposableBuilder } from 'cli-forge';

import { withVerbose, withDryRun } from '../builders/common';
import { withFormat, withOutputFile } from '../builders/output';

/**
 * The build command composes multiple option builders.
 * TypeScript correctly infers the combined type of all options.
 */
export const buildCommand = makeComposableBuilder((args) =>
  args.command('build', {
    description: 'Build the project',
    builder: (cmd) =>
      chain(
        cmd,
        withVerbose,
        withDryRun,
        withFormat,
        withOutputFile
      ).option('target', {
        type: 'string',
        description: 'Build target',
        default: 'production',
      }),

    handler: (args) => {
      // All composed options are available with correct types
      if (args.verbose) {
        console.log('Build configuration:');
        console.log(`  verbose: ${args.verbose}`);
        console.log(`  dryRun: ${args.dryRun}`);
        console.log(`  format: ${args.format}`);
        console.log(`  output: ${args.output ?? 'stdout'}`);
        console.log(`  target: ${args.target}`);
      }

      if (args.dryRun) {
        console.log('Dry run: would build project');
        return;
      }

      console.log(`Building for ${args.target}...`);
    },
  })
);

import { chain, makeComposableBuilder } from 'cli-forge';

import { withVerbose, withConfig } from '../builders/common';

/**
 * The serve command reuses the same verbose option as build.
 * This ensures consistent behavior across commands.
 */
export const serveCommand = makeComposableBuilder((args) =>
  args.command('serve', {
    description: 'Start development server',
    builder: (cmd) =>
      chain(cmd, withVerbose, withConfig).option('port', {
        type: 'number',
        alias: ['p'],
        description: 'Port to listen on',
        default: 3000,
      }),

    handler: (args) => {
      if (args.verbose) {
        console.log('Server configuration:');
        console.log(`  verbose: ${args.verbose}`);
        console.log(`  config: ${args.config ?? 'default'}`);
        console.log(`  port: ${args.port}`);
      }

      console.log(`Starting server on port ${args.port}...`);
    },
  })
);

import { chain, cli } from 'cli-forge';

import { buildCommand } from './commands/build';
import { serveCommand } from './commands/serve';

const subcommand = cli('subcommand', {
  builder: (args) => args.option('foo', { type: 'string' }),
});

/**
 * Main CLI that composes commands from separate modules.
 * Each command uses shared option builders for consistency.
 */
const app = cli('composable-demo', {
  description: 'Demonstrates composable option builders',
  builder: (args) =>
    chain(args, buildCommand, serveCommand).command(subcommand),
});

export default app;

if (require.main === module) {
  app.forge();
}