@kb-labs/shared 1.1.0

package/packages/shared-cli-ui/src/debug/components/trace.ts

@@ -0,0 +1,101 @@
+import type { DebugEntry } from '../types';
+import { formatTimelineWithSummary } from '../formatters/timeline';
+import { DebugTree } from './tree';
+
+export interface TraceOptions {
+  showSummary?: boolean;
+  groupByPlugin?: boolean;
+  maxDepth?: number;
+}
+
+export class DebugTrace {
+  private readonly entries: DebugEntry[] = [];
+  private readonly options: TraceOptions;
+
+  constructor(entries: DebugEntry[] = [], options: TraceOptions = {}) {
+    this.entries.push(...entries);
+    this.options = options;
+  }
+
+  add(entry: DebugEntry): void {
+    this.entries.push(entry);
+  }
+
+  addAll(entries: DebugEntry[]): void {
+    this.entries.push(...entries);
+  }
+
+  clear(): void {
+    this.entries.length = 0;
+  }
+
+  format(): string {
+    if (this.entries.length === 0) {
+      return '';
+    }
+
+    const sorted = [...this.entries].sort((a, b) => a.timestamp - b.timestamp);
+    if (this.options.groupByPlugin) {
+      return this.formatGrouped(sorted);
+    }
+
+    return formatTimelineWithSummary(sorted);
+  }
+
+  private formatGrouped(entries: DebugEntry[]): string {
+    const groups = new Map<string, DebugEntry[]>();
+    for (const entry of entries) {
+      const plugin = entry.namespace.split(':')[0] ?? entry.namespace;
+      if (!groups.has(plugin)) {
+        groups.set(plugin, []);
+      }
+      groups.get(plugin)!.push(entry);
+    }
+
+    const parts: string[] = [];
+    for (const [plugin, pluginEntries] of groups) {
+      const tree = new DebugTree(pluginEntries, {
+        showSummary: this.options.showSummary,
+        maxDepth: this.options.maxDepth,
+      });
+      const formatted = tree.format();
+      if (formatted) {
+        parts.push(`[${plugin}]`, formatted);
+      }
+    }
+    return parts.join('\n\n');
+  }
+
+  getStats(): {
+    totalEntries: number;
+    plugins: string[];
+    totalDuration: number;
+    errorCount: number;
+    warnCount: number;
+  } {
+    const plugins = new Set<string>();
+    let totalDuration = 0;
+    let errorCount = 0;
+    let warnCount = 0;
+
+    for (const entry of this.entries) {
+      const plugin = entry.namespace.split(':')[0] ?? entry.namespace;
+      plugins.add(plugin);
+      totalDuration += entry.duration ?? 0;
+      if (entry.level === 'error') {
+        errorCount += 1;
+      } else if (entry.level === 'warn') {
+        warnCount += 1;
+      }
+    }
+
+    return {
+      totalEntries: this.entries.length,
+      plugins: Array.from(plugins),
+      totalDuration,
+      errorCount,
+      warnCount,
+    };
+  }
+}
+

package/packages/shared-cli-ui/src/debug/components/tree.ts

