@ai-setting/roy-agent-core 1.0.0

package/src/env/commands/commands-config-registration.test.ts

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview Commands Component 配置注册测试
+ * 
+ * TDD: 先写测试，验证配置注册机制
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import os from "os";
+import path from "path";
+import { ConfigComponent } from "../../config/config-component";
+import { CommandsComponent } from "./commands-component";
+import { COMMANDS_CONFIG_REGISTRATION, COMMANDS_DEFAULTS } from "./commands-config-registration";
+
+describe("Commands Config Registration", () => {
+  let configComponent: ConfigComponent;
+  let component: CommandsComponent;
+
+  beforeEach(() => {
+    configComponent = new ConfigComponent();
+    component = new CommandsComponent();
+  });
+
+  describe("COMMANDS_CONFIG_REGISTRATION", () => {
+    it("应该包含正确的 name", () => {
+      expect(COMMANDS_CONFIG_REGISTRATION.name).toBe("command");
+    });
+
+    it("应该包含 env source 配置", () => {
+      const envSource = COMMANDS_CONFIG_REGISTRATION.sources.find(
+        (s) => s.type === "env"
+      );
+      expect(envSource).toBeDefined();
+      expect(envSource?.envPrefix).toBe("COMMAND");
+      expect(envSource?.priority).toBe(20);
+    });
+
+    it("应该包含所有配置 keys", () => {
+      const keys = COMMANDS_CONFIG_REGISTRATION.keys;
+      expect(keys).toContainEqual(
+        expect.objectContaining({ key: "command.userCommandsDir" })
+      );
+      expect(keys).toContainEqual(
+        expect.objectContaining({ key: "command.projectCommandsDir" })
+      );
+      expect(keys).toContainEqual(
+        expect.objectContaining({ key: "command.cacheDir" })
+      );
+    });
+  });
+
+  describe("COMMANDS_DEFAULTS", () => {
+    it("应该包含 userCommandsDir 键（动态默认值在 registerConfig 中设置）", () => {
+      expect("command.userCommandsDir" in COMMANDS_DEFAULTS).toBe(true);
+    });
+
+    it("应该包含 projectCommandsDir 键（动态默认值在 registerConfig 中设置）", () => {
+      expect("command.projectCommandsDir" in COMMANDS_DEFAULTS).toBe(true);
+    });
+
+    it("应该包含 cacheDir 键（动态默认值在 registerConfig 中设置）", () => {
+      expect("command.cacheDir" in COMMANDS_DEFAULTS).toBe(true);
+    });
+  });
+
+  describe("配置注册到 ConfigComponent", () => {
+    it("应该能够注册 COMMANDS_CONFIG_REGISTRATION", () => {
+      configComponent.registerComponent(COMMANDS_CONFIG_REGISTRATION);
+      expect(() => configComponent.registerComponent(COMMANDS_CONFIG_REGISTRATION)).not.toThrow();
+    });
+
+    // 注意：defaults 字段已被移除，默认值通过 configComponent.set() 在 registerConfig 中设置
+
+    it("注册后 keys 应该被注册（默认值需要通过 configComponent.set() 设置）", async () => {
+      configComponent.registerComponent(COMMANDS_CONFIG_REGISTRATION);
+      await configComponent.load();
+      
+      // 注意：默认值需要通过 configComponent.set() 设置，不会自动加载
+      // 但 keys 已注册
+      expect(configComponent.get("command.userCommandsDir")).toBeUndefined();
+    });
+  });
+
+  describe("Component 配置加载", () => {
+    it("应该需要 ConfigComponent 初始化", async () => {
+      await expect(
+        component.init({
+          options: {},
+        } as any)
+      ).rejects.toThrow("ConfigComponent is required");
+    });
+
+    it("应该能够使用 ConfigComponent 初始化", async () => {
+      await component.init({
+        options: {
+          configComponent,
+        },
+      } as any);
+      
+      expect(component.name).toBe("commands");
+      expect(component.version).toBe("2.0.0");
+    });
+
+    it("应该能够通过 config 对象传入配置", async () => {
+      // 使用 tmpdir 作为测试路径
+      const tmpDir = os.tmpdir();
+      
+      await component.init({
+        options: {
+          configComponent,
+          config: {
+            userCommandsDir: path.join(tmpDir, "test-user-commands"),
+            projectCommandsDir: path.join(tmpDir, "test-project-commands"),
+          },
+        },
+      } as any);
+      
+      expect(component.name).toBe("commands");
+    });
+  });
+
+  describe("环境变量覆盖", () => {
+    it("应该能够通过环境变量覆盖配置", async () => {
+      // 设置环境变量（使用有效的 tmp 路径）
+      const originalValue = process.env.COMMAND_COMMAND_USER_COMMANDS_DIR;
+      const tmpPath = path.join(os.tmpdir(), "test-env-path");
+      process.env.COMMAND_COMMAND_USER_COMMANDS_DIR = tmpPath;
+      
+      try {
+        await component.init({
+          options: {
+            configComponent,
+          },
+        } as any);
+        
+        expect(component.name).toBe("commands");
+      } finally {
+        // 恢复环境变量
+        if (originalValue !== undefined) {
+          process.env.COMMAND_COMMAND_USER_COMMANDS_DIR = originalValue;
+        } else {
+          delete process.env.COMMAND_COMMAND_USER_COMMANDS_DIR;
+        }
+      }
+    });
+
+    it("环境变量应该能够覆盖默认值", async () => {
+      const originalValue = process.env.COMMAND_COMMAND_USER_COMMANDS_DIR;
+      const tmpPath = path.join(os.tmpdir(), "env-override-test");
+      process.env.COMMAND_COMMAND_USER_COMMANDS_DIR = tmpPath;
+      
+      try {
+        // 创建新 component 来使用新的环境变量
+        const newComponent = new CommandsComponent();
+        await newComponent.init({
+          options: {
+            configComponent,
+          },
+        } as any);
+        
+        // 环境变量应该覆盖默认值
+        // 注意：在 CommandsComponent.init 中，registerConfig 会在 load 之后再次设置环境变量
+        expect(configComponent.get("command.userCommandsDir")).toBe(tmpPath);
+      } finally {
+        if (originalValue !== undefined) {
+          process.env.COMMAND_COMMAND_USER_COMMANDS_DIR = originalValue;
+        } else {
+          delete process.env.COMMAND_COMMAND_USER_COMMANDS_DIR;
+        }
+      }
+    });
+  });
+
+  describe("ConfigComponent.registerComponent 模式集成", () => {
+    it("初始化后 ConfigComponent 应该包含命令配置", async () => {
+      await component.init({
+        options: {
+          configComponent,
+        },
+      } as any);
+      
+      // 验证 ConfigComponent 有命令相关配置
+      const value = configComponent.get("command.userCommandsDir");
+      expect(value).toBeDefined();
+      expect(typeof value).toBe("string");
+    });
+
+    it("registerComponent 注册后应该能通过 load 获取已配置的 keys", async () => {
+      // 直接使用 registerComponent 和 load 验证模式
+      configComponent.registerComponent(COMMANDS_CONFIG_REGISTRATION);
+      await configComponent.load("command");
+      
+      // 注意：默认值不会自动加载，需要通过 configComponent.set() 设置
+      // 验证 keys 已注册（从 ConfigComponent 获取会返回 undefined）
+      const userDir = configComponent.get("command.userCommandsDir");
+      expect(userDir).toBeUndefined(); // 默认值未设置
+    });
+  });
+});

