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

package/dist/core/src/env/commands/parser.test.js

@@ -0,0 +1,155 @@
+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.js";
+describe("parser", () => {
+    let tempDir;
+    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["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);
+        });
+    });
+});
+//# sourceMappingURL=parser.test.js.map

package/dist/core/src/env/commands/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Commands Component Types
+ *
+ * 定义 CommandsComponent 的类型系统（收藏式）
+ */
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * CommandsComponent 配置（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface CommandsComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "COMMAND"） */
+    envPrefix?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<CommandsComponentConfig>;
+}
+/**
+ * CommandsComponent 配置
+ */
+export interface CommandsComponentConfig {
+    /** User 级别命令目录 */
+    userCommandsDir?: string;
+    /** 项目级别命令目录 */
+    projectCommandsDir?: string;
+    /** 描述缓存目录 */
+    cacheDir?: string;
+}
+/**
+ * 命令来源
+ */
+export type CommandSource = 'user' | 'project';
+/**
+ * 命令索引
+ */
+export interface CommandIndex {
+    /** 命令名称（文件名） */
+    name: string;
+    /** 命令路径 */
+    path: string;
+    /** 来源类型 */
+    source: CommandSource;
+    /** 简短描述（从 --help 第一行提取） */
+    shortDescription: string;
+    /** 最后获取描述时间 */
+    lastFetched?: number;
+}
+/**
+ * 来源统计
+ */
+export interface SourceStats {
+    /** User 级别命令数 */
+    userCount: number;
+    /** Project 级别命令数 */
+    projectCount: number;
+}
+/**
+ * 扫描结果
+ */
+export interface ScanResult {
+    /** 命令列表 */
+    commands: CommandIndex[];
+    /** 来源统计 */
+    stats: SourceStats;
+}
+/**
+ * 发现选项
+ */
+export interface DiscoverOptions {
+    /** glob 过滤模式 */
+    pattern?: string;
+    /** 来源过滤 */
+    source?: CommandSource;
+}
+/**
+ * 添加命令选项
+ */
+export interface AddCommandOptions {
+    /** 命令名称 */
+    name: string;
+    /** 目标路径或命令 */
+    target: string;
+    /** 来源类型 */
+    source?: CommandSource;
+    /** 功能描述（用于 Prompt 注入） */
+    description?: string;
+    /** 探索提示（用于 Prompt 注入） */
+    tips?: string;
+}
+/**
+ * 命令元信息（用于 Prompt 注入）
+ */
+export interface CommandMeta {
+    /** 命令名称 */
+    name: string;
+    /** 功能描述 */
+    description: string;
+    /** 探索提示 */
+    tips?: string;
+    /** meta.md 文件路径 */
+    filePath: string;
+    /** 来源类型 */
+    source: CommandSource;
+}
+/**
+ * 移除命令选项
+ */
+export interface RemoveCommandOptions {
+    /** 命令名称 */
+    name: string;
+    /** 来源类型（可选，不指定则尝试两个目录） */
+    source?: CommandSource;
+}
+/**
+ * 执行结果
+ */
+export interface ExecutionResult {
+    /** 标准输出 */
+    stdout: string;
+    /** 标准错误 */
+    stderr: string;
+    /** 退出码 */
+    exitCode: number;
+    /** 是否成功 */
+    success: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/src/env/commands/types.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Commands Component Types
+ *
+ * 定义 CommandsComponent 的类型系统（收藏式）
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

package/dist/core/src/env/commands-prompt-integration.test.js

@@ -0,0 +1,205 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+import { CommandsComponent } from "./commands/commands-component.js";
+import { PromptComponent } from "./prompt/prompt-component.js";
+/**
+ * 创建 Mock ConfigComponent
+ *
+ * 关键：模拟真实的 ConfigComponent 行为：
+ * 1. registerComponent 注册默认值
+ * 2. load() 后 storage 中应该有值
+ * 3. 直接通过 config 设置的值优先级最高
+ */
+function createMockConfigComponent(initialConfig = {}) {
+    const storage = new Map(Object.entries(initialConfig));
+    return {
+        get(key) {
+            // 如果 storage 中没有值，返回 undefined（让 CommandsComponent 设置默认值）
+            // 注意：这里不自动返回默认值，由 CommandsComponent 的 registerConfig 控制
+            return storage.get(key);
+        },
+        set(key, value) {
+            storage.set(key, value);
+        },
+        has(key) {
+            return storage.has(key);
+        },
+        delete(key) {
+            return storage.delete(key);
+        },
+        clear() {
+            storage.clear();
+        },
+        getAll() {
+            return Object.fromEntries(storage);
+        },
+        registerSource: vi.fn(),
+        registerComponent: vi.fn().mockImplementation((registration) => {
+            // 注册 defaults 到 storage
+            if (registration.defaults) {
+                for (const [key, value] of Object.entries(registration.defaults)) {
+                    const fullKey = `${registration.name}.${key}`;
+                    if (!storage.has(fullKey)) {
+                        storage.set(fullKey, value);
+                    }
+                }
+            }
+        }),
+        load: vi.fn().mockResolvedValue(undefined),
+        getSources: vi.fn().mockReturnValue([]),
+        ensureSourcesCreated: vi.fn(),
+    };
+}
+/**
+ * 模拟 registerCommandsPromptHook 的逻辑
+ */
+async function renderDefaultPromptWithCommands(promptComponent, commandsComponent) {
+    // 渲染 default prompt
+    const content = await promptComponent.getPrompt("default");
+    // 获取命令元信息
+    const metaList = await commandsComponent.getCommandsMeta();
+    // 如果有命令，追加命令表格
+    if (metaList.length > 0) {
+        const sortedMeta = [...metaList].sort((a, b) => a.name.localeCompare(b.name));
+        const rows = sortedMeta
+            .map(m => `| \`${m.name}\` | ${m.description} |`)
+            .join("\n");
+        return content + "\n\n" + `## Your Commands Arsenal
+
+You have access to these custom commands:
+
+| Command | Description |
+|---------|-------------|
+${rows}
+
+Progressive Discovery: Run \`<command> --help\` to explore full capabilities.`;
+    }
+    return content;
+}
+describe("Commands Prompt Integration", () => {
+    let tempDir;
+    let configComponent;
+    let commandsComponent;
+    let promptComponent;
+    beforeEach(async () => {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "roy-integration-test-"));
+        // 创建 mock ConfigComponent
+        configComponent = createMockConfigComponent({
+            "command.userCommandsDir": path.join(tempDir, "commands"),
+            "command.projectCommandsDir": path.join(tempDir, "project-commands"),
+        });
+        commandsComponent = new CommandsComponent();
+        await commandsComponent.init({
+            name: "commands",
+            version: "2.0.0",
+            enabled: true,
+            options: { configComponent },
+        });
+        promptComponent = new PromptComponent();
+        await promptComponent.init({
+            name: "prompt",
+            version: "1.0.0",
+            enabled: true,
+            options: { configComponent },
+        });
+    });
+    afterEach(async () => {
+        await fs.rm(tempDir, { recursive: true, force: true });
+    });
+    describe("renderDefaultPromptWithCommands", () => {
+        it("should inject commands into default prompt", async () => {
+            // 添加带 meta.md 的命令
+            await commandsComponent.add({
+                name: "git",
+                target: "/usr/bin/git",
+                description: "Git version control system",
+                tips: "Use 'git --help' to explore",
+            });
+            // 渲染 prompt
+            const prompt = await renderDefaultPromptWithCommands(promptComponent, commandsComponent);
+            expect(prompt).toContain("Your Commands Arsenal");
+            expect(prompt).toContain("| `git` | Git version control system |");
+            expect(prompt).toContain("Run `<command> --help`");
+        });
+        it("should not inject when no commands exist", async () => {
+            const prompt = await renderDefaultPromptWithCommands(promptComponent, commandsComponent);
+            // 应该不包含我们的自定义 commands section
+            expect(prompt).not.toContain("Your Commands Arsenal");
+            // 原始 prompt 中没有 custom commands 表格
+            expect(prompt).not.toContain("| `git` |");
+        });
+        it("should inject multiple commands", async () => {
+            await commandsComponent.add({
+                name: "git",
+                target: "/usr/bin/git",
+                description: "Git version control",
+            });
+            await commandsComponent.add({
+                name: "npm",
+                target: "/usr/bin/npm",
+                description: "Node package manager",
+            });
+            const prompt = await renderDefaultPromptWithCommands(promptComponent, commandsComponent);
+            expect(prompt).toContain("| `git` | Git version control |");
+            expect(prompt).toContain("| `npm` | Node package manager |");
+        });
+        it("should sort commands alphabetically", async () => {
+            await commandsComponent.add({
+                name: "zulu",
+                target: "/usr/bin/zulu",
+                description: "Zulu command",
+            });
+            await commandsComponent.add({
+                name: "alpha",
+                target: "/usr/bin/alpha",
+                description: "Alpha command",
+            });
+            await commandsComponent.add({
+                name: "middle",
+                target: "/usr/bin/middle",
+                description: "Middle command",
+            });
+            const prompt = await renderDefaultPromptWithCommands(promptComponent, commandsComponent);
+            // 验证 alpha 在最前面，zulu 在最后面
+            const alphaIndex = prompt.indexOf("| `alpha`");
+            const middleIndex = prompt.indexOf("| `middle`");
+            const zuluIndex = prompt.indexOf("| `zulu`");
+            expect(alphaIndex).toBeLessThan(middleIndex);
+            expect(middleIndex).toBeLessThan(zuluIndex);
+        });
+    });
+    describe("CommandsComponent.getCommandsMeta", () => {
+        it("should return empty array when no commands exist", async () => {
+            const metaList = await commandsComponent.getCommandsMeta();
+            expect(metaList).toEqual([]);
+        });
+        it("should return command metadata", async () => {
+            await commandsComponent.add({
+                name: "test-cmd",
+                target: "/usr/bin/echo",
+                description: "Test command description",
+                tips: "Try with --help",
+            });
+            const metaList = await commandsComponent.getCommandsMeta();
+            expect(metaList).toHaveLength(1);
+            expect(metaList[0].name).toBe("test-cmd");
+            expect(metaList[0].description).toBe("Test command description");
+            expect(metaList[0].tips).toBe("Try with --help");
+            expect(metaList[0].source).toBe("user");
+        });
+        it("should handle command without description", async () => {
+            await commandsComponent.add({
+                name: "simple-cmd",
+                target: "/usr/bin/true",
+                // 不提供 description
+            });
+            const metaList = await commandsComponent.getCommandsMeta();
+            expect(metaList).toHaveLength(1);
+            expect(metaList[0].name).toBe("simple-cmd");
+            expect(metaList[0].description).toBe("Command: simple-cmd"); // 默认值
+        });
+    });
+});
+//# sourceMappingURL=commands-prompt-integration.test.js.map

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

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

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

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "bun:test";
+import { BaseComponent } from "./component.js";
+/**
+ * 测试用 Component
+ */
+class TestComponent extends BaseComponent {
+    name = "test-component";
+    version = "1.0.0";
+    initialized = false;
+    getInitialized() {
+        return this.initialized;
+    }
+    async onInit() {
+        this.initialized = true;
+    }
+}
+/**
+ * Mock Environment（实现 Environment 接口的最小实现）
+ */
+const createMockEnv = () => ({
+    name: "mock-env",
+    version: "1.0.0",
+    getConfig: () => ({ name: "mock-env", version: "1.0.0", enabled: true, env: null }),
+    registerComponent: () => { },
+    unregisterComponent: () => { },
+    getComponent: () => undefined,
+    listComponents: () => [],
+    handle_query: async () => "",
+    handle_action: async () => ({ success: true, output: "" }),
+    subscribe: () => () => { },
+    subscribeTo: () => () => { },
+    subscribeAll: () => () => { },
+    pushEnvEvent: () => { },
+});
+describe("Component env injection", () => {
+    describe("init() env validation", () => {
+        it("should init successfully without env (env is optional)", async () => {
+            const component = new TestComponent();
+            // env 是可选的，支持组件独立测试场景
+            await component.init({
+                name: "test",
+                version: "1.0.0",
+                enabled: true,
+            });
+            expect(component.getStatus()).toBe("running");
+            expect(component.getInitialized()).toBe(true);
+        });
+    });
+    describe("init() env injection", () => {
+        it("should inject env on successful init", async () => {
+            const env = createMockEnv();
+            const component = new TestComponent();
+            await component.init({
+                name: "test",
+                version: "1.0.0",
+                enabled: true,
+                env,
+            });
+            // 验证状态变为 running
+            expect(component.getStatus()).toBe("running");
+            // 验证 env 被正确注入（通过 as any 访问 protected 属性）
+            expect(component.env).toBe(env);
+        });
+        it("should call onInit after env is set", async () => {
+            const env = createMockEnv();
+            const component = new TestComponent();
+            await component.init({
+                name: "test",
+                version: "1.0.0",
+                enabled: true,
+                env,
+            });
+            expect(component.getInitialized()).toBe(true);
+        });
+        it("should store env in protected property", async () => {
+            const env = createMockEnv();
+            const component = new TestComponent();
+            await component.init({
+                name: "test",
+                version: "1.0.0",
+                enabled: true,
+                env,
+            });
+            // 通过 getEnv() 方法访问
+            expect(component.getEnv()).toBe(env);
+        });
+        it("should allow getting component from env", async () => {
+            const mockEnv = createMockEnv();
+            const component = new TestComponent();
+            await component.init({
+                name: "test",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+            });
+            // 验证可以通过 getEnv().getComponent() 获取其他组件
+            expect(component.getEnv().getComponent("non-existent")).toBeUndefined();
+        });
+    });
+});
+//# sourceMappingURL=component-env.test.js.map