@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/core/src/env/commands/commands-component.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview CommandsComponent
+ *
+ * 命令管理核心组件（收藏式）
+ *
+ * 功能：
+ * - 管理 user/project 多路径命令目录
+ * - 提供命令发现、添加、移除、执行能力
+ * - 支持 File/Env/Object 三种配置来源
+ */
+import { BaseComponent, type ComponentConfig } from "../component";
+import type { CommandIndex, CommandMeta, ScanResult, DiscoverOptions, AddCommandOptions, RemoveCommandOptions, ExecutionResult } from "./types";
+export declare class CommandsComponent extends BaseComponent {
+    readonly name = "commands";
+    readonly version = "2.0.0";
+    private config?;
+    private configComponent?;
+    private userCommandsDir;
+    private projectCommandsDir;
+    private descriptionCache;
+    private descriptionCacheFile;
+    constructor();
+    private initDefaultDirs;
+    /**
+     * 初始化组件
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. File - 配置文件
+     * 2. Env - 环境变量
+     * 3. Object - 直接传入的 config 对象
+     */
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 使用 SessionComponent 的正确模式：
+     * 1. 使用 registerComponent() 注册配置（包含 sources、keys、defaults）
+     * 2. 使用 load("command") 加载配置值
+     * 3. 处理环境变量后备方案
+     * 4. 处理 config 对象（最高优先级）
+     */
+    private registerConfig;
+    /**
+     * 将嵌套配置扁平化
+     */
+    private flattenConfig;
+    /**
+     * 从 ConfigComponent 应用配置
+     */
+    private applyConfig;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * 获取命令目录列表
+     */
+    getCommandDirs(): Promise<{
+        user: string;
+        project: string;
+    }>;
+    /**
+     * 发现命令
+     */
+    discover(options?: DiscoverOptions): Promise<ScanResult>;
+    /**
+     * 添加命令
+     */
+    add(options: AddCommandOptions): Promise<void>;
+    /**
+     * 创建命令的 meta.md 文件
+     */
+    private createCommandMeta;
+    /**
+     * 获取所有收藏命令的元信息（用于 Prompt 注入）
+     */
+    getCommandsMeta(): Promise<CommandMeta[]>;
+    /**
+     * 移除命令
+     */
+    remove(options: RemoveCommandOptions): Promise<void>;
+    /**
+     * 获取命令信息
+     */
+    getInfo(name: string): Promise<CommandIndex | null>;
+    /**
+     * 执行命令
+     */
+    exec(options: {
+        name: string;
+        args?: string[];
+        cwd?: string;
+    }): Promise<ExecutionResult>;
+    private scanDir;
+    private matchPattern;
+    private getDescription;
+    private loadDescriptionCache;
+    private saveDescriptionCache;
+}
+//# sourceMappingURL=commands-component.d.ts.map

package/dist/core/src/env/commands/commands-component.js