package/src/env/commands/commands-config-registration.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Commands Component 配置注册
+ * 
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+
+import type { ComponentRegistration } from "../../config/config-component";
+
+/**
+ * Commands Component 默认配置值（占位，实际值在 registerConfig 中动态设置）
+ * 
+ * 注意：这些默认值在 CommandsComponent.registerConfig() 中
+ * 通过 configComponent.set() 设置到 ConfigComponent，使用基于 HOME 的绝对路径
+ */
+export const COMMANDS_DEFAULTS: Record<string, unknown> = {
+  "command.userCommandsDir": undefined, // 动态设置：${HOME}/.roy-agent/commands
+  "command.projectCommandsDir": undefined, // 动态设置：${cwd}/.roy/commands
+  "command.cacheDir": undefined, // 动态设置：${HOME}/.cache/roy-agent/commands
+};
+
+/**
+ * Commands Component 配置注册常量
+ * 
+ * 定义了所有 Commands 相关的配置项和来源
+ */
+export const COMMANDS_CONFIG_REGISTRATION: ComponentRegistration = {
+  name: "command",
+  
+  sources: [
+    { type: "env", envPrefix: "COMMAND", priority: 20, watch: false },
+  ],
+  
+  keys: [
+    { key: "command.userCommandsDir", sources: ["env", "file"] },
+    { key: "command.projectCommandsDir", sources: ["env", "file"] },
+    { key: "command.cacheDir", sources: ["env", "file"] },
+  ],
+};

