@ryuun/cli-framework

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

特性

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

快速开始

创建新的CLI项目

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

基本用法

// 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);

// 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

使用配置管理

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');

配置文件示例

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

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

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

中间件系统

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: [/* ... */]
}));

交互式组件

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

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 目录获取完整的示例项目。

贡献

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

许可证

MIT License - 查看 LICENSE 文件了解详细信息。