# 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 ```text 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. ```text 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. ```text source/essential ├── exchange ├── hidden └── visible ``` --- ### Essential Exchange Provides the framework interaction model. ```text 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. ```text hidden └── service ├── management └── bridge ``` #### Management Framework lifecycle and maintenance capabilities. ```text management ├── install ├── support └── uninstall ``` Responsibilities: - Framework installation. - Framework maintenance. - Framework support operations. - Framework removal. #### Bridge Third-party integration isolation layer. ```text 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. ```text visible └── service └── helper ``` Available helper capabilities include: ```text 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. ```text source/operational ├── exchange └── service ``` This is the primary software development area. --- ### Operational Exchange Provides the software interaction model. ```text 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. ```text service └── [service] └── [feature] ``` Example: ```text service ├── project │ ├── create │ └── delete ├── customer │ └── register └── invoice └── generate ``` Feature structure: ```text 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. ```text source/run ├── exchange └── main ``` --- ### Runtime Exchange Receives incoming requests and dispatches execution. ```text 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. ```text main └── main.go ``` #### Responsibilities - Framework initialization. - Software initialization. - Runtime startup. - Lifecycle coordination. - Execution entry point. --- ### Interaction Flow The framework follows a layered execution model. ```text 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: ```text source/data/software source/operational ``` Softwares should consume reusable framework capabilities from: ```text source/essential/visible ``` Softwares should not directly depend on: ```text source/essential/hidden ``` as these components are considered internal framework implementation details and may change without notice.