RCC CLI Framework

🎉 构建成功状态

✅ 所有编译构建已完成并验证通过

• TypeScript编译: 所有严格类型检查通过 ✅
• ESM模块构建: 纯ESM格式包生成成功 ✅
• TypeScript声明: 完整.d.ts文件生成 ✅
• 功能测试: 核心功能端到端测试通过 ✅
• 依赖集成: 与rcc-basemodule 0.2.3集成成功 ✅

A universal command-line interface framework built on BaseModule architecture, serving as the global entry point for all RCC system commands.

🎯 Overview

The RCC CLI Framework is the central command entry point for the entire RCC ecosystem. It provides a dynamic, extensible command system with built-in lifecycle management, error handling, and logging powered by BaseModule.

🏗️ Architecture

文件结构和详细功能说明

rcc-cli-framework/
├── src/                          # 源代码目录
│   ├── core/                      # 核心框架组件 (核心功能，请勿修改)
│   │   ├── CLIEngine.ts          # [核心] 主CLI引擎 - 继承BaseModule，处理生命周期
│   │   │   ├── 动态BaseModule导入和初始化
│   │   │   ├── 命令路由和执行调度
│   │   │   ├── 错误处理和日志记录集成
│   │   │   ├── 配置管理和验证
│   │   │   ├── 帮助系统集成和生成
│   │   │   ├── 命令发现和注册管理
│   │   │   └── 生命周期管理 (initialize → execute → destroy)
│   │   ├── CommandRegistry.ts    # [核心] 动态命令注册和发现系统
│   │   │   ├── 命令注册/注销管理
│   │   │   ├── 目录扫描和文件发现 (支持 .js, .ts, .mjs, .cjs)
│   │   │   ├── 模块模式匹配 (rcc-command-*, @rcc/command-*)
│   │   │   ├── 别名管理和冲突解决
│   │   │   ├── 命令验证和类型检查
│   │   │   ├── 插件系统集成
│   │   │   └── 动态模块加载 (ESM兼容)
│   │   └── ArgumentParser.ts     # [核心] 命令行参数处理
│   │       ├── argv解析和标准化
│   │       ├── 选项验证和类型转换
│   │       ├── 帮助文本自动生成
│   │       ├── 命令选项验证
│   │       └── 参数解析错误处理
│   ├── commands/                 # 内置命令实现 (扩展点)
│   │   ├── start/               # rcc start 命令实现
│   │   │   ├── StartCommand.ts  # 系统启动命令
│   │   │   │   ├── 端口配置和验证 (默认5506)
│   │   │   │   ├── 配置文件路径管理
│   │   │   │   ├── 调试系统集成
│   │   │   │   ├── 自动重启功能
│   │   │   │   ├── 管道跟踪启用
│   │   │   │   └── 详细输出模式
│   │   │   └── index.ts         # 命令导出文件
│   │   ├── stop/                # rcc stop 命令实现
│   │   │   ├── StopCommand.ts   # 系统停止命令
│   │   │   │   ├── 优雅关闭逻辑
│   │   │   │   ├── 强制停止功能
│   │   │   │   ├── 超时管理 (默认5000ms)
│   │   │   │   ├── 详细状态输出
│   │   │   │   └── 进程清理
│   │   │   └── index.ts         # 命令导出文件
│   │   └── code/                # rcc code 命令实现
│   │       ├── CodeCommand.ts   # 开发工具命令
│   │       │   ├── 代码生成模板
│   │       │   ├── 构建系统集成
│   │       │   ├── 监听模式功能
│   │       │   └── 项目脚手架
│   │       └── index.ts         # 命令导出文件
│   ├── types/                    # TypeScript类型定义 (参考用)
│   │   ├── index.ts              # 核心接口和类型定义
│   │   │   ├── ICommand 接口定义
│   │   │   ├── CommandContext 上下文结构
│   │   │   ├── CommandOption 选项定义
│   │   │   ├── CLIEngineConfig 配置接口
│   │   │   ├── ILogger 日志接口
│   │   │   └── CommandDiscoveryOptions 发现选项
│   │   └── rcc-basemodule.d.ts   # rcc-basemodule类型声明
│   │       ├── BaseModule 类型声明
│   │       ├── ModuleInfo 接口定义
│   │       └── ESM模块兼容性处理
│   └── index.ts                  # 框架入口点和导出
│       ├── CLIEngine类导出
│       ├── createCLIEngine工厂函数
│       ├── 核心类型和接口导出
│       └── 框架公共API
├── dist/                         # 构建输出目录 (自动生成)
│   ├── index.js                  # ESM格式的主包文件
│   └── index.d.ts                # TypeScript类型声明文件
├── test-cli.mjs                  # 测试脚本 (ESM格式)
│   ├── CLI引擎创建和初始化测试
│   ├── 帮助和版本功能测试
│   ├── 命令注册和执行测试
│   ├── 错误处理测试
│   └── 资源清理测试
├── rollup.config.mjs            # Rollup构建配置 (ESM)
│   ├── TypeScript编译配置
│   ├── ESM输出格式配置
│   ├── 外部依赖管理
│   ├── 声明文件生成
│   └── CommonJS兼容性处理
├── tsconfig.json                # TypeScript配置
│   ├── 严格类型检查启用
│   ├── ESM模块系统配置
│   ├── 声明文件生成设置
│   └── 编译目标设置
└── package.json                  # 包配置和依赖管理
    ├── 模块基本信息和版本
    ├── 依赖管理 (rcc-basemodule ^0.2.3)
    ├── 构建脚本配置
    ├── 开发依赖管理
    └── npm发布配置

