# cacjs/cac architecture

> Architecture diagram of the GitHub repository cacjs/cac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cacjs/cac
- Repository: https://github.com/cacjs/cac

## Overview

##### Project Type and Purpose
- This is an **open‑source JavaScript/TypeScript library** (“CAC”) whose sole purpose is to help other developers build command‑line applications easily. It is **not** a full‑stack service or microservice, but rather a highly modular CLI framework you import into your programs.

##### Core Architectural Components
From the file tree and README, we can partition the system into two big domains:
A. **Runtime Modules** (src/)
1. CAC Core (`CAC.ts`) – creates the CLI instance, holds commands/options, orchestrates parse → run
2. Command Definition (`Command.ts`) – models each command, its name, args, options, action callback, examples, aliases
3. Option Definition (`Option.ts`) – models global & command‑specific options (name, type, default, negation, nested keys)
4. Parser & Utilities (`utils.ts`, `index.ts`) – split raw argv, normalize dash/camelCase, coerce types, collect parsedArgs
5. Environment Adapters (`node.ts`, `deno.ts`) – glue logic for reading process.argv vs Deno.args, printing output
6. Entry Points (`mod.ts`, `mod.js`, `index-compat.js`) – export a compatible API surface for both ESM and CommonJS
B. **Build & QA**
1. Bundler (`rollup.config.js`) – compiles & bundles the library into distributable ESM/CJS files
2. Deno Build Script (`scripts/build-deno.ts`) – produces a Deno‑friendly module at mod.ts
3. Testing (`src/__test__/*`, `jest.config.js`) – unit tests validating command parsing, option behaviors, snapshots
4. Examples (`examples/`) – sample CLI programs demonstrating usage patterns

##### Relationships & Data Flows
- **Consumer CLI App**
↳ import/require `cac` entry point
↳ call `const cli = cac()`
↳ declare commands (`cli.command(...)`), global options (`cli.option(...)`), help/version handlers
↳ invoke `cli.parse()`
- **CAC Core Flow**
1. **Capture** raw arguments via environment adapter (Node or Deno)
2. **Split & Normalize** arguments (`utils.splitArgv`)
3. **Match** against registered commands (name patterns, default command)
4. **Parse** global and command‑specific options (using Option models)
5. **Trigger** help/version if flags present (via `cli.help()`, `cli.version()`)
6. **Execute** the matched command’s action callback with parsed args & options
7. **Emit** events (`cli.on('command:foo')`) for advanced use
- **Build Pipeline**
Source TS/JS → Rollup (transpile + bundle) → outputs `index-compat.js`, `mod.js` → published to npm
Separate Deno build script generates `mod.ts` for Deno usage.

##### Architectural Patterns & Principles
- **Modularity & Single Responsibility**: each class/file has a distinct role (CLI orchestration vs. command vs. option vs. env abstraction).
- **Pluggability & Extensibility**: commands and options are registered via method chaining; new adapters (e.g. for another runtime) can slot into the same pipeline.
- **Dual Distribution**: supports both CommonJS and native ES modules + Deno.

##### Checklist
- Call out extensibility points: method‑chain registration, event hooks, environment adapters
- Build output artifacts (e.g. `mod.js`, `index-compat.js`) separate from source

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Layer
    subgraph "Consumer CLI App"
        CLIApp["Import cac & define commands\n(cli.command(), cli.option(), cli.parse())"]:::external
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        direction TB
        Entry["API Entry Points\nindex-compat.js, mod.js, mod.ts"]:::entry
        CLI["CAC Core\nsrc/CAC.ts"]:::core
        Cmd["Command Definition\nsrc/Command.ts"]:::core
        Opt["Option Definition\nsrc/Option.ts"]:::core
        Parser["Parser & Utilities\nsrc/utils.ts, src/index.ts"]:::parser
        Raw["RawArgs\n(process.argv / Deno.args)"]:::data
        Parsed["ParsedArgv\n(object)"]:::data
        Action["Action Runner\n(user callback)"]:::core
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        NodeAdapter["Node Adapter\nsrc/node.ts"]:::adapter
        DenoAdapter["Deno Adapter\nsrc/deno.ts"]:::adapter
    end

    %% Build/Test Layer
    subgraph "Build & QA"
        direction TB
        Rollup["Rollup Bundler\nrollup.config.js"]:::tool
        DenoBuild["Deno Build Script\nscripts/build-deno.ts"]:::tool
        JestConfig["Jest Config\njest.config.js"]:::tool
        Tests["Testing Suite\nsrc/__test__/index.test.ts\nsrc/__test__/__snapshots__"]:::tool
        Examples["Examples\nexamples/"]:::tool
    end

    %% Flow
    CLIApp -->|"import/require cac"| Entry
    Entry -->|"initialize cli()"| CLI
    Raw -->|capture| CLI
    NodeAdapter -->|provide argv| Raw
    DenoAdapter -->|provide argv| Raw
    CLI -->|"split & normalize"| Parser
    Parser -->|"produce ParsedArgv"| Parsed
    CLI -->|"use ParsedArgv"| Parsed
    CLI -->|"register"| Cmd
    CLI -->|"register"| Opt
    CLI -->|"execute action"| Action
    CLI -->|"emit events"| Cmd
    Rollup -->|bundle source| Entry
    DenoBuild -->|generate Deno module| Entry
    Tests -->|validate parsing| CLI
    Examples -->|demo usage| CLIApp

    %% Click Events
    click CLI "https://github.com/cacjs/cac/blob/master/src/CAC.ts"
    click Cmd "https://github.com/cacjs/cac/blob/master/src/Command.ts"
    click Opt "https://github.com/cacjs/cac/blob/master/src/Option.ts"
    click Parser "https://github.com/cacjs/cac/blob/master/src/utils.ts"
    click Parser "https://github.com/cacjs/cac/blob/master/src/index.ts"
    click NodeAdapter "https://github.com/cacjs/cac/blob/master/src/node.ts"
    click DenoAdapter "https://github.com/cacjs/cac/blob/master/src/deno.ts"
    click Entry "https://github.com/cacjs/cac/blob/master/index-compat.js"
    click Entry "https://github.com/cacjs/cac/blob/master/mod.js"
    click Entry "https://github.com/cacjs/cac/blob/master/mod.ts"
    click Rollup "https://github.com/cacjs/cac/blob/master/rollup.config.js"
    click DenoBuild "https://github.com/cacjs/cac/blob/master/scripts/build-deno.ts"
    click Tests "https://github.com/cacjs/cac/blob/master/src/__test__/index.test.ts"
    click Tests "https://github.com/cacjs/cac/tree/master/src/__test__/__snapshots__"
    click Examples "https://github.com/cacjs/cac/tree/master/examples/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef parser fill:#FFF5CC,stroke:#D4A017,color:#D4A017
    classDef adapter fill:#E6FFEA,stroke:#28A745,color:#28A745
    classDef data fill:#FFF4EB,stroke:#E08606,color:#E08606,stroke-dasharray: 5 5
    classDef tool fill:#F5F5F5,stroke:#6A737D,color:#6A737D
    classDef entry fill:#EAF5FF,stroke:#1C7ED6,color:#1C7ED6
    classDef external fill:#FFFFFF,stroke:#8B949E,color:#8B949E,stroke-dasharray: 2 2
```
