@htyf-mp/cli 0.2.0-beta.1 → 0.2.2

package/src/debug.mjs

@@ -0,0 +1,179 @@
+/**
+ * 调试模块
+ * 负责启动小程序真机调试服务器
+ * 
+ * @module debug
+ */
+
+import path from 'path';
+import fse from 'fs-extra';
+import superstatic from 'superstatic';
+import portfinder from 'portfinder';
+import chalk from 'chalk';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import { Logger } from './logger.mjs';
+import { ConfigValidator } from './validators.mjs';
+import { mpBuildShell } from './build.mjs';
+import { printQrcode } from './utils-functions.mjs';
+
+/**
+ * 小程序真机调试
+ * 
+ * 功能流程：
+ * 1. 构建小程序包
+ * 2. 验证网络配置
+ * 3. 启动本地调试服务器
+ * 4. 生成调试二维码
+ * 
+ * @param {object} newAppInfo - 应用信息
+ * @param {string} newAppInfo.name - 应用名称
+ * @param {string} newAppInfo.appid - 应用ID
+ * @param {string} newAppInfo.version - 应用版本
+ * @param {string} [newAppInfo.entry] - 入口文件（普通小程序必需，Godot 项目不需要）
+ * @param {boolean} [isGodot=false] - 是否为 Godot 项目
+ * @throws {Error} 当必需字段缺失或网络配置验证失败时抛出错误
+ * 
+ * @example
+ * await mpDebugShell({
+ *   name: '我的应用',
+ *   appid: 'com.example.app',
+ *   version: '1.0.0',
+ *   entry: './src/index.js'
+ * }, false);
+ */
+export async function mpDebugShell(newAppInfo, isGodot = false) {
+  try {
+    // ========== 参数验证 ==========
+    // Godot 项目不需要 entry 字段，普通小程序需要
+    if (!isGodot && !newAppInfo.entry) {
+      throw new Error('缺少必需的应用信息: entry');
+    }
+    
+    // ========== 构建小程序包 ==========
+    Logger.info('开始构建小程序包...');
+    const zipPath = await mpBuildShell(newAppInfo, isGodot);
+    const assetsPath = path.dirname(zipPath);
+    const appJsonPath = path.join(assetsPath, 'app.json');
+
+    Logger.info(`资源路径: ${assetsPath}`);
+    const applocaljson = fse.readJsonSync(appJsonPath);
+
+    // ========== 网络配置验证 ==========
+    const networkValidation = await ConfigValidator.validateNetworkConfig();
+    if (!networkValidation.isValid) {
+      throw new Error(`网络配置验证失败: ${networkValidation.error}`);
+    }
+
+    // ========== 启动调试服务器 ==========
+    const host = networkValidation.host;
+    const port = await portfinder.getPortPromise();  // 自动查找可用端口
+
+    // 创建静态文件服务器
+    const app = superstatic.server({
+      port: port,
+      address: host,
+      cwd: assetsPath  // 服务器根目录
+    });
+
+    // 启动服务器
+    const server = app.listen(function () {
+      const address = server.address();
+
+      // ========== 生成调试配置 ==========
+      // 构建调试用的 URL
+      const debugerAppUrlConfig = `http://${host}:${address.port}/app.json`;
+      const debugerZip = `http://${host}:${address.port}/dist.dgz`;
+      
+      // 构建调试参数
+      const args = {
+        ...applocaljson,
+        development: true,  // 标记为开发模式
+        "name": applocaljson.name,
+        "appid": applocaljson.appid,
+        "version": applocaljson.version,
+        appUrlConfig: debugerAppUrlConfig,
+        zipUrl: debugerZip,
+      };
+
+      // 更新 app.json 文件，写入调试 URL
+      fse.writeJSONSync(appJsonPath, {
+        ...fse.readJSONSync(appJsonPath),
+        appUrlConfig: debugerAppUrlConfig,
+        zipUrl: debugerZip,
+      });
+
+      // 生成调试二维码 URL
+      const qrcodeUrl = `https://share.dagouzhi.com/#/pages/index/index?data=${encodeURIComponent(JSON.stringify(args))}`;
+
+      // ========== 显示调试信息 ==========
+      console.log('\n');
+      console.log(boxen(
+        gradient.rainbow('小程序真机调试') + '\n\n' +
+        chalk.cyan('服务器地址: ') + chalk.white(`${host}:${address.port}`) + '\n' +
+        chalk.cyan('应用名称: ') + chalk.white(applocaljson.name) + '\n' +
+        chalk.cyan('应用ID: ') + chalk.white(applocaljson.appid) + '\n' +
+        chalk.cyan('版本: ') + chalk.white(applocaljson.version),
+        {
+          padding: 1,
+          margin: 1,
+          borderStyle: 'round',
+          borderColor: 'cyan'
+        }
+      ));
+
+      // 显示调试配置 JSON
+      console.log('\n' + chalk.yellow('调试配置:'));
+      console.log(JSON.stringify(args, undefined, 2));
+
+      // 显示调试链接
+      console.log('\n' + chalk.green('调试链接:'));
+      console.log(qrcodeUrl);
+
+      // 显示二维码
+      console.log('\n' + chalk.blue('二维码:'));
+      printQrcode(qrcodeUrl);
+
+      Logger.info('调试服务器已启动，按 Ctrl+C 停止');
+    });
+
+    // ========== 优雅关闭处理 ==========
+    // 移除全局的信号处理，添加专用的服务器关闭处理
+    // 这样可以确保服务器能够正确关闭，避免资源泄漏
+    const handleShutdown = () => {
+      Logger.info('\n正在关闭调试服务器...');
+      let isClosed = false;
+      
+      // 尝试关闭服务器
+      server.close(() => {
+        if (!isClosed) {
+          isClosed = true;
+          Logger.success('调试服务器已关闭');
+          process.exit(0);
+        }
+      });
+      
+      // 如果服务器在 3 秒内没有关闭，强制退出
+      // 防止服务器关闭卡死导致进程无法退出
+      setTimeout(() => {
+        if (!isClosed) {
+          isClosed = true;
+          Logger.warn('强制退出...');
+          process.exit(0);
+        }
+      }, 3000);
+    };
+
+    // 注册信号处理器
+    // 移除可能存在的全局处理器，避免冲突
+    process.removeAllListeners('SIGINT');
+    process.removeAllListeners('SIGTERM');
+    process.once('SIGINT', handleShutdown);   // Ctrl+C
+    process.once('SIGTERM', handleShutdown);  // 终止信号
+
+  } catch (error) {
+    Logger.error(`小程序调试失败: ${error.message}`);
+    process.exit(1);
+  }
+}
+