各文件详细作用说明

核心文件 (src/core/)

CLIEngine.ts - CLI引擎核心

• 主要职责: 继承BaseModule，提供完整的CLI框架生命周期管理
• 动态导入: 使用ESM动态导入加载rcc-basemodule，确保兼容性
• 命令管理: 统一的命令注册、发现和执行调度
• 错误处理: 集成BaseModule的错误处理和日志系统
• 配置管理: 支持灵活的命令发现配置
• 帮助系统: 自动生成帮助文本和版本信息
• 生命周期: initialize() → execute() → destroy() 完整流程

CommandRegistry.ts - 命令注册中心

• 动态发现: 支持从目录和npm模块自动发现命令
• 文件扫描: 识别 .js, .ts, .mjs, .cjs 文件作为命令源
• 模块加载: 使用ESM import()动态加载命令模块
• 别名管理: 支持命令别名和冲突解决
• 类型安全: 完整的TypeScript类型检查和验证
• 插件系统: 支持外部rcc-command-*模块插件

ArgumentParser.ts - 参数解析器

• argv处理: 标准化命令行参数解析
• 选项验证: 支持多种类型选项 (string, number, boolean)
• 帮助生成: 自动生成命令帮助和使用说明
• 错误处理: 参数解析错误的友好提示

命令实现 (src/commands/)

StartCommand.ts - 系统启动命令

• 端口管理: 默认端口5506，支持自定义端口配置
• 配置文件: 支持配置文件路径指定
• 调试支持: 集成调试和跟踪功能
• 自动重启: 支持系统自动重启机制
• 详细输出: 可选的详细日志输出

StopCommand.ts - 系统停止命令

• 优雅关闭: 支持超时控制的优雅关闭
• 强制停止: 提供强制停止选项
• 状态反馈: 详细的停止状态反馈
• 资源清理: 完整的系统资源清理

CodeCommand.ts - 开发工具命令

• 开发辅助: 提供代码生成和项目管理工具
• 构建集成: 与构建系统的集成支持
• 监听模式: 支持文件监听和自动重建

类型定义 (src/types/)

index.ts - 核心类型定义

• ICommand: 命令接口标准定义
• CommandContext: 命令执行上下文
• CommandOption: 命令选项配置
• CLIEngineConfig: 引擎配置接口
• ILogger: 日志记录接口

rcc-basemodule.d.ts - 外部模块类型声明

• BaseModule: 基础模块类型声明
• ModuleInfo: 模块信息接口
• ESM兼容: 确保与ESM模块系统的兼容性

配置文件

rollup.config.mjs - 构建配置

• ESM输出: 纯ESM模块格式输出
• TypeScript: 集成TypeScript编译和声明文件生成
• 依赖管理: 正确处理外部依赖和内部依赖
• CommonJS: 兼容性处理用于__dirname等Node.js特性

tsconfig.json - TypeScript配置

• 严格模式: 启用所有严格类型检查
• ESM目标: 针对ESM模块系统优化
• 声明文件: 自动生成.d.ts类型声明文件

test-cli.mjs - 功能测试脚本

• 完整测试: 覆盖所有核心功能的端到端测试
• ESM格式: 使用ESM import语法确保兼容性
• 错误处理: 完整的错误处理和资源清理
• 自动化: 可作为CI/CD流程的一部分

Core Components

1. CLIEngine (src/core/CLIEngine.ts)

• Extends BaseModule for built-in lifecycle management
• Command discovery - Automatically scans and loads commands
• Execution orchestration - Routes commands to appropriate handlers
• Error handling - Inherits BaseModule's error management
• Logging - Uses BaseModule's built-in logging system

