@garrick0/c2-cli

Command-line interface for the C2 check system.

Overview

This package provides a CLI for running C2 checks. It serves as a host application that uses the @garrick0/c2 package for check execution.

Installation

npm install -g @garrick0/c2-cli

Usage

c2 [options]

Options:
  --cwd <path>      Working directory (default: current directory)
  --config <file>   Path to config file (default: c2.config.ts)
  --preset <name>   Use a built-in preset (c2:recommended, c2:strict, c2:minimal)
  --no-config       Skip loading config file
  --json            Output results as JSON
  --verbose, -v     Verbose output
  --version, -V     Show version number
  --help, -h        Show this help

Examples

Run checks in current directory

c2

Output:

C2 Check Results
================

✓ [git:no-protected-branch] Passed
✗ [WARNING] [git:uncommitted-lines-limit] Too many uncommitted lines (1500)
✓ [git:clean-working-tree] Passed

Total: 3 | Passed: 2 | Failed: 1 (0 errors, 1 warnings)
Duration: 42ms

Use a built-in preset

c2 --preset c2:recommended

Run in specific directory

c2 --cwd /path/to/project

Get JSON output

c2 --json

Output:

{
  "results": [
    {
      "checkId": "git:no-protected-branch",
      "passed": true
    }
  ],
  "summary": {
    "total": 3,
    "passed": 2,
    "failed": 1,
    "errors": 0,
    "warnings": 1
  },
  "durationMs": 42
}

Configuration

Create a c2.config.ts in your project root:

import { defineUserConfig } from '@garrick0/c2';

export default defineUserConfig({
  extends: ['c2:recommended'],
  checks: {
    'git:no-protected-branch': 'error',
    'git:clean-working-tree': 'warning',
  },
});

The CLI will automatically load this configuration file.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success (all checks passed or only warnings) | | 1 | Fatal error (e.g., invalid config, missing directory) | | 2 | Check errors (one or more checks failed with error severity) |

Programmatic Usage

The CLI exports functions for programmatic use:

import { runChecks, formatOutput, getExitCode, type CliOptions } from '@garrick0/c2-cli';

const options: CliOptions = {
  cwd: '/path/to/project',
  format: 'text',
  verbose: true,
};

const result = await runChecks(options);
const output = formatOutput(result, options);
const exitCode = getExitCode(result);

console.log(output);
process.exit(exitCode);

API Reference

runChecks(options?)

Run checks and return results.

function runChecks(options?: CliOptions): Promise<RunResult>;

interface CliOptions {
  cwd?: string;              // Working directory (default: process.cwd())
  format?: 'text' | 'json';  // Output format
  verbose?: boolean;         // Verbose output
  configFile?: string;       // Path to config file
  noConfig?: boolean;        // Skip loading config file
  preset?: string;           // Built-in preset to use
}

formatOutput(result, options?)

Format results for display.

function formatOutput(result: RunResult, options?: CliOptions): string;

getExitCode(result)

Determine exit code from results.

function getExitCode(result: RunResult): number;

main(args?)

Main CLI entry point.

function main(args?: string[]): Promise<number>;

Architecture

The CLI is a host application in the C2 architecture:

CLI (this package)
    ↓
@garrick0/c2 (main package)
    ↓
core-application (check engine)
    ↓
core-domain (pure types)

It:

1. Parses command-line arguments
2. Loads user configuration from c2.config.ts
3. Creates host context with git plugin
4. Executes checks via run() API
5. Formats and outputs results
6. Returns appropriate exit code

Development

# Build
npx nx build @garrick0/c2-cli

# Test
npx nx test @garrick0/c2-cli

# Lint
npx nx lint @garrick0/c2-cli

License

MIT