@ai-setting/roy-agent-core 1.0.0

package/src/env/log-trace/log-trace-config-registration.test.ts

@@ -0,0 +1,348 @@
+/**
+ * @fileoverview LogTrace Component 配置注册测试
+ * 
+ * TDD: 先写测试，验证配置注册机制
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { ConfigComponent } from "../../config/config-component";
+import { LogTraceComponent } from "./log-trace-component";
+import { LOG_TRACE_CONFIG_REGISTRATION, LOG_TRACE_DEFAULTS } from "./log-trace-config-registration";
+
+describe("LogTrace Config Registration (TDD)", () => {
+  let configComponent: ConfigComponent;
+  let component: LogTraceComponent;
+
+  beforeEach(() => {
+    configComponent = new ConfigComponent();
+    component = new LogTraceComponent();
+  });
+
+  // ========================================================================
+  // 核心验收标准：registerConfig 必须遵循 SessionComponent 模式
+  // ========================================================================
+
+  describe("【验收标准】默认值注册", () => {
+    it("应该注册 log-trace.logging.enabled 的默认值为 true", async () => {
+      await component.init({
+        options: { configComponent },
+      });
+
+      const enabled = configComponent.get("log-trace.logging.enabled");
+      expect(enabled).toBe(true);
+    });
+
+    it("应该注册 log-trace.logging.level 的默认值为 info", async () => {
+      await component.init({
+        options: { configComponent },
+      });
+
+      const level = configComponent.get("log-trace.logging.level");
+      expect(level).toBe("info");
+    });
+
+    it("应该注册 log-trace.logging.quiet 的默认值为 false", async () => {
+      await component.init({
+        options: { configComponent },
+      });
+
+      const quiet = configComponent.get("log-trace.logging.quiet");
+      expect(quiet).toBe(false);
+    });
+
+    it("应该注册 log-trace.tracing.enabled 的默认值为 true", async () => {
+      await component.init({
+        options: { configComponent },
+      });
+
+      const enabled = configComponent.get("log-trace.tracing.enabled");
+      expect(enabled).toBe(true);
+    });
+
+    it("应该注册 log-trace.logging.dir 的默认值", async () => {
+      await component.init({
+        options: { configComponent },
+      });
+
+      const logDir = configComponent.get("log-trace.logging.dir");
+      expect(logDir).toBeDefined();
+      expect(typeof logDir).toBe("string");
+    });
+
+    it("应该注册 log-trace.logging.maxOutput 的默认值为 0", async () => {
+      await component.init({
+        options: { configComponent },
+      });
+
+      const maxOutput = configComponent.get("log-trace.logging.maxOutput");
+      expect(maxOutput).toBe(0);
+    });
+  });
+
+  describe("【验收标准】配置优先级 - config 对象覆盖默认值", () => {
+    it("应该允许 config 对象覆盖 logging.level", async () => {
+      await component.init({
+        options: {
+          configComponent,
+          config: {
+            logging: {
+              level: "debug",
+            },
+          },
+        },
+      });
+
+      const level = configComponent.get("log-trace.logging.level");
+      expect(level).toBe("debug");
+    });
+
+    it("应该允许 config 对象覆盖 logging.enabled", async () => {
+      await component.init({
+        options: {
+          configComponent,
+          config: {
+            logging: {
+              enabled: false,
+            },
+          },
+        },
+      });
+
+      const enabled = configComponent.get("log-trace.logging.enabled");
+      expect(enabled).toBe(false);
+    });
+
+    it("应该允许 config 对象覆盖 tracing.enabled", async () => {
+      await component.init({
+        options: {
+          configComponent,
+          config: {
+            tracing: {
+              enabled: false,
+            },
+          },
+        },
+      });
+
+      const enabled = configComponent.get("log-trace.tracing.enabled");
+      expect(enabled).toBe(false);
+    });
+  });
+
+  describe("【验收标准】环境变量覆盖", () => {
+    it("应该通过环境变量覆盖 logging.level", async () => {
+      // 设置环境变量：LOG_TRACE_LOGGING_LEVEL -> log-trace.logging.level
+      const originalValue = process.env.LOG_TRACE_LOGGING_LEVEL;
+      process.env.LOG_TRACE_LOGGING_LEVEL = "debug";
+
+      try {
+        await component.init({
+          options: { configComponent },
+        });
+
+        const level = configComponent.get("log-trace.logging.level");
+        expect(level).toBe("debug");
+      } finally {
+        if (originalValue !== undefined) {
+          process.env.LOG_TRACE_LOGGING_LEVEL = originalValue;
+        } else {
+          delete process.env.LOG_TRACE_LOGGING_LEVEL;
+        }
+      }
+    });
+
+    // 注意：环境变量总是字符串，ConfigComponent.get 返回的也是字符串
+    // 如果需要布尔值，应该在应用层进行类型转换
+    it("应该通过环境变量覆盖 logging.enabled (字符串形式)", async () => {
+      const originalValue = process.env.LOG_TRACE_LOGGING_ENABLED;
+      process.env.LOG_TRACE_LOGGING_ENABLED = "false";
+
+      try {
+        await component.init({
+          options: { configComponent },
+        });
+
+        const enabled = configComponent.get("log-trace.logging.enabled");
+        expect(enabled).toBe("false");
+      } finally {
+        if (originalValue !== undefined) {
+          process.env.LOG_TRACE_LOGGING_ENABLED = originalValue;
+        } else {
+          delete process.env.LOG_TRACE_LOGGING_ENABLED;
+        }
+      }
+    });
+
+    it("应该通过环境变量覆盖 tracing.enabled (字符串形式)", async () => {
+      const originalValue = process.env.LOG_TRACE_TRACING_ENABLED;
+      process.env.LOG_TRACE_TRACING_ENABLED = "false";
+
+      try {
+        await component.init({
+          options: { configComponent },
+        });
+
+        const enabled = configComponent.get("log-trace.tracing.enabled");
+        expect(enabled).toBe("false");
+      } finally {
+        if (originalValue !== undefined) {
+          process.env.LOG_TRACE_TRACING_ENABLED = originalValue;
+        } else {
+          delete process.env.LOG_TRACE_TRACING_ENABLED;
+        }
+      }
+    });
+  });
+
+  describe("【验收标准】LOG_TRACE_CONFIG_REGISTRATION 使用", () => {
+    it("应该导出正确的 registration 对象", () => {
+      expect(LOG_TRACE_CONFIG_REGISTRATION.name).toBe("log-trace");
+    });
+
+    it("应该包含所有必需的 keys", () => {
+      const expectedKeys = [
+        "log-trace.logging.enabled",
+        "log-trace.logging.level",
+        "log-trace.logging.quiet",
+        "log-trace.tracing.enabled",
+      ];
+
+      for (const key of expectedKeys) {
+        const found = LOG_TRACE_CONFIG_REGISTRATION.keys.some((k) => k.key === key);
+        expect(found).toBe(true);
+      }
+    });
+
+    it("应该导出默认值常量（完整格式）", () => {
+      expect(LOG_TRACE_DEFAULTS).toBeDefined();
+      expect(LOG_TRACE_DEFAULTS["log-trace.logging.enabled"]).toBe(true);
+      expect(LOG_TRACE_DEFAULTS["log-trace.logging.level"]).toBe("info");
+      expect(LOG_TRACE_DEFAULTS["log-trace.tracing.enabled"]).toBe(true);
+    });
+  });
+});
+
+// Legacy tests preserved for reference
+describe("LogTrace Config Registration (Legacy)", () => {
+  let configComponent: ConfigComponent;
+  let component: LogTraceComponent;
+
+  beforeEach(() => {
+    configComponent = new ConfigComponent();
+    component = new LogTraceComponent();
+  });
+
+  describe("LOG_TRACE_CONFIG_REGISTRATION", () => {
+    it("应该包含正确的 name", () => {
+      expect(LOG_TRACE_CONFIG_REGISTRATION.name).toBe("log-trace");
+    });
+
+    it("应该包含 env source 配置", () => {
+      const envSource = LOG_TRACE_CONFIG_REGISTRATION.sources.find(
+        (s) => s.type === "env"
+      );
+      expect(envSource).toBeDefined();
+      expect(envSource?.envPrefix).toBe("LOG_TRACE");
+      expect(envSource?.priority).toBe(20);
+    });
+
+    it("应该包含所有配置 keys", () => {
+      const keys = LOG_TRACE_CONFIG_REGISTRATION.keys;
+      expect(keys).toContainEqual(
+        expect.objectContaining({ key: "log-trace.logging.enabled" })
+      );
+      expect(keys).toContainEqual(
+        expect.objectContaining({ key: "log-trace.logging.level" })
+      );
+      expect(keys).toContainEqual(
+        expect.objectContaining({ key: "log-trace.tracing.enabled" })
+      );
+    });
+  });
+
+  describe("LOG_TRACE_DEFAULTS", () => {
+    it("应该包含 logging.enabled 默认值（完整格式）", () => {
+      expect(LOG_TRACE_DEFAULTS["log-trace.logging.enabled"]).toBe(true);
+    });
+
+    it("应该包含 logging.level 默认值（完整格式）", () => {
+      expect(LOG_TRACE_DEFAULTS["log-trace.logging.level"]).toBe("info");
+    });
+
+    it("应该包含 tracing.enabled 默认值（完整格式）", () => {
+      expect(LOG_TRACE_DEFAULTS["log-trace.tracing.enabled"]).toBe(true);
+    });
+  });
+
+  describe("配置注册到 ConfigComponent", () => {
+    it("应该能够注册 LOG_TRACE_CONFIG_REGISTRATION", () => {
+      configComponent.registerComponent(LOG_TRACE_CONFIG_REGISTRATION);
+      expect(() => configComponent.registerComponent(LOG_TRACE_CONFIG_REGISTRATION)).not.toThrow();
+    });
+  });
+
+  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("log-trace");
+      expect(component.version).toBe("1.0.0");
+    });
+
+    it("应该能够通过 config 对象传入配置", async () => {
+      await component.init({
+        options: {
+          configComponent,
+          config: {
+            logging: {
+              enabled: false,
+              level: "debug",
+            },
+            tracing: {
+              enabled: true,
+            },
+          },
+        },
+      } as any);
+      
+      expect(component.name).toBe("log-trace");
+    });
+  });
+
+  describe("环境变量覆盖", () => {
+    it("应该能够通过环境变量覆盖配置", async () => {
+      // 设置环境变量
+      const originalValue = process.env.LOG_TRACE_LOGGING_LEVEL;
+      process.env.LOG_TRACE_LOGGING_LEVEL = "debug";
+      
+      try {
+        await component.init({
+          options: {
+            configComponent,
+          },
+        } as any);
+        
+        expect(component.name).toBe("log-trace");
+      } finally {
+        // 恢复环境变量
+        if (originalValue !== undefined) {
+          process.env.LOG_TRACE_LOGGING_LEVEL = originalValue;
+        } else {
+          delete process.env.LOG_TRACE_LOGGING_LEVEL;
+        }
+      }
+    });
+  });
+});

package/src/env/log-trace/log-trace-config-registration.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview LogTrace Component 配置注册
+ * 
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+
+import type { ComponentRegistration } from "../../config/config-component";
+
+/**
+ * LogTrace Component 默认配置值
+ * 
+ * 注意：键使用完整格式（带 "log-trace." 前缀），在 registerConfig 中手动设置
+ * 注意：动态默认值（logging.dir, logging.file, logging.maxOutput）在 registerConfig 中单独处理
+ */
+export const LOG_TRACE_DEFAULTS: Record<string, unknown> = {
+  "log-trace.logging.enabled": true,
+  "log-trace.logging.level": "info",
+  "log-trace.logging.quiet": false,
+  "log-trace.tracing.enabled": true,
+};
+
+/**
+ * LogTrace Component 配置注册常量
+ * 
+ * 定义了所有 LogTrace 相关的配置项和来源
+ */
+export const LOG_TRACE_CONFIG_REGISTRATION: ComponentRegistration = {
+  name: "log-trace",
+  
+  sources: [
+    { type: "env", envPrefix: "LOG_TRACE", priority: 20, watch: false },
+  ],
+  
+  keys: [
+    { key: "log-trace.logging.enabled", sources: ["env", "file"] },
+    { key: "log-trace.logging.level", sources: ["env", "file"] },
+    { key: "log-trace.logging.quiet", sources: ["env", "file"] },
+    { key: "log-trace.logging.dir", sources: ["env", "file"] },
+    { key: "log-trace.logging.file", sources: ["env", "file"] },
+    { key: "log-trace.logging.maxOutput", sources: ["env", "file"] },
+    { key: "log-trace.tracing.enabled", sources: ["env", "file"] },
+    { key: "log-trace.tracing.dbPath", sources: ["env", "file"] },
+  ],
+  // 注意：不使用 defaults 字段，默认值在 registerConfig 中手动 set
+};