2. CommandRegistry (src/core/CommandRegistry.ts)

• Dynamic registration - Supports plugin commands at runtime
• Command validation - Ensures command interface compliance
• Namespace management - Handles command naming and conflicts
• Help system - Generates command documentation automatically

3. ArgumentParser (src/core/ArgumentParser.ts)

• argv parsing - Processes command line arguments
• Option validation - Validates command options and flags
• Type conversion - Converts string arguments to appropriate types
• Help generation - Creates usage information for commands

🚀 Core Commands

1. rcc start

Purpose: Start the RCC system Usage: rcc start [options] Features:

• System initialization
• Service startup
• Port allocation and management
• Startup verification

2. rcc stop

Purpose: Stop the RCC system Usage: rcc stop [options] Features:

• Graceful shutdown
• Process termination
• Resource cleanup
• Status reporting

3. rcc code

Purpose: Development and code management tools Usage: rcc code [subcommand] Features:

• Code generation
• Project scaffolding
• Development server management
• Build tools integration

🔌 Extensibility

Command Plugin System

// Custom command implementation
import { ICommand, CommandContext } from 'rcc-cli-framework';

export class CustomCommand implements ICommand {
  name = 'custom';
  description = 'Custom command example';
  
  async execute(context: CommandContext) {
    // Command implementation
    console.log('Custom command executed');
  }
}

Dynamic Registration

Commands can be registered:

1. Built-in: Pre-packaged with the framework
2. Module-based: Loaded from external modules
3. Runtime: Registered programmatically

🛠️ Integration with BaseModule

Inherited Features

• Lifecycle Management: initialize() → execute() → destroy()
• Error Handling: Automatic error catching and reporting
• Logging: Built-in log levels and output handling
• Configuration: BaseModule config system integration
• Dependency Management: Module dependency resolution

Custom Enhancements

• Command-specific logging: Per-command log contexts
• Execution metrics: Command performance tracking
• User feedback: Interactive command output
• Progress reporting: Real-time progress indicators

📦 Installation

As Global Command

npm install -g rcc-cli-framework

As Dependency

npm install rcc-cli-framework

🚦 Usage

Basic Usage

# Start the RCC system
rcc start

# Stop the RCC system  
rcc stop

# Development tools
rcc code --help

Advanced Usage

# Start with specific port
rcc start --port 8080

# Stop force shutdown
rcc stop --force

# Verbose output
rcc start --verbose

🔧 Development Guidelines

✅ Implementation Patterns (Use These)

1. Adding New Commands

// commands/new-feature/NewFeatureCommand.ts
export class NewFeatureCommand implements ICommand {
  name = 'new-feature';
  description = 'Description of new feature';
  
  options = [
    {
      name: 'option1',
      type: 'string',
      description: 'Option description',
      required: true
    }
  ];

  async execute(context: CommandContext) {
    // Implementation using context.logger for logging
    context.logger.info('Executing new feature');
  }
}

// commands/new-feature/index.ts
export { NewFeatureCommand, newFeatureCommand } from './NewFeatureCommand';

2. Plugin Commands (External Modules)

// External module package.json
{
  "name": "rcc-command-myplugin",
  "main": "dist/index.js"
}

// External module implementation
export function registerCommands(registry: CommandRegistry) {
  registry.register(new MyPluginCommand());
}

❌ Anti-Patterns (Avoid These)

1. DUPLICATE CORE FUNCTIONALITY

// ❌ WRONG - Don't create alternative CLI engines
class CustomCLI { /* ... */ }

// ❌ WRONG - Don't implement manual argv parsing
const args = process.argv.slice(2);

// ❌ WRONG - Don't create separate command registries
const myRegistry = new Map();

2. HARDCODED COMMAND PATHS

// ❌ WRONG - Don't hardcode command locations
import { SomeCommand } from '../../some/path';

// ✅ CORRECT - Use dynamic discovery
// Commands are automatically discovered from:
// - ./commands/ directory
// - External rcc-command-* modules
// - Configuration-specified paths

3. MANUAL ERROR HANDLING

// ❌ WRONG - Don't implement custom error handling
try { /* ... */ } catch (error) { 
  console.error('Custom error'); 
}

// ✅ CORRECT - Use BaseModule integrated error handling
// Errors are automatically handled and logged through BaseModule

File Responsibility Matrix

