@effect-tui/react 0.1.3 → 0.1.5

package/src/trace/index.tsx

@@ -1,205 +0,0 @@
-// OpenTelemetry trace visualization for Effect programs
-
-import React from "react"
-import { spawn } from "node:child_process"
-import { fileURLToPath } from "node:url"
-import { isAppPath } from "./location.js"
-import * as NodeSdk from "@effect/opentelemetry/NodeSdk"
-import type * as OtelResource from "@effect/opentelemetry/Resource"
-import { Effect, Layer, Logger } from "effect"
-import { createRenderer, createRoot } from "../renderer.js"
-import { useKeyboard } from "../hooks/index.js"
-import { SpanTreeState } from "./span-state.js"
-import { TuiSpanProcessor } from "./span-processor.js"
-import { SpanTree } from "./SpanTree.js"
-import { makeTuiLogger } from "./tui-logger.js"
-import { DiagnosticsPanel } from "../debug/DiagnosticsPanel.js"
-
-export { SpanTreeState } from "./span-state.js"
-export { TuiSpanProcessor } from "./span-processor.js"
-export { SpanTree } from "./SpanTree.js"
-export { makeTuiLogger } from "./tui-logger.js"
-
-const FRAME_INTERVAL_MS = 16 // ~60fps
-const COMPLETION_DELAY_MS = 500
-
-export interface TraceVisualizeOptions {
-  /** Service name for OpenTelemetry resource (default: "effect-app") */
-  serviceName?: string
-  /** Show diagnostics panel inside the trace UI */
-  debugPanel?: boolean
-}
-
-// Wrapper component that drives 60fps render loop
-function SpanTreeWrapper({
-  state,
-  renderer,
-  serviceName,
-  done,
-  showDebug,
-}: {
-  state: SpanTreeState
-  renderer: ReturnType<typeof createRenderer>
-  serviceName?: string
-  done: boolean
-  showDebug?: boolean
-}) {
-  const [, forceUpdate] = React.useState(0)
-
-  const openInEditor = React.useCallback((location: { file: string; line: number; column?: number }) => {
-    const normalizedFile = location.file.startsWith("file://") ? fileURLToPath(location.file) : location.file
-
-    if (!isAppPath(normalizedFile)) {
-      if (process.env.EFFECT_TUI_DEBUG_STACKS === "1") {
-        // eslint-disable-next-line no-console
-        console.error("[effect-tui] refusing to open non-app path", normalizedFile)
-      }
-      return
-    }
-
-    const target =
-      location.column !== undefined
-        ? `${normalizedFile}:${location.line}:${location.column}`
-        : `${normalizedFile}:${location.line}`
-
-    const candidates = [
-      process.env.EFFECT_TUI_EDITOR ? `${process.env.EFFECT_TUI_EDITOR} ${target}` : null,
-      process.env.EDITOR ? `${process.env.EDITOR} ${target}` : null,
-      `code -g ${target}`,
-      `open ${target}`,
-      `xdg-open ${target}`,
-    ].filter(Boolean) as string[]
-
-    for (const cmd of candidates) {
-      try {
-        const child = spawn(cmd, { shell: true, stdio: "ignore", detached: true })
-        child.unref()
-        return
-      } catch {
-        // keep trying next candidate
-      }
-    }
-
-    // eslint-disable-next-line no-console
-    console.error("Could not launch editor. Set EFFECT_TUI_EDITOR or EDITOR to your preferred command.")
-  }, [])
-
-  React.useEffect(() => {
-    const interval = setInterval(() => {
-      state.tick()
-      forceUpdate((n) => n + 1)
-      renderer.requestRender()
-    }, FRAME_INTERVAL_MS)
-    return () => clearInterval(interval)
-  }, [renderer, state])
-
-  // Handle keyboard
-  useKeyboard(
-    React.useCallback(
-      (key) => {
-        // q quits when done (Ctrl+C always works via renderer)
-        if (done && key.text === "q") {
-          process.exit(0)
-        }
-        // Navigate between spans with logs
-        if (key.name === "up") {
-          state.selectPrev()
-        } else if (key.name === "down") {
-          state.selectNext()
-        } else if (key.name === "return" || key.name === "enter") {
-          // Toggle expand selected span's logs
-          state.toggleExpand()
-        } else if (key.name === "char" && key.text?.toLowerCase() === "o") {
-          const loc = state.getOpenTarget()
-          if (loc) {
-            openInEditor(loc)
-          } else {
-            state.toggleExpand()
-          }
-        }
-      },
-      [done, state, openInEditor],
-    ),
-  )
-
-  return (
-    <vstack spacing={1}>
-      <SpanTree state={state} spinnerIndex={state.spinnerIndex} serviceName={serviceName} showExitPrompt={done} />
-      {showDebug && <DiagnosticsPanel title="Trace Diagnostics" />}
-    </vstack>
-  )
-}
-
-/**
- * Run an Effect program with TUI visualization of OpenTelemetry spans.
- *
- * Shows a tree of spans as they execute, with spinners for in-progress
- * and checkmarks/X for completed spans.
- *
- * @example
- * ```ts
- * const program = Effect.gen(function* () {
- *   yield* Effect.sleep(1000).pipe(Effect.withSpan("step-1"))
- *   yield* Effect.sleep(500).pipe(Effect.withSpan("step-2"))
- * }).pipe(Effect.withSpan("main"))
- *
- * await traceVisualize(program)
- * ```
- */
-export const traceVisualize = <A, E, R>(
-  effect: Effect.Effect<A, E, R>,
-  options?: TraceVisualizeOptions,
-): Effect.Effect<void, never, Exclude<R, OtelResource.Resource>> =>
-  Effect.gen(function* () {
-    // Create state and processor
-    const state = new SpanTreeState()
-
-    // Create renderer - handles terminal setup (raw mode, keyboard)
-    const renderer = createRenderer({ mode: "inline" })
-    const root = createRoot(renderer)
-
-    // Connect processor to renderer
-    const requestRender = () => renderer.requestRender()
-    const processor = new TuiSpanProcessor(state, requestRender)
-
-    const serviceName = options?.serviceName ?? "effect-app"
-    const showDebug = options?.debugPanel ?? false
-
-    // Create OpenTelemetry layer
-    const TracerLive = NodeSdk.layer(() => ({
-      resource: { serviceName },
-      spanProcessor: processor,
-    }))
-
-    // Create TUI logger that feeds into state (replaces console logger)
-    const tuiLogger = makeTuiLogger(state, requestRender)
-    const TuiLoggerLive = Logger.replace(Logger.defaultLogger, tuiLogger)
-
-    // Mount React component
-    root.render(
-      <SpanTreeWrapper
-        state={state}
-        renderer={renderer}
-        serviceName={serviceName}
-        done={false}
-        showDebug={showDebug}
-      />,
-    )
-
-    // Combine tracing layer with TUI logger
-    const Live = Layer.merge(TracerLive, TuiLoggerLive)
-
-    // Run the effect with tracing (ignore result, visualization shows success/failure)
-    yield* effect.pipe(Effect.provide(Live), Effect.ignore)
-
-    // Wait a bit for final render
-    yield* Effect.sleep(COMPLETION_DELAY_MS)
-
-    // Show exit prompt - component handles Enter keypress with process.exit(0)
-    root.render(
-      <SpanTreeWrapper state={state} renderer={renderer} serviceName={serviceName} done={true} showDebug={showDebug} />,
-    )
-
-    // Keep process alive until user presses Enter (component will call process.exit)
-    return yield* Effect.never
-  }) as Effect.Effect<void, never, Exclude<R, OtelResource.Resource>>

