jackwener--opencli/docs/developer/architecture.md

Architecture

OpenCLI is a command surface that sits on top of four major subsystems:

1. command discovery and registry
2. execution and formatting
3. browser / daemon / CDP connectivity
4. adapter, plugin, and external CLI integration

Runtime Shape

opencli CLI
  ├─ command discovery / registry
  ├─ execution / output
  ├─ browser runtime
  │   ├─ Browser Bridge extension
  │   ├─ local daemon
  │   └─ direct CDP path
  ├─ adapter loading
  │   ├─ built-in site adapters
  │   ├─ generated adapters
  │   └─ pipeline-backed adapters
  ├─ plugin loading
  └─ external CLI passthrough

Core Modules

CLI Surface

• src/main.ts — process entrypoint
• src/cli.ts — top-level command tree and built-in command groups
• src/completion.ts / src/completion-fast.ts — shell completion

Discovery, Registry, Execution

• src/discovery.ts — discovers built-in adapters, generated adapters, plugins, and manifests
• src/registry.ts — central command registry
• src/registry-api.ts — adapter-facing registration helpers
• src/execution.ts — argument validation, lazy loading, and command execution
• src/commanderAdapter.ts — bridges registry metadata into Commander subcommands
• src/output.ts — table, json, yaml, md, csv formatting
• src/serialization.ts — registry and manifest serialization helpers

Browser and Runtime

• src/runtime.ts — shared command runtime and target resolution
• src/daemon.ts — lifecycle and bridge behavior for the local daemon
• src/doctor.ts — browser bridge diagnostics
• src/observation/ — trace artifacts, redaction, and structured runtime evidence
• src/interceptor.ts — interception helpers for browser-backed strategies
• src/browser/ — Browser Bridge connection and browser-side primitives

Pipeline Engine

• src/pipeline/executor.ts — pipeline execution
• src/pipeline/template.ts — template expansion
• src/pipeline/transform.ts — transform helpers
• src/pipeline/steps/ — concrete steps such as:
  • fetch
  • download
  • browser
  • intercept
  • tap
  • transform

Adapter and Extension Surfaces

• clis/ — built-in site adapters
• src/plugin.ts / src/plugin-manifest.ts / src/plugin-scaffold.ts — plugin install, metadata, scaffold
• src/external.ts / src/external-clis.yaml — external CLI passthrough and installable tools
• src/electron-apps.ts — desktop / Electron app support

Command Sources

OpenCLI merges commands from multiple places into one registry:

Source	Location	Examples
Built-in adapters	clis/	twitter, bilibili, reddit, chatgpt-app
Generated / local adapters	~/.opencli/clis/	user-authored adapters
Plugins	~/.opencli/plugins/	community-contributed commands
External CLIs	src/external-clis.yaml + local registrations	gh, docker, vercel

The user sees one unified command tree through opencli list.

Connectivity Modes

Browser Bridge mode

Primary path for browser-backed commands:

opencli process
  ↔ local daemon
  ↔ Browser Bridge extension
  ↔ logged-in Chrome / Chromium

This path is used for:

• cookie-backed websites
• browser automation primitives
• interactive browser verification

Direct CDP mode

Used when OpenCLI talks directly to a Chrome or Electron debugging endpoint through OPENCLI_CDP_ENDPOINT.

Typical uses:

• remote Chrome
• headless Chrome
• Electron desktop adapters

Authentication / Access Strategies

OpenCLI currently uses these access strategies:

Strategy	Purpose
public	direct fetch with no login
cookie	reuse browser session cookies
intercept	capture the app's own network responses
ui	DOM / accessibility driven interaction

The key distinction is operational:

• public favors direct network access
• cookie, intercept, ui depend on a live browser or desktop surface

High-Risk Change Zones

Changes in these files usually affect broad command behavior:

• src/cli.ts
• src/commanderAdapter.ts
• src/discovery.ts
• src/execution.ts
• src/runtime.ts
• src/daemon.ts
• src/plugin.ts
• src/external.ts
• src/pipeline/**

These areas deserve targeted tests first, then broader validation when the change crosses module boundaries.

Mental Model

The simplest accurate model is:

1. OpenCLI discovers command definitions.
2. It registers them into one command registry.
3. It resolves each invocation through execution + runtime.
4. It reaches the target through one of:
   • network fetch
   • Browser Bridge
   • direct CDP
   • external CLI passthrough
5. It formats the result into a stable output surface.

That is the architecture to preserve when refactoring.