| File | Responsibility | Extension Point | |------|----------------|-----------------| | CLIEngine.ts | Core framework lifecycle | ❌ DO NOT MODIFY | | CommandRegistry.ts | Command discovery system | ❌ DO NOT MODIFY | | ArgumentParser.ts | Argument processing | ❌ DO NOT MODIFY | | commands/*/ | Command implementations | ✅ EXTEND HERE | | types/index.ts | Interface definitions | ✅ EXTEND TYPES | | bin/rcc | Global entry point | ⚠️ UPDATE CAREFULLY |

Configuration Extensibility

Command Discovery Paths

// Add additional command directories
const cli = createCLIEngine({
  commandDiscovery: {
    commandDirs: [
      './commands',                    // Built-in
      './src/commands',               // Project commands  
      './vendor/rcc-commands',        // Additional vendor commands
      process.env.CUSTOM_COMMANDS_PATH // Environment configured
    ],
    modulePatterns: [
      'rcc-command-*',               // Official plugins
      '@myorg/rcc-command-*',        // Organization plugins
      '*-rcc-command'               // Alternative naming
    ]
  }
});

Testing Patterns

Unit Test Structure

// tests/commands/NewFeatureCommand.test.ts
describe('NewFeatureCommand', () => {
  it('should validate options correctly', async () => {
    const command = new NewFeatureCommand();
    const context = createMockContext();
    
    await expect(command.validate(context)).resolves.toBe(true);
  });
});

构建状态 ✅

构建已成功完成并验证

npm run build
# ✅ 成功生成ESM格式包和TypeScript声明文件
# ✅ 所有TypeScript严格类型检查通过
# ✅ 动态模块加载和ESM兼容性验证通过

功能测试 ✅

完整功能测试已通过验证

node test-cli.mjs
# ✅ CLI引擎创建和初始化测试通过
# ✅ 帮助和版本功能测试通过
# ✅ 命令注册和执行测试通过
# ✅ 错误处理和资源清理测试通过
# ✅ 与rcc-basemodule 0.2.3集成测试通过

核心功能验证 ✅

以下核心功能已验证正常工作:

1. CLI引擎生命周期管理: initialize → execute → destroy
2. 动态命令注册和发现: 支持运行时命令注册
3. 参数解析和验证: 完整的命令行参数处理
4. 帮助系统生成: 自动帮助文本和版本信息
5. 错误处理和日志: 继承BaseModule的错误处理
6. ESM模块兼容: 纯ESM格式，支持动态导入
7. TypeScript类型安全: 严格类型检查，完整声明文件

开发模式

npm run dev

🎨 Command Interface

ICommand Interface

interface ICommand {
  name: string;
  description: string;
  usage?: string;
  aliases?: string[];
  options?: CommandOption[];
  execute(context: CommandContext): Promise<void>;
}

interface CommandContext {
  args: string[];
  options: Record<string, any>;
  logger: ILogger;
  cwd: string;
}

Command Options

interface CommandOption {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'array';
  description: string;
  required?: boolean;
  default?: any;
  alias?: string;
}

🌐 Global Integration

Replacement Strategy

This framework replaces:

• Current direct rcc command implementation
• Ad-hoc command parsing in start-rcc-system.mjs
• Manual argument processing

Migration Path

1. Phase 1: Implement framework with core commands
2. Phase 2: Migrate existing functionality
3. Phase 3: Deprecate old entry points
4. Phase 4: Full framework adoption

📊 Performance

Optimizations

• Lazy loading: Commands loaded on-demand
• Caching: Command metadata and help caching
• Parallel processing: Concurrent command execution support
• Memory efficiency: Minimal overhead for command routing

Metrics Tracking

• Command execution time
• Memory usage per command
• Success/failure rates
• Usage statistics

🔒 Security

Features

• Input validation: Sanitize all command arguments
• Permission checking: Command execution permissions
• Audit logging: Security-relevant command execution
• Sandboxing: Isolated command execution environments

📈 Future Enhancements

Planned Features

• Interactive mode: REPL-style command interface
• Command composition: Pipe command outputs
• Plugin ecosystem: Official command plugin support
• Auto-completion: Shell completion generation
• Remote commands: Execute commands on remote systems

🤝 Contributing

Adding New Commands

1. Create command in src/commands/
2. Implement ICommand interface
3. Add tests in __tests__/
4. Update documentation

Plugin Development

// Plugin entry point
export function registerCommands(registry: CommandRegistry) {
  registry.register(new CustomCommand());
}

📝 License

MIT License - see LICENSE file for details.

🆘 Support

• GitHub Issues: https://github.com/rcc/rcc-cli-framework/issues
• Documentation: https://rcc.dev/docs/cli-framework
• Community: https://community.rcc.dev

Built with ❤️ by the RCC Team