@xiaozhi-client/cli 1.9.4-beta.10

package/src/services/__tests__/TemplateManager.test.ts

@@ -0,0 +1,337 @@
+/**
+ * 模板管理服务单元测试
+ */
+
+import { FileError, ValidationError } from "@cli/errors/index.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { TemplateCreateOptions } from "../TemplateManager";
+import { TemplateManagerImpl } from "../TemplateManager";
+
+// Mock 依赖
+vi.mock("@cli/utils/PathUtils.js", () => ({
+  PathUtils: {
+    findTemplatesDir: vi.fn(),
+    getTemplatePath: vi.fn(),
+  },
+}));
+
+vi.mock("@cli/utils/FileUtils.js", () => ({
+  FileUtils: {
+    exists: vi.fn(),
+    readFile: vi.fn(),
+    writeFile: vi.fn(),
+    ensureDir: vi.fn(),
+    copyDirectory: vi.fn(),
+    listDirectory: vi.fn(),
+  },
+}));
+
+vi.mock("@cli/utils/Validation.js", () => ({
+  Validation: {
+    validateTemplateName: vi.fn(),
+    validateRequired: vi.fn(),
+    validateProjectName: vi.fn(),
+  },
+}));
+
+vi.mock("node:fs", () => ({
+  default: {
+    readdirSync: vi.fn(),
+  },
+}));
+
+vi.mock("node:path", () => ({
+  default: {
+    join: vi.fn((...args) => args.join("/")),
+    resolve: vi.fn((p) => `/resolved/${p}`),
+    relative: vi.fn((from, to) => String(to).replace(`${String(from)}/`, "")),
+  },
+}));
+
+const { PathUtils } = await import("@cli/utils/PathUtils.js");
+const { FileUtils } = await import("@cli/utils/FileUtils.js");
+const { Validation } = await import("@cli/utils/Validation.js");
+const fs = await import("node:fs");
+
+describe("TemplateManagerImpl", () => {
+  let templateManager: TemplateManagerImpl;
+
+  beforeEach(() => {
+    templateManager = new TemplateManagerImpl();
+
+    // 重置所有 mock
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("getAvailableTemplates", () => {
+    it("should return empty array if templates directory not found", async () => {
+      (PathUtils.findTemplatesDir as any).mockReturnValue(null);
+
+      const templates = await templateManager.getAvailableTemplates();
+
+      expect(templates).toEqual([]);
+    });
+
+    it("should return available templates", async () => {
+      (PathUtils.findTemplatesDir as any).mockReturnValue("/templates");
+      (fs.default.readdirSync as any).mockReturnValue([
+        { name: "template1", isDirectory: () => true },
+        { name: "template2", isDirectory: () => true },
+        { name: "file.txt", isDirectory: () => false },
+      ]);
+      (PathUtils.getTemplatePath as any).mockImplementation(
+        (name: string) => `/templates/${name}`
+      );
+      (FileUtils.exists as any).mockReturnValue(false); // No template.json
+      (FileUtils.listDirectory as any).mockReturnValue([
+        "/templates/template1/index.js",
+      ]);
+
+      const templates = await templateManager.getAvailableTemplates();
+
+      expect(templates).toHaveLength(2);
+      expect(templates[0].name).toBe("template1");
+      expect(templates[1].name).toBe("template2");
+    });
+
+    it("should handle template directory read errors", async () => {
+      (PathUtils.findTemplatesDir as any).mockReturnValue("/templates");
+      (fs.default.readdirSync as any).mockImplementation(() => {
+        throw new Error("Permission denied");
+      });
+
+      await expect(templateManager.getAvailableTemplates()).rejects.toThrow(
+        FileError
+      );
+    });
+  });
+
+  describe("getTemplateInfo", () => {
+    it("should validate template name", async () => {
+      (Validation.validateTemplateName as any).mockImplementation(() => {
+        throw new ValidationError("Invalid template name", "templateName");
+      });
+
+      await expect(
+        templateManager.getTemplateInfo("invalid-name")
+      ).rejects.toThrow(ValidationError);
+    });
+
+    it("should return null if template path not found", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue(null);
+
+      const result = await templateManager.getTemplateInfo("nonexistent");
+
+      expect(result).toBeNull();
+    });
+
+    it("should return template info without config file", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/test");
+      (FileUtils.exists as any).mockReturnValue(false);
+      (FileUtils.listDirectory as any).mockReturnValue([
+        "/templates/test/index.js",
+      ]);
+
+      const result = await templateManager.getTemplateInfo("test");
+
+      expect(result).toEqual({
+        name: "test",
+        path: "/templates/test",
+        description: "test 模板",
+        version: "1.0.0",
+        author: undefined,
+        files: ["/templates/test/index.js"],
+      });
+    });
+
+    it("should return template info with config file", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/test");
+      (FileUtils.exists as any).mockReturnValue(true);
+      (FileUtils.readFile as any).mockReturnValue(
+        JSON.stringify({
+          description: "Test template",
+          version: "2.0.0",
+          author: "Test Author",
+        })
+      );
+      (FileUtils.listDirectory as any).mockReturnValue([
+        "/templates/test/index.js",
+      ]);
+
+      const result = await templateManager.getTemplateInfo("test");
+
+      expect(result).toEqual({
+        name: "test",
+        path: "/templates/test",
+        description: "Test template",
+        version: "2.0.0",
+        author: "Test Author",
+        files: ["/templates/test/index.js"],
+      });
+    });
+
+    it("should handle invalid config file gracefully", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/test");
+      (FileUtils.exists as any).mockReturnValue(true);
+      (FileUtils.readFile as any).mockReturnValue("invalid json");
+      (FileUtils.listDirectory as any).mockReturnValue([]);
+
+      const result = await templateManager.getTemplateInfo("test");
+
+      expect(result?.description).toBe("test 模板");
+      expect(result?.version).toBe("1.0.0");
+    });
+
+    it("should cache template info", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/test");
+      (FileUtils.exists as any).mockReturnValue(false);
+      (FileUtils.listDirectory as any).mockReturnValue([]);
+
+      // First call
+      await templateManager.getTemplateInfo("test");
+      // Second call
+      await templateManager.getTemplateInfo("test");
+
+      expect(PathUtils.getTemplatePath).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("createProject", () => {
+    const defaultOptions: TemplateCreateOptions = {
+      targetPath: "my-project",
+      projectName: "MyProject",
+    };
+
+    it("should validate create options", async () => {
+      (Validation.validateRequired as any).mockImplementation(() => {
+        throw new ValidationError("Required field missing", "field");
+      });
+
+      await expect(
+        templateManager.createProject(defaultOptions)
+      ).rejects.toThrow(ValidationError);
+    });
+
+    it("should throw error if template not found", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue(null);
+
+      await expect(
+        templateManager.createProject({
+          ...defaultOptions,
+          templateName: "nonexistent",
+        })
+      ).rejects.toThrow(FileError);
+    });
+
+    it("should throw error if target path already exists", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/default");
+      (FileUtils.exists as any).mockImplementation((path: string) => {
+        return path === "/resolved/my-project";
+      });
+      (FileUtils.listDirectory as any).mockReturnValue([]);
+
+      await expect(
+        templateManager.createProject(defaultOptions)
+      ).rejects.toThrow(FileError);
+    });
+
+    it("should create project successfully", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/default");
+      (FileUtils.exists as any).mockImplementation((path: string) => {
+        return path !== "/resolved/my-project"; // Target doesn't exist
+      });
+      (FileUtils.listDirectory as any).mockReturnValue([
+        "/templates/default/package.json",
+      ]);
+
+      await templateManager.createProject(defaultOptions);
+
+      expect(FileUtils.ensureDir).toHaveBeenCalledWith("/resolved/my-project");
+      expect(FileUtils.copyDirectory).toHaveBeenCalledWith(
+        "/templates/default",
+        "/resolved/my-project",
+        expect.objectContaining({
+          exclude: ["template.json", ".git", "node_modules"],
+          overwrite: false,
+          recursive: true,
+        })
+      );
+    });
+
+    it("should process template variables", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/default");
+      (FileUtils.exists as any).mockImplementation((path: string) => {
+        return path !== "/resolved/my-project" && path.includes("package.json");
+      });
+      (FileUtils.listDirectory as any).mockReturnValue([
+        "/resolved/my-project/package.json",
+      ]);
+      (FileUtils.readFile as any).mockReturnValue(
+        '{"name": "{{PROJECT_NAME}}"}'
+      );
+
+      await templateManager.createProject({
+        ...defaultOptions,
+        variables: { CUSTOM_VAR: "custom_value" },
+      });
+
+      expect(FileUtils.writeFile).toHaveBeenCalledWith(
+        "/resolved/my-project/package.json",
+        '{"name": "MyProject"}',
+        { overwrite: true }
+      );
+    });
+  });
+
+  describe("validateTemplate", () => {
+    it("should return false if template not found", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue(null);
+
+      const isValid = await templateManager.validateTemplate("nonexistent");
+
+      expect(isValid).toBe(false);
+    });
+
+    it("should return false if required files missing", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/test");
+      (FileUtils.exists as any).mockImplementation((path: string) => {
+        return !path.includes("package.json");
+      });
+      (FileUtils.listDirectory as any).mockReturnValue([]);
+
+      const isValid = await templateManager.validateTemplate("test");
+
+      expect(isValid).toBe(false);
+    });
+
+    it("should return true if template is valid", async () => {
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/test");
+      (FileUtils.exists as any).mockReturnValue(true);
+      (FileUtils.listDirectory as any).mockReturnValue([]);
+
+      const isValid = await templateManager.validateTemplate("test");
+
+      expect(isValid).toBe(true);
+    });
+  });
+
+  describe("clearCache", () => {
+    it("should clear template cache", async () => {
+      // Add something to cache first
+      (PathUtils.getTemplatePath as any).mockReturnValue("/templates/test");
+      (FileUtils.exists as any).mockReturnValue(false);
+      (FileUtils.listDirectory as any).mockReturnValue([]);
+
+      await templateManager.getTemplateInfo("test");
+      templateManager.clearCache();
+
+      // Should call getTemplatePath again after cache clear
+      await templateManager.getTemplateInfo("test");
+      expect(PathUtils.getTemplatePath).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/types/backend.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Backend 模块类型声明
+ * 使用 any 类型避免递归解析 backend 代码
+ */
+
+declare module "@/lib/config/manager" {
+  export interface LocalMCPServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+  }
+
+  export interface MCPServerConfig {
+    type?: string;
+    url?: string;
+    command?: string;
+    args?: string[];
+    headers?: Record<string, string>;
+  }
+
+  export const configManager: any;
+}
+
+declare module "@/lib/config/manager.js" {
+  export interface LocalMCPServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+  }
+
+  export interface MCPServerConfig {
+    type?: string;
+    url?: string;
+    command?: string;
+    args?: string[];
+    headers?: Record<string, string>;
+  }
+
+  export const configManager: any;
+}
+
+declare module "@root/WebServer" {
+  export class WebServer {}
+}
+
+declare module "@root/WebServer.js" {
+  export class WebServer {}
+}

package/src/utils/FileUtils.ts

@@ -0,0 +1,320 @@
+/**
+ * 文件操作工具
+ */
+
+import fs from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { FileOperationOptions } from "../Types";
+import { FileError } from "../errors/index";
+
+/**
+ * 文件工具类
+ */
+export class FileUtils {
+  /**
+   * 检查文件是否存在
+   */
+  static exists(filePath: string): boolean {
+    try {
+      return fs.existsSync(filePath);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 确保目录存在
+   */
+  static ensureDir(dirPath: string): void {
+    try {
+      if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+      }
+    } catch (error) {
+      throw new FileError("无法创建目录", dirPath);
+    }
+  }
+
+  /**
+   * 读取文件内容
+   */
+  static readFile(filePath: string, encoding: BufferEncoding = "utf8"): string {
+    try {
+      if (!FileUtils.exists(filePath)) {
+        throw FileError.notFound(filePath);
+      }
+      return fs.readFileSync(filePath, encoding);
+    } catch (error) {
+      if (error instanceof FileError) {
+        throw error;
+      }
+      throw new FileError("无法读取文件", filePath);
+    }
+  }
+
+  /**
+   * 写入文件内容
+   */
+  static writeFile(
+    filePath: string,
+    content: string,
+    options?: { overwrite?: boolean }
+  ): void {
+    try {
+      if (!options?.overwrite && FileUtils.exists(filePath)) {
+        throw FileError.alreadyExists(filePath);
+      }
+
+      // 确保目录存在
+      const dir = path.dirname(filePath);
+      FileUtils.ensureDir(dir);
+
+      fs.writeFileSync(filePath, content, "utf8");
+    } catch (error) {
+      if (error instanceof FileError) {
+        throw error;
+      }
+      throw new FileError("无法写入文件", filePath);
+    }
+  }
+
+  /**
+   * 复制文件
+   */
+  static copyFile(
+    srcPath: string,
+    destPath: string,
+    options?: { overwrite?: boolean }
+  ): void {
+    try {
+      if (!FileUtils.exists(srcPath)) {
+        throw FileError.notFound(srcPath);
+      }
+
+      if (!options?.overwrite && FileUtils.exists(destPath)) {
+        throw FileError.alreadyExists(destPath);
+      }
+
+      // 确保目标目录存在
+      const destDir = path.dirname(destPath);
+      FileUtils.ensureDir(destDir);
+
+      fs.copyFileSync(srcPath, destPath);
+    } catch (error) {
+      if (error instanceof FileError) {
+        throw error;
+      }
+      throw new FileError("无法复制文件", srcPath);
+    }
+  }
+
+  /**
+   * 删除文件
+   */
+  static deleteFile(filePath: string): void {
+    try {
+      if (FileUtils.exists(filePath)) {
+        fs.unlinkSync(filePath);
+      }
+    } catch (error) {
+      throw new FileError("无法删除文件", filePath);
+    }
+  }
+
+  /**
+   * 复制目录
+   */
+  static copyDirectory(
+    srcDir: string,
+    destDir: string,
+    options: FileOperationOptions = {}
+  ): void {
+    try {
+      if (!FileUtils.exists(srcDir)) {
+        throw FileError.notFound(srcDir);
+      }
+
+      // 确保目标目录存在
+      FileUtils.ensureDir(destDir);
+
+      const items = fs.readdirSync(srcDir);
+
+      for (const item of items) {
+        // 检查是否在排除列表中
+        if (options.exclude?.includes(item)) {
+          continue;
+        }
+
+        const srcPath = path.join(srcDir, item);
+        const destPath = path.join(destDir, item);
+        const stat = fs.statSync(srcPath);
+
+        if (stat.isDirectory()) {
+          if (options.recursive !== false) {
+            FileUtils.copyDirectory(srcPath, destPath, options);
+          }
+        } else {
+          FileUtils.copyFile(srcPath, destPath, {
+            overwrite: options.overwrite,
+          });
+        }
+      }
+    } catch (error) {
+      if (error instanceof FileError) {
+        throw error;
+      }
+      throw new FileError("无法复制目录", srcDir);
+    }
+  }
+
+  /**
+   * 删除目录
+   */
+  static deleteDirectory(
+    dirPath: string,
+    options: { recursive?: boolean } = {}
+  ): void {
+    try {
+      if (FileUtils.exists(dirPath)) {
+        fs.rmSync(dirPath, {
+          recursive: options.recursive ?? true,
+          force: true,
+        });
+      }
+    } catch (error) {
+      throw new FileError("无法删除目录", dirPath);
+    }
+  }
+
+  /**
+   * 获取文件信息
+   */
+  static getFileInfo(filePath: string): {
+    size: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    mtime: Date;
+    ctime: Date;
+  } {
+    try {
+      if (!FileUtils.exists(filePath)) {
+        throw FileError.notFound(filePath);
+      }
+
+      const stats = fs.statSync(filePath);
+      return {
+        size: stats.size,
+        isFile: stats.isFile(),
+        isDirectory: stats.isDirectory(),
+        mtime: stats.mtime,
+        ctime: stats.ctime,
+      };
+    } catch (error) {
+      if (error instanceof FileError) {
+        throw error;
+      }
+      throw new FileError("无法获取文件信息", filePath);
+    }
+  }
+
+  /**
+   * 列出目录内容
+   */
+  static listDirectory(
+    dirPath: string,
+    options: {
+      recursive?: boolean;
+      includeHidden?: boolean;
+    } = {}
+  ): string[] {
+    try {
+      if (!FileUtils.exists(dirPath)) {
+        throw FileError.notFound(dirPath);
+      }
+
+      const items = fs.readdirSync(dirPath);
+      let result: string[] = [];
+
+      for (const item of items) {
+        // 跳过隐藏文件（除非明确要求包含）
+        if (!options.includeHidden && item.startsWith(".")) {
+          continue;
+        }
+
+        const itemPath = path.join(dirPath, item);
+        result.push(itemPath);
+
+        // 递归处理子目录
+        if (options.recursive && fs.statSync(itemPath).isDirectory()) {
+          const subItems = FileUtils.listDirectory(itemPath, options);
+          result = result.concat(subItems);
+        }
+      }
+
+      return result;
+    } catch (error) {
+      if (error instanceof FileError) {
+        throw error;
+      }
+      throw new FileError("无法列出目录内容", dirPath);
+    }
+  }
+
+  /**
+   * 创建临时文件
+   */
+  static createTempFile(prefix = "xiaozhi-", suffix = ".tmp"): string {
+    const tempDir = process.env.TMPDIR || process.env.TEMP || tmpdir();
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2);
+    const fileName = `${prefix}${timestamp}-${random}${suffix}`;
+    return path.join(tempDir, fileName);
+  }
+
+  /**
+   * 检查文件权限
+   */
+  static checkPermissions(
+    filePath: string,
+    mode: number = fs.constants.R_OK | fs.constants.W_OK
+  ): boolean {
+    try {
+      fs.accessSync(filePath, mode);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 获取文件扩展名
+   */
+  static getExtension(filePath: string): string {
+    return path.extname(filePath).toLowerCase();
+  }
+
+  /**
+   * 获取文件名（不含扩展名）
+   */
+  static getBaseName(filePath: string): string {
+    return path.basename(filePath, path.extname(filePath));
+  }
+
+  /**
+   * 规范化路径
+   */
+  static normalizePath(filePath: string): string {
+    return path.normalize(filePath);
+  }
+
+  /**
+   * 解析相对路径为绝对路径
+   */
+  static resolvePath(filePath: string, basePath?: string): string {
+    if (basePath) {
+      return path.resolve(basePath, filePath);
+    }
+    return path.resolve(filePath);
+  }
+}