@xubill/xx-cli 1.0.6 → 2.0.0

package/lib/utils/config-manager.js

@@ -15,7 +15,7 @@ class ConfigManager {
    * @param {Object} options - 配置选项
    */
   constructor(pluginName, options = {}) {
-    this.homeDir = process.env.HOME || process.env.USERPROFILE;
+    this.homeDir = process.env.HOME || process.env.USERPROFILE || process.cwd();
     this.globalConfigDir = path.join(this.homeDir, '.xx-cli', pluginName);
     this.localConfigPath = options.localConfigPath || `.${pluginName}Config`;
     this.ensureConfigDir();

package/lib/utils/history-manager.js

@@ -8,7 +8,8 @@ const fs = require('fs');
 const path = require('path');
 
 // 历史记录文件路径
-const historyPath = path.join(process.env.HOME || process.env.USERPROFILE, '.xx-cli', 'history.json');
+const homeDir = process.env.HOME || process.env.USERPROFILE || process.cwd();
+const historyPath = path.join(homeDir, '.xx-cli', 'history.json');
 
 /**
  * 确保历史记录目录存在

package/lib/utils/plugins-helper.js

@@ -0,0 +1,276 @@
+/**
+ * 插件辅助工具
+ * 提供与 BasePlugin 相同的通用功能，供新的插件实现方式使用
+ */
+
+const ConfigManager = require('./config-manager');
+const chalk = require('chalk').default;
+const ora = require('ora').default;;
+const clipboardy = require('clipboardy').default;
+
+/**
+ * 插件辅助类
+ * @param {string} pluginName - 插件名称
+ * @param {Object} options - 选项
+ */
+class PluginsHelper {
+  constructor(pluginName, options = {}) {
+    this.pluginName = pluginName;
+    this.homeDir = process.env.HOME || process.env.USERPROFILE || process.cwd();
+    this.configManager = new ConfigManager(pluginName, options);
+    this.spinner = null;
+    this.progressTotal = 0;
+    this.progressCurrent = 0;
+    this.hooks = {};
+  }
+
+  /**
+   * 显示加载状态
+   * @param {string} text - 加载文本
+   */
+  startLoading(text) {
+    this.spinner = ora(text).start();
+  }
+
+  /**
+   * 停止加载状态
+   * @param {string} text - 成功文本
+   */
+  stopLoading(text) {
+    if (this.spinner) {
+      this.spinner.succeed(text);
+      this.spinner = null;
+    }
+  }
+
+  /**
+   * 显示错误状态
+   * @param {string} text - 错误文本
+   */
+  showError(text) {
+    if (this.spinner) {
+      this.spinner.fail(text);
+      this.spinner = null;
+    } else {
+      console.error(chalk.red(`❌ ${text}`));
+    }
+  }
+
+  /**
+   * 启动进度条
+   * @param {string} text - 进度条文本
+   * @param {number} total - 总进度值
+   */
+  startProgressBar(text, total = 100) {
+    this.spinner = ora({
+      text,
+      spinner: 'arc',
+      color: 'cyan'
+    }).start();
+    this.progressTotal = total;
+    this.progressCurrent = 0;
+  }
+
+  /**
+   * 更新进度条
+   * @param {number} current - 当前进度值
+   * @param {string} text - 进度条文本
+   */
+  updateProgressBar(current, text) {
+    if (this.spinner && this.progressTotal > 0) {
+      this.progressCurrent = current;
+      const percentage = Math.min(Math.round((current / this.progressTotal) * 100), 100);
+      this.spinner.text = `${text || ''} ${percentage}%`;
+    }
+  }
+
+  /**
+   * 停止进度条
+   * @param {string} text - 完成文本
+   */
+  stopProgressBar(text) {
+    if (this.spinner) {
+      this.spinner.succeed(text);
+      this.spinner = null;
+      this.progressTotal = 0;
+      this.progressCurrent = 0;
+    }
+  }
+
+  /**
+   * 显示成功信息
+   * @param {string} text - 成功文本
+   */
+  showSuccess(text) {
+    console.log(chalk.green(`✅ ${text}`));
+  }
+
+  /**
+   * 显示警告信息
+   * @param {string} text - 警告文本
+   */
+  showWarning(text) {
+    console.log(chalk.yellow(`⚠️  ${text}`));
+  }
+
+  /**
+   * 显示信息
+   * @param {string} text - 信息文本
+   */
+  showInfo(text) {
+    console.log(chalk.blue(`${text}`));
+  }
+
+  /**
+   * 加载配置
+   * @param {string} configName - 配置名称
+   * @param {Object} cliOptions - 命令行选项
+   * @returns {Object} 合并后的配置对象
+   */
+  loadConfig(configName = 'config', cliOptions = {}) {
+    return this.configManager.loadConfig(configName, cliOptions);
+  }
+
+  /**
+   * 保存配置
+   * @param {Object} config - 配置对象
+   * @param {string} configName - 配置名称
+   * @param {boolean} isGlobal - 是否保存到全局配置
+   */
+  saveConfig(config, configName = 'config', isGlobal = true) {
+    this.configManager.saveConfig(config, configName, isGlobal);
+  }
+
+  /**
+   * 验证配置
+   * @param {Object} config - 配置对象
+   * @param {Object} schema - 配置 schema
+   * @returns {Object} 验证结果
+   */
+  validateConfig(config, schema) {
+    return this.configManager.validateConfig(config, schema);
+  }
+
+  /**
+   * 错误处理
+   * @param {Error} error - 错误对象
+   * @param {string} message - 错误消息
+   */
+  handleError(error, message = '操作失败') {
+    this.showError(`${message}: ${error.message}`);
+    // 可以添加错误日志记录等逻辑
+  }
+
+  /**
+   * 执行异步操作
+   * @param {Function} fn - 异步函数
+   * @param {string} loadingText - 加载文本
+   * @param {string} successText - 成功文本
+   * @param {string} errorText - 错误文本
+   * @returns {Promise<any>}
+   */
+  async executeAsync(fn, loadingText, successText, errorText) {
+    try {
+      this.startLoading(loadingText);
+      const result = await fn();
+      this.stopLoading(successText);
+      return result;
+    } catch (error) {
+      this.handleError(error, errorText);
+      throw error;
+    }
+  }
+
+  /**
+   * 注册钩子
+   * @param {string} event - 事件名称
+   * @param {Function} callback - 回调函数
+   */
+  registerHook(event, callback) {
+    if (!this.hooks) {
+      this.hooks = {};
+    }
+    
+    if (!this.hooks[event]) {
+      this.hooks[event] = [];
+    }
+    
+    this.hooks[event].push(callback);
+  }
+
+  /**
+   * 触发钩子
+   * @param {string} event - 事件名称
+   * @param {*} data - 事件数据
+   * @returns {Promise<Array>} 钩子执行结果
+   */
+  async triggerHook(event, data) {
+    if (!this.hooks || !this.hooks[event]) {
+      return [];
+    }
+    
+    const results = [];
+    for (const callback of this.hooks[event]) {
+      try {
+        const result = await callback(data);
+        results.push(result);
+      } catch (error) {
+        this.handleError(error, `执行钩子 ${event} 时出错`);
+      }
+    }
+    
+    return results;
+  }
+
+  /**
+   * 检查是否注册了指定钩子
+   * @param {string} event - 事件名称
+   * @returns {boolean} 是否注册了钩子
+   */
+  hasHook(event) {
+    return this.hooks && this.hooks[event] && this.hooks[event].length > 0;
+  }
+
+  /**
+   * 复制文本到剪贴板
+   * @param {string} text - 要复制的文本
+   * @param {string} successMessage - 成功消息
+   * @returns {Promise<boolean>} 是否复制成功
+   */
+  async copyToClipboard(text, successMessage) {
+    try {
+      // 尝试不同的 clipboardy API 调用方式
+      if (clipboardy.default && typeof clipboardy.default.write === 'function') {
+        await clipboardy.default.write(text);
+      } else if (typeof clipboardy.write === 'function') {
+        await clipboardy.write(text);
+      } else if (typeof clipboardy.writeSync === 'function') {
+        clipboardy.writeSync(text);
+      } else {
+        throw new Error('clipboardy API 不可用');
+      }
+      if (successMessage) {
+        this.showSuccess(successMessage);
+      }
+      return true;
+    } catch (error) {
+      this.showWarning(`复制到剪贴板失败: ${error.message}`);
+      return false;
+    }
+  }
+}
+
+/**
+ * 创建插件辅助实例
+ * @param {string} pluginName - 插件名称
+ * @param {Object} options - 选项
+ * @returns {PluginsHelper} 插件辅助实例
+ */
+function createPluginsHelper(pluginName, options = {}) {
+  return new PluginsHelper(pluginName, options);
+}
+
+module.exports = {
+  PluginsHelper,
+  createPluginsHelper
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xubill/xx-cli",
-  "version": "1.0.6",
+  "version": "2.0.0",
   "description": "个人工具集",
   "main": "lib/core/index.js",
   "bin": {

package/readme.md

@@ -24,6 +24,10 @@ xx <command> [options]
 - 修复原生插件和用户插件区别
 - 壳功能移动到原生插件目录
 
+### v2.0.0
+- 支持新格式命令注册，兼容旧格式插件
+- 更新插件创建模板，采用配置对象格式并包含类结构实现
+
 ## 框架自带命令
 
 xx-cli 框架自带以下核心命令（位于 core 模块中）：
@@ -109,7 +113,7 @@ xx-cli 提供了 `plugin create` 命令，可以快速生成插件模板。这
 ##### 基本用法
 
 ```bash
-# 创建插件到插件目录
+# 创建插件到插件目录（默认使用新格式，包含类结构实现）
 xx plugin create <plugin-name>
 
 # 或者使用别名
@@ -119,6 +123,17 @@ xx p create <plugin-name>
 xx p cr <plugin-name>
 ```
 
+##### 插件模板格式
+
+从 v2.0.0 版本开始，`plugin create` 命令生成的插件模板采用统一的格式：
+
+- **配置对象格式**：使用配置对象定义插件的基本信息和命令
+- **包含类结构实现**：核心功能通过类结构实现，提高代码模块化和可维护性
+- **自动生成命令名称**：根据插件名称自动生成驼峰命名的命令名称
+- **标准的用户提示**：使用标准化的用户提示和错误处理
+
+这种格式结合了配置对象的简洁性和类结构的模块化优势，是推荐的插件开发方式。
+
 ##### 示例
 
 ```bash
@@ -142,9 +157,86 @@ xx plugin create hello-world
 
 ### 插件结构
 
-#### 基本插件结构
+#### 插件格式
+
+xx-cli 支持两种插件格式：
 
-使用 `plugin create` 命令生成的插件模板包含以下结构：
+1. **旧格式（类结构格式）**：继承自 `BasePlugin` 类的插件实现
+2. **新格式（配置对象格式）**：使用配置对象定义的插件实现（推荐）
+
+#### 新格式（配置对象格式）插件结构
+
+使用 `plugin create` 命令生成的默认插件模板包含以下结构（v2.0.0 版本更新）：
+
+```javascript
+/**
+ * hello-world 插件
+ * 用于实现 hello-world 相关功能
+ * 
+ * 命令说明：
+ * - helloWorld [options]：hello-world 相关功能
+ *   - 示例：helloWorld
+ * 
+ * 功能说明：
+ * - 实现 hello-world 相关功能
+ * 
+ * 用户体验：
+ * - 使用标准化的用户提示
+ * - 提供清晰的错误提示
+ * - 支持命令行参数
+ */
+
+/**
+ * hello-world 插件类
+ * 实现 hello-world 相关核心功能
+ */
+class HelloWorldPlugin {
+  constructor() {
+    this.pluginName = 'hello-world';
+  }
+
+  /**
+   * 执行 hello-world 命令
+   * @param {Array} args - 命令参数
+   * @param {Object} options - 命令选项
+   * @param {Object} helper - 插件帮助器
+   */
+  async execute(args, options, helper) {
+    helper.showInfo('hello-world 命令执行成功！');
+    if (options && options.verbose) {
+      helper.showInfo('详细信息:');
+      helper.showInfo('- 命令名称: helloWorld');
+      helper.showInfo('- 执行时间: ' + new Date().toLocaleString());
+    }
+  }
+}
+
+// 创建插件实例
+const pluginInstance = new HelloWorldPlugin();
+
+module.exports = {
+  name: "helloWorld",
+  alias: "h",
+  description: "hello-world 相关功能",
+  options: [
+    {
+      name: "-v, --verbose",
+      description: "显示详细信息",
+    },
+    {
+      name: "-h, --help",
+      description: "显示帮助信息",
+    },
+  ],
+  action: async (args, options, helper) => {
+    await pluginInstance.execute(args, options, helper);
+  },
+};
+```
+
+#### 旧格式（类结构格式）插件结构
+
+使用 `plugin create --format old` 命令生成的插件模板包含以下结构：
 
 ```javascript
 /**
@@ -203,19 +295,35 @@ module.exports = HelloWorldPlugin;
 
 #### 命令注册
 
-插件必须实现 `registerCommands` 方法，用于向 Commander.js 注册命令。
+##### 新格式（配置对象格式）命令注册
 
-##### 基本命令注册
+对于新格式的插件，命令注册通过配置对象的 `options` 和 `action` 属性实现：
 
 ```javascript
-registerCommands(program) {
-  program.command('helloWorld')
-    .description('hello-world 相关功能')
-    .action(() => this.helloWorldCommand());
-}
+module.exports = {
+  name: 'hello-world',
+  alias: 'hw',
+  description: 'hello-world 相关功能',
+  options: [
+    {
+      name: '-v, --verbose',
+      description: '显示详细信息'
+    },
+    {
+      name: '-n, --name <name>',
+      description: '指定名称'
+    }
+  ],
+  action: (args, options, cmd) => {
+    const helper = createPluginsHelper('hello-world');
+    helloWorldCommand(args.alias, options, helper);
+  }
+};
 ```
 
-##### 带选项的命令注册
+##### 旧格式（类结构格式）命令注册
+
+对于旧格式的插件，命令注册通过实现 `registerCommands` 方法实现：
 
 ```javascript
 registerCommands(program) {
@@ -305,11 +413,110 @@ fs.ensureDirSync(pluginConfigDir);
 fs.writeFileSync(configFile, JSON.stringify(config, null, 2));
 ```
 
-### 基础插件类
+### 插件工具
+
+#### 新格式（配置对象格式）插件工具
+
+对于新格式的插件，使用 `plugins-helper` 提供的功能来替代 `BasePlugin` 类的方法：
+
+##### 导入 plugins-helper
+
+```javascript
+const { createPluginsHelper } = require('../utils/plugins-helper');
+```
+
+##### 核心功能
+
+`plugins-helper` 提供了以下核心功能：
+
+##### 1. 用户界面
+
+- **`helper.showInfo(text)`**：显示信息
+- **`helper.showSuccess(text)`**：显示成功信息
+- **`helper.showWarning(text)`**：显示警告信息
+- **`helper.showError(text)`**：显示错误信息
+- **`helper.startLoading(text)`**：显示加载状态
+- **`helper.stopLoading(text)`**：停止加载状态
+
+##### 2. 配置管理
+
+可以使用 `fs-extra` 和 `path` 模块来实现配置管理：
+
+```javascript
+const fs = require('fs-extra');
+const path = require('path');
+
+// 确保配置目录存在
+function ensureConfigDir(pluginName) {
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  const xxDir = path.join(homeDir, '.xx-cli');
+  const pluginConfigDir = path.join(xxDir, pluginName);
+  fs.ensureDirSync(pluginConfigDir);
+  return pluginConfigDir;
+}
+
+// 加载配置
+function loadConfig(pluginName) {
+  const configDir = ensureConfigDir(pluginName);
+  const configFile = path.join(configDir, 'config.json');
+  if (fs.existsSync(configFile)) {
+    return JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  }
+  return {};
+}
+
+// 保存配置
+function saveConfig(pluginName, config) {
+  const configDir = ensureConfigDir(pluginName);
+  const configFile = path.join(configDir, 'config.json');
+  fs.writeFileSync(configFile, JSON.stringify(config, null, 2));
+}
+```
+
+##### 使用示例
+
+```javascript
+const { createPluginsHelper } = require('../utils/plugins-helper');
+
+function myCommand(options, helper) {
+  try {
+    helper.showInfo('执行操作...');
+    
+    // 执行操作
+    setTimeout(() => {
+      helper.showSuccess('操作成功');
+      
+      if (options && options.verbose) {
+        helper.showInfo('详细信息:');
+        helper.showInfo('- 执行时间:', new Date().toLocaleString());
+      }
+    }, 1000);
+  } catch (error) {
+    helper.showError(`执行命令失败: ${error.message}`);
+  }
+}
+
+module.exports = {
+  name: 'my-plugin',
+  description: 'My plugin command',
+  options: [
+    {
+      name: '-v, --verbose',
+      description: '显示详细信息'
+    }
+  ],
+  action: (args, options, cmd) => {
+    const helper = createPluginsHelper('my-plugin');
+    myCommand(options, helper);
+  }
+};
+```
+
+#### 旧格式（类结构格式）基础插件类
 
-xx-cli 提供了 `BasePlugin` 基类，所有插件都应该继承此类以确保一致性和获得通用功能支持。
+对于旧格式的插件，使用 `BasePlugin` 基类：
 
-#### 基础插件类路径
+##### 基础插件类路径
 
 `BasePlugin` 类位于 `/Users/xub/xx-cli/lib/core/base-plugin.js`，插件可以通过以下方式导入：
 
@@ -317,7 +524,7 @@ xx-cli 提供了 `BasePlugin` 基类，所有插件都应该继承此类以确
 const BasePlugin = require('../core/base-plugin');
 ```
 
-#### 核心功能
+##### 核心功能
 
 `BasePlugin` 类提供了以下核心功能：
 
@@ -365,7 +572,7 @@ const BasePlugin = require('../core/base-plugin');
 
 - **`copyToClipboard(text, successMessage)`**：复制文本到剪贴板
 
-#### 使用示例
+##### 使用示例
 
 ```javascript
 const BasePlugin = require('../core/base-plugin');