package/src/trace/location.ts

@@ -1,90 +0,0 @@
-import * as path from "node:path"
-import { fileURLToPath } from "node:url"
-import type { SourceLocation } from "./span-state.js"
-
-const cwd = process.cwd()
-
-export function normalizeFile(file: string): string {
-  if (file.startsWith("file://")) return fileURLToPath(file)
-  return file
-}
-
-export function isAppPath(file: string): boolean {
-  const normalized = normalizeFile(file)
-  if (normalized.includes(`${path.sep}node_modules${path.sep}`)) return false
-  if (normalized.includes(`${path.sep}.bun${path.sep}`)) return false
-  return normalized.startsWith(cwd)
-}
-
-export function isLibraryPath(file: string): boolean {
-  const normalized = normalizeFile(file)
-  return (
-    normalized.includes(`${path.sep}node_modules${path.sep}`) ||
-    normalized.includes("fiberRuntime") ||
-    normalized.includes("native")
-  )
-}
-
-export function pickBestLocation(candidates: SourceLocation[]): SourceLocation | undefined {
-  if (candidates.length === 0) return undefined
-  const app = candidates.find((c) => isAppPath(c.file))
-  if (app) return app
-  const nonLib = candidates.find((c) => !isLibraryPath(c.file))
-  return nonLib ?? candidates[0]
-}
-
-export function parseStackLine(line: string): SourceLocation | undefined {
-  const re = /at\s+(?:.+?\s+\()?((?:file:\/\/)?[^):]+):(\d+):(\d+)\)?$/
-  const match = re.exec(line.trim())
-  if (match) {
-    const file = normalizeFile(match[1]!)
-    return {
-      file,
-      line: Number(match[2]),
-      column: Number(match[3]),
-    }
-  }
-}
-
-export function parseStackTrace(stack?: unknown): SourceLocation | undefined {
-	if (typeof stack !== "string") return
-	const lines = stack.split("\n")
-	const parsed: SourceLocation[] = []
-	for (const line of lines) {
-		const loc = parseStackLine(line)
-		if (loc) parsed.push(loc)
-	}
-	return pickBestLocation(parsed)
-}
-
-export function captureAppLocation(ignore: Array<RegExp | string> = []): SourceLocation | undefined {
-	const prev = Error.prepareStackTrace
-	try {
-		Error.prepareStackTrace = (_err, structured) => structured
-		const err = new Error()
-		Error.captureStackTrace(err, captureAppLocation)
-		const stack = err.stack as unknown as NodeJS.CallSite[] | undefined
-		if (!stack) return
-
-		const isIgnored = (file: string | null | undefined) => {
-			if (!file) return false
-			return ignore.some((p) => typeof p === "string" ? file.includes(p) : p.test(file))
-		}
-
-		const candidates: SourceLocation[] = []
-		for (const frame of stack) {
-			const file = frame.getFileName() || frame.getScriptNameOrSourceURL()
-			if (!file || isIgnored(file)) continue
-			const loc: SourceLocation = {
-				file: normalizeFile(file),
-				line: frame.getLineNumber() ?? 0,
-				column: frame.getColumnNumber() ?? undefined,
-			}
-			candidates.push(loc)
-		}
-
-		return pickBestLocation(candidates)
-	} finally {
-		Error.prepareStackTrace = prev
-	}
-}

