CmdForge Architecture

Module Structure

src/cmdforge/
├── cli/                    # CLI commands
│   ├── __init__.py
│   ├── tool_commands.py    # list, create, edit, delete
│   ├── provider_commands.py # providers management
│   └── registry_commands.py # publish, install
├── registry/               # Registry API
│   ├── app.py              # Flask API endpoints
│   ├── db.py               # SQLite schema and queries
│   ├── sync.py             # Git repo sync
│   └── rate_limit.py
├── web/                    # Web UI
│   ├── app.py              # Flask app factory
│   ├── routes.py           # Page routes
│   ├── auth.py             # User authentication
│   ├── forum/              # Forum feature
│   ├── templates/          # Jinja2 templates
│   └── static/             # CSS, JS
├── ui_urwid/               # Terminal UI
│   ├── __init__.py         # Main TUI
│   ├── widgets.py          # Custom widgets
│   └── palette.py          # Color scheme
├── tool.py                 # Tool dataclass and loading
├── runner.py               # Tool execution engine
└── providers.py            # AI provider abstraction

Data Flow

CLI Tool Execution

User Input (stdin)
       │
       ▼
┌─────────────┐
│  runner.py  │ ──── Loads tool from ~/.cmdforge/<name>/config.yaml
└─────────────┘
       │
       ▼
┌─────────────┐
│   Steps     │
│  (prompt/   │ ──── For prompt steps, calls providers.py
│   code)     │ ──── For code steps, exec() Python
└─────────────┘
       │
       ▼
    Output (stdout)

Web UI Request Flow

Browser Request
       │
       ▼
┌─────────────────┐
│   Cloudflare    │ ──── HTTPS termination
└─────────────────┘
       │
       ▼
┌─────────────────┐
│  Flask :5050    │ ──── web/app.py
└─────────────────┘
       │
       ├──── /api/* → registry/app.py (API)
       └──── /* → web/routes.py (Pages)
              │
              ▼
       ┌─────────────┐
       │  SQLite DB  │
       └─────────────┘

Key Classes

Tool (tool.py)

@dataclass
class Tool:
    name: str
    description: str
    category: str
    arguments: List[ToolArgument]
    steps: List[Step]           # PromptStep | CodeStep | ToolStep
    output: str
    dependencies: List[str]
    source: Optional[ToolSource]  # Attribution for imports
    version: str

ToolSource (tool.py)

@dataclass
class ToolSource:
    type: str          # "original", "imported", "forked"
    license: str
    url: str
    author: str
    original_tool: str  # e.g., "fabric/patterns/extract_wisdom"

Provider (providers.py)

@dataclass
class Provider:
    name: str           # e.g., "opencode-pickle"
    command: str        # e.g., "$HOME/.opencode/bin/opencode run --model ..."
    description: str

Configuration Files

File	Location	Purpose
Tool config	~/.cmdforge/<name>/config.yaml	Tool definition
Providers	~/.cmdforge/providers.yaml	AI provider commands
Main config	~/.cmdforge/config.yaml	Registry URL, client ID