@@ -0,0 +1,517 @@
+/**
+ * @fileoverview CommandsComponent
+ *
+ * 命令管理核心组件（收藏式）
+ *
+ * 功能：
+ * - 管理 user/project 多路径命令目录
+ * - 提供命令发现、添加、移除、执行能力
+ * - 支持 File/Env/Object 三种配置来源
+ */
+import path from "path";
+import os from "os";
+import { BaseComponent } from "../component.js";
+import { createLogger } from "../log-trace/logger.js";
+import * as fs from "fs/promises";
+import { exec } from "child_process";
+import { promisify } from "util";
+import { parseMetaFile } from "./parser.js";
+import { toEnvKey, envKeyToConfigKey } from "../../config/env-key.js";
+import { COMMANDS_CONFIG_REGISTRATION } from "./commands-config-registration.js";
+const execAsync = promisify(exec);
+const logger = createLogger("commands");
+// 默认配置
+const DEFAULT_USER_DIR = ".roy-agent/commands";
+const DEFAULT_PROJECT_DIR = ".roy/commands";
+const DEFAULT_CACHE_DIR = ".cache/roy-agent/commands";
+const DESCRIPTIONS_FILE = "descriptions.json";
+// 配置键名列表
+const CONFIG_KEYS = [
+    "command.userCommandsDir",
+    "command.projectCommandsDir",
+    "command.cacheDir",
+];
+export class CommandsComponent extends BaseComponent {
+    name = "commands";
+    version = "2.0.0";
+    config;
+    configComponent;
+    userCommandsDir = "";
+    projectCommandsDir = "";
+    descriptionCache = new Map();
+    descriptionCacheFile = "";
+    constructor() {
+        super();
+        this.initDefaultDirs();
+    }
+    initDefaultDirs() {
+        const homeDir = os.homedir();
+        this.userCommandsDir = path.join(homeDir, DEFAULT_USER_DIR);
+        this.projectCommandsDir = DEFAULT_PROJECT_DIR;
+        this.descriptionCacheFile = path.join(homeDir, DEFAULT_CACHE_DIR, DESCRIPTIONS_FILE);
+    }
+    // ========================================================================
+    // Component Lifecycle
+    // ========================================================================
+    /**
+     * 初始化组件
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. File - 配置文件
+     * 2. Env - 环境变量
+     * 3. Object - 直接传入的 config 对象
+     */
+    async init(config) {
+        await super.init(config);
+        const options = config?.options;
+        if (!options?.configComponent) {
+            throw new Error("ConfigComponent is required for CommandsComponent initialization");
+        }
+        this.configComponent = options.configComponent;
+        await this.registerConfig(options);
+        // 确保 user 目录存在
+        await fs.mkdir(this.userCommandsDir, { recursive: true });
+        // 加载描述缓存
+        await this.loadDescriptionCache();
+        logger.info(`CommandsComponent initialized: user=${this.userCommandsDir}, project=${this.projectCommandsDir}`);
+    }
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 使用 SessionComponent 的正确模式：
+     * 1. 使用 registerComponent() 注册配置（包含 sources、keys、defaults）
+     * 2. 使用 load("command") 加载配置值
+     * 3. 处理环境变量后备方案
+     * 4. 处理 config 对象（最高优先级）
+     */
+    async registerConfig(options) {
+        const configComponent = this.configComponent;
+        if (!configComponent)
+            return;
+        const { configPath, envPrefix, config } = options;
+        // 1. 注册 COMMANDS_CONFIG_REGISTRATION（包含 defaults、sources、keys）
+        configComponent.registerComponent(COMMANDS_CONFIG_REGISTRATION);
+        // 2. 如果提供了 configPath，添加额外的 file source
+        if (configPath) {
+            configComponent.registerSource({
+                type: "file",
+                relativePath: configPath,
+                optional: true,
+                watch: false,
+            });
+        }
+        // 3. 使用 load 加载配置（会使用 defaults 填充，然后被环境变量覆盖）
+        await configComponent.load("command");
+        // 4. 环境变量后备方案（确保环境变量能够覆盖配置）
+        const prefix = envPrefix !== undefined ? envPrefix : "COMMAND";
+        for (const key of CONFIG_KEYS) {
+            const envKey = toEnvKey(key, prefix);
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 5. 自动发现其他相关环境变量
+        const loadedKeys = new Set(CONFIG_KEYS);
+        for (const envKey of Object.keys(process.env)) {
+            const configKey = envKeyToConfigKey(envKey, prefix, "command");
+            if (!configKey)
+                continue;
+            if (loadedKeys.has(configKey))
+                continue;
+            loadedKeys.add(configKey);
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                await configComponent.set(configKey, value);
+            }
+        }
+        // 6. 直接配置对象（最高优先级）
+        if (config) {
+            const flatConfig = this.flattenConfig(config);
+            for (const [key, value] of Object.entries(flatConfig)) {
+                if (value !== undefined) {
+                    await configComponent.set(key, value);
+                }
+            }
+        }
+        // 7. 设置默认值（只有当配置不存在时）
+        // 注意：commands 使用基于 HOME 的绝对路径作为默认值
+        const homeDir = os.homedir();
+        const defaultDirs = {
+            "command.userCommandsDir": path.join(homeDir, DEFAULT_USER_DIR),
+            "command.projectCommandsDir": DEFAULT_PROJECT_DIR,
+            "command.cacheDir": path.join(homeDir, DEFAULT_CACHE_DIR),
+        };
+        for (const [key, value] of Object.entries(defaultDirs)) {
+            if (configComponent.get(key) === undefined) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 应用最终配置
+        this.applyConfig(configComponent);
+    }
+    /**
+     * 将嵌套配置扁平化
+     */
+    flattenConfig(config) {
+        const result = {};
+        if (config.userCommandsDir !== undefined) {
+            result["command.userCommandsDir"] = config.userCommandsDir;
+        }
+        if (config.projectCommandsDir !== undefined) {
+            result["command.projectCommandsDir"] = config.projectCommandsDir;
+        }
+        if (config.cacheDir !== undefined) {
+            result["command.cacheDir"] = config.cacheDir;
+        }
+        return result;
+    }
+    /**
+     * 从 ConfigComponent 应用配置
+     */
+    applyConfig(configComponent) {
+        const userDir = configComponent.get("command.userCommandsDir");
+        const projectDir = configComponent.get("command.projectCommandsDir");
+        const cacheDir = configComponent.get("command.cacheDir");
+        this.userCommandsDir = userDir || path.join(os.homedir(), DEFAULT_USER_DIR);
+        this.projectCommandsDir = projectDir || DEFAULT_PROJECT_DIR;
+        this.descriptionCacheFile = path.join(cacheDir || path.join(os.homedir(), DEFAULT_CACHE_DIR), DESCRIPTIONS_FILE);
+        this.config = {
+            userCommandsDir: this.userCommandsDir,
+            projectCommandsDir: this.projectCommandsDir,
+            cacheDir: cacheDir,
+        };
+    }
+    async start() {
+        await super.start();
+        logger.debug("CommandsComponent started");
+    }
+    async stop() {
+        await this.saveDescriptionCache();
+        await super.stop();
+        logger.debug("CommandsComponent stopped");
+    }
+    /**
+     * 获取命令目录列表
+     */
+    async getCommandDirs() {
+        return {
+            user: this.userCommandsDir,
+            project: this.projectCommandsDir,
+        };
+    }
+    /**
+     * 发现命令
+     */
+    async discover(options) {
+        const commands = [];
+        let userCount = 0;
+        let projectCount = 0;
+        // 先扫描 project 目录（优先）
+        try {
+            const projectCommands = await this.scanDir(this.projectCommandsDir, "project", options?.pattern);
+            commands.push(...projectCommands);
+            projectCount = projectCommands.length;
+        }
+        catch (error) {
+            logger.debug(`Failed to scan project dir: ${error}`);
+        }
+        // 再扫描 user 目录（去重）
+        try {
+            const userCommands = await this.scanDir(this.userCommandsDir, "user", options?.pattern);
+            for (const cmd of userCommands) {
+                const exists = commands.find((c) => c.name === cmd.name);
+                if (!exists) {
+                    commands.push(cmd);
+                    userCount++;
+                }
+            }
+        }
+        catch (error) {
+            logger.debug(`Failed to scan user dir: ${error}`);
+        }
+        commands.sort((a, b) => a.name.localeCompare(b.name));
+        return {
+            commands,
+            stats: { userCount, projectCount },
+        };
+    }
+    /**
+     * 添加命令
+     */
+    async add(options) {
+        const { name, target, source = "user", description, tips } = options;
+        const dir = source === "user" ? this.userCommandsDir : this.projectCommandsDir;
+        const targetPath = path.resolve(target);
+        await fs.mkdir(dir, { recursive: true });
+        const commandPath = path.join(dir, name);
+        try {
+            await fs.access(commandPath);
+            throw new Error(`Command '${name}' already exists`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        // 创建符号链接
+        await fs.symlink(targetPath, commandPath);
+        logger.info(`Added command '${name}' -> ${targetPath} (${source})`);
+        // 创建 meta.md（用于 Prompt 注入）
+        const commandDir = path.join(dir, name);
+        await this.createCommandMeta(commandDir, {
+            name,
+            target: targetPath,
+            description: description || `Command: ${name}`,
+            tips,
+            source,
+        });
+    }
+    /**
+     * 创建命令的 meta.md 文件
+     */
+    async createCommandMeta(commandDir, options) {
+        // 确保命令目录存在（符号链接本身不能作为目录）
+        // meta.md 存在命令的父目录中
+        const parentDir = path.dirname(commandDir);
+        const metaPath = path.join(parentDir, `${options.name}.meta.md`);
+        const tipsContent = options.tips
+            ? `\ntips: "${options.tips}"`
+            : "";
+        const content = `---
+name: ${options.name}
+description: ${options.description}${tipsContent}
+source: ${options.source}
+---
+
+# ${options.name} Command
+
+## Target
+\`${options.target}\`
+
+## 功能
+${options.description}
+
+## 探索提示
+Run \`${options.name} --help\` to explore full capabilities.
+`;
+        await fs.writeFile(metaPath, content, "utf-8");
+        logger.info(`[CommandsComponent] Created meta.md for '${options.name}'`);
+    }
+    /**
+     * 获取所有收藏命令的元信息（用于 Prompt 注入）
+     */
+    async getCommandsMeta() {
+        const metaList = [];
+        // 扫描 user 目录
+        try {
+            const entries = await fs.readdir(this.userCommandsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile() && entry.name.endsWith(".meta.md")) {
+                    const metaPath = path.join(this.userCommandsDir, entry.name);
+                    const meta = await parseMetaFile(metaPath, "user");
+                    if (meta) {
+                        metaList.push(meta);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // 目录不存在时忽略
+            if (error.code !== "ENOENT") {
+                logger.debug(`Failed to scan user commands dir: ${error}`);
+            }
+        }
+        // 扫描 project 目录
+        try {
+            const entries = await fs.readdir(this.projectCommandsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile() && entry.name.endsWith(".meta.md")) {
+                    const metaPath = path.join(this.projectCommandsDir, entry.name);
+                    const meta = await parseMetaFile(metaPath, "project");
+                    if (meta) {
+                        metaList.push(meta);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // 目录不存在时忽略
+            if (error.code !== "ENOENT") {
+                logger.debug(`Failed to scan project commands dir: ${error}`);
+            }
+        }
+        return metaList;
+    }
+    /**
+     * 移除命令
+     */
+    async remove(options) {
+        const { name, source } = options;
+        const dirsToCheck = source
+            ? [source === "user" ? this.userCommandsDir : this.projectCommandsDir]
+            : [this.userCommandsDir, this.projectCommandsDir];
+        for (const dir of dirsToCheck) {
+            const commandPath = path.join(dir, name);
+            try {
+                await fs.unlink(commandPath);
+                logger.info(`Removed command '${name}' from ${dir}`);
+                return;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+        }
+        throw new Error(`Command '${name}' not found`);
+    }
+    /**
+     * 获取命令信息
+     */
+    async getInfo(name) {
+        const dirsToCheck = [this.projectCommandsDir, this.userCommandsDir];
+        for (const dir of dirsToCheck) {
+            const commandPath = path.join(dir, name);
+            try {
+                const stat = await fs.lstat(commandPath);
+                const realPath = stat.isSymbolicLink() ? await fs.readlink(commandPath) : commandPath;
+                const cmdSource = dir === this.projectCommandsDir ? "project" : "user";
+                const shortDescription = await this.getDescription(realPath);
+                return {
+                    name,
+                    path: realPath,
+                    source: cmdSource,
+                    shortDescription,
+                };
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * 执行命令
+     */
+    async exec(options) {
+        const { name, args = [], cwd } = options;
+        const info = await this.getInfo(name);
+        if (!info) {
+            return {
+                stdout: "",
+                stderr: `Command '${name}' not found`,
+                exitCode: 127,
+                success: false,
+            };
+        }
+        const cmd = `${info.path} ${args.join(" ")}`;
+        try {
+            const { stdout, stderr } = await execAsync(cmd, {
+                cwd: cwd || process.cwd(),
+                timeout: 30000,
+            });
+            return {
+                stdout,
+                stderr,
+                exitCode: 0,
+                success: true,
+            };
+        }
+        catch (error) {
+            return {
+                stdout: error.stdout || "",
+                stderr: error.stderr || error.message,
+                exitCode: error.code || 1,
+                success: false,
+            };
+        }
+    }
+    // ========================================================================
+    // Private Methods
+    // ========================================================================
+    async scanDir(dir, source, pattern) {
+        const commands = [];
+        try {
+            const entries = await fs.readdir(dir);
+            for (const entry of entries) {
+                if (entry.startsWith("."))
+                    continue;
+                if (pattern && !this.matchPattern(entry, pattern))
+                    continue;
+                const fullPath = path.join(dir, entry);
+                try {
+                    const stat = await fs.lstat(fullPath);
+                    if (!stat.isSymbolicLink() && !stat.isFile())
+                        continue;
+                    if (stat.isFile()) {
+                        try {
+                            await fs.access(fullPath, fs.constants.X_OK);
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                    const realPath = stat.isSymbolicLink() ? await fs.readlink(fullPath) : fullPath;
+                    const shortDescription = await this.getDescription(realPath);
+                    commands.push({
+                        name: entry,
+                        path: realPath,
+                        source,
+                        shortDescription,
+                    });
+                }
+                catch (error) {
+                    logger.debug(`Failed to stat ${fullPath}: ${error}`);
+                }
+            }
+        }
+        catch (error) {
+            logger.debug(`Failed to scan dir ${dir}: ${error}`);
+        }
+        return commands;
+    }
+    matchPattern(name, pattern) {
+        const regex = new RegExp("^" + pattern.replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
+        return regex.test(name);
+    }
+    async getDescription(commandPath) {
+        const cached = this.descriptionCache.get(commandPath);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const { stdout } = await execAsync(`${commandPath} --help 2>/dev/null | head -1`, {
+                timeout: 2000,
+            });
+            const description = stdout.trim().split("\n")[0] || "";
+            this.descriptionCache.set(commandPath, description);
+            return description;
+        }
+        catch {
+            return "";
+        }
+    }
+    async loadDescriptionCache() {
+        try {
+            const content = await fs.readFile(this.descriptionCacheFile, "utf-8");
+            const data = JSON.parse(content);
+            this.descriptionCache = new Map(Object.entries(data));
+        }
+        catch {
+            // 缓存文件不存在，忽略
+        }
+    }
+    async saveDescriptionCache() {
+        try {
+            await fs.mkdir(path.dirname(this.descriptionCacheFile), { recursive: true });
+            const data = Object.fromEntries(this.descriptionCache);
+            await fs.writeFile(this.descriptionCacheFile, JSON.stringify(data, null, 2));
+        }
+        catch (error) {
+            logger.debug(`Failed to save description cache: ${error}`);
+        }
+    }
+}
+//# sourceMappingURL=commands-component.js.map

package/dist/core/src/env/commands/commands-component.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=commands-component.test.d.ts.map