commander 9.5.0: CommanderError

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: verify commander.CommanderError in pkg:npm/commander@9.5.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/commander@9.5.0
Demonstrate these symbols/APIs:
  - commander.CommanderError
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:965d15de5d4701ee8e6cb06ba6991161d140b5dc8f98a4ceb6b32b1a709c54c4","constraints":{"executionContext":"node"},"contract":["CommanderError instantiates with exitCode, code, and message properties representing CLI execution errors","exitOverride causes Command parsing errors such as unknown command or missing mandatory option to throw CommanderError instances","exitOverride throws CommanderError with exitCode 0 and code commander.version or commander.helpDisplayed for version and help triggers","CommanderError instances inherit from the standard JavaScript Error class and can be caught with try-catch blocks","Custom exitOverride error handlers can inspect and rethrow or customize CommanderError instances"],"goal":"verify commander.CommanderError in pkg:npm/commander@9.5.0","kind":"HOW","packages":["pkg:npm/commander@9.5.0"],"schemaVersion":1,"symbols":["commander.CommanderError"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/commander@9.5.0"],"schemaVersion":1,"subject":"pkg:npm/commander@9.5.0","symbols":["commander.CommanderError"],"verifierAdapter":"node-typescript@1"}

'use strict';

const { CommanderError, Command } = require('commander');

/**
 * Creates a new CommanderError instance.
 * @param {number} exitCode - The process exit code.
 * @param {string} code - The error identifier code.
 * @param {string} message - The error message.
 * @returns {CommanderError}
 */
function createCustomError(exitCode, code, message) {
  return new CommanderError(exitCode, code, message);
}

/**
 * Creates a Command configured with exitOverride and silent output handlers.
 * @param {Function} [customHandler] - Optional custom exitOverride handler function.
 * @returns {Command}
 */
function createSilentProgram(customHandler) {
  const program = new Command();
  if (typeof customHandler === 'function') {
    program.exitOverride(customHandler);
  } else {
    program.exitOverride();
  }
  program.configureOutput({
    writeOut: () => {},
    writeErr: () => {}
  });
  return program;
}

/**
 * Checks if a given object is an instance of CommanderError.
 * @param {*} err - The error object to check.
 * @returns {boolean}
 */
function isCommanderError(err) {
  return err instanceof CommanderError;
}

/**
 * Classifies an error and extracts CommanderError metadata if applicable.
 * @param {*} err - The error to classify.
 * @returns {{ isCommanderError: boolean, exitCode?: number, code?: string, message?: string }}
 */
function classifyError(err) {
  if (err instanceof CommanderError) {
    return {
      isCommanderError: true,
      exitCode: err.exitCode,
      code: err.code,
      message: err.message
    };
  }
  return {
    isCommanderError: false
  };
}

module.exports = {
  CommanderError,
  Command,
  createCustomError,
  createSilentProgram,
  isCommanderError,
  classifyError
};

{
  "name": "sample-commander-error",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-commander-error",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "commander": "9.5.0"
      }
    },
    "node_modules/commander": {
      "version": "9.5.0",
      "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz",
      "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==",
      "license": "MIT",
      "engines": {
        "node": "^12.20.0 || >=14"
      }
    }
  }
}

