@ai-setting/roy-agent-cli 1.0.0

package/src/commands/debug/log.test.ts

@@ -0,0 +1,233 @@
+/**
+ * @fileoverview Debug Log Command - TDD Tests
+ * 
+ * TDD 开发流程:
+ * 1. RED - 编写失败的测试
+ * 2. GREEN - 编写最小代码让测试通过
+ * 3. REFACTOR - 重构
+ * 
+ * 测试目标: debug log --tail -n xxx
+ * 功能: 读取 log-trace component 的日志文件配置的尾部 n 行
+ */
+
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import * as fs from "fs";
+import * as path from "path";
+
+describe("Debug Log Command - TDD", () => {
+  let tempDir: string;
+  let tempLogFile: string;
+
+  beforeEach(() => {
+    // Create temp directory and file
+    tempDir = fs.mkdtempSync("/tmp/debug-log-test-");
+    tempLogFile = path.join(tempDir, "test.log");
+  });
+
+  afterEach(() => {
+    // Cleanup
+    try {
+      if (fs.existsSync(tempLogFile)) {
+        fs.unlinkSync(tempLogFile);
+      }
+      if (fs.existsSync(tempDir)) {
+        fs.rmSync(tempDir, { recursive: true });
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe("RED: getDefaultLogFile()", () => {
+    test("should return path in XDG_DATA_HOME/roy-agent/logs/app.log by default", async () => {
+      const { getDefaultLogFile } = await import("./log");
+      
+      // Clear environment variables
+      delete process.env.LOG_TRACE_LOGGING_DIR;
+      delete process.env.LOG_TRACE_LOGGING_FILE;
+      
+      const logFile = getDefaultLogFile();
+      
+      expect(logFile).toContain("roy-agent");
+      expect(logFile).toContain("logs");
+      expect(logFile).toContain("app.log");
+    });
+
+    test("should use LOG_TRACE_LOGGING_DIR environment variable when set", async () => {
+      const { getDefaultLogFile } = await import("./log");
+      
+      const customDir = "/custom/logs/dir";
+      process.env.LOG_TRACE_LOGGING_DIR = customDir;
+      
+      const logFile = getDefaultLogFile();
+      
+      expect(logFile).toStartWith(customDir);
+      expect(logFile).toEndWith("app.log");
+      
+      delete process.env.LOG_TRACE_LOGGING_DIR;
+    });
+
+    test("should use LOG_TRACE_LOGGING_FILE environment variable when set to absolute path", async () => {
+      const { getDefaultLogFile } = await import("./log");
+      
+      const customFile = "/absolute/path/custom.log";
+      process.env.LOG_TRACE_LOGGING_FILE = customFile;
+      
+      const logFile = getDefaultLogFile();
+      
+      expect(logFile).toBe(customFile);
+      
+      delete process.env.LOG_TRACE_LOGGING_FILE;
+    });
+
+    test("should use custom filename in default log dir when LOG_TRACE_LOGGING_FILE is just filename", async () => {
+      const { getDefaultLogFile } = await import("./log");
+      
+      process.env.LOG_TRACE_LOGGING_DIR = "/custom/logs";
+      process.env.LOG_TRACE_LOGGING_FILE = "custom-app.log";
+      
+      const logFile = getDefaultLogFile();
+      
+      expect(logFile).toBe("/custom/logs/custom-app.log");
+      
+      delete process.env.LOG_TRACE_LOGGING_DIR;
+      delete process.env.LOG_TRACE_LOGGING_FILE;
+    });
+  });
+
+  describe("RED: readTailLines()", () => {
+    test("should read last n lines from file", async () => {
+      // Write test file
+      const lines = Array.from({ length: 100 }, (_, i) => `Line ${i + 1}`);
+      fs.writeFileSync(tempLogFile, lines.join("\n"));
+      
+      const { readTailLines } = await import("./log");
+      
+      const tailLines = await readTailLines(tempLogFile, 10);
+      
+      expect(tailLines).toHaveLength(10);
+      expect(tailLines[0]).toBe("Line 91");
+      expect(tailLines[9]).toBe("Line 100");
+    });
+
+    test("should return all lines if file has fewer lines than n", async () => {
+      const lines = ["Line 1", "Line 2", "Line 3"];
+      fs.writeFileSync(tempLogFile, lines.join("\n"));
+      
+      const { readTailLines } = await import("./log");
+      
+      const tailLines = await readTailLines(tempLogFile, 10);
+      
+      expect(tailLines).toHaveLength(3);
+      expect(tailLines[0]).toBe("Line 1");
+    });
+
+    test("should return empty array for empty file", async () => {
+      fs.writeFileSync(tempLogFile, "");
+      
+      const { readTailLines } = await import("./log");
+      
+      const tailLines = await readTailLines(tempLogFile, 10);
+      
+      expect(tailLines).toHaveLength(0);
+    });
+
+    test("should handle file with trailing newline", async () => {
+      const lines = ["Line 1", "Line 2", "Line 3"];
+      fs.writeFileSync(tempLogFile, lines.join("\n") + "\n");
+      
+      const { readTailLines } = await import("./log");
+      
+      const tailLines = await readTailLines(tempLogFile, 3);
+      
+      // readline treats each newline as end of line
+      expect(tailLines).toHaveLength(3);
+    });
+
+    test("should handle n=0 and return empty array", async () => {
+      const lines = ["Line 1", "Line 2", "Line 3"];
+      fs.writeFileSync(tempLogFile, lines.join("\n"));
+      
+      const { readTailLines } = await import("./log");
+      
+      const tailLines = await readTailLines(tempLogFile, 0);
+      
+      expect(tailLines).toHaveLength(0);
+    });
+
+    test("should reject promise when file does not exist", async () => {
+      const { readTailLines } = await import("./log");
+      
+      await expect(readTailLines("/non/existent/file.log", 10)).rejects.toThrow();
+    });
+  });
+
+  describe("GREEN: LogCommand structure", () => {
+    test("should have correct command name 'log'", async () => {
+      const { LogCommand } = await import("./index");
+      
+      expect(LogCommand.command).toBe("log");
+    });
+
+    test("should have describe text mentioning tail functionality", async () => {
+      const { LogCommand } = await import("./index");
+      
+      expect(LogCommand.describe).toContain("tail");
+    });
+
+    test("should have builder that adds --tail option", async () => {
+      const { LogCommand } = await import("./index");
+      
+      let capturedOptions: Record<string, any> = {};
+      let optionCalls = 0;
+      const mockYargs = {
+        option: (name: string, config: any) => {
+          optionCalls++;
+          capturedOptions[name] = config;
+          return mockYargs;
+        },
+      };
+      
+      LogCommand.builder(mockYargs as any);
+      
+      expect(optionCalls).toBeGreaterThanOrEqual(1);
+      expect(capturedOptions.tail).toBeDefined();
+      expect(capturedOptions.tail.alias).toBe("n");
+      expect(capturedOptions.tail.type).toBe("number");
+    });
+
+    test("should have --tail option with default value 50", async () => {
+      const { LogCommand } = await import("./index");
+      
+      let capturedOptions: Record<string, any> = {};
+      const mockYargs = {
+        option: (name: string, config: any) => {
+          capturedOptions[name] = config;
+          return mockYargs;
+        },
+      };
+      
+      LogCommand.builder(mockYargs as any);
+      
+      expect(capturedOptions.tail.default).toBe(50);
+    });
+
+    test("should have --file option for custom log file path", async () => {
+      const { LogCommand } = await import("./index");
+      
+      let capturedOptions: Record<string, any> = {};
+      const mockYargs = {
+        option: (name: string, config: any) => {
+          capturedOptions[name] = config;
+          return mockYargs;
+        },
+      };
+      
+      LogCommand.builder(mockYargs as any);
+      
+      expect(capturedOptions.file).toBeDefined();
+      expect(capturedOptions.file.alias).toBe("f");
+      expect(capturedOptions.file.type).toBe("string");
+    });
+  });
+});

package/src/commands/debug/log.ts

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Debug Log Command
+ * 
+ * Command: roy debug log --tail -n <lines>
+ * 
+ * 读取 log-trace component 日志配置对应的日志文件，显示尾部 n 行
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as readline from "readline";
+import type { CommandModule } from "yargs";
+
+interface LogOptions {
+  tail?: number;
+  file?: string;
+}
+
+export const LogCommand: CommandModule<object, LogOptions> = {
+  command: "log",
+  describe: "查看日志文件（支持 --tail -n 显示尾部行）",
+
+  builder: (yargs) =>
+    yargs
+      .option("tail", {
+        alias: "n",
+        type: "number",
+        description: "显示尾部 n 行（默认 50）",
+        default: 50,
+      })
+      .option("file", {
+        alias: "f",
+        type: "string",
+        description: "日志文件路径（可选，默认使用配置路径）",
+      }),
+
+  async handler(args) {
+    // 获取日志文件路径
+    const logFile = args.file || getDefaultLogFile();
+    
+    if (!fs.existsSync(logFile)) {
+      console.error(`Log file not found: ${logFile}`);
+      process.exit(1);
+    }
+
+    try {
+      const lines = await readTailLines(logFile, args.tail || 50);
+      
+      if (lines.length === 0) {
+        console.log("(empty log file)");
+        return;
+      }
+
+      // 逐行输出
+      for (const line of lines) {
+        console.log(line);
+      }
+    } catch (error) {
+      console.error(`Failed to read log file: ${error}`);
+      process.exit(1);
+    }
+  },
+};
+
+/**
+ * 读取文件尾部 n 行
+ */
+export async function readTailLines(filePath: string, n: number): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    const lines: string[] = [];
+    const rl = readline.createInterface({
+      input: fs.createReadStream(filePath),
+      crlfDelay: Infinity,
+    });
+
+    rl.on("line", (line) => {
+      lines.push(line);
+      // 只保留尾部 n 行
+      if (lines.length > n) {
+        lines.shift();
+      }
+    });
+
+    rl.on("close", () => {
+      resolve(lines);
+    });
+
+    rl.on("error", (err) => {
+      reject(err);
+    });
+  });
+}
+
+/**
+ * 获取默认日志文件路径
+ * 
+ * 使用 log-trace component 的配置：
+ * - log-trace.logging.dir: 日志目录
+ * - log-trace.logging.file: 日志文件名
+ * 
+ * 默认: ~/.local/share/roy-agent/logs/app.log
+ */
+export function getDefaultLogFile(): string {
+  // 支持环境变量覆盖
+  if (process.env.LOG_TRACE_LOGGING_DIR) {
+    const dir = process.env.LOG_TRACE_LOGGING_DIR;
+    const file = process.env.LOG_TRACE_LOGGING_FILE || "app.log";
+    return path.join(dir, file);
+  }
+  
+  // 支持直接指定文件路径
+  if (process.env.LOG_TRACE_LOGGING_FILE?.includes("/") || process.env.LOG_TRACE_LOGGING_FILE?.includes("\\")) {
+    return process.env.LOG_TRACE_LOGGING_FILE;
+  }
+
+  // 使用 XDG 标准路径
+  const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+  const dataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  const logDir = path.join(dataHome, "roy-agent", "logs");
+  const logFile = process.env.LOG_TRACE_LOGGING_FILE || "app.log";
+  
+  return path.join(logDir, logFile);
+}

package/src/commands/debug/span.test.ts

@@ -0,0 +1,297 @@
+/**
+ * @fileoverview Debug Span Command - TDD Tests
+ * 
+ * TDD 开发流程:
+ * 1. RED - 编写失败的测试
+ * 2. GREEN - 编写最小代码让测试通过
+ * 3. REFACTOR - 重构
+ * 
+ * 测试目标: roy debug span <spanId>
+ * 功能: 通过 spanId 从 SQLite 中查询详细的 span 信息
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Span } from "@ai-setting/roy-agent-core";
+import { SpanKind, SpanStatus } from "@ai-setting/roy-agent-core";
+
+describe("Debug Span Command - TDD", () => {
+  describe("RED: formatSpanDetail()", () => {
+    test("should format span with all fields", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_123",
+        parentSpanId: "span_parent",
+        name: "test-operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000000000000,
+        endTime: 1000000001500,
+        attributes: { "http.method": "GET", "http.url": "/api/test" },
+        result: { data: "success" },
+        children: [],
+      };
+
+      const output = formatSpanDetail(span);
+      
+      expect(output).toContain("span_123");
+      expect(output).toContain("test-operation");
+      expect(output).toContain("trace_1");
+      expect(output).toContain("500ms"); // duration
+    });
+
+    test("should show running span without duration", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_running",
+        name: "running-operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000000000000,
+        endTime: undefined,
+        attributes: {},
+        children: [],
+      };
+
+      const output = formatSpanDetail(span);
+      
+      expect(output).toContain("span_running");
+      expect(output).toContain("(running)");
+    });
+
+    test("should show error span with error message", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_error",
+        name: "failed-operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.ERROR,
+        startTime: 1000000000000,
+        endTime: 1000000001000,
+        attributes: {},
+        error: "Something went wrong",
+        children: [],
+      };
+
+      const output = formatSpanDetail(span);
+      
+      // status 是小写的
+      expect(output).toContain("Status:     error");
+      expect(output).toContain("Something went wrong");
+    });
+
+    test("should format attributes as key-value pairs", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_attrs",
+        name: "operation-with-attrs",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000000000000,
+        endTime: 1000000001000,
+        attributes: { 
+          "http.method": "POST",
+          "http.url": "/api/users",
+          "http.status_code": 200
+        },
+        children: [],
+      };
+
+      const output = formatSpanDetail(span);
+      
+      expect(output).toContain("http.method");
+      expect(output).toContain("POST");
+      expect(output).toContain("http.url");
+      expect(output).toContain("/api/users");
+    });
+
+    test("should show result if present", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_result",
+        name: "operation-with-result",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000000000000,
+        endTime: 1000000001000,
+        attributes: {},
+        result: { items: ["a", "b", "c"], count: 3 },
+        children: [],
+      };
+
+      const output = formatSpanDetail(span);
+      
+      expect(output).toContain("Result:");
+      expect(output).toContain('"a"');
+      expect(output).toContain("count");
+      expect(output).toContain("3");
+    });
+
+    test("should show parent span info", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_child",
+        parentSpanId: "span_parent",
+        name: "child-operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000000000000,
+        endTime: 1000000001000,
+        attributes: {},
+        children: [],
+      };
+
+      const output = formatSpanDetail(span);
+      
+      // 首字母大写格式
+      expect(output).toContain("Parent:");
+      expect(output).toContain("span_parent");
+    });
+
+    test("should show kind information", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_kind",
+        name: "server-handler",
+        kind: SpanKind.SERVER,
+        status: SpanStatus.OK,
+        startTime: 1000000000000,
+        endTime: 1000000001000,
+        attributes: {},
+        children: [],
+      };
+
+      const output = formatSpanDetail(span);
+      
+      // 首字母大写格式，值是小写的
+      expect(output).toContain("Kind:");
+      expect(output).toContain("server");
+    });
+
+    test("should handle circular reference in result", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      // 创建循环引用对象
+      const circularObj: any = { name: "test" };
+      circularObj.self = circularObj;
+      
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_circular",
+        name: "operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000000000000,
+        endTime: 1000000001000,
+        attributes: {},
+        result: circularObj,
+        children: [],
+      };
+
+      // Should not throw, should handle circular reference
+      expect(() => formatSpanDetail(span)).not.toThrow();
+      const output = formatSpanDetail(span);
+      expect(output).toContain("Result:");
+      expect(output).toContain("[Circular]");
+    });
+
+    test("should handle corrupted result string from old data", async () => {
+      const { formatSpanDetail } = await import("./span");
+      
+      // 模拟已经存储的损坏数据
+      const span: Span = {
+        traceId: "trace_1",
+        spanId: "span_corrupted",
+        name: "operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000000000000,
+        endTime: 1000000001000,
+        attributes: {},
+        result: "[Object with circular reference: some error message]" as any,
+        children: [],
+      };
+
+      const output = formatSpanDetail(span);
+      expect(output).toContain("Result:");
+      expect(output).toContain("Circular reference");
+    });
+  });
+
+  describe("GREEN: SpanCommand structure", () => {
+    test("should have correct command name 'span'", async () => {
+      const { SpanCommand } = await import("./index");
+      
+      expect(SpanCommand.command).toBe("span");
+    });
+
+    test("should have describe text mentioning span lookup", async () => {
+      const { SpanCommand } = await import("./index");
+      
+      expect(SpanCommand.describe).toBeDefined();
+      expect(typeof SpanCommand.describe).toBe("string");
+      expect((SpanCommand.describe || "").toLowerCase()).toContain("span");
+    });
+
+    test("should have builder that adds spanId positional argument", async () => {
+      const { SpanCommand } = await import("./index");
+      
+      let positionalConfig: any = null;
+      const mockYargs = {
+        positional: (name: string, config: any) => {
+          if (name === "spanId") {
+            positionalConfig = config;
+          }
+          return mockYargs;
+        },
+        option: () => mockYargs,
+      };
+      
+      SpanCommand.builder(mockYargs as any);
+      
+      expect(positionalConfig).toBeDefined();
+      expect(positionalConfig.type).toBe("string");
+    });
+
+    test("should have --db option for custom db path", async () => {
+      const { SpanCommand } = await import("./index");
+      
+      let capturedOptions: Record<string, any> = {};
+      const mockYargs = {
+        option: (name: string, config: any) => {
+          capturedOptions[name] = config;
+          return mockYargs;
+        },
+        positional: () => mockYargs,
+      };
+      
+      SpanCommand.builder(mockYargs as any);
+      
+      expect(capturedOptions.db).toBeDefined();
+      expect(capturedOptions.db.type).toBe("string");
+    });
+  });
+
+  describe("GREEN: SpanCommand handler integration", () => {
+    test("should be exported from debug/index.ts", async () => {
+      // This test verifies the span command is properly integrated
+      const debugModule = await import("./index");
+      
+      expect(debugModule.SpanCommand).toBeDefined();
+      expect(debugModule.SpanCommand.command).toBe("span");
+    });
+  });
+});