cac 6.7.14: CAC

audit=false

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 cac.CAC in pkg:npm/cac@6.7.14
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/cac@6.7.14
Demonstrate these symbols/APIs:
  - cac.CAC
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:dd69015d0bd05a1dc951adf3d7a38d82d024b8e061ddca4f49a64bac64755d6a","constraints":{"executionContext":"node"},"contract":["CAC constructs an EventEmitter-backed CLI instance with a custom program name and global command","CAC configures application version and global usage text","CAC registers sub-commands and parses arguments and options without executing action handlers","CAC executes registered command action callbacks and tracks parsed args and options on the instance","CAC emits custom events and resets matched command state via unsetMatchedCommand"],"goal":"verify cac.CAC in pkg:npm/cac@6.7.14","kind":"HOW","packages":["pkg:npm/cac@6.7.14"],"schemaVersion":1,"symbols":["cac.CAC"]},"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/cac@6.7.14"],"schemaVersion":1,"subject":"pkg:npm/cac@6.7.14","symbols":["cac.CAC"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-cac",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-cac",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "cac": "6.7.14"
      }
    },
    "node_modules/cac": {
      "version": "6.7.14",
      "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
      "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    }
  }
}

{
  "name": "sample-cac",
  "version": "1.0.0",
  "private": true,
  "description": "verify cac.CAC in pkg:npm/cac@6.7.14",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "cac": "6.7.14"
  }
}

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

const { CAC, Command, cac } = require('cac');

/**
 * Creates a CAC CLI application instance.
 *
 * @param {string} [name] - Optional program name
 * @returns {CAC} CAC application instance
 */
function createCli(name) {
  return new CAC(name);
}

module.exports = {
  CAC,
  Command,
  cac,
  createCli
};

const assert = require('node:assert/strict');
const { EventEmitter } = require('node:events');
const { CAC, Command, createCli } = require('../src/index.js');

// 1. CAC constructs an EventEmitter-backed CLI instance with a custom program name and global command
{
  const cli = new CAC('my-cli');
  assert.equal(cli instanceof CAC, true);
  assert.equal(cli instanceof EventEmitter, true);
  assert.equal(cli.name, 'my-cli');
  assert.ok(cli.globalCommand);

  const helperCli = createCli('helper-cli');
  assert.equal(helperCli instanceof CAC, true);
  assert.equal(helperCli.name, 'helper-cli');
}

// 2. CAC configures application version and global usage text
{
  const cli = new CAC('my-cli');
  cli.version('2.1.0');
  cli.usage('my-cli <command> [options]');
  assert.equal(cli.globalCommand.versionNumber, '2.1.0');
  assert.equal(cli.globalCommand.usageText, 'my-cli <command> [options]');
}

// 3. CAC registers sub-commands and parses arguments and options without executing action handlers
{
  const cli = new CAC('my-cli');
  const cmd = cli.command('serve <port>', 'Start server').option('--host <host>', 'Host address', { default: 'localhost' });
  assert.equal(cmd instanceof Command, true);

  const parsed = cli.parse(['node', 'cli.js', 'serve', '8080', '--host', '127.0.0.1'], { run: false });
  assert.equal(cli.matchedCommandName, 'serve');
  assert.deepEqual(parsed.args, ['8080']);
  assert.equal(parsed.options.host, '127.0.0.1');
}

// 4. CAC executes registered command action callbacks and tracks parsed args and options on the instance
{
  const cli = new CAC('my-cli');
  let executed = false;
  let receivedEntry = null;
  let receivedOpts = null;

  cli.command('build <entry>', 'Build project')
    .option('--minify', 'Minify output')
    .action((entry, opts) => {
      executed = true;
      receivedEntry = entry;
      receivedOpts = opts;
    });

  cli.parse(['node', 'cli.js', 'build', 'index.js', '--minify']);
  assert.equal(executed, true);
  assert.equal(receivedEntry, 'index.js');
  assert.equal(receivedOpts.minify, true);
  assert.deepEqual(cli.args, ['index.js']);
  assert.equal(cli.options.minify, true);
}

// 5. CAC emits custom events and resets matched command state via unsetMatchedCommand
{
  const cli = new CAC('my-cli');
  let eventFired = false;
  cli.on('custom-event', (val) => {
    eventFired = val;
  });
  cli.emit('custom-event', true);
  assert.equal(eventFired, true);

  cli.command('run', 'Run task');
  cli.parse(['node', 'cli.js', 'run'], { run: false });
  assert.ok(cli.matchedCommand);

  cli.unsetMatchedCommand();
  assert.equal(cli.matchedCommand, undefined);
}