@ryuun/cli-framework NPM

@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