@@ -0,0 +1,88 @@
+import type { DebugEntry, DebugTreeNode } from '../types';
+import { createDebugTree } from '../utilities';
+import { formatTimelineNode } from '../formatters/timeline';
+
+export interface DebugTreeOptions {
+  showSummary?: boolean;
+  maxDepth?: number;
+}
+
+interface DebugTreeStats {
+  totalDuration: number;
+  errorCount: number;
+  warnCount: number;
+  nodeCount: number;
+}
+
+export class DebugTree {
+  private tree: DebugTreeNode | null = null;
+  private readonly options: DebugTreeOptions;
+
+  constructor(entries: DebugEntry[], options: DebugTreeOptions = {}) {
+    this.options = options;
+    this.tree = createDebugTree(entries);
+  }
+
+  update(entries: DebugEntry[]): void {
+    this.tree = createDebugTree(entries);
+  }
+
+  format(): string {
+    if (!this.tree) {
+      return '';
+    }
+
+    const lines = formatTimelineNode(this.tree, true, '', this.options.maxDepth);
+    if (this.options.showSummary) {
+      const summary = this.getSummary();
+      if (summary) {
+        lines.push('', summary);
+      }
+    }
+    return lines.join('\n');
+  }
+
+  private getSummary(): string {
+    if (!this.tree) {
+      return '';
+    }
+
+    const stats = this.collectStats(this.tree);
+    const parts: string[] = [];
+
+    if (stats.totalDuration > 0) {
+      parts.push(`total ${stats.totalDuration}ms`);
+    }
+    if (stats.errorCount > 0) {
+      parts.push(`${stats.errorCount} errors`);
+    }
+    if (stats.warnCount > 0) {
+      parts.push(`${stats.warnCount} warnings`);
+    }
+    parts.push(`${stats.nodeCount} nodes`);
+
+    return `Summary: ${parts.join(', ')}`;
+  }
+
+  private collectStats(node: DebugTreeNode): DebugTreeStats {
+    let totalDuration = node.entry.duration ?? 0;
+    let errorCount = node.entry.level === 'error' ? 1 : 0;
+    let warnCount = node.entry.level === 'warn' ? 1 : 0;
+    let nodeCount = 1;
+
+    for (const child of node.children) {
+      const childStats = this.collectStats(child);
+      totalDuration += childStats.totalDuration;
+      errorCount += childStats.errorCount;
+      warnCount += childStats.warnCount;
+      nodeCount += childStats.nodeCount;
+    }
+
+    return { totalDuration, errorCount, warnCount, nodeCount };
+  }
+
+  get root(): DebugTreeNode | null {
+    return this.tree;
+  }
+}
+

package/packages/shared-cli-ui/src/debug/formatters/ai.ts

@@ -0,0 +1,17 @@
+import type { DebugEntry, DebugFormat } from '../types';
+
+export function formatDebugEntryAI(entry: DebugEntry): string {
+  return JSON.stringify(entry, null, 2);
+}
+
+export function formatDebugEntriesAI(entries: DebugEntry[]): string {
+  return JSON.stringify(entries, null, 2);
+}
+
+export function shouldUseAIFormat(format?: DebugFormat, jsonMode?: boolean): boolean {
+  if (jsonMode) {
+    return true;
+  }
+  return format === 'ai';
+}
+

package/packages/shared-cli-ui/src/debug/formatters/human.ts