package/src/env/commands/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Commands Component Module
+ * 
+ * 导出 CommandsComponent 及其类型
+ */
+
+// Component
+export { CommandsComponent } from "./commands-component";
+
+// Types
+export type {
+  CommandsComponentOptions,
+  CommandsComponentConfig,
+  CommandSource,
+  CommandIndex,
+  ScanResult,
+  DiscoverOptions,
+  AddCommandOptions,
+  RemoveCommandOptions,
+  ExecutionResult,
+} from "./types";

package/src/env/commands/parser.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { parseFrontmatter, parseMetaFile, scanMetaFiles } from "./parser";
+
+describe("parser", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "roy-commands-parser-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe("parseFrontmatter", () => {
+    it("should parse simple key-value pairs", () => {
+      const text = `name: git
+description: Git version control`;
+      
+      const result = parseFrontmatter(text);
+      
+      expect(result.name).toBe("git");
+      expect(result.description).toBe("Git version control");
+    });
+
+    it("should handle quoted values", () => {
+      const text = `name: "quoted name"
+description: "with spaces"`;
+      
+      const result = parseFrontmatter(text);
+      
+      expect(result.name).toBe("quoted name");
+      expect(result.description).toBe("with spaces");
+    });
+
+    it("should handle empty text", () => {
+      const result = parseFrontmatter("");
+      
+      expect(Object.keys(result)).toHaveLength(0);
+    });
+
+    it("should handle values with colons", () => {
+      const text = `name: git
+description: Git version control: manage repositories`;
+      
+      const result = parseFrontmatter(text);
+      
+      expect(result.description).toBe("Git version control: manage repositories");
+    });
+
+    it("should handle single quoted values (kept as-is)", () => {
+      const text = `name: 'single quoted'
+description: 'with content'`;
+      
+      const result = parseFrontmatter(text);
+      
+      // 当前实现只支持双引号，单引号会被保留
+      expect(result.name).toBe("'single quoted'");
+      expect(result.description).toBe("'with content'");
+    });
+
+    it("should skip lines without colon", () => {
+      const text = `name: git
+this line has no colon
+description: Git`;
+      
+      const result = parseFrontmatter(text);
+      
+      expect(result.name).toBe("git");
+      expect(result.description).toBe("Git");
+      expect((result as any)["this line has no colon"]).toBeUndefined();
+    });
+  });
+
+  describe("parseMetaFile", () => {
+    it("should parse valid meta.md file", async () => {
+      const metaPath = path.join(tempDir, "meta.md");
+      await fs.writeFile(metaPath, `---
+name: git
+description: Git version control
+tips: Use --help to explore
+source: user
+---
+
+# Git Command`);
+      
+      const result = await parseMetaFile(metaPath, "user");
+      
+      expect(result).not.toBeNull();
+      expect(result!.name).toBe("git");
+      expect(result!.description).toBe("Git version control");
+      expect(result!.tips).toBe("Use --help to explore");
+      expect(result!.source).toBe("user");
+    });
+
+    it("should return null for missing frontmatter", async () => {
+      const metaPath = path.join(tempDir, "meta.md");
+      await fs.writeFile(metaPath, `# No frontmatter`);
+      
+      const result = await parseMetaFile(metaPath, "user");
+      
+      expect(result).toBeNull();
+    });
+
+    it("should return null for missing name", async () => {
+      const metaPath = path.join(tempDir, "meta.md");
+      await fs.writeFile(metaPath, `---
+description: Only description
+---`);
+      
+      const result = await parseMetaFile(metaPath, "user");
+      
+      expect(result).toBeNull();
+    });
+
+    it("should return null for missing description", async () => {
+      const metaPath = path.join(tempDir, "meta.md");
+      await fs.writeFile(metaPath, `---
+name: git
+---`);
+      
+      const result = await parseMetaFile(metaPath, "user");
+      
+      expect(result).toBeNull();
+    });
+
+    it("should handle meta with empty tips", async () => {
+      const metaPath = path.join(tempDir, "meta.md");
+      await fs.writeFile(metaPath, `---
+name: git
+description: Git version control
+tips: 
+---`);
+      
+      const result = await parseMetaFile(metaPath, "user");
+      
+      expect(result).not.toBeNull();
+      expect(result!.name).toBe("git");
+      // 空 tips 会被解析为空格（trim 后的结果）
+      expect(result!.tips?.trim()).toBe("");
+    });
+
+    it("should handle description with special characters", async () => {
+      const metaPath = path.join(tempDir, "meta.md");
+      await fs.writeFile(metaPath, `---
+name: docker
+description: Container management - build | run | push images
+---`);
+      
+      const result = await parseMetaFile(metaPath, "user");
+      
+      expect(result).not.toBeNull();
+      expect(result!.description).toBe("Container management - build | run | push images");
+    });
+  });
+
+  describe("scanMetaFiles", () => {
+    it("should scan meta.md in directory", async () => {
+      const metaPath = path.join(tempDir, "meta.md");
+      await fs.writeFile(metaPath, `---
+name: git
+description: Git version control
+---`);
+      
+      const result = await scanMetaFiles(tempDir, "user");
+      
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe("git");
+      expect(result[0].description).toBe("Git version control");
+      expect(result[0].source).toBe("user");
+    });
+
+    it("should return empty array for non-existent directory", async () => {
+      const result = await scanMetaFiles("/non/existent/path", "user");
+      
+      expect(result).toEqual([]);
+    });
+
+    it("should skip hidden files", async () => {
+      const hiddenPath = path.join(tempDir, ".hidden.md");
+      await fs.writeFile(hiddenPath, `---
+name: should-not-appear
+description: test
+---`);
+      
+      const result = await scanMetaFiles(tempDir, "user");
+      
+      expect(result).toHaveLength(0);
+    });
+
+    it("should skip non-meta files", async () => {
+      const readmePath = path.join(tempDir, "README.md");
+      await fs.writeFile(readmePath, `# Readme`);
+      
+      const result = await scanMetaFiles(tempDir, "user");
+      
+      expect(result).toHaveLength(0);
+    });
+  });
+});

