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

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

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Debug Component
+ *
+ * Provides debugging capabilities for roy-agent applications by parsing
+ * trace logs and presenting formatted output.
+ */
+import { BaseComponent, type ComponentConfig } from '../component';
+import { LogReader } from './reader/log-reader';
+import { SpanDbReader } from './reader/span-db-reader';
+import { RegexParser } from './parser/regex-parser';
+import { SpanBuilder } from './parser/span-builder';
+import { TraceFormatter, TreeFormatter } from './formatters';
+import type { ParserOptions, TraceEntry, TraceTreeNode, TraceSummary, FormatOptions } from './types';
+/**
+ * Data source type for trace retrieval
+ */
+export type TraceDataSource = 'log' | 'sqlite';
+/**
+ * Extended parser options with data source support
+ */
+export interface TraceParserOptions extends ParserOptions {
+    /** Data source type: 'log' (default) or 'sqlite' */
+    source?: TraceDataSource;
+    /** SQLite database path (required when source is 'sqlite') */
+    dbPath?: string;
+}
+/**
+ * DebugComponent configuration options
+ */
+export interface DebugComponentOptions {
+    /** Log directory path */
+    logDir?: string;
+    /** Default log file */
+    defaultLogFile?: string;
+}
+/**
+ * Debug Component for trace analysis and debugging
+ */
+export declare class DebugComponent extends BaseComponent {
+    name: string;
+    version: string;
+    private reader;
+    private spanDbReader;
+    private parser;
+    private spanBuilder;
+    private traceFormatter;
+    private treeFormatter;
+    private options;
+    constructor(options?: DebugComponentOptions);
+    /**
+     * Initialize the span database reader
+     */
+    initSpanDbReader(dbPath?: string): Promise<void>;
+    /**
+     * Get the span database reader
+     */
+    getSpanDbReader(): SpanDbReader | null;
+    /**
+     * Get trace by ID from live Tracer storage
+     *
+     * This method retrieves traces directly from the Tracer's span storage,
+     * which includes spans from the current session that may not yet be persisted
+     * to log files.
+     */
+    getLiveTrace(traceId: string): Promise<any | null>;
+    /**
+     * List all available traces from live Tracer storage
+     */
+    listLiveTraces(limit?: number): Promise<any>;
+    /**
+     * Format a live trace for display
+     */
+    formatLiveTrace(traceId: string): Promise<string>;
+    /**
+     * Initialize the component
+     */
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * Stop the component
+     */
+    stop(): Promise<void>;
+    /**
+     * Get traces matching the options
+     */
+    getTraces(options?: TraceParserOptions): Promise<TraceEntry[]>;
+    /**
+     * Get traces from SQLite database
+     */
+    private getTracesFromSqlite;
+    /**
+     * List available trace IDs
+     */
+    listTraceIds(options?: TraceParserOptions & {
+        limit?: number;
+    }): Promise<TraceSummary>;
+    /**
+     * List trace IDs from SQLite database
+     */
+    private listTraceIdsFromSqlite;
+    /**
+     * Get call tree for a specific trace
+     */
+    getCallTree(options?: TraceParserOptions): Promise<TraceTreeNode | null>;
+    /**
+     * Get the log reader instance
+     */
+    getReader(): LogReader;
+    /**
+     * Get the parser instance
+     */
+    getParser(): RegexParser;
+    /**
+     * Get the span builder instance
+     */
+    getSpanBuilder(): SpanBuilder;
+    /**
+     * Get the trace formatter instance
+     */
+    getTraceFormatter(): TraceFormatter;
+    /**
+     * Get the tree formatter instance
+     */
+    getTreeFormatter(): TreeFormatter;
+    /**
+     * Format traces for display
+     */
+    formatTraces(entries: TraceEntry[], options?: FormatOptions): string;
+    /**
+     * Format a single trace entry
+     */
+    formatTraceEntry(entry: TraceEntry, options?: FormatOptions): string;
+    /**
+     * Format traces as JSON
+     */
+    tracesToJSON(entries: TraceEntry[]): string;
+    /**
+     * Format traces as summary
+     */
+    tracesToSummary(entries: TraceEntry[]): string;
+    /**
+     * Format call tree for display
+     */
+    formatTree(node: TraceTreeNode): string;
+    /**
+     * Format multiple call trees
+     */
+    formatTrees(trees: TraceTreeNode[]): string;
+    /**
+     * Format trees as JSON
+     */
+    treesToJSON(trees: TraceTreeNode[]): string;
+    /**
+     * Format tree summary (sorted by duration)
+     */
+    formatTreeSummary(node: TraceTreeNode): string;
+    /**
+     * Format tree with timeline visualization
+     */
+    formatTreeTimeline(node: TraceTreeNode): string;
+}
+//# sourceMappingURL=debug-component.d.ts.map

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