package/src/env/log-trace/logger.test.ts

@@ -0,0 +1,149 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import {
+  createLogger,
+  getLogDir,
+  getLogLevel,
+  getCategoryLogLevel,
+  setQuietMode,
+  isQuietMode,
+  setConfigComponent,
+  type LogLevel,
+} from "./logger";
+import * as fs from "fs";
+import * as path from "path";
+
+describe("Logger", () => {
+  beforeEach(() => {
+    // 创建临时日志目录用于测试
+  });
+
+  afterEach(() => {
+    // 清理
+  });
+
+  describe("createLogger", () => {
+    test("should create logger with default config", () => {
+      const logger = createLogger("test");
+      expect(logger).toBeDefined();
+      expect(typeof logger.debug).toBe("function");
+      expect(typeof logger.info).toBe("function");
+      expect(typeof logger.warn).toBe("function");
+      expect(typeof logger.error).toBe("function");
+    });
+
+    test("should create logger with custom prefix", () => {
+      const logger = createLogger("custom-prefix");
+      expect(logger).toBeDefined();
+    });
+
+    test("should create multiple loggers with same name (caching)", () => {
+      const logger1 = createLogger("shared");
+      const logger2 = createLogger("shared");
+      expect(logger1).toBe(logger2); // 同一个实例
+    });
+  });
+
+  describe("log levels", () => {
+    test("should log debug messages", () => {
+      const logger = createLogger("debug-test");
+      // 不应该抛出错误
+      expect(() => logger.debug("test message")).not.toThrow();
+    });
+
+    test("should log info messages", () => {
+      const logger = createLogger("info-test");
+      expect(() => logger.info("test message")).not.toThrow();
+    });
+
+    test("should log warn messages", () => {
+      const logger = createLogger("warn-test");
+      expect(() => logger.warn("test message")).not.toThrow();
+    });
+
+    test("should log error messages", () => {
+      const logger = createLogger("error-test");
+      expect(() => logger.error("test message")).not.toThrow();
+    });
+
+    test("should log with data", () => {
+      const logger = createLogger("data-test");
+      expect(() => logger.info("test message", { key: "value" })).not.toThrow();
+    });
+  });
+
+  describe("quiet mode", () => {
+    test("should enable quiet mode", () => {
+      setQuietMode(true);
+      expect(isQuietMode()).toBe(true);
+    });
+
+    test("should disable quiet mode", () => {
+      setQuietMode(false);
+      expect(isQuietMode()).toBe(false);
+    });
+
+    test("should not output to console in quiet mode", () => {
+      setQuietMode(true);
+      const logger = createLogger("quiet-test");
+      
+      // 在 quiet 模式下，日志应该只写入文件，不输出到控制台
+      expect(() => logger.info("quiet message")).not.toThrow();
+    });
+  });
+
+  describe("getLogDir", () => {
+    test("should return default logs directory", () => {
+      const logDir = getLogDir();
+      // 默认应该是 XDG 路径
+      expect(logDir).toMatch(/\.local\/share\/roy-agent\/logs$/);
+    });
+  });
+
+  describe("category log levels", () => {
+    // Mock ConfigComponent
+    const mockConfigComponent = {
+      get: (key: string): unknown => {
+        const config: Record<string, unknown> = {
+          "log_trace.logging.levels": {
+            llm: "debug",
+            agent: "warn",
+          },
+          "log_trace.logging.level": "info",
+        };
+        return config[key];
+      },
+    };
+
+    test("should return default log level", () => {
+      // 在没有配置的情况下应该返回默认值 info
+      setConfigComponent(null);
+      const level = getLogLevel();
+      expect(["debug", "info", "warn", "error"]).toContain(level);
+    });
+
+    test("should return category-specific log level", () => {
+      setConfigComponent(mockConfigComponent);
+      // llm 配置为 debug
+      expect(getCategoryLogLevel("llm")).toBe("debug");
+      // agent 配置为 warn
+      expect(getCategoryLogLevel("agent")).toBe("warn");
+    });
+
+    test("should fallback to global level for unconfigured categories", () => {
+      setConfigComponent(mockConfigComponent);
+      // tool 没有配置，应该返回全局级别 info
+      expect(getCategoryLogLevel("tool")).toBe("info");
+    });
+
+    test("should use category level in logger", () => {
+      setConfigComponent(mockConfigComponent);
+      // llm logger 使用 debug 级别
+      const llmLogger = createLogger("llm");
+      expect(() => llmLogger.debug("debug message")).not.toThrow();
+      
+      // agent logger 使用 warn 级别
+      const agentLogger = createLogger("agent");
+      expect(() => agentLogger.warn("warn message")).not.toThrow();
+    });
+  });
+});