package/src/env/commands/parser.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Command Meta.md Parser
+ * 
+ * 解析命令目录下的 meta.md 文件，提取 Frontmatter 元信息
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import { createLogger } from "../log-trace/logger";
+import type { CommandMeta, CommandSource } from "./types";
+
+const logger = createLogger("commands-parser");
+
+/**
+ * 解析 frontmatter 文本
+ */
+export function parseFrontmatter(text: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const lines = text.split("\n");
+
+  for (const line of lines) {
+    // 匹配 key: value 格式
+    const match = line.match(/^(\w+):\s*"?(.+?)"?\s*$/);
+    if (match) {
+      const key = match[1];
+      let value = match[2];
+      // 移除首尾引号
+      if (value.startsWith('"') && value.endsWith('"')) {
+        value = value.slice(1, -1);
+      }
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 解析单个 meta.md 文件
+ */
+export async function parseMetaFile(
+  filePath: string,
+  source: CommandSource
+): Promise<CommandMeta | null> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+
+    // 匹配 frontmatter: --- ... ---
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?/);
+    if (!frontmatterMatch) {
+      logger.warn(`[Parser] Missing frontmatter in: ${filePath}`);
+      return null;
+    }
+
+    const frontmatter = parseFrontmatter(frontmatterMatch[1]);
+    const name = frontmatter.name;
+    const description = frontmatter.description;
+
+    if (!name) {
+      logger.warn(`[Parser] Missing name in frontmatter: ${filePath}`);
+      return null;
+    }
+
+    if (!description) {
+      logger.warn(`[Parser] Missing description in frontmatter: ${filePath}`);
+      return null;
+    }
+
+    return {
+      name,
+      description,
+      tips: frontmatter.tips,
+      filePath,
+      source,
+    };
+  } catch (error) {
+    logger.error(`[Parser] Failed to parse file: ${filePath}`, error);
+    return null;
+  }
+}
+
+/**
+ * 扫描目录下的所有 meta.md 文件
+ */
+export async function scanMetaFiles(
+  dirPath: string,
+  source: CommandSource
+): Promise<CommandMeta[]> {
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const metaList: CommandMeta[] = [];
+
+    for (const entry of entries) {
+      // 跳过隐藏文件和目录
+      if (entry.name.startsWith(".")) continue;
+      
+      if (entry.isFile() && entry.name === "meta.md") {
+        const metaFilePath = path.join(dirPath, entry.name);
+        const meta = await parseMetaFile(metaFilePath, source);
+        if (meta) {
+          metaList.push(meta);
+        }
+      }
+    }
+
+    return metaList;
+  } catch (error) {
+    // 目录不存在时返回空数组
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return [];
+    }
+    logger.error(`[Parser] Failed to scan directory: ${dirPath}`, error);
+    return [];
+  }
+}