package/src/export_godot.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+/**
+ * Godot 导出模块
+ * 负责处理 Godot 游戏项目的导出和打包
+ * 
+ * @module export_godot
+ */
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { accessSync, constants as fsConstants } from 'node:fs';
+import process from 'node:process';
+import { homedir } from 'node:os';
+import fs from 'fs-extra';
+import AdmZip from 'adm-zip';
+import { execa } from 'execa';
+import inquirer from 'inquirer';
+
+// ========== 常量定义 ==========
+
+/** Godot 编辑器默认路径（macOS） */
+const DEFAULT_GODOT_BIN = '/Applications/Godot.app/Contents/MacOS/Godot';
+
+/** Godot 配置缓存目录 */
+const GODOT_CACHE_DIR = path.join(homedir() || process.cwd(), '.htyf');
+
+/** Godot 配置缓存文件路径 */
+const GODOT_CACHE_FILE = path.join(GODOT_CACHE_DIR, 'godot-config.json');
+
+/** 支持的平台枚举 */
+const PLATFORMS = {
+  IOS: 'ios',
+  ANDROID: 'android'
+};
+
+/** 平台预设名称映射 */
+const PRESET_NAMES = {
+  [PLATFORMS.IOS]: 'iOS',
+  [PLATFORMS.ANDROID]: 'Android'
+};
+
+/**
+ * 提示用户输入或确认 Godot 导出选项
+ * 
+ * 如果所有必需参数都已提供，则直接返回，不进行交互式询问
+ * 否则通过命令行交互获取用户输入
+ * 
+ * @param {object} [defaults={}] - 默认选项
+ * @param {string} [defaults.targetBaseDir] - 导出目标根目录
+ * @param {string} [defaults.projectDir] - Godot 项目目录
+ * @param {string} [defaults.appid] - 应用ID（用作导出文件名）
+ * @param {string} [defaults.preset] - Godot 导出预设名称
+ * @param {string} [defaults.platform] - 导出平台（'ios' 或 'android'）
+ * @returns {Promise<object>} Godot 导出选项对象
+ * 
+ * @example
+ * const options = await promptGodotOptions({
+ *   targetBaseDir: './dist',
+ *   projectDir: './game',
+ *   appid: 'com.example.game',
+ *   preset: 'iOS',
+ *   platform: 'ios'
+ * });
+ */
+export async function promptGodotOptions(defaults = {}) {
+  // 如果所有必需的值都已提供，直接返回，不进行询问（用于自动化场景）
+  if (
+    defaults.targetBaseDir &&
+    defaults.projectDir &&
+    defaults.appid &&
+    defaults.preset &&
+    defaults.platform
+  ) {
+    return {
+      targetBaseDir: String(defaults.targetBaseDir).trim(),
+      projectDir: String(defaults.projectDir).trim(),
+      name: String(defaults.appid).trim(),
+      preset: String(defaults.preset).trim(),
+      platform: defaults.platform
+    };
+  }
+
+  // 通过交互式命令行获取用户输入
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'targetBaseDir',
+      message: '请输入导出目标根目录 (项目 dist 目录):',
+      default: defaults.targetBaseDir || path.resolve(process.cwd(), './dist'),
+      validate: (input) => !!input.trim() || '目标根目录不能为空'
+    },
+    {
+      type: 'input',
+      name: 'projectDir',
+      message: '请输入 Godot 项目目录:',
+      default: defaults.projectDir || process.cwd(),
+      validate: (input) => !!input.trim() || '项目目录不能为空'
+    },
+    {
+      type: 'input',
+      name: 'name',
+      message: '请输入导出文件名称 (不含扩展名):',
+      default: defaults.name || 'GodotExport',
+      validate: (input) => !!input.trim() || '导出文件名称不能为空'
+    },
+    {
+      type: 'input',
+      name: 'preset',
+      message: '请输入 Godot 导出预设名称:',
+      default: defaults.preset || '',
+      validate: (input) => !!input.trim() || '导出预设名称不能为空'
+    },
+    {
+      type: 'list',
+      name: 'platform',
+      message: '请选择导出平台:',
+      choices: [
+        { name: 'iOS', value: PLATFORMS.IOS },
+        { name: 'Android', value: PLATFORMS.ANDROID }
+      ],
+      default: defaults.platform || 'ios'
+    }
+  ]);
+
+  return {
+    targetBaseDir: answers.targetBaseDir.trim(),
+    projectDir: answers.projectDir.trim(),
+    name: answers.name.trim(),
+    preset: answers.preset.trim(),
+    platform: answers.platform
+  };
+}
+
+/**
+ * 检查文件是否可执行
+ * 
+ * @param {string} filePath - 文件路径
+ * @returns {boolean} 文件是否可执行
+ */
+function isExecutable(filePath) {
+  if (!filePath) return false;
+  if (!fs.existsSync(filePath)) return false;
+
+  try {
+    accessSync(filePath, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 读取缓存的 Godot 编辑器路径
+ * 
+ * @returns {string} 缓存的路径，如果不存在则返回空字符串
+ */
+function readCachedGodotPath() {
+  try {
+    if (!fs.existsSync(GODOT_CACHE_FILE)) {
+      return '';
+    }
+    const data = fs.readJsonSync(GODOT_CACHE_FILE);
+    return typeof data?.godotPath === 'string' ? data.godotPath : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 保存 Godot 编辑器路径到缓存
+ * 
+ * @param {string} godotPath - Godot 编辑器路径
+ */
+async function writeCachedGodotPath(godotPath) {
+  try {
+    await fs.ensureDir(GODOT_CACHE_DIR);
+    await fs.writeJson(GODOT_CACHE_FILE, { godotPath }, { spaces: 2 });
+  } catch {
+    // 缓存失败不应该阻塞执行
+  }
+}
+
+/**
+ * 提示用户输入 Godot 编辑器路径
+ * 
+ * @param {string} defaultPath - 默认路径
+ * @returns {Promise<string>} 用户输入的路径
+ */
+async function promptForGodotBinaryPath(defaultPath) {
+  const { godotPath } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'godotPath',
+      message: '请输入 Godot Editor 可执行文件路径:',
+      default: defaultPath,
+      validate: (input) => !!input.trim() || '路径不能为空'
+    }
+  ]);
+
+  return godotPath.trim();
+}
+
+/**
+ * 解析并获取 Godot 编辑器可执行文件路径
+ * 
+ * 优先级：环境变量 > 缓存 > 默认路径
+ * 总是会询问用户，但将缓存值或默认值作为默认输入
+ * 
+ * @returns {Promise<string>} Godot 编辑器可执行文件路径
+ * @throws {Error} 当路径不可执行时抛出错误
+ */
+async function resolveGodotBinary() {
+  // 获取可能的默认值（优先级：环境变量 > 缓存 > 默认路径）
+  const override = process.env.GODOT_EDITOR ? process.env.GODOT_EDITOR.trim() : '';
+  const cached = readCachedGodotPath();
+  
+  // 确定默认值
+  let defaultPath = override || cached || DEFAULT_GODOT_BIN;
+  
+  // 总是询问用户，但将缓存值或默认值作为默认输入
+  const godotPath = await promptForGodotBinaryPath(defaultPath);
+
+  // 验证路径是否可执行
+  if (!isExecutable(godotPath)) {
+    throw new Error(`Godot 二进制文件不可执行: ${godotPath}`);
+  }
+
+  // 保存用户输入作为下次的默认值
+  await writeCachedGodotPath(godotPath);
+  return godotPath;
+}
+
+/**
+ * 执行 Godot 命令行命令
+ * 
+ * @param {string} godotBin - Godot 编辑器可执行文件路径
+ * @param {string[]} args - 命令参数
+ */
+async function runGodotCommand(godotBin, args) {
+  await execa(godotBin, args, { stdio: 'inherit' });
+}
+
+/**
+ * 处理 Android 平台导出
+ * 
+ * Android 导出流程：
+ * 1. 使用 Godot 导出为 ZIP 包
+ * 2. 解压 ZIP 包到指定目录
+ * 3. 清理临时 ZIP 文件
+ * 
+ * @param {object} options - 导出选项
+ * @param {string} options.godotBin - Godot 编辑器路径
+ * @param {string} options.projectDir - Godot 项目目录
+ * @param {string} options.preset - 导出预设名称
+ * @param {string} options.targetBaseDir - 目标根目录
+ * @param {string} options.name - 导出文件名（不含扩展名）
+ */
+async function handleAndroidExport({ godotBin, projectDir, preset, targetBaseDir, name }) {
+  // Android 导出路径：targetBaseDir/android/app/src/main/assets/
+  const assetsBaseDir = path.join(targetBaseDir, 'android', 'app', 'src', 'main', 'assets');
+  await fs.ensureDir(assetsBaseDir);
+
+  // 使用 Godot 导出为 ZIP 包
+  const zipPath = path.join(assetsBaseDir, `${name}.zip`);
+  await runGodotCommand(godotBin, ['--headless', '--path', projectDir, '--export-pack', preset, zipPath]);
+
+  // 解压 ZIP 包到目标目录
+  const targetDir = path.join(assetsBaseDir, name);
+  await fs.remove(targetDir);
+  await fs.ensureDir(targetDir);
+
+  const zip = new AdmZip(zipPath);
+  zip.extractAllTo(targetDir, true);
+  
+  // 清理临时 ZIP 文件
+  await fs.remove(zipPath);
+}
+
+/**
+ * 处理 iOS 平台导出
+ * 
+ * iOS 导出流程：
+ * 1. 使用 Godot 直接导出为 PCK 文件
+ * 
+ * @param {object} options - 导出选项
+ * @param {string} options.godotBin - Godot 编辑器路径
+ * @param {string} options.projectDir - Godot 项目目录
+ * @param {string} options.preset - 导出预设名称
+ * @param {string} options.targetBaseDir - 目标根目录
+ * @param {string} options.name - 导出文件名（不含扩展名）
+ */
+async function handleIosExport({ godotBin, projectDir, preset, targetBaseDir, name }) {
+  // iOS 导出路径：targetBaseDir/ios/
+  const assetsBaseDir = path.join(targetBaseDir, 'ios');
+  await fs.ensureDir(assetsBaseDir);
+  
+  // 使用 Godot 直接导出为 PCK 文件
+  const outputPath = path.join(assetsBaseDir, `${name}.pck`);
+  await runGodotCommand(godotBin, ['--headless', '--path', projectDir, '--export-pack', preset, outputPath]);
+}
+
+/**
+ * 导出 Godot 项目
+ * 
+ * 主要流程：
+ * 1. 解析并获取 Godot 编辑器路径
+ * 2. 执行资源导入（执行两次以确保资源正确导入）
+ * 3. 根据平台执行相应的导出流程
+ * 
+ * @param {object} options - 导出选项
+ * @param {string} options.platform - 导出平台（'ios' 或 'android'）
+ * @param {string} options.projectDir - Godot 项目目录
+ * @param {string} options.preset - Godot 导出预设名称
+ * @param {string} options.targetBaseDir - 目标根目录
+ * @param {string} options.name - 导出文件名（不含扩展名）
+ * @throws {Error} 当平台不支持时抛出错误
+ * 
+ * @example
+ * await exportGodot({
+ *   platform: 'ios',
+ *   projectDir: './game',
+ *   preset: 'iOS',
+ *   targetBaseDir: './dist',
+ *   name: 'MyGame'
+ * });
+ */
+export async function exportGodot(options) {
+  // 解析并获取 Godot 编辑器路径
+  const godotBin = await resolveGodotBinary();
+  const { platform, projectDir, preset, targetBaseDir, name } = options;
+
+  // 执行两次 import 以确保资源正确导入
+  // 某些情况下，第一次导入可能不完整，执行两次可以确保所有资源都被正确导入
+  const importArgs = ['--headless', '--path', projectDir, '--import'];
+  await runGodotCommand(godotBin, importArgs);
+  await runGodotCommand(godotBin, importArgs);
+
+  // 根据平台执行相应的导出流程
+  switch (platform) {
+    case PLATFORMS.IOS:
+      await handleIosExport({ godotBin, projectDir, preset, targetBaseDir, name });
+      break;
+    case PLATFORMS.ANDROID:
+      await handleAndroidExport({ godotBin, projectDir, preset, targetBaseDir, name });
+      break;
+    default:
+      throw new Error(`Unsupported platform: ${platform}. Supported: ${Object.values(PLATFORMS).join(', ')}`);
+  }
+}
+
+/**
+ * 主函数（当文件作为 CLI 直接执行时）
+ * 
+ * 如果该文件被直接执行（而非作为模块导入），则运行主函数
+ */
+async function main() {
+  const options = await promptGodotOptions();
+  await exportGodot(options);
+}
+
+/**
+ * 检查当前文件是否作为 CLI 直接执行
+ * 
+ * @returns {boolean} 是否为 CLI 执行
+ */
+const isCliExecution = (() => {
+  if (!process.argv[1]) {
+    return false;
+  }
+  const cliUrl = pathToFileURL(process.argv[1]).href;
+  return cliUrl === import.meta.url;
+})();
+
+// 如果作为 CLI 直接执行，运行主函数
+if (isCliExecution) {
+  main().catch((error) => {
+    console.error(error.message || error);
+    process.exitCode = 1;
+  });
+}
+

package/src/file-system.mjs

@@ -0,0 +1,114 @@
+import fs from 'fs';
+import path from 'path';
+import fse from 'fs-extra';
+import { Logger } from './logger.mjs';
+
+/**
+ * 文件系统工具类
+ */
+export class FileSystemUtils {
+  static ensureDirectory(dirPath) {
+    try {
+      fse.ensureDirSync(dirPath);
+      Logger.debug(`目录已确保存在: ${dirPath}`);
+      return true;
+    } catch (error) {
+      Logger.error(`创建目录失败: ${dirPath}`, error.message);
+      return false;
+    }
+  }
+
+  static cleanDirectory(dirPath) {
+    try {
+      if (fs.existsSync(dirPath)) {
+        fse.removeSync(dirPath);
+        Logger.info(`目录已清理: ${dirPath}`);
+      }
+      return true;
+    } catch (error) {
+      Logger.error(`清理目录失败: ${dirPath}`, error.message);
+      return false;
+    }
+  }
+
+  static backupFile(filePath) {
+    try {
+      if (fs.existsSync(filePath)) {
+        const backupPath = `${filePath}.backup.${Date.now()}`;
+        fse.copySync(filePath, backupPath);
+        Logger.info(`文件已备份: ${backupPath}`);
+        return backupPath;
+      }
+      return null;
+    } catch (error) {
+      Logger.error(`备份文件失败: ${filePath}`, error.message);
+      return null;
+    }
+  }
+
+  static getFileSize(filePath) {
+    try {
+      const stats = fs.statSync(filePath);
+      return stats.size;
+    } catch (error) {
+      return 0;
+    }
+  }
+
+  static formatFileSize(bytes) {
+    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+    if (bytes === 0) return '0 Bytes';
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    return Math.round(bytes / Math.pow(1024, i) * 100) / 100 + ' ' + sizes[i];
+  }
+
+  /**
+   * 检查目录是否为空
+   * @param {string} dirPath
+   * @returns {boolean}
+   */
+  static isDirectoryEmpty(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+      return true;
+    }
+    try {
+      const entries = fs.readdirSync(dirPath);
+      return entries.length === 0;
+    } catch (error) {
+      Logger.warn(`读取目录内容失败: ${dirPath}`, error.message);
+      return false;
+    }
+  }
+
+  static validatePath(path) {
+    // if (/[ -	fa5]/gi.test(path)) {
+    //   return { isValid: false, error: '路径中包含中文字符' };
+    // }
+    return { isValid: true };
+  }
+
+  /**
+   * 计算目录大小
+   * @param {string} dirPath - 目录路径
+   * @returns {number} 目录大小（字节）
+   */
+  static calculateDirectorySize(dirPath) {
+    if (!fs.existsSync(dirPath)) return 0;
+    let size = 0;
+    try {
+      const items = fse.readdirSync(dirPath, { withFileTypes: true });
+      for (const item of items) {
+        const itemPath = path.join(dirPath, item.name);
+        if (item.isDirectory()) {
+          size += this.calculateDirectorySize(itemPath);
+        } else {
+          size += fs.statSync(itemPath).size;
+        }
+      }
+    } catch (error) {
+      Logger.warn(`计算目录大小失败: ${dirPath}`, error.message);
+    }
+    return size;
+  }
+}
+