434 lines
8.8 KiB
Markdown
434 lines
8.8 KiB
Markdown
# 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. |