npm package: @ryuun/cli-framework
Description: A modern, extensible CLI framework built with React Ink and TypeScript
Author: Your Name
Latest version: 1.0.36

# @ryuun/cli-framework

一个现代化、可扩展的CLI开发框架，基于React Ink和TypeScript构建。

## 特性

- 🚀 **现代化**: 使用TypeScript + React组件模式构建CLI
- 🔧 **可扩展**: 支持中间件、插件系统
- ⚙️ **配置管理**: 内置强大的配置管理系统，支持多种配置文件格式
- 🎨 **交互式**: 丰富的交互式组件支持
- 📦 **开箱即用**: 提供项目模板生成器
- 🔍 **类型安全**: 完整的TypeScript支持

## 快速开始

### 创建新的CLI项目

```bash
# 使用项目生成器
bunx @ryuun/cli-framework create
```

### 基本用法

```typescript
// src/cli.ts
import { createCLI, defineCLI } from '@ryuun/cli-framework';
import { HelloCommand } from './commands/HelloCommand.js';

const cli = createCLI(defineCLI({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My awesome CLI tool',
  
  commands: [
    {
      name: 'hello',
      description: 'Say hello',
      component: HelloCommand,
      flags: [
        {
          name: 'name',
          type: 'string',
          alias: 'n',
          description: 'Name to greet',
          default: 'World'
        }
      ]
    }
  ]
}));

cli.run().catch(console.error);
```

```tsx
// src/commands/HelloCommand.tsx
import React from 'react';
import { Box, Text } from '@ryuun/cli-framework';
import type { CommandProps } from '@ryuun/cli-framework';

export const HelloCommand: React.FC<CommandProps> = ({ flags }) => {
  const name = flags.name || 'World';
  
  return (
    <Box padding={1}>
      <Text color="green">Hello, {name}! 👋</Text>
    </Box>
  );
};
```

## 配置管理

框架内置了强大的配置管理系统，基于cosmiconfig，支持多种配置文件格式：

### 支持的配置文件

对于名为`my-cli`的工具，框架会自动搜索以下配置文件：

- `package.json` 中的 `my-cli` 属性
- `.my-clirc` (JSON/YAML格式)
- `.my-clirc.json`
- `.my-clirc.yaml` / `.my-clirc.yml`
- `.my-clirc.js` / `.my-clirc.ts`
- `.config/my-clirc` 及其各种扩展名
- `my-cli.config.js` / `my-cli.config.ts`

### 使用配置管理

```typescript
import { createConfigManager } from '@ryuun/cli-framework';

const config = createConfigManager('my-cli', {
  defaults: {
    theme: 'dark',
    verbose: false
  }
});

// 异步获取配置
const userConfig = await config.loadConfig();
console.log(userConfig.theme); // 'dark' 或用户配置的值

// 同步获取配置
const theme = config.getSync('theme', 'light');

// 设置全局配置
await config.set('theme', 'light');

// 删除配置
await config.delete('theme');
```

### 配置文件示例

```json
// package.json
{
  "name": "my-project",
  "my-cli": {
    "theme": "dark",
    "verbose": true
  }
}
```

```yaml
# .my-clirc.yaml
theme: dark
verbose: true
features:
  - autocomplete
  - syntax-highlighting
```

```javascript
// my-cli.config.js
export default {
  theme: 'dark',
  verbose: process.env.NODE_ENV === 'development',
  plugins: ['@my-cli/plugin-git']
};
```

## 中间件系统

```typescript
import { 
  createCLI, 
  defineCLI,
  createLoggingMiddleware,
  createTimingMiddleware,
  defineMiddleware
} from '@ryuun/cli-framework';

// 使用内置中间件
const cli = createCLI(defineCLI({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My CLI',
  
  middleware: [
    createLoggingMiddleware({ logLevel: 'debug' }),
    createTimingMiddleware(),
    
    // 自定义中间件
    defineMiddleware({
      name: 'auth',
      handler: async (context, next) => {
        // 认证逻辑
        if (!isAuthenticated()) {
          console.error('Please login first');
          process.exit(1);
        }
        await next();
      }
    })
  ],
  
  commands: [/* ... */]
}));
```

## 交互式组件

框架提供了丰富的交互式组件：

```tsx
import React, { useState } from 'react';
import { 
  Box, 
  Text,
  Input,
  Select,
  Confirm,
  Spinner,
  ProgressBar
} from '@ryuun/cli-framework';

export const InteractiveCommand: React.FC = () => {
  const [step, setStep] = useState('input');
  const [name, setName] = useState('');

  if (step === 'input') {
    return (
      <Input
        placeholder="Enter your name"
        onSubmit={(value) => {
          setName(value);
          setStep('confirm');
        }}
      />
    );
  }

  if (step === 'confirm') {
    return (
      <Confirm
        message={`Hello ${name}, continue?`}
        onYes={() => setStep('done')}
        onNo={() => setStep('input')}
      />
    );
  }

  return <Text color="green">Welcome, {name}!</Text>;
};
```

## 项目结构建议

```
my-cli/
├── src/
│   ├── commands/           # 命令实现
│   │   ├── HelloCommand.tsx
│   │   └── ConfigCommand.tsx
│   ├── components/         # 自定义组件
│   ├── middleware/         # 自定义中间件
│   ├── utils/             # 工具函数
│   └── cli.ts             # CLI入口点
├── package.json
├── tsconfig.json
└── README.md
```

## API参考

### 核心API

- `createCLI(config)` - 创建CLI实例
- `defineCLI(config)` - 定义CLI配置（提供类型提示）
- `defineCommand(command)` - 定义命令
- `defineMiddleware(middleware)` - 定义中间件

### 配置管理

- `createConfigManager(name, options)` - 创建配置管理器
- `ConfigManager` - 配置管理器类

### 中间件

- `createLoggingMiddleware(options)` - 日志中间件
- `createTimingMiddleware(options)` - 计时中间件
- `createErrorHandlingMiddleware(options)` - 错误处理中间件

### 组件

- `Input` - 文本输入
- `Select` - 选择列表
- `Confirm` - 确认提示
- `Spinner` - 加载动画
- `ProgressBar` - 进度条

## 最佳实践

### 1. 配置管理

- 为你的CLI工具提供合理的默认配置
- 支持多种配置文件格式以适应不同用户偏好
- 使用全局配置存储用户偏好设置

### 2. 命令设计

- 保持命令简单且专注
- 提供清晰的帮助信息
- 使用一致的命名约定

### 3. 错误处理

- 提供有意义的错误消息
- 使用错误处理中间件统一处理错误
- 在开发模式下显示详细的错误堆栈

### 4. 性能

- 使用计时中间件监控命令执行时间
- 对于长时间运行的操作显示进度指示器
- 考虑使用缓存来提高重复操作的性能

## 示例项目

查看 [examples](./examples) 目录获取完整的示例项目。

## 贡献

欢迎贡献代码！请查看 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解详细信息。

## 许可证

MIT License - 查看 [LICENSE](./LICENSE) 文件了解详细信息。