@@ -0,0 +1,98 @@
+import { safeColors, safeSymbols } from '../../colors';
+import type { DebugEntry } from '../types';
+
+export interface HumanFormatterOptions {
+  showTimestamp?: boolean;
+  showDuration?: boolean;
+  groupBy?: 'namespace' | 'group' | 'none';
+}
+
+function formatTimestamp(timestamp: number): string {
+  const date = new Date(timestamp);
+  return date.toISOString();
+}
+
+function formatDuration(duration: number): string {
+  if (duration < 1000) {
+    return `${duration}ms`;
+  }
+  return `${(duration / 1000).toFixed(2)}s`;
+}
+
+export function formatDebugEntryHuman(entry: DebugEntry, options: HumanFormatterOptions = {}): string {
+  const parts: string[] = [];
+
+  if (options.showTimestamp) {
+    parts.push(safeColors.dim(formatTimestamp(entry.timestamp)));
+  }
+
+  parts.push(safeColors.bold(`[${entry.namespace}]`));
+  parts.push(entry.message);
+
+  if (options.showDuration && typeof entry.duration === 'number') {
+    parts.push(safeColors.dim(`(${formatDuration(entry.duration)})`));
+  }
+
+  if (entry.level === 'error') {
+    parts.push(safeColors.error(safeSymbols.error));
+  } else if (entry.level === 'warn') {
+    parts.push(safeColors.warning(safeSymbols.warning));
+  }
+
+  return parts.join(' ');
+}
+
+export function formatDebugEntriesHuman(entries: DebugEntry[], options: HumanFormatterOptions = {}): string {
+  if (entries.length === 0) {
+    return '';
+  }
+
+  const sorted = [...entries].sort((a, b) => a.timestamp - b.timestamp);
+  const lines: string[] = [];
+
+  if (options.groupBy === 'namespace') {
+    const namespaces = new Map<string, DebugEntry[]>();
+    for (const entry of sorted) {
+      if (!namespaces.has(entry.namespace)) {
+        namespaces.set(entry.namespace, []);
+      }
+      namespaces.get(entry.namespace)!.push(entry);
+    }
+
+    for (const [namespace, namespaceEntries] of namespaces) {
+      lines.push(safeColors.bold(namespace));
+      for (const entry of namespaceEntries) {
+        lines.push(`  ${formatDebugEntryHuman(entry, options)}`);
+      }
+      lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+  }
+
+  if (options.groupBy === 'group') {
+    const groups = new Map<string, DebugEntry[]>();
+    for (const entry of sorted) {
+      const groupName = entry.group ?? 'default';
+      if (!groups.has(groupName)) {
+        groups.set(groupName, []);
+      }
+      groups.get(groupName)!.push(entry);
+    }
+
+    for (const [groupName, groupEntries] of groups) {
+      lines.push(safeColors.bold(groupName));
+      for (const entry of groupEntries) {
+        lines.push(`  ${formatDebugEntryHuman(entry, options)}`);
+      }
+      lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+  }
+
+  for (const entry of sorted) {
+    lines.push(formatDebugEntryHuman(entry, options));
+  }
+
+  return lines.join('\n');
+}
+

package/packages/shared-cli-ui/src/debug/formatters/timeline.ts

@@ -0,0 +1,94 @@
+import { safeColors, safeSymbols } from '../../colors';
+import type { DebugEntry, DebugTreeNode } from '../types';
+import { createDebugTree } from '../utilities';
+
+function formatDuration(duration: number): string {
+  if (duration < 1000) {
+    return `${duration}ms`;
+  }
+  return `${(duration / 1000).toFixed(2)}s`;
+}
+
+export function formatTimelineNode(
+  node: DebugTreeNode,
+  isLast: boolean,
+  prefix = '',
+  maxDepth?: number,
+): string[] {
+  const lines: string[] = [];
+  const connector = isLast ? '└─' : '├─';
+  const parts: string[] = [];
+
+  parts.push(safeColors.bold(`[${node.entry.namespace}]`));
+  parts.push(node.entry.message);
+
+  if (typeof node.entry.duration === 'number') {
+    parts.push(safeColors.dim(`(${formatDuration(node.entry.duration)})`));
+  }
+
+  if (node.entry.level === 'error') {
+    parts.push(safeColors.error(safeSymbols.error));
+  } else if (node.entry.level === 'warn') {
+    parts.push(safeColors.warning(safeSymbols.warning));
+  }
+
+  lines.push(`${prefix}${connector} ${parts.join(' ')}`.trimEnd());
+
+  if (maxDepth !== undefined && node.depth + 1 >= maxDepth) {
+    return lines;
+  }
+
+  const childPrefix = prefix + (isLast ? '   ' : '│  ');
+  for (let index = 0; index < node.children.length; index++) {
+    const child = node.children[index];
+    if (!child) {
+      continue;
+    }
+    const childIsLast = index === node.children.length - 1;
+    lines.push(...formatTimelineNode(child, childIsLast, childPrefix, maxDepth));
+  }
+
+  return lines;
+}
+
+export function formatTimeline(entries: DebugEntry[]): string {
+  if (entries.length === 0) {
+    return '';
+  }
+
+  const tree = createDebugTree(entries);
+  if (!tree) {
+    return '';
+  }
+
+  return formatTimelineNode(tree, true).join('\n');
+}
+
+export function formatTimelineWithSummary(entries: DebugEntry[]): string {
+  const timeline = formatTimeline(entries);
+  if (timeline.length === 0) {
+    return '';
+  }
+
+  const totalDuration = entries.reduce((acc, entry) => acc + (entry.duration ?? 0), 0);
+  const errorCount = entries.filter((entry) => entry.level === 'error').length;
+  const warnCount = entries.filter((entry) => entry.level === 'warn').length;
+
+  const summaryParts: string[] = [];
+  if (totalDuration > 0) {
+    summaryParts.push(`Total: ${formatDuration(totalDuration)}`);
+  }
+  if (errorCount > 0) {
+    summaryParts.push(safeColors.error(`${errorCount} errors`));
+  }
+  if (warnCount > 0) {
+    summaryParts.push(safeColors.warning(`${warnCount} warnings`));
+  }
+
+  if (summaryParts.length === 0) {
+    return timeline;
+  }
+
+  return `${timeline}\n\n${safeColors.bold('Summary:')} ${summaryParts.join(', ')}`;
+}
+

package/packages/shared-cli-ui/src/debug/index.ts

@@ -0,0 +1,56 @@
+export type {
+  DebugContext,
+  DebugDetailLevel,
+  DebugEntry,
+  DebugExportOptions,
+  DebugFilterOptions,
+  DebugFormat,
+  DebugLevel,
+  DebugMeta,
+  DebugTreeNode,
+} from './types';
+
+export {
+  formatDebugEntryAI,
+  formatDebugEntriesAI,
+  shouldUseAIFormat,
+} from './formatters/ai';
+
+export {
+  formatDebugEntryHuman,
+  formatDebugEntriesHuman,
+  type HumanFormatterOptions,
+} from './formatters/human';
+
+export { formatTimelineNode, formatTimeline, formatTimelineWithSummary } from './formatters/timeline';
+
+export {
+  DebugOutput,
+  DebugSection,
+  formatDebugOutput,
+  formatDebugOutputs,
+  type DebugOutputOptions,
+} from './components/output';
+
+export { DebugTree, type DebugTreeOptions } from './components/tree';
+
+export { DebugTrace, type TraceOptions } from './components/trace';
+
+export {
+  createDebugTree,
+  describeEntriesAI,
+  describeEntriesHuman,
+  describeEntriesTimeline,
+  exportDebugEntries,
+  exportToChromeFormat,
+  exportToJSON,
+  exportToPlainText,
+  filterByLevel,
+  filterByNamespace,
+  filterByTimeRange,
+  filterDebugEntries,
+  groupByGroup,
+  groupByNamespace,
+  searchInLogs,
+} from './utilities';
+

package/packages/shared-cli-ui/src/debug/types.ts

@@ -0,0 +1,57 @@
+export type DebugLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export type DebugDetailLevel = 'debug' | 'verbose' | 'trace';
+
+export type DebugFormat = 'ai' | 'human';
+
+export type DebugMeta = Record<string, unknown>;
+
+export interface DebugEntry {
+  timestamp: number;
+  namespace: string;
+  level: DebugLevel;
+  message: string;
+  meta?: DebugMeta;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  duration?: number;
+  group?: string;
+  groupDepth?: number;
+}
+
+export interface DebugContext {
+  format?: DebugFormat;
+  detailLevel?: DebugDetailLevel;
+  namespace?: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  groupDepth?: number;
+  enabled?: boolean;
+}
+
+export interface DebugTreeNode {
+  entry: DebugEntry;
+  children: DebugTreeNode[];
+  depth: number;
+}
+
+export interface DebugFilterOptions {
+  namespace?: string | RegExp;
+  level?: DebugLevel | DebugLevel[];
+  timeRange?: {
+    from?: number;
+    to?: number;
+  };
+  search?: string;
+  traceId?: string;
+}
+
+export interface DebugExportOptions {
+  format?: 'json' | 'chrome' | 'text';
+  path?: string;
+  filter?: DebugFilterOptions;
+  includeMeta?: boolean;
+}
+