@ai-setting/roy-agent-core 1.0.0

package/src/env/debug/types.ts

@@ -0,0 +1,171 @@
+/**
+ * @fileoverview Debug Component Types
+ * 
+ * Type definitions for trace parsing, formatting, and debugging utilities.
+ */
+
+// ============================================================================
+// Core Trace Types
+// ============================================================================
+
+/**
+ * Trace action type
+ */
+export type TraceAction = 'enter' | 'quit' | 'error';
+
+/**
+ * Log level type
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Trace entry representing a single log line with trace info
+ */
+export interface TraceEntry {
+  /** Unique request/trace identifier */
+  traceId: string;
+  /** Timestamp of the entry (ISO format) */
+  timestamp: string;
+  /** Function/method name */
+  function: string;
+  /** Action type: enter, quit, or error */
+  action: TraceAction;
+  /** Parameters (for enter action) */
+  params?: unknown[];
+  /** Result (for quit action) */
+  result?: unknown;
+  /** Error message (for error action) */
+  error?: string;
+  /** Calculated duration in milliseconds (for quit action) */
+  durationMs?: number;
+  /** Span ID (for SQLite spans) */
+  spanId?: string;
+  /** Parent span ID (for SQLite spans) */
+  parentSpanId?: string;
+}
+
+/**
+ * Call tree node for hierarchical trace visualization
+ */
+export interface TraceTreeNode {
+  /** Unique request/trace identifier */
+  traceId: string;
+  /** Function/method name */
+  function: string;
+  /** Start timestamp */
+  startTime: string;
+  /** End timestamp (for completed nodes) */
+  endTime?: string;
+  /** Duration in milliseconds */
+  durationMs?: number;
+  /** Child nodes */
+  children: TraceTreeNode[];
+  /** Original trace entry (optional for programmatically created nodes) */
+  entry?: TraceEntry;
+  /** Span ID (for SQLite spans) */
+  spanId?: string;
+  /** Parent span ID (for SQLite spans) */
+  parentSpanId?: string;
+}
+
+// ============================================================================
+// Parser Types
+// ============================================================================
+
+/**
+ * Options for parsing logs
+ */
+export interface ParserOptions {
+  /** Log file path to read */
+  logFile?: string;
+  /** Filter by trace ID */
+  traceId?: string;
+  /** Filter by function name (supports partial match) */
+  function?: string;
+  /** Start time filter (ISO format or relative like "1h") */
+  since?: string;
+  /** End time filter (ISO format) */
+  until?: string;
+  /** Log level filter */
+  level?: LogLevel;
+}
+
+/**
+ * Options for log discovery
+ */
+export interface LogDiscoveryOptions {
+  /** Log directory to search */
+  logDir?: string;
+  /** File pattern to match */
+  pattern?: string;
+}
+
+/**
+ * Parsed log line with extracted fields
+ */
+export interface ParsedLogLine {
+  /** Original log line */
+  raw: string;
+  /** Timestamp extracted from log */
+  timestamp: string;
+  /** Log level (INFO, DEBUG, WARN, ERROR) */
+  level: string;
+  /** Source file/location */
+  source: string;
+  /** Category (traced:...) */
+  category: string;
+  /** Action symbol (>>> or <<< or !!!) */
+  action: string;
+  /** Method/function name */
+  method: string;
+  /** Action type (enter, quit, error) */
+  actionType: TraceAction;
+  /** Raw arguments string */
+  rawArgs: string;
+  /** Request ID extracted from log (if present) */
+  requestId: string | null;
+}
+
+// ============================================================================
+// Info Types
+// ============================================================================
+
+/**
+ * Trace ID information summary
+ */
+export interface TraceIdInfo {
+  /** Trace ID */
+  traceId: string;
+  /** First occurrence timestamp */
+  firstTime: string;
+  /** Last occurrence timestamp */
+  lastTime?: string;
+  /** Number of entries for this trace */
+  count: number;
+}
+
+// ============================================================================
+// Formatter Types
+// ============================================================================
+
+/**
+ * Output format options
+ */
+export interface FormatOptions {
+  /** Use pretty printing */
+  pretty?: boolean;
+  /** Maximum depth for recursive objects */
+  maxDepth?: number;
+  /** Include raw data */
+  includeRaw?: boolean;
+}
+
+/**
+ * Trace summary for list output
+ */
+export interface TraceSummary {
+  /** List of trace ID info */
+  traceIds: TraceIdInfo[];
+  /** Total count */
+  count: number;
+}