{
  "name": "sample-commander-error",
  "version": "1.0.0",
  "private": true,
  "description": "verify commander.CommanderError in pkg:npm/commander@9.5.0",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "commander": "9.5.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify commander.CommanderError in pkg:npm/commander@9.5.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/commander@9.5.0"
  ],
  "symbols": [
    "commander.CommanderError"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

'use strict';

const assert = require('assert');
const {
  CommanderError,
  Command,
  createCustomError,
  createSilentProgram,
  isCommanderError,
  classifyError
} = require('../index.js');

function testDirectInstantiation() {
  const err = createCustomError(2, 'commander.customError', 'Custom error occurred');
  assert.strictEqual(isCommanderError(err), true);
  assert.strictEqual(err instanceof Error, true);
  assert.strictEqual(err.name, 'CommanderError');
  assert.strictEqual(err.exitCode, 2);
  assert.strictEqual(err.code, 'commander.customError');
  assert.strictEqual(err.message, 'Custom error occurred');

  const classification = classifyError(err);
  assert.deepStrictEqual(classification, {
    isCommanderError: true,
    exitCode: 2,
    code: 'commander.customError',
    message: 'Custom error occurred'
  });

  const plainErr = new Error('Standard JS error');
  assert.strictEqual(isCommanderError(plainErr), false);
  assert.deepStrictEqual(classifyError(plainErr), {
    isCommanderError: false
  });
}

function testUnknownCommandError() {
  const program = createSilentProgram();
  program
    .command('build')
    .action(() => {});
  program
    .command('serve')
    .action(() => {});

  assert.throws(
    () => {
      program.parse(['node', 'cli', 'deploy']);
    },
    (err) => {
      assert.strictEqual(isCommanderError(err), true);
      assert.strictEqual(err.code, 'commander.unknownCommand');
      assert.strictEqual(err.exitCode, 1);
      assert.match(err.message, /unknown command 'deploy'/);
      return true;
    }
  );
}

function testMissingMandatoryOption() {
  const program = createSilentProgram();
  program
    .requiredOption('-c, --config <path>', 'path to configuration file')
    .action(() => {});

  assert.throws(
    () => {
      program.parse(['node', 'cli']);
    },
    (err) => {
      assert.strictEqual(isCommanderError(err), true);
      assert.strictEqual(err.code, 'commander.missingMandatoryOptionValue');
      assert.strictEqual(err.exitCode, 1);
      assert.match(err.message, /required option '-c, --config <path>' not specified/);
      return true;
    }
  );
}

function testUnknownOption() {
  const program = createSilentProgram();
  program
    .option('-v, --verbose', 'enable verbose logging')
    .action(() => {});

  assert.throws(
    () => {
      program.parse(['node', 'cli', '--invalid-flag']);
    },
    (err) => {
      assert.strictEqual(isCommanderError(err), true);
      assert.strictEqual(err.code, 'commander.unknownOption');
      assert.strictEqual(err.exitCode, 1);
      assert.match(err.message, /unknown option '--invalid-flag'/);
      return true;
    }
  );
}

function testVersionAndHelpTriggers() {
  const versionProgram = createSilentProgram();
  versionProgram.version('2.4.0');

  assert.throws(
    () => {
      versionProgram.parse(['node', 'cli', '--version']);
    },
    (err) => {
      assert.strictEqual(isCommanderError(err), true);
      assert.strictEqual(err.code, 'commander.version');
      assert.strictEqual(err.exitCode, 0);
      assert.strictEqual(err.message, '2.4.0');
      return true;
    }
  );

  const helpProgram = createSilentProgram();
  assert.throws(
    () => {
      helpProgram.parse(['node', 'cli', '--help']);
    },
    (err) => {
      assert.strictEqual(isCommanderError(err), true);
      assert.strictEqual(err.code, 'commander.helpDisplayed');
      assert.strictEqual(err.exitCode, 0);
      return true;
    }
  );
}

function testCustomExitOverrideHandler() {
  let interceptedError = null;
  const customHandler = (err) => {
    interceptedError = err;
    throw new Error(`Custom handler wrapped: [${err.code}] ${err.message}`);
  };

  const program = createSilentProgram(customHandler);
  program.requiredOption('-e, --env <name>', 'environment');

  assert.throws(
    () => {
      program.parse(['node', 'cli']);
    },
    (err) => {
      assert.strictEqual(isCommanderError(interceptedError), true);
      assert.strictEqual(interceptedError.code, 'commander.missingMandatoryOptionValue');
      assert.strictEqual(err instanceof CommanderError, false);
      assert.match(err.message, /Custom handler wrapped: \[commander\.missingMandatoryOptionValue\]/);
      return true;
    }
  );
}

function run() {
  testDirectInstantiation();
  testUnknownCommandError();
  testMissingMandatoryOption();
  testUnknownOption();
  testVersionAndHelpTriggers();
  testCustomExitOverrideHandler();
  console.log('Contract tests passed successfully.');
  process.exit(0);
}

run();