a5c-ai/yargs-scaffolder

Yargs Scaffolder

Generate a complete Yargs CLI application with TypeScript, middleware support, and best practices.

Capabilities

• Generate TypeScript-based Yargs CLI projects
• Create command modules with positional arguments
• Set up middleware for common operations (logging, config loading)
• Configure type coercion and validation
• Implement strict mode and fail handlers
• Set up build and development workflows

Usage

Invoke this skill when you need to:

• Bootstrap a new CLI application using Yargs
• Create a CLI with command modules pattern
• Set up middleware-based processing
• Configure complex argument parsing

Inputs

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectName | string | Yes | Name of the CLI project (kebab-case) | | description | string | Yes | Short description of the CLI | | commands | array | No | List of commands to scaffold | | typescript | boolean | No | Use TypeScript (default: true) | | packageManager | string | No | npm, yarn, or pnpm (default: npm) | | strictMode | boolean | No | Enable strict mode (default: true) |

Command Structure

{
  "commands": [
    {
      "name": "serve",
      "description": "Start the server",
      "aliases": ["s"],
      "positional": [
        { "name": "port", "type": "number", "default": 3000 }
      ],
      "options": [
        { "name": "host", "type": "string", "default": "localhost" },
        { "name": "watch", "type": "boolean", "alias": "w" }
      ]
    }
  ]
}

Output Structure

<projectName>/
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md
├── src/
│   ├── index.ts              # Entry point
│   ├── cli.ts                # Yargs setup
│   ├── commands/
│   │   ├── index.ts          # Command exports
│   │   └── <command>.ts      # Command modules
│   ├── middleware/
│   │   ├── logger.ts         # Logging middleware
│   │   └── config.ts         # Config loading middleware
│   ├── utils/
│   │   └── helpers.ts        # Helper utilities
│   └── types/
│       └── index.ts          # Type definitions
└── tests/
    └── commands/
        └── <command>.test.ts

Generated Code Patterns

Main CLI Entry (src/cli.ts)

import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
import * as commands from './commands';
import { loggerMiddleware } from './middleware/logger';

export const cli = yargs(hideBin(process.argv))
  .scriptName('<projectName>')
  .usage('$0 <cmd> [args]')
  .middleware([loggerMiddleware])
  .command(commands.serveCommand)
  .command(commands.buildCommand)
  .demandCommand(1, 'You need at least one command')
  .strict()
  .fail((msg, err, yargs) => {
    if (err) throw err;
    console.error(msg);
    console.error(yargs.help());
    process.exit(1);
  })
  .help()
  .alias('help', 'h')
  .version()
  .alias('version', 'v')
  .wrap(Math.min(120, process.stdout.columns || 80));

Command Module Template

import { CommandModule, Argv } from 'yargs';

interface ServeArgs {
  port: number;
  host: string;
  watch: boolean;
}

export const serveCommand: CommandModule<{}, ServeArgs> = {
  command: 'serve [port]',
  aliases: ['s'],
  describe: 'Start the development server',
  builder: (yargs: Argv) => {
    return yargs
      .positional('port', {
        type: 'number',
        default: 3000,
        describe: 'Port to listen on'
      })
      .option('host', {
        type: 'string',
        default: 'localhost',
        describe: 'Host to bind to'
      })
      .option('watch', {
        alias: 'w',
        type: 'boolean',
        default: false,
        describe: 'Enable watch mode'
      });
  },
  handler: async (argv) => {
    console.log(`Starting server on ${argv.host}:${argv.port}`);
  }
};

Dependencies

{
  "dependencies": {
    "yargs": "^17.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@types/yargs": "^17.0.0",
    "typescript": "^5.0.0",
    "tsx": "^4.0.0",
    "vitest": "^1.0.0"
  }
}

Workflow

1. Validate inputs - Check project name, commands structure
2. Create directory structure - Set up folders and base files
3. Generate package.json - Configure project metadata
4. Generate tsconfig.json - TypeScript configuration
5. Create CLI entry point - Yargs setup with middleware
6. Generate command modules - Individual command files
7. Create middleware - Logger, config middleware
8. Set up tests - Test structure for commands
9. Initialize git - Optional git initialization

Best Practices Applied

• TypeScript strict mode enabled
• Command module pattern for scalability
• Middleware for cross-cutting concerns
• Strict mode with custom fail handler
• Proper type definitions for arguments
• Completion script support

References

• Yargs Documentation: https://yargs.js.org/
• Yargs GitHub: https://github.com/yargs/yargs
• Command Modules: https://yargs.js.org/docs/#api-reference-commandmodule

Target Processes

• cli-application-bootstrap
• argument-parser-setup
• cli-command-structure-design