package/src/trace/span-processor.ts

@@ -1,65 +0,0 @@
-// Custom SpanProcessor that feeds into TUI visualization
-
-import type { Context, Span } from "@opentelemetry/api"
-import type { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base"
-import { SpanStatusCode } from "@opentelemetry/api"
-import type { SpanTreeState } from "./span-state.js"
-import { captureAppLocation, parseStackTrace } from "./location.js"
-
-/**
- * OpenTelemetry SpanProcessor that updates SpanTreeState for TUI visualization.
- */
-export class TuiSpanProcessor implements SpanProcessor {
-  constructor(
-    private state: SpanTreeState,
-    private onUpdate: () => void,
-  ) {}
-
-  onStart(span: Span, parentContext: Context): void {
-    const spanContext = span.spanContext()
-    const parentSpanContext = parentContext.getValue(Symbol.for("OpenTelemetry Context Key SPAN"))
-    const location = captureAppLocation([/span-processor/, /SpanProcessor/, /@effect-tui\/react/])
-
-    // Extract parent span ID if available
-    let parentId: string | null = null
-    if (parentSpanContext && typeof parentSpanContext === "object" && "spanContext" in parentSpanContext) {
-      const parentCtx = (parentSpanContext as Span).spanContext()
-      parentId = parentCtx.spanId
-    }
-
-    // Get span name - the span object has a private _name, but we can get it from ReadableSpan later
-    // For now use the spanId as placeholder, we'll update on end
-    const name = (span as any).name || spanContext.spanId
-
-    this.state.addSpan(spanContext.spanId, parentId, name, location)
-    this.onUpdate()
-  }
-
-  onEnd(span: ReadableSpan): void {
-    const spanContext = span.spanContext()
-    const status = span.status
-    let location = parseStackTrace((span.attributes as any)?.["code.stacktrace"])
-    if (!location) {
-      location = captureAppLocation([/span-processor/, /SpanProcessor/])
-      if (!location && process.env.EFFECT_TUI_DEBUG_STACKS === "1") {
-        // eslint-disable-next-line no-console
-        console.error("[effect-tui] span end missing location; attributes stack:", (span.attributes as any)?.["code.stacktrace"])
-      }
-    }
-
-    // Determine success/failure from span status
-    const isSuccess = status.code !== SpanStatusCode.ERROR
-    const error = status.code === SpanStatusCode.ERROR ? status.message : undefined
-
-    this.state.endSpan(spanContext.spanId, isSuccess ? "success" : "failure", error, location)
-    this.onUpdate()
-  }
-
-  forceFlush(): Promise<void> {
-    return Promise.resolve()
-  }
-
-  shutdown(): Promise<void> {
-    return Promise.resolve()
-  }
-}

package/src/trace/span-state.ts

@@ -1,286 +0,0 @@
-import { isAppPath } from "./location.js"
-
-// Span tree state for TUI visualization
-
-export type SpanStatus = "running" | "success" | "failure"
-
-export type LogLevel = "INFO" | "WARN" | "ERROR" | "DEBUG" | "TRACE"
-
-export interface SourceLocation {
-  file: string
-  line: number
-  column?: number
-}
-
-export interface LogEntry {
-  level: LogLevel
-  message: string
-  timestamp: number
-  location?: SourceLocation
-}
-
-export interface LogCounts {
-  info: number
-  warn: number
-  error: number
-  debug: number
-  total: number
-}
-
-export interface SpanNode {
-  id: string
-  parentId: string | null
-  name: string
-  status: SpanStatus
-  startTime: number // ms since epoch
-  endTime?: number
-  duration?: number // ms
-  error?: string
-  logEntries: LogEntry[]
-  children: SpanNode[]
-  completedAt?: number // when status changed to success/failure, for fade timing
-  // Animated opacity (0-1, where 1 is fully opaque)
-  opacity: number
-  targetOpacity: number
-  opacityVelocity: number
-  location?: SourceLocation
-}
-
-const SPINNER_FRAMES_COUNT = 6
-const SPIN_INTERVAL_MS = 80
-
-/**
- * Manages span tree state for visualization.
- * Tracks hierarchy, status, and notifies listeners on changes.
- */
-export class SpanTreeState {
-  private roots: SpanNode[] = []
-  private nodesById = new Map<string, SpanNode>()
-  private listeners = new Set<() => void>()
-
-  // Selection state for log navigation
-  selectedSpanId: string | null = null
-  expandedSpanIds = new Set<string>()
-
-  // Animation timing (managed here to decouple from React)
-  spinnerIndex = 0
-  private lastSpinnerTime = performance.now()
-  private lastTickTime = performance.now()
-
-  /** Add a new running span */
-  addSpan(id: string, parentId: string | null, name: string, location?: SourceLocation): void {
-    const node: SpanNode = {
-      id,
-      parentId,
-      name,
-      status: "running",
-      startTime: Date.now(),
-      logEntries: [],
-      children: [],
-      opacity: 1,
-      targetOpacity: 1,
-      opacityVelocity: 0,
-      location,
-    }
-
-    this.nodesById.set(id, node)
-
-    if (parentId) {
-      const parent = this.nodesById.get(parentId)
-      if (parent) {
-        parent.children.push(node)
-      } else {
-        // Parent not found, add as root
-        this.roots.push(node)
-      }
-    } else {
-      this.roots.push(node)
-    }
-
-    this.notify()
-  }
-
-  /** Mark a span as completed */
-  endSpan(id: string, status: "success" | "failure", error?: string, location?: SourceLocation): void {
-    const node = this.nodesById.get(id)
-    if (!node) return
-
-    const endTime = Date.now()
-    node.status = status
-    node.endTime = endTime
-    node.duration = endTime - node.startTime
-    node.completedAt = performance.now() // Use perf time for fade animation timing
-    // Keep opaque for now, fade will start after FADE_DELAY_MS in tickAnimations
-    node.targetOpacity = 1
-    if (error) node.error = error
-    if (location) node.location = location
-
-    this.notify()
-  }
-
-  /** Add a log entry to a span (called by custom logger) */
-  addLog(spanId: string, level: LogLevel, message: string, location?: SourceLocation): void {
-    const node = this.nodesById.get(spanId)
-    if (!node) return
-
-    node.logEntries.push({
-      level,
-      message,
-      timestamp: Date.now(),
-      location,
-    })
-
-    this.notify()
-  }
-
-  /** Get all spans that have logs or captured locations (for navigation) in tree order */
-  getSpansWithLogs(): SpanNode[] {
-    const result: SpanNode[] = []
-    const visit = (node: SpanNode) => {
-      if (node.logEntries.length > 0 || node.location) result.push(node)
-      for (const child of node.children) visit(child)
-    }
-    for (const root of this.roots) visit(root)
-    return result
-  }
-
-  /** Select next span with logs */
-  selectNext(): void {
-    const spans = this.getSpansWithLogs()
-    if (spans.length === 0) return
-
-    if (this.selectedSpanId === null) {
-      this.selectedSpanId = spans[0]?.id
-    } else {
-      const idx = spans.findIndex((s) => s.id === this.selectedSpanId)
-      if (idx < spans.length - 1) {
-        this.selectedSpanId = spans[idx + 1]?.id
-      }
-    }
-    this.notify()
-  }
-
-  /** Select previous span with logs */
-  selectPrev(): void {
-    const spans = this.getSpansWithLogs()
-    if (spans.length === 0) return
-
-    if (this.selectedSpanId === null) {
-      this.selectedSpanId = spans[spans.length - 1]?.id
-    } else {
-      const idx = spans.findIndex((s) => s.id === this.selectedSpanId)
-      if (idx > 0) {
-        this.selectedSpanId = spans[idx - 1]?.id
-      }
-    }
-    this.notify()
-  }
-
-  /** Toggle expansion of selected span */
-  toggleExpand(): void {
-    if (this.selectedSpanId === null) return
-
-    if (this.expandedSpanIds.has(this.selectedSpanId)) {
-      this.expandedSpanIds.delete(this.selectedSpanId)
-    } else {
-      this.expandedSpanIds.add(this.selectedSpanId)
-    }
-    this.notify()
-  }
-
-  /** Tick animations (spinner + fades). Call at 60fps for smooth rendering. */
-  tick(): void {
-    const now = performance.now()
-    // Cap dt to prevent large jumps when frames are delayed (GC, etc.)
-    const dt = Math.min((now - this.lastTickTime) / 1000, 0.05)
-    this.lastTickTime = now
-
-    // Advance spinner at its own rate
-    if (now - this.lastSpinnerTime >= SPIN_INTERVAL_MS) {
-      this.spinnerIndex = (this.spinnerIndex + 1) % SPINNER_FRAMES_COUNT
-      this.lastSpinnerTime = now
-    }
-
-    // Fade animations
-    const fadeDelayMs = 1000
-    const halfLife = 0.3
-    const decay = 0.5 ** (dt / halfLife)
-    const epsilon = 0.01
-
-    for (const node of this.nodesById.values()) {
-      // Check if completed span should start fading
-      if (node.completedAt && node.targetOpacity === 1) {
-        if (now - node.completedAt >= fadeDelayMs) {
-          node.targetOpacity = 0.4 // Start fading
-        }
-      }
-
-      const diff = Math.abs(node.opacity - node.targetOpacity)
-      if (diff > epsilon) {
-        // Exponential decay toward target - unconditionally stable
-        node.opacity = node.targetOpacity + (node.opacity - node.targetOpacity) * decay
-      } else if (diff > 0) {
-        // Snap to target when close enough
-        node.opacity = node.targetOpacity
-      }
-    }
-  }
-
-  /** Get all root spans */
-  getRoots(): readonly SpanNode[] {
-    return this.roots
-  }
-
-  /** Get a span by ID */
-  getSpan(id: string): SpanNode | undefined {
-    return this.nodesById.get(id)
-  }
-
-  /** Best-effort source location for the currently selected span or its logs */
-  getOpenTarget(): SourceLocation | null {
-    if (!this.selectedSpanId) return null
-    const node = this.nodesById.get(this.selectedSpanId)
-    if (!node) return null
-    let fallback: SourceLocation | undefined
-
-    // Prefer app-path log entries (latest first)
-    for (let i = node.logEntries.length - 1; i >= 0; i--) {
-      const entry = node.logEntries[i]
-      if (entry.location) {
-        if (isAppPath(entry.location.file)) return entry.location
-        if (!fallback) fallback = entry.location
-      }
-    }
-
-    if (node.location) {
-      if (isAppPath(node.location.file)) return node.location
-      if (!fallback) fallback = node.location
-    }
-
-    if (!fallback) return null
-    if (process.env.EFFECT_TUI_DEBUG_STACKS === "1") {
-      // eslint-disable-next-line no-console
-      console.error("[effect-tui] only non-app locations available", fallback)
-    }
-
-    return null
-  }
-
-  /** Check if any spans are still running */
-  hasRunning(): boolean {
-    for (const node of this.nodesById.values()) {
-      if (node.status === "running") return true
-    }
-    return false
-  }
-
-  /** Subscribe to state changes */
-  subscribe(listener: () => void): () => void {
-    this.listeners.add(listener)
-    return () => this.listeners.delete(listener)
-  }
-
-  private notify(): void {
-    this.listeners.forEach((l) => l())
-  }
-}