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

package/dist/core/src/config/file-source.test.js

@@ -0,0 +1,275 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { promises as fs } from "fs";
+import path from "path";
+import { FileSource } from "./file-source.js";
+describe("FileSource", () => {
+    const testDir = path.join(__dirname, ".test-file-source");
+    const testFile = path.join(testDir, "config.json");
+    beforeEach(async () => {
+        // 创建测试目录
+        await fs.mkdir(testDir, { recursive: true });
+    });
+    afterEach(async () => {
+        // 清理测试目录
+        try {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    test("read returns undefined for non-existent key", async () => {
+        const source = new FileSource(testFile);
+        const value = source.read("nonExistent");
+        expect(value).toBeUndefined();
+    });
+    test("read loads value from JSON file", async () => {
+        // 初始化文件
+        await fs.writeFile(testFile, JSON.stringify({ name: "roy", age: 30 }), "utf-8");
+        const source = new FileSource(testFile);
+        expect(source.read("name")).toBe("roy");
+        expect(source.read("age")).toBe(30);
+    });
+    test("read returns nested value using dot notation", async () => {
+        await fs.writeFile(testFile, JSON.stringify({ user: { profile: { name: "alice" } } }), "utf-8");
+        const source = new FileSource(testFile);
+        expect(source.read("user.profile.name")).toBe("alice");
+    });
+    test("write saves value to JSON file", async () => {
+        const source = new FileSource(testFile);
+        const result = source.write("name", "roy");
+        expect(result).toBe(true);
+        // 等待防抖延迟完成
+        await new Promise((r) => setTimeout(r, 150));
+        const content = await fs.readFile(testFile, "utf-8");
+        const data = JSON.parse(content);
+        expect(data.name).toBe("roy");
+    });
+    test("write updates existing value", async () => {
+        await fs.writeFile(testFile, JSON.stringify({ name: "old" }), "utf-8");
+        const source = new FileSource(testFile);
+        source.write("name", "new");
+        // 等待防抖延迟完成
+        await new Promise((r) => setTimeout(r, 150));
+        const content = await fs.readFile(testFile, "utf-8");
+        const data = JSON.parse(content);
+        expect(data.name).toBe("new");
+    });
+    test("write creates nested structure for dot notation keys", async () => {
+        const source = new FileSource(testFile);
+        source.write("user.profile.name", "bob");
+        // 等待防抖延迟完成
+        await new Promise((r) => setTimeout(r, 150));
+        const content = await fs.readFile(testFile, "utf-8");
+        const data = JSON.parse(content);
+        expect(data.user.profile.name).toBe("bob");
+    });
+    test("list returns all key-value pairs", async () => {
+        await fs.writeFile(testFile, JSON.stringify({ name: "roy", age: 30, active: true }), "utf-8");
+        const source = new FileSource(testFile);
+        const entries = source.list();
+        expect(entries).toContainEqual({ key: "name", value: "roy" });
+        expect(entries).toContainEqual({ key: "age", value: 30 });
+        expect(entries).toContainEqual({ key: "active", value: true });
+    });
+    test("list returns flattened nested structure", async () => {
+        await fs.writeFile(testFile, JSON.stringify({ user: { name: "roy", age: 30 } }), "utf-8");
+        const source = new FileSource(testFile);
+        const entries = source.list();
+        expect(entries).toContainEqual({ key: "user.name", value: "roy" });
+        expect(entries).toContainEqual({ key: "user.age", value: 30 });
+    });
+    test("watch monitors file changes", async () => {
+        await fs.writeFile(testFile, JSON.stringify({ name: "roy" }), "utf-8");
+        const source = new FileSource(testFile);
+        const events = [];
+        const unwatch = source.watch((event) => {
+            events.push(event);
+        });
+        // 等待文件系统稳定
+        await new Promise((r) => setTimeout(r, 100));
+        // 修改文件
+        await fs.writeFile(testFile, JSON.stringify({ name: "alice" }), "utf-8");
+        // 等待事件触发
+        await new Promise((r) => setTimeout(r, 200));
+        unwatch();
+        expect(events.length).toBeGreaterThan(0);
+    });
+    test("watch returns unsubscribe function", async () => {
+        const source = new FileSource(testFile);
+        const callback = vi.fn();
+        const unwatch = source.watch(callback);
+        unwatch();
+        await fs.writeFile(testFile, JSON.stringify({ name: "changed" }), "utf-8");
+        await new Promise((r) => setTimeout(r, 200));
+        expect(callback).not.toHaveBeenCalled();
+    });
+    test("has correct name and priority", () => {
+        const source = new FileSource(testFile);
+        expect(source.name).toBe("file");
+        expect(source.priority).toBe(10);
+    });
+    test("delete removes key from file", async () => {
+        await fs.writeFile(testFile, JSON.stringify({ name: "roy", age: 30 }), "utf-8");
+        const source = new FileSource(testFile);
+        const result = source.delete("name");
+        expect(result).toBe(true);
+        // 等待防抖延迟完成
+        await new Promise((r) => setTimeout(r, 150));
+        const content = await fs.readFile(testFile, "utf-8");
+        const data = JSON.parse(content);
+        expect(data.name).toBeUndefined();
+        expect(data.age).toBe(30);
+    });
+    test("delete returns false for non-existent key", async () => {
+        await fs.writeFile(testFile, JSON.stringify({ name: "roy" }), "utf-8");
+        const source = new FileSource(testFile);
+        const result = source.delete("nonExistent");
+        expect(result).toBe(false);
+    });
+    test("should parse JSONC file with single-line comments", async () => {
+        const jsoncFile = path.join(testDir, "config.jsonc");
+        const content = `{
+      // API Configuration
+      "apiKey": "test-key",
+      "model": "gpt-4o"
+    }`;
+        await fs.writeFile(jsoncFile, content, "utf-8");
+        const source = new FileSource(jsoncFile);
+        expect(source.read("apiKey")).toBe("test-key");
+        expect(source.read("model")).toBe("gpt-4o");
+    });
+    test("should parse JSONC file with multi-line comments", async () => {
+        const jsoncFile = path.join(testDir, "config.jsonc");
+        const content = `{
+      /* This is a
+         multi-line comment */
+      "name": "test"
+    }`;
+        await fs.writeFile(jsoncFile, content, "utf-8");
+        const source = new FileSource(jsoncFile);
+        expect(source.read("name")).toBe("test");
+    });
+    test("should substitute env vars in config values", async () => {
+        process.env.TEST_API_KEY = "my-secret-key";
+        const envFile = path.join(testDir, "env-config.json");
+        await fs.writeFile(envFile, JSON.stringify({ apiKey: "${TEST_API_KEY}" }), "utf-8");
+        const source = new FileSource(envFile);
+        expect(source.read("apiKey")).toBe("my-secret-key");
+        delete process.env.TEST_API_KEY;
+    });
+    test("should substitute env vars with defaults", async () => {
+        delete process.env.NONEXISTENT_KEY;
+        const envFile = path.join(testDir, "env-defaults.json");
+        await fs.writeFile(envFile, JSON.stringify({ key: "${NONEXISTENT_KEY:-default-value}" }), "utf-8");
+        const source = new FileSource(envFile);
+        expect(source.read("key")).toBe("default-value");
+    });
+    test("should handle combined JSONC and env vars", async () => {
+        process.env.CFG_HOST = "localhost";
+        process.env.CFG_PORT = "8080";
+        const combinedFile = path.join(testDir, "combined.jsonc");
+        const content = `{
+      // Server configuration
+      "host": "\${CFG_HOST}",  // from env
+      "port": "\${CFG_PORT}",
+      "name": "app"
+    }`;
+        await fs.writeFile(combinedFile, content, "utf-8");
+        const source = new FileSource(combinedFile);
+        expect(source.read("host")).toBe("localhost");
+        expect(source.read("port")).toBe("8080");
+        expect(source.read("name")).toBe("app");
+        delete process.env.CFG_HOST;
+        delete process.env.CFG_PORT;
+    });
+    test("should preserve non-string values during env substitution", async () => {
+        const mixedFile = path.join(testDir, "mixed.json");
+        await fs.writeFile(mixedFile, JSON.stringify({
+            count: "${UNDEFINED_VAR:-42}",
+            enabled: true,
+            rate: 0.95
+        }), "utf-8");
+        const source = new FileSource(mixedFile);
+        expect(source.read("count")).toBe("42"); // env var resolved to string
+        expect(source.read("enabled")).toBe(true);
+        expect(source.read("rate")).toBe(0.95);
+    });
+    test("should resolve protocol references when resolver is provided", async () => {
+        // 创建被引用的文件
+        const authFile = path.join(testDir, "auth.json");
+        await fs.writeFile(authFile, JSON.stringify({
+            api: { key: "secret-key-from-file", url: "https://api.example.com" }
+        }), "utf-8");
+        // 创建主配置文件
+        const mainFile = path.join(testDir, "main.json");
+        await fs.writeFile(mainFile, JSON.stringify({
+            apiKey: "${file://" + authFile + "#api.key}",
+            apiUrl: "${file://" + authFile + "#api.url}"
+        }), "utf-8");
+        // 使用绝对路径的 file:// 协议
+        const { ProtocolResolver } = require("./protocol-resolver");
+        const resolver = new ProtocolResolver();
+        const source = new FileSource(mainFile, resolver);
+        expect(source.read("apiKey")).toBe("secret-key-from-file");
+        expect(source.read("apiUrl")).toBe("https://api.example.com");
+    });
+    test("should resolve file:// protocol references", async () => {
+        // 创建引用文件
+        const refFile = path.join(testDir, "ref.json");
+        await fs.writeFile(refFile, JSON.stringify({
+            token: "file-token-xxx",
+            secret: "file-secret"
+        }), "utf-8");
+        // 创建主配置文件
+        const mainFile = path.join(testDir, "app.json");
+        await fs.writeFile(mainFile, JSON.stringify({
+            token: "${file://ref.json#token}",
+            secret: "${file://ref.json#secret}"
+        }), "utf-8");
+        // 使用 file:// 协议
+        const { ProtocolResolver } = require("./protocol-resolver");
+        const resolver = new ProtocolResolver({
+            xdgDataHome: testDir,
+        });
+        const source = new FileSource(mainFile, resolver);
+        expect(source.read("token")).toBe("file-token-xxx");
+        expect(source.read("secret")).toBe("file-secret");
+    });
+    test("should resolve env:// protocol references", async () => {
+        process.env.PROTOCOL_TEST_VAR = "protocol-env-value";
+        const envFile = path.join(testDir, "env.json");
+        await fs.writeFile(envFile, JSON.stringify({
+            value: "${env://PROTOCOL_TEST_VAR}",
+            other: "static"
+        }), "utf-8");
+        const { ProtocolResolver } = require("./protocol-resolver");
+        const resolver = new ProtocolResolver();
+        const source = new FileSource(envFile, resolver);
+        expect(source.read("value")).toBe("protocol-env-value");
+        expect(source.read("other")).toBe("static");
+        delete process.env.PROTOCOL_TEST_VAR;
+    });
+    test("should handle combined env and protocol references", async () => {
+        process.env.DEFAULT_DB_HOST = "db.example.com";
+        // 创建引用文件
+        const refFile = path.join(testDir, "ref.json");
+        await fs.writeFile(refFile, JSON.stringify({
+            apiKey: "secret-api-key"
+        }), "utf-8");
+        const combinedFile = path.join(testDir, "combined.json");
+        await fs.writeFile(combinedFile, JSON.stringify({
+            host: "${env://DEFAULT_DB_HOST:-localhost}",
+            apiKey: "${file://ref.json#apiKey:-no-key}"
+        }), "utf-8");
+        const { ProtocolResolver } = require("./protocol-resolver");
+        const resolver = new ProtocolResolver({
+            xdgDataHome: testDir,
+        });
+        const source = new FileSource(combinedFile, resolver);
+        expect(source.read("host")).toBe("db.example.com");
+        expect(source.read("apiKey")).toBe("secret-api-key");
+        delete process.env.DEFAULT_DB_HOST;
+    });
+});
+//# sourceMappingURL=file-source.test.js.map

package/dist/core/src/config/index.d.ts

@@ -0,0 +1,5 @@
+export { type ConfigSource, type ConfigSourceType, type ConfigChangeEvent, type ConfigComponentOptions, type SourceRegistration, type KeyRegistration, type ComponentRegistration, ConfigSourceNotFoundError, ConfigFileNotFoundError, ConfigComponent, MemorySource, } from "./config-component";
+export { FileSource, type FileSourceOptions } from "./file-source";
+export { EnvSource, type EnvSourceOptions } from "./env-source";
+export { parseJSONC, parseJSONCWithEnv, parseJSONCWithProtocols, substituteEnvVars, substituteProtocolRefs, } from "./config-parser";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/src/config/index.js

@@ -0,0 +1,5 @@
+export { ConfigSourceNotFoundError, ConfigFileNotFoundError, ConfigComponent, MemorySource, } from "./config-component.js";
+export { FileSource } from "./file-source.js";
+export { EnvSource } from "./env-source.js";
+export { parseJSONC, parseJSONCWithEnv, parseJSONCWithProtocols, substituteEnvVars, substituteProtocolRefs, } from "./config-parser.js";
+//# sourceMappingURL=index.js.map

package/dist/core/src/config/protocol-resolver.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Protocol Resolver
+ *
+ * Resolves configuration references using protocols:
+ * - file:// - Read from files, relative paths based on XDG_DATA_HOME
+ * - env:// - Read from environment variables
+ *
+ * Syntax: ${protocol://path#key}
+ */
+export type ProtocolType = "file" | "env";
+declare const PROTOCOL_PATTERN: RegExp;
+/**
+ * Protocol reference structure
+ */
+export interface ProtocolRef {
+    protocol: ProtocolType;
+    path: string;
+    key: string;
+    defaultValue?: string;
+    raw: string;
+}
+/**
+ * Resolve result
+ */
+export interface ResolveResult {
+    value: unknown;
+    source: ProtocolType;
+}
+/**
+ * ProtocolResolver 配置
+ */
+export interface ProtocolResolverOptions {
+    /** XDG 数据目录，默认 ~/.local/share */
+    xdgDataHome?: string;
+    /** 文件读取函数（用于测试注入） */
+    readFileFn?: (path: string) => string;
+}
+/**
+ * 协议解析器
+ *
+ * 解析配置中的协议引用，支持：
+ * - ${file://path#key} - 从文件读取（相对路径基于 XDG_DATA_HOME）
+ * - ${env://varName} - 从环境变量读取
+ */
+export declare class ProtocolResolver {
+    private _xdgDataHome;
+    private readFileFn;
+    constructor(options?: ProtocolResolverOptions);
+    /**
+     * 获取当前的 XDG_DATA_HOME
+     */
+    get xdgDataHome(): string;
+    /**
+     * 设置 XDG_DATA_HOME（用于运行时更新）
+     */
+    set xdgDataHome(value: string);
+    /**
+     * 获取默认 XDG_DATA_HOME
+     */
+    static getDefaultXDGDataHome(): string;
+    /**
+     * 解析协议引用
+     * 支持默认值语法: ${protocol://path#key:-default}
+     */
+    parse(ref: string): ProtocolRef | null;
+    /**
+     * 检查是否是协议引用
+     */
+    isProtocolRef(value: string): boolean;
+    /**
+     * 解析并获取协议引用的值
+     *
+     * @returns 解析结果，包含值和来源；解析失败时返回 null
+     */
+    resolve(ref: string): ResolveResult | null;
+    /**
+     * 解析文件引用
+     */
+    private resolveFileRef;
+    /**
+     * 解析并获取协议引用的值
+     * 返回 null 表示解析失败（如协议不支持、文件不存在等）
+     */
+    private resolveInternal;
+    /**
+     * 解析路径（处理相对路径）
+     */
+    private resolvePath;
+    /**
+     * 获取嵌套值
+     */
+    private getNestedValue;
+}
+export { PROTOCOL_PATTERN };
+//# sourceMappingURL=protocol-resolver.d.ts.map

package/dist/core/src/config/protocol-resolver.js

@@ -0,0 +1,175 @@
+/**
+ * Protocol Resolver
+ *
+ * Resolves configuration references using protocols:
+ * - file:// - Read from files, relative paths based on XDG_DATA_HOME
+ * - env:// - Read from environment variables
+ *
+ * Syntax: ${protocol://path#key}
+ */
+// Protocol reference pattern: ${protocol://path} or ${protocol://path#key}
+// 支持默认值语法: ${protocol://path#key:-default}
+const PROTOCOL_PATTERN = /^\$\{([^:]+):\/\/([^:#]+)(?:#([^:-]+))?(?::-(.*))?\}$/;
+/**
+ * 协议解析器
+ *
+ * 解析配置中的协议引用，支持：
+ * - ${file://path#key} - 从文件读取（相对路径基于 XDG_DATA_HOME）
+ * - ${env://varName} - 从环境变量读取
+ */
+export class ProtocolResolver {
+    _xdgDataHome;
+    readFileFn;
+    constructor(options = {}) {
+        this._xdgDataHome = options.xdgDataHome ?? ProtocolResolver.getDefaultXDGDataHome();
+        if (options.readFileFn) {
+            this.readFileFn = options.readFileFn;
+        }
+        else {
+            const fsSync = require("fs");
+            this.readFileFn = (path) => fsSync.readFileSync(path, "utf-8");
+        }
+    }
+    /**
+     * 获取当前的 XDG_DATA_HOME
+     */
+    get xdgDataHome() {
+        return this._xdgDataHome;
+    }
+    /**
+     * 设置 XDG_DATA_HOME（用于运行时更新）
+     */
+    set xdgDataHome(value) {
+        this._xdgDataHome = value;
+    }
+    /**
+     * 获取默认 XDG_DATA_HOME
+     */
+    static getDefaultXDGDataHome() {
+        return process.env.XDG_DATA_HOME ?? `${process.env.HOME ?? "~"}/.local/share`;
+    }
+    /**
+     * 解析协议引用
+     * 支持默认值语法: ${protocol://path#key:-default}
+     */
+    parse(ref) {
+        const match = ref.match(PROTOCOL_PATTERN);
+        if (!match)
+            return null;
+        const [, protocol, path, key, defaultValue] = match;
+        if (!["file", "env"].includes(protocol))
+            return null;
+        return {
+            protocol: protocol,
+            path,
+            key: key ?? "",
+            defaultValue,
+            raw: ref,
+        };
+    }
+    /**
+     * 检查是否是协议引用
+     */
+    isProtocolRef(value) {
+        return PROTOCOL_PATTERN.test(value);
+    }
+    /**
+     * 解析并获取协议引用的值
+     *
+     * @returns 解析结果，包含值和来源；解析失败时返回 null
+     */
+    resolve(ref) {
+        const parsed = this.parse(ref);
+        if (!parsed)
+            return null;
+        const value = this.resolveInternal(parsed);
+        // 对于 file 协议，如果值是 undefined/null，表示解析失败
+        if (parsed.protocol === "file" && value === undefined) {
+            return null;
+        }
+        // 对于 env 协议，如果值是 undefined 且没有默认值，返回 null
+        if (value === undefined && parsed.protocol === "env" && parsed.defaultValue === undefined) {
+            return null;
+        }
+        // 如果值是 undefined 但有默认值，返回默认值
+        if (value === undefined && parsed.defaultValue !== undefined) {
+            return {
+                value: parsed.defaultValue,
+                source: parsed.protocol,
+            };
+        }
+        return {
+            value,
+            source: parsed.protocol,
+        };
+    }
+    /**
+     * 解析文件引用
+     */
+    resolveFileRef(filePath, key) {
+        // 解析相对路径
+        const resolvedPath = this.resolvePath(filePath);
+        try {
+            const content = this.readFileFn(resolvedPath);
+            // 尝试解析 JSON
+            let data;
+            try {
+                data = JSON.parse(content);
+            }
+            catch {
+                // 如果不是 JSON，作为纯文本处理
+                return content;
+            }
+            // 获取嵌套值
+            return this.getNestedValue(data, key);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * 解析并获取协议引用的值
+     * 返回 null 表示解析失败（如协议不支持、文件不存在等）
+     */
+    resolveInternal(ref) {
+        switch (ref.protocol) {
+            case "env":
+                return process.env[ref.path];
+            case "file":
+                return this.resolveFileRef(ref.path, ref.key);
+        }
+    }
+    /**
+     * 解析路径（处理相对路径）
+     */
+    resolvePath(filePath) {
+        if (filePath.startsWith("/")) {
+            // 绝对路径
+            return filePath;
+        }
+        if (filePath.startsWith("~")) {
+            // ~ 开头，替换为 HOME
+            return filePath.replace("~", process.env.HOME ?? "");
+        }
+        // 相对路径，基于 XDG_DATA_HOME
+        return `${this._xdgDataHome}/${filePath}`;
+    }
+    /**
+     * 获取嵌套值
+     */
+    getNestedValue(obj, key) {
+        if (key === "$" || key === "")
+            return obj;
+        const keys = key.split(".");
+        let current = obj;
+        for (const k of keys) {
+            if (current === null || current === undefined || typeof current !== "object") {
+                return undefined;
+            }
+            current = current[k];
+        }
+        return current;
+    }
+}
+export { PROTOCOL_PATTERN };
+//# sourceMappingURL=protocol-resolver.js.map

package/dist/core/src/config/protocol-resolver.test.d.ts

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