commander 2.20.3: Parse options, custom coercion, and command arguments in commander 2.20.3

# Option Parsing, Custom Coercion, and Subcommand Actions in Commander 2.20.3

## Known Solutions Search

A search via `search_known_solution` returned existing compatible samples covering modern Commander (13.x and 15.x), but no verified solutions for the Commander 2.x release line.

## Verified Capabilities in Commander 2.20.3

- Setting option definitions with required arguments `<val>` and defaults stores parsed arguments on the Command instance directly as camelCase properties and in `.opts()`.
- Negated flags `--no-*` default to `true` and evaluate to `false` when provided.
- Custom coercion functions (such as `parseInt` or custom callback transformers) transform option string values before assignment.
- Collector functions enable accumulating multiple option occurrences into an array.
- Subcommands registered via `.command()` invoke their `.action()` listener with parsed positional parameters, variadic arguments, and the command object instance upon `program.parse(argv)`.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: Parse options, custom coercion, and command arguments in commander 2.20.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/commander@2.20.3
Demonstrate these symbols/APIs:
  - Command.action
  - Command.option
  - Command.parse

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:ed3ce9280e76a71c4a93397caa3ab1ac2a809a35daa4bee7c263643da5598578","contract":["Defining an option with a required argument and default value parses passed CLI arguments into camelCase properties on the Command instance and populates opts().","Defining a negated boolean option with --no-* initializes its default property value to true and flips it to false when the flag is present.","Passing a custom coercion function to Command.option transforms option string arguments before storing them on the command instance.","Passing a custom collector function to Command.option accumulates multiple repeated option occurrences into an array.","Command.action receives parsed positional arguments and the subcommand instance when a registered subcommand is invoked via Command.parse.","Command.action with variadic argument syntax captures all remaining positional arguments into an array."],"goal":"Parse options, custom coercion, and command arguments in commander 2.20.3","kind":"HOW","packages":["pkg:npm/commander@2.20.3"],"schemaVersion":1,"symbols":["Command.action","Command.option","Command.parse"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/commander@2.20.3"],"schemaVersion":1,"subject":"pkg:npm/commander@2.20.3","symbols":["Command.action","Command.option","Command.parse"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-2386158332",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-2386158332",
      "version": "1.0.0",
      "license": "ISC",
      "dependencies": {
        "commander": "2.20.3"
      }
    },
    "node_modules/commander": {
      "version": "2.20.3",
      "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
      "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
      "license": "MIT"
    }
  }
}

{
  "name": "npm-commander-v2",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "commander": "2.20.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "Parse options, custom coercion, and command arguments in commander 2.20.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/commander@2.20.3"
  ],
  "symbols": [
    "Command.action",
    "Command.option",
    "Command.parse"
  ]
}

import assert from 'node:assert/strict';
import { Command } from 'commander';

// 1. Defining an option with a required argument and default value parses passed CLI arguments into camelCase properties on the Command instance and populates opts().
{
  const program = new Command();
  program.option('-p, --port <number>', 'port number', '8080');
  program.option('-h, --host <hostname>', 'host name');
  program.parse(['node', 'cli', '-h', 'localhost', '-p', '3000']);

  assert.strictEqual(program.port, '3000');
  assert.strictEqual(program.host, 'localhost');
  assert.strictEqual(program.opts().port, '3000');
  assert.strictEqual(program.opts().host, 'localhost');
}

// 2. Defining a negated boolean option with --no-* initializes its default property value to true and flips it to false when the flag is present.
{
  const program = new Command();
  program.option('-c, --cheese', 'add cheese');
  program.option('-b, --no-butter', 'do not add butter');
  program.parse(['node', 'cli', '--no-butter']);

  assert.strictEqual(program.butter, false);
  assert.strictEqual(program.cheese, undefined);
  assert.strictEqual(program.opts().butter, false);
}

// 3. Passing a custom coercion function to Command.option transforms option string arguments before storing them on the command instance.
{
  const program = new Command();
  program.option('-i, --integer <n>', 'an integer argument', (val) => parseInt(val, 10));
  program.parse(['node', 'cli', '-i', '123']);

  assert.strictEqual(program.integer, 123);
  assert.strictEqual(typeof program.integer, 'number');
}

// 4. Passing a custom collector function to Command.option accumulates multiple repeated option occurrences into an array.
{
  function collect(val, memo) {
    memo.push(val);
    return memo;
  }
  const program = new Command();
  program.option('-t, --tag <tag>', 'tag names', collect, []);
  program.parse(['node', 'cli', '-t', 'alpha', '-t', 'beta', '-t', 'gamma']);

  assert.deepStrictEqual(program.tag, ['alpha', 'beta', 'gamma']);
  assert.deepStrictEqual(program.opts().tag, ['alpha', 'beta', 'gamma']);
}

// 5. Command.action receives parsed positional arguments and the subcommand instance when a registered subcommand is invoked via Command.parse.
{
  let actionCalled = false;
  let receivedSource = null;
  let receivedDest = null;
  let receivedCmd = null;

  const program = new Command();
  program
    .command('clone <source> [destination]')
    .description('clone a repository')
    .action((source, destination, cmd) => {
      actionCalled = true;
      receivedSource = source;
      receivedDest = destination;
      receivedCmd = cmd;
    });

  program.parse(['node', 'cli', 'clone', 'https://example.com/repo.git', './dest']);

  assert.strictEqual(actionCalled, true);
  assert.strictEqual(receivedSource, 'https://example.com/repo.git');
  assert.strictEqual(receivedDest, './dest');
  assert.strictEqual(typeof receivedCmd, 'object');
  assert.strictEqual(receivedCmd._name, 'clone');
}

// 6. Command.action with variadic argument syntax captures all remaining positional arguments into an array.
{
  let capturedEnv = null;
  let capturedServers = null;

  const program = new Command();
  program
    .command('deploy <env> [servers...]')
    .description('deploy to servers')
    .action((env, servers) => {
      capturedEnv = env;
      capturedServers = servers;
    });

  program.parse(['node', 'cli', 'deploy', 'production', 'srv1', 'srv2', 'srv3']);

  assert.strictEqual(capturedEnv, 'production');
  assert.deepStrictEqual(capturedServers, ['srv1', 'srv2', 'srv3']);
}