package/src/env/environment-init.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { BaseEnvironment, type BaseEnvironmentConfig } from "./environment";
+import { BaseComponent } from "./component";
+
+// 全局初始化计数器，用于跟踪初始化顺序
+let initCounter = 0;
+
+/**
+ * 测试用 ConfigComponent
+ */
+class TestConfigComponent extends BaseComponent {
+  readonly name = "config";
+  readonly version = "1.0.0";
+  protected initOrder = 0;
+  
+  getInitOrder(): number {
+    return this.initOrder;
+  }
+  
+  protected async onInit(): Promise<void> {
+    this.initOrder = ++initCounter;
+  }
+}
+
+/**
+ * 测试用 ToolComponent
+ */
+class TestToolComponent extends BaseComponent {
+  readonly name = "tool";
+  readonly version = "1.0.0";
+  protected initOrder = 0;
+  
+  getInitOrder(): number {
+    return this.initOrder;
+  }
+  
+  protected async onInit(): Promise<void> {
+    this.initOrder = ++initCounter;
+  }
+}
+
+/**
+ * 测试用 PromptComponent
+ */
+class TestPromptComponent extends BaseComponent {
+  readonly name = "prompt";
+  readonly version = "1.0.0";
+  protected initOrder = 0;
+  
+  getInitOrder(): number {
+    return this.initOrder;
+  }
+  
+  protected async onInit(): Promise<void> {
+    this.initOrder = ++initCounter;
+  }
+}
+
+describe("Environment component initialization", () => {
+  let env: BaseEnvironment;
+  
+  beforeEach(() => {
+    env = new BaseEnvironment({ name: "test-env", version: "1.0.0" });
+  });
+
+  describe("分阶段初始化", () => {
+    it("should init ConfigComponent first", async () => {
+      const configComp = new TestConfigComponent();
+      const toolComp = new TestToolComponent();
+      
+      // 故意先注册 tool，再注册 config
+      env.registerComponent(toolComp);
+      env.registerComponent(configComp);
+      
+      await env.init();
+      
+      // ConfigComponent 应该先于 ToolComponent 完成初始化
+      expect(configComp.getStatus()).toBe("running");
+      expect(toolComp.getStatus()).toBe("running");
+      expect(configComp.getInitOrder()).toBeLessThan(toolComp.getInitOrder());
+    });
+    
+    it("should pass env to all components", async () => {
+      const toolComp = new TestToolComponent();
+      env.registerComponent(toolComp);
+      
+      await env.init();
+      
+      // 验证 env 被正确注入
+      expect((toolComp as any).env).toBe(env);
+    });
+    
+    it("should not re-init already initialized components", async () => {
+      const configComp = new TestConfigComponent();
+      env.registerComponent(configComp);
+      
+      // 手动初始化
+      await configComp.init({
+        name: "config",
+        version: "1.0.0",
+        enabled: true,
+        env,
+      });
+      
+      const firstInitTime = configComp.getInitOrder();
+      
+      // 调用环境初始化
+      await env.init();
+      
+      // initOrder 不应该改变（因为已经初始化过了）
+      expect(configComp.getInitOrder()).toBe(firstInitTime);
+    });
+    
+    it("should init multiple components in correct order", async () => {
+      const configComp = new TestConfigComponent();
+      const toolComp = new TestToolComponent();
+      const promptComp = new TestPromptComponent();
+      
+      // 以任意顺序注册
+      env.registerComponent(promptComp);
+      env.registerComponent(toolComp);
+      env.registerComponent(configComp);
+      
+      await env.init();
+      
+      // 验证初始化顺序
+      expect(configComp.getInitOrder()).toBeLessThan(toolComp.getInitOrder());
+      expect(configComp.getInitOrder()).toBeLessThan(promptComp.getInitOrder());
+      
+      // 验证所有组件都正确初始化
+      expect(configComp.getStatus()).toBe("running");
+      expect(toolComp.getStatus()).toBe("running");
+      expect(promptComp.getStatus()).toBe("running");
+    });
+    
+    it("should handle environment without ConfigComponent", async () => {
+      const toolComp = new TestToolComponent();
+      const promptComp = new TestPromptComponent();
+      
+      env.registerComponent(toolComp);
+      env.registerComponent(promptComp);
+      
+      await env.init();
+      
+      // 没有 ConfigComponent 时，其他组件也应该正常初始化
+      expect(toolComp.getStatus()).toBe("running");
+      expect(promptComp.getStatus()).toBe("running");
+    });
+    
+    it("should set env property on Environment itself", async () => {
+      await env.init();
+      
+      // Environment 自身也应该有 env 属性（自引用）
+      expect((env as any).env).toBe(env);
+    });
+  });
+  
+  describe("getEnv() access", () => {
+    it("should allow components to access env via getEnv()", async () => {
+      const toolComp = new TestToolComponent();
+      env.registerComponent(toolComp);
+      
+      await env.init();
+      
+      // 组件应该能通过 getEnv() 访问 Environment
+      expect(toolComp.getEnv()).toBe(env);
+    });
+    
+    it("should allow components to get other components", async () => {
+      const configComp = new TestConfigComponent();
+      const toolComp = new TestToolComponent();
+      
+      env.registerComponent(configComp);
+      env.registerComponent(toolComp);
+      
+      await env.init();
+      
+      // 组件应该能通过 env.getComponent() 获取其他组件
+      const retrieved = toolComp.getEnv().getComponent("config");
+      expect(retrieved).toBe(configComp);
+    });
+  });
+});