8.8 KiB
CLI Framework
Description
CLI Framework is a layered command-line software framework designed to provide a structured foundation for building maintainable, extensible, and scalable terminal softwares.
The framework separates framework capabilities, software capabilities, resource management, and runtime execution into clearly defined architectural layers. It provides standardized interaction processing, reusable utility services, runtime orchestration, and controlled extension points for software developers.
The framework supports multiple interaction styles including:
- Interactive workflows
- Imperative command execution
- Directive-driven execution
- Request routing and dispatching
Built-in integrations with external terminal software libraries are isolated behind framework-managed interfaces, allowing softwares to benefit from third-party tooling without becoming tightly coupled to vendor implementations.
The architecture is organized into four primary layers:
- Data — Framework and software resources.
- Essential — Reusable framework capabilities and infrastructure.
- Operational — Software-specific business capabilities.
- Run — Runtime initialization, routing, and execution.
This separation enables developers to focus on software behavior while relying on a consistent framework foundation for interaction processing, utility services, resource management, and runtime coordination.
Purpose
CLI Framework exists to provide a consistent, maintainable, and extensible architecture for building command-line softwares while establishing clear boundaries between framework responsibilities and software responsibilities.
Objectives
- Establish clear separation of concerns.
- Standardize command-line interaction processing.
- Distinguish framework-owned and software-owned resources.
- Provide reusable infrastructure and utility capabilities.
- Simplify software development through a structured architecture.
- Improve maintainability and scalability.
- Enable controlled software extensibility.
- Protect internal framework implementation details.
- Reduce coupling to third-party dependencies.
Design Principles
Layered Architecture
Each architectural layer is responsible for a specific concern and communicates through clearly defined boundaries.
Ownership Separation
Framework-owned capabilities remain separate from software-owned capabilities to prevent implementation leakage and architectural drift.
Extensibility
Softwares extend the framework through approved extension surfaces without modifying framework internals.
Reusability
Common functionality is implemented once and reused throughout both framework and software layers.
Encapsulation
Internal framework implementation details remain hidden behind stable interfaces.
Consistency
Interaction processing, execution patterns, and resource management follow standardized conventions throughout the framework.
Architecture
High-Level Structure
source
├── data
├── essential
├── operational
└── run
The architecture is organized into four primary layers that collectively provide resource management, reusable framework capabilities, software capabilities, and runtime execution.
Data Layer
The Data Layer stores all framework-owned and software-owned resources.
source/data
├── framework
│ ├── metadata
│ └── glossary
└── software
├── metadata
└── glossary
Responsibilities
- Store framework metadata and configuration resources.
- Store framework glossary and terminology resources.
- Store software metadata and configuration resources.
- Store software glossary and terminology resources.
- Provide centralized resource ownership boundaries.
Ownership
| Area | Owner |
|---|---|
| data/framework | Framework |
| data/software | Software |
Essential Layer
The Essential Layer contains reusable framework capabilities, infrastructure services, integrations, and shared functionality.
source/essential
├── exchange
├── hidden
└── visible
Essential Exchange
Provides the framework interaction model.
exchange
├── router
├── interactive
├── imperative
└── directive
Responsibilities
- Request routing.
- Interactive workflow processing.
- Imperative command execution.
- Directive execution.
- Framework-level interaction orchestration.
Essential Hidden
Contains internal framework capabilities that are not intended for software consumption.
hidden
└── service
├── management
└── bridge
Management
Framework lifecycle and maintenance capabilities.
management
├── install
├── support
└── uninstall
Responsibilities:
- Framework installation.
- Framework maintenance.
- Framework support operations.
- Framework removal.
Bridge
Third-party integration isolation layer.
bridge
├── cobra
├── bubbletea
└── lipgloss
Responsibilities:
- Encapsulate external dependencies.
- Provide framework-controlled integration interfaces.
- Prevent direct software dependency on vendor implementations.
Essential Visible
Contains reusable framework capabilities available to softwares.
visible
└── service
└── helper
Available helper capabilities include:
retriever
status
log
progress
filesystem
datetime
marker
key
hash
cipher
codec
Responsibilities
- Resource retrieval.
- Status reporting.
- Structured logging.
- Progress tracking.
- Filesystem operations.
- Date and time utilities.
- Identifier generation.
- Key generation.
- Hash calculation and comparison.
- Encryption and decryption.
- Encoding and decoding.
Operational Layer
The Operational Layer contains all software-specific behavior and business capabilities.
source/operational
├── exchange
└── service
This is the primary software development area.
Operational Exchange
Provides the software interaction model.
exchange
├── router
├── interactive
├── imperative
└── directive
Responsibilities
- Software request routing.
- Interactive workflow execution.
- Imperative command execution.
- Directive execution.
- Software-level interaction processing.
Operational Service
Contains software-specific business capabilities.
service
└── [service]
└── [feature]
Example:
service
├── project
│ ├── create
│ └── delete
├── customer
│ └── register
└── invoice
└── generate
Feature structure:
service
└── project
└── create
├── function.go
└── function-data.json
Responsibilities
- Implement business rules.
- Manage software workflows.
- Execute domain-specific operations.
- Consume reusable framework capabilities.
Runtime Layer
The Runtime Layer initializes and coordinates framework and software execution.
source/run
├── exchange
└── main
Runtime Exchange
Receives incoming requests and dispatches execution.
exchange
├── router
├── interactive
├── imperative
└── directive
Responsibilities
- Runtime request processing.
- Command dispatching.
- Interactive execution routing.
- Directive execution routing.
- Execution coordination.
Runtime Main
Software bootstrap and startup.
main
└── main.go
Responsibilities
- Framework initialization.
- Software initialization.
- Runtime startup.
- Lifecycle coordination.
- Execution entry point.
Interaction Flow
The framework follows a layered execution model.
User Input
│
▼
Runtime Exchange
│
▼
Software Exchange
│
▼
Software Service
│
▼
Framework Services
│
▼
Resource Layer
Ownership Model
| Layer | Owner | Responsibility |
|---|---|---|
| data/framework | Framework | Framework resources |
| data/software | Software | Software resources |
| essential | Framework | Reusable framework capabilities |
| operational | Software | Business capabilities |
| run | Framework | Runtime execution and orchestration |
Extension Surface
Softwares are expected to extend the framework through the following locations:
source/data/software
source/operational
Softwares should consume reusable framework capabilities from:
source/essential/visible
Softwares should not directly depend on:
source/essential/hidden
as these components are considered internal framework implementation details and may change without notice.