npm package: @garrick0/c2-cli
Description: C2 CLI - Command-line interface for check execution
Author: garrick0
Latest version: 6.1.0

# @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

```bash
npm install -g @garrick0/c2-cli
```

## Usage

```bash
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

```bash
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

```bash
c2 --preset c2:recommended
```

### Run in specific directory

```bash
c2 --cwd /path/to/project
```

### Get JSON output

```bash
c2 --json
```

Output:
```json
{
  "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:

```typescript
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:

```typescript
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.

```typescript
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.

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

### getExitCode(result)

Determine exit code from results.

```typescript
function getExitCode(result: RunResult): number;
```

### main(args?)

Main CLI entry point.

```typescript
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

```bash
# Build
npx nx build @garrick0/c2-cli

# Test
npx nx test @garrick0/c2-cli

# Lint
npx nx lint @garrick0/c2-cli
```

## License

MIT