@@ -0,0 +1,441 @@
+/**
+ * @fileoverview Debug Component
+ *
+ * Provides debugging capabilities for roy-agent applications by parsing
+ * trace logs and presenting formatted output.
+ */
+import { BaseComponent } from "../component.js";
+import { LogReader } from "./reader/log-reader.js";
+import { SpanDbReader } from "./reader/span-db-reader.js";
+import { RegexParser } from "./parser/regex-parser.js";
+import { SpanBuilder } from "./parser/span-builder.js";
+import { TraceFormatter, TreeFormatter } from "./formatters/index.js";
+/**
+ * Debug Component for trace analysis and debugging
+ */
+export class DebugComponent extends BaseComponent {
+    name = 'debug';
+    version = '1.0.0';
+    reader;
+    spanDbReader = null;
+    parser;
+    spanBuilder;
+    traceFormatter;
+    treeFormatter;
+    options;
+    constructor(options) {
+        super();
+        this.options = options || {};
+        this.reader = new LogReader({ logDir: this.options.logDir });
+        this.parser = new RegexParser();
+        this.spanBuilder = new SpanBuilder();
+        this.traceFormatter = new TraceFormatter();
+        this.treeFormatter = new TreeFormatter();
+    }
+    /**
+     * Initialize the span database reader
+     */
+    async initSpanDbReader(dbPath) {
+        if (!this.spanDbReader) {
+            this.spanDbReader = new SpanDbReader({ dbPath });
+            await this.spanDbReader.initialize();
+        }
+    }
+    /**
+     * Get the span database reader
+     */
+    getSpanDbReader() {
+        return this.spanDbReader;
+    }
+    // =========================================================================
+    // Live Trace Methods (from Tracer storage)
+    // =========================================================================
+    /**
+     * Get trace by ID from live Tracer storage
+     *
+     * This method retrieves traces directly from the Tracer's span storage,
+     * which includes spans from the current session that may not yet be persisted
+     * to log files.
+     */
+    async getLiveTrace(traceId) {
+        try {
+            // Import OTel TracerProvider utilities dynamically to avoid circular dependencies
+            const { getTracerProvider } = await import('../log-trace/opentelemetry/tracer-provider');
+            const provider = getTracerProvider();
+            if (!provider.isInitialized()) {
+                await provider.initialize();
+            }
+            // Get storage directly from provider
+            const storage = provider.getStorage();
+            // Get all spans for this trace
+            const spans = storage.findByTraceId(traceId);
+            if (spans.length === 0) {
+                return null;
+            }
+            // Flatten spans for call tree building
+            const flattenSpans = (spanList) => {
+                const result = [];
+                for (const span of spanList) {
+                    result.push({
+                        traceId: span.traceId,
+                        spanId: span.spanId,
+                        parentSpanId: span.parentSpanId,
+                        function: span.name,
+                        action: 'enter',
+                        timestamp: new Date(span.startTime).toISOString(),
+                        params: Object.entries(span.attributes || {}).map(([k, v]) => ({ key: k, value: v })),
+                    });
+                    if (span.children && span.children.length > 0) {
+                        result.push(...flattenSpans(span.children));
+                    }
+                }
+                return result;
+            };
+            // Convert tree structure to flat entries for TraceEntry
+            const flatSpans = flattenSpans(spans);
+            const tree = this.spanBuilder.buildCallTree(flatSpans);
+            // Get root spans (spans without parentSpanId in original list)
+            const rootSpans = spans.filter((s) => !s.parentSpanId);
+            return {
+                traceId,
+                spans,
+                callTree: tree,
+                spanCount: flatSpans.length,
+                rootSpans,
+            };
+        }
+        catch (error) {
+            console.error('Failed to get trace from live storage:', error);
+            return null;
+        }
+    }
+    /**
+     * List all available traces from live Tracer storage
+     */
+    async listLiveTraces(limit = 20) {
+        try {
+            // Import OTel TracerProvider utilities dynamically to avoid circular dependencies
+            const { getTracerProvider } = await import('../log-trace/opentelemetry/tracer-provider');
+            const provider = getTracerProvider();
+            if (!provider.isInitialized()) {
+                await provider.initialize();
+            }
+            // Get storage directly from provider
+            const storage = provider.getStorage();
+            const traces = storage.listTraces(limit);
+            return {
+                traces,
+                count: traces.length,
+            };
+        }
+        catch (error) {
+            console.error('Failed to list live traces:', error);
+            return { traces: [], count: 0 };
+        }
+    }
+    /**
+     * Format a live trace for display
+     */
+    async formatLiveTrace(traceId) {
+        try {
+            // Import OTel TracerProvider utilities dynamically to avoid circular dependencies
+            const { getTracerProvider } = await import('../log-trace/opentelemetry/tracer-provider');
+            const provider = getTracerProvider();
+            if (!provider.isInitialized()) {
+                await provider.initialize();
+            }
+            // Get storage directly from provider
+            const storage = provider.getStorage();
+            const spans = storage.findByTraceId(traceId);
+            if (spans.length === 0) {
+                return `No trace found for traceId: ${traceId}`;
+            }
+            // Flatten spans for formatting
+            const flattenSpans = (spanList) => {
+                const result = [];
+                for (const span of spanList) {
+                    result.push({
+                        traceId: span.traceId,
+                        spanId: span.spanId,
+                        parentSpanId: span.parentSpanId,
+                        function: span.name,
+                        action: 'enter',
+                        timestamp: new Date(span.startTime).toISOString(),
+                        params: Object.entries(span.attributes || {}).map(([k, v]) => ({ key: k, value: v })),
+                    });
+                    if (span.children && span.children.length > 0) {
+                        result.push(...flattenSpans(span.children));
+                    }
+                }
+                return result;
+            };
+            const flatSpans = flattenSpans(spans);
+            const tree = this.spanBuilder.buildCallTree(flatSpans);
+            // Handle null case (no valid tree structure)
+            if (!tree) {
+                return 'No trace structure found';
+            }
+            // Use treeFormatter to format the call tree
+            return this.treeFormatter.formatTree(tree);
+        }
+        catch (error) {
+            return `Failed to format trace: ${error}`;
+        }
+    }
+    /**
+     * Initialize the component
+     */
+    async init(config) {
+        await super.init(config);
+        this.setStatus('running');
+    }
+    /**
+     * Stop the component
+     */
+    async stop() {
+        this.setStatus('stopping');
+        // Cleanup if needed
+        this.setStatus('stopped');
+    }
+    /**
+     * Get traces matching the options
+     */
+    async getTraces(options) {
+        // Use SQLite data source if specified
+        if (options?.source === 'sqlite') {
+            return this.getTracesFromSqlite(options);
+        }
+        // Default: use log file
+        const logFile = options?.logFile || this.reader.getLogPath();
+        // Read and filter log lines
+        const lines = [];
+        for await (const line of this.reader.readLines(logFile, options)) {
+            // Filter by function name if specified
+            if (options?.function && !line.includes(options.function)) {
+                continue;
+            }
+            // Filter by traceId if specified
+            if (options?.traceId && !line.includes(`requestId=${options.traceId}`)) {
+                continue;
+            }
+            // Only include trace lines
+            if (this.parser.isTraceLine(line)) {
+                lines.push(line);
+            }
+        }
+        // Parse lines
+        const parsedLines = this.parser.parseLines(lines);
+        // Build trace entries
+        const entries = this.spanBuilder.buildTraceEntries(parsedLines);
+        // Filter by function name at entry level
+        let filteredEntries = entries;
+        if (options?.function) {
+            filteredEntries = entries.filter(e => e.function.includes(options.function));
+        }
+        // Pair enter/quit and calculate duration
+        const paired = this.spanBuilder.pairEnterQuit(filteredEntries);
+        // Build flat list with duration info
+        const result = [];
+        for (const span of paired) {
+            result.push({
+                ...span.enter,
+                durationMs: span.durationMs,
+            });
+            if (span.quit) {
+                result.push({
+                    ...span.quit,
+                    durationMs: span.durationMs,
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Get traces from SQLite database
+     */
+    async getTracesFromSqlite(options) {
+        if (!options?.traceId) {
+            return [];
+        }
+        await this.initSpanDbReader(options.dbPath);
+        const reader = this.getSpanDbReader();
+        if (!reader) {
+            throw new Error('Failed to initialize span database reader');
+        }
+        const entries = await reader.getTraceEntries(options.traceId);
+        // Filter by function name if specified
+        if (options?.function) {
+            return entries.filter(e => e.function.includes(options.function));
+        }
+        return entries;
+    }
+    /**
+     * List available trace IDs
+     */
+    async listTraceIds(options) {
+        // Use SQLite data source if specified
+        if (options?.source === 'sqlite') {
+            return this.listTraceIdsFromSqlite(options);
+        }
+        // Default: use log file
+        const logFile = options?.logFile || this.reader.getLogPath();
+        const limit = options?.limit || 20;
+        // Map to store trace info
+        const traceMap = new Map();
+        // Read all trace lines
+        for await (const line of this.reader.readLines(logFile, options)) {
+            if (!this.parser.isTraceLine(line))
+                continue;
+            const parsed = this.parser.parseLogLine(line);
+            if (!parsed)
+                continue;
+            // Extract traceId or generate virtual one
+            const traceId = this.parser.extractTraceId(line) ||
+                this.spanBuilder.generateVirtualTraceId(parsed.method, parsed.timestamp);
+            const existing = traceMap.get(traceId);
+            if (existing) {
+                existing.lastTime = parsed.timestamp;
+                existing.count++;
+            }
+            else {
+                traceMap.set(traceId, {
+                    firstTime: parsed.timestamp,
+                    lastTime: parsed.timestamp,
+                    count: 1,
+                });
+            }
+        }
+        // Convert to array and sort by first time (most recent first)
+        const traceIds = [];
+        for (const [traceId, info] of traceMap.entries()) {
+            traceIds.push({
+                traceId,
+                firstTime: info.firstTime,
+                lastTime: info.lastTime,
+                count: info.count,
+            });
+        }
+        traceIds.sort((a, b) => b.firstTime.localeCompare(a.firstTime));
+        return {
+            traceIds: traceIds.slice(0, limit),
+            count: traceIds.length,
+        };
+    }
+    /**
+     * List trace IDs from SQLite database
+     */
+    async listTraceIdsFromSqlite(options) {
+        const limit = options?.limit || 20;
+        await this.initSpanDbReader(options?.dbPath);
+        const reader = this.getSpanDbReader();
+        if (!reader) {
+            throw new Error('Failed to initialize span database reader');
+        }
+        return reader.listTraceIds(limit);
+    }
+    /**
+     * Get call tree for a specific trace
+     */
+    async getCallTree(options) {
+        if (!options?.traceId) {
+            return null;
+        }
+        // Get all traces for this traceId
+        const traces = await this.getTraces({
+            ...options,
+            traceId: options.traceId,
+        });
+        if (traces.length === 0) {
+            return null;
+        }
+        return this.spanBuilder.buildCallTree(traces);
+    }
+    /**
+     * Get the log reader instance
+     */
+    getReader() {
+        return this.reader;
+    }
+    /**
+     * Get the parser instance
+     */
+    getParser() {
+        return this.parser;
+    }
+    /**
+     * Get the span builder instance
+     */
+    getSpanBuilder() {
+        return this.spanBuilder;
+    }
+    /**
+     * Get the trace formatter instance
+     */
+    getTraceFormatter() {
+        return this.traceFormatter;
+    }
+    /**
+     * Get the tree formatter instance
+     */
+    getTreeFormatter() {
+        return this.treeFormatter;
+    }
+    // =========================================================================
+    // Formatting Methods
+    // =========================================================================
+    /**
+     * Format traces for display
+     */
+    formatTraces(entries, options) {
+        return this.traceFormatter.formatEntries(entries, options);
+    }
+    /**
+     * Format a single trace entry
+     */
+    formatTraceEntry(entry, options) {
+        return this.traceFormatter.formatEntry(entry, options);
+    }
+    /**
+     * Format traces as JSON
+     */
+    tracesToJSON(entries) {
+        return this.traceFormatter.toJSON(entries);
+    }
+    /**
+     * Format traces as summary
+     */
+    tracesToSummary(entries) {
+        return this.traceFormatter.toSummary(entries);
+    }
+    /**
+     * Format call tree for display
+     */
+    formatTree(node) {
+        return this.treeFormatter.formatTree(node);
+    }
+    /**
+     * Format multiple call trees
+     */
+    formatTrees(trees) {
+        return this.treeFormatter.formatTrees(trees);
+    }
+    /**
+     * Format trees as JSON
+     */
+    treesToJSON(trees) {
+        return this.treeFormatter.toJSON(trees);
+    }
+    /**
+     * Format tree summary (sorted by duration)
+     */
+    formatTreeSummary(node) {
+        return this.treeFormatter.formatSummary(node);
+    }
+    /**
+     * Format tree with timeline visualization
+     */
+    formatTreeTimeline(node) {
+        return this.treeFormatter.formatTimeline(node);
+    }
+}
+//# sourceMappingURL=debug-component.js.map

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

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

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

@@ -0,0 +1,89 @@
+import { describe, expect, test, beforeEach } from 'bun:test';
+import { DebugComponent } from "./debug-component.js";
+describe('DebugComponent', () => {
+    let component;
+    beforeEach(() => {
+        component = new DebugComponent();
+    });
+    describe('initialization', () => {
+        test('should have correct name and version', () => {
+            expect(component.name).toBe('debug');
+            expect(component.version).toBe('1.0.0');
+        });
+        test('should initialize with running status', async () => {
+            await component.init();
+            expect(component.getStatus()).toBe('running');
+        });
+    });
+    describe('getTraces', () => {
+        test('should return traces from log file', async () => {
+            await component.init();
+            // Note: Without proper file mocking, we test the structure
+            const traces = await component.getTraces({
+                logFile: '/nonexistent/app.log',
+            });
+            expect(Array.isArray(traces)).toBe(true);
+            // Non-existent file returns empty array
+            expect(traces).toEqual([]);
+        });
+        test('should filter by function name', async () => {
+            await component.init();
+            const traces = await component.getTraces({
+                logFile: '/real/app.log',
+                function: 'llm.invoke',
+            });
+            expect(traces.every(t => t.function.includes('llm'))).toBe(true);
+        });
+        test('should return empty array for non-existent file', async () => {
+            await component.init();
+            const traces = await component.getTraces({
+                logFile: '/nonexistent/file.log',
+            });
+            expect(traces).toEqual([]);
+        });
+    });
+    describe('listTraceIds', () => {
+        test('should return trace ID list', async () => {
+            await component.init();
+            const result = await component.listTraceIds({
+                logFile: '/real/app.log',
+            });
+            expect(result).toHaveProperty('traceIds');
+            expect(result).toHaveProperty('count');
+            expect(Array.isArray(result.traceIds)).toBe(true);
+        });
+        test('should respect limit parameter', async () => {
+            await component.init();
+            const result = await component.listTraceIds({
+                logFile: '/real/app.log',
+                limit: 5,
+            });
+            expect(result.traceIds.length).toBeLessThanOrEqual(5);
+        });
+    });
+    describe('getCallTree', () => {
+        test('should return call tree for trace', async () => {
+            await component.init();
+            const tree = await component.getCallTree({
+                logFile: '/real/app.log',
+                traceId: 'req_123',
+            });
+            if (tree) {
+                expect(tree).toHaveProperty('traceId');
+                expect(tree).toHaveProperty('function');
+                expect(tree).toHaveProperty('children');
+                expect(Array.isArray(tree.children)).toBe(true);
+            }
+        });
+        test('should return null for non-existent trace', async () => {
+            await component.init();
+            const tree = await component.getCallTree({
+                logFile: '/real/app.log',
+                traceId: 'nonexistent',
+            });
+            // May return null or empty tree depending on implementation
+            expect(tree === null || tree.traceId !== 'nonexistent').toBe(true);
+        });
+    });
+});
+//# sourceMappingURL=debug-component.test.js.map

package/dist/core/src/env/debug/formatters/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Debug Formatters
+ *
+ * Export all formatters for trace and tree visualization
+ */
+export { TraceFormatter } from './trace-formatter';
+export { TreeFormatter } from './tree-formatter';
+export { ReplFormatter } from './repl-formatter';
+//# sourceMappingURL=index.d.ts.map