@vladpazych/dexter 0.1.0

package/src/pipe/format.ts

@@ -0,0 +1,167 @@
+/**
+ * Log formatting for terminal and file output.
+ */
+
+import { bold, dim, gray, red, reset, yellow } from "../terminal/colors.ts"
+import type { LogLevel, PipedEntry } from "./types.ts"
+
+/**
+ * Get terminal width from multiple sources.
+ * Priority: COLUMNS env > stdout.columns > 120
+ */
+function getTerminalWidth(): number {
+  // COLUMNS env var (set by shell or parent)
+  const envColumns = process.env.COLUMNS
+  if (envColumns) {
+    const parsed = parseInt(envColumns, 10)
+    if (!Number.isNaN(parsed) && parsed > 0) return parsed
+  }
+
+  // stdout.columns (works when TTY)
+  if (process.stdout.columns && process.stdout.columns > 0) {
+    return process.stdout.columns
+  }
+
+  // Default fallback
+  return 120
+}
+
+const LEVEL_LABELS: Record<LogLevel, string> = {
+  trace: "T",
+  debug: "D",
+  info: "I",
+  warn: "W",
+  error: "E",
+  fatal: "F",
+}
+
+const LEVEL_COLORS: Record<LogLevel, string> = {
+  trace: gray,
+  debug: dim,
+  info: "",
+  warn: yellow,
+  error: red,
+  fatal: bold + red,
+}
+
+/** Fields to exclude from key=value output */
+const SUPPRESSED = new Set(["level", "time", "pid", "hostname", "name", "msg", "message", "v", "timestamp"])
+
+/**
+ * Format fields as key=value pairs.
+ * @param fields - Log fields
+ * @param maxValueLen - Max length per value (truncate with ...)
+ */
+function formatFields(fields: Record<string, unknown>, maxValueLen = 20): string {
+  const pairs: string[] = []
+
+  for (const [key, value] of Object.entries(fields)) {
+    if (SUPPRESSED.has(key) || value === undefined) continue
+
+    let strValue = typeof value === "string" ? value : JSON.stringify(value)
+    if (strValue.length > maxValueLen) {
+      strValue = `${strValue.slice(0, maxValueLen - 1)}…`
+    }
+    pairs.push(`${key}=${strValue}`)
+  }
+
+  return pairs.join(" ")
+}
+
+/**
+ * Format file:line prefix with fixed-width line number.
+ */
+function formatPrefix(logFile: string, lineNumber: number): string {
+  const line = lineNumber.toString().padEnd(5, " ")
+  return `${logFile}:${line}`
+}
+
+export type FormatTerminalOptions = {
+  /** Terminal width for truncation */
+  width?: number
+  /** Max width per field value */
+  maxValueLen?: number
+}
+
+/**
+ * Strip ANSI escape codes for length calculation.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ANSI pattern
+const ANSI_REGEX = /\x1b\[[0-9;]*m/g
+function stripAnsiLocal(str: string): string {
+  return str.replace(ANSI_REGEX, "")
+}
+
+/**
+ * Format log entry for terminal output.
+ *
+ * Format: "L file:line  message kv..."
+ * - Level character is colored
+ * - Message preserves original ANSI codes (e.g., vite colors)
+ * - Truncated to terminal width
+ * - file:line is clickable in most terminals
+ */
+export function formatTerminal(entry: PipedEntry, options: FormatTerminalOptions = {}): string {
+  const { width = getTerminalWidth(), maxValueLen = 20 } = options
+
+  const label = LEVEL_LABELS[entry.level]
+  const levelColor = LEVEL_COLORS[entry.level]
+  const prefix = formatPrefix(entry.logFile, entry.lineNumber)
+  const kv = formatFields(entry.fields, maxValueLen)
+
+  let message = entry.message
+  let kvPart = kv ? ` ${kv}` : ""
+
+  // Calculate visible length (without ANSI codes)
+  const messagePlain = stripAnsiLocal(message)
+
+  // Fixed parts: "L " + prefix + " "
+  const fixedWidth = 2 + prefix.length + 1
+  const available = width - fixedWidth
+
+  if (available > 0) {
+    const total = messagePlain.length + kvPart.length
+
+    if (total > available) {
+      // Truncate kv first, then message
+      if (kvPart.length > 0 && messagePlain.length < available - 3) {
+        const kvMax = available - messagePlain.length - 4
+        kvPart = kvMax > 0 ? ` ${kv.slice(0, kvMax)}…` : ""
+      } else {
+        kvPart = ""
+        if (messagePlain.length > available - 1) {
+          // Truncate message (approximate - may cut mid-ANSI sequence)
+          const truncLen = available - 2
+          if (truncLen > 0 && truncLen < messagePlain.length) {
+            // Simple truncation for messages with ANSI - preserve some content
+            message = `${message.slice(0, truncLen + (message.length - messagePlain.length))}${reset}…`
+          }
+        }
+      }
+    }
+  }
+
+  // Color only the level character, preserve message colors
+  // Dim the file:line prefix for reduced visual noise
+  const coloredLabel = levelColor ? `${levelColor}${label}${reset}` : label
+  const dimmedPrefix = `${dim}${prefix}${reset}`
+  return `${coloredLabel} ${dimmedPrefix} ${message}${kvPart}`
+}
+
+/**
+ * Format log entry for file output.
+ *
+ * Format: "L HH:MM:SS message kv..."
+ * - No colors (ANSI stripped)
+ * - No truncation (full content)
+ * - No file:line (the file IS the source)
+ */
+export function formatFile(entry: PipedEntry): string {
+  const label = LEVEL_LABELS[entry.level]
+  const time = new Date(entry.timestamp).toISOString().slice(11, 19)
+  const kv = formatFields(entry.fields, 1000) // No truncation
+  const message = stripAnsiLocal(entry.message) // Strip ANSI for file
+
+  const kvPart = kv ? ` ${kv}` : ""
+  return `${label} ${time} ${message}${kvPart}`
+}

package/src/pipe/index.ts

@@ -0,0 +1,4 @@
+export * from "./format.ts"
+export * from "./parse.ts"
+export * from "./spawn.ts"
+export * from "./types.ts"

package/src/pipe/parse.ts

@@ -0,0 +1,131 @@
+/**
+ * Log line parsing.
+ *
+ * Handles both structured JSON (pino, etc.) and raw text output.
+ */
+
+import { stripAnsi } from "../terminal/colors.ts"
+import type { LogEntry, LogLevel } from "./types.ts"
+
+/** Pino numeric level to LogLevel */
+const PINO_LEVELS: Record<number, LogLevel> = {
+  10: "trace",
+  20: "debug",
+  30: "info",
+  40: "warn",
+  50: "error",
+  60: "fatal",
+}
+
+/**
+ * Parse a JSON log line (pino format).
+ * Returns null if not valid JSON or missing required fields.
+ */
+export function parseJson(line: string): LogEntry | null {
+  try {
+    const data = JSON.parse(line) as Record<string, unknown>
+
+    // Pino uses numeric levels
+    if (typeof data.level === "number") {
+      return {
+        level: PINO_LEVELS[data.level] ?? "info",
+        message: (data.msg as string) ?? "",
+        fields: data,
+        timestamp: (data.time as number) ?? Date.now(),
+        raw: line,
+      }
+    }
+
+    // String level (other loggers)
+    if (typeof data.level === "string") {
+      return {
+        level: data.level as LogLevel,
+        message: (data.msg as string) ?? (data.message as string) ?? "",
+        fields: data,
+        timestamp: (data.time as number) ?? (data.timestamp as number) ?? Date.now(),
+        raw: line,
+      }
+    }
+
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Detect log level from raw text content.
+ */
+function detectLevel(text: string): LogLevel {
+  const lower = text.toLowerCase()
+
+  // Error patterns
+  if (
+    lower.includes("error") ||
+    lower.includes("failed") ||
+    lower.includes("exception") ||
+    lower.includes("eaddrinuse") ||
+    lower.includes("enoent") ||
+    lower.includes("eacces") ||
+    text.startsWith("throw ") ||
+    text.includes("Emitted 'error'")
+  ) {
+    return "error"
+  }
+
+  // Stack trace and error object patterns (continuation of error)
+  if (
+    text.trimStart().startsWith("at ") ||
+    text.includes("node:") ||
+    (text.startsWith("    ") && text.includes("(")) ||
+    /^\s*\^$/.test(text) ||
+    /code: '/.test(text) ||
+    /errno:/.test(text) ||
+    /syscall:/.test(text) ||
+    /address:/.test(text) ||
+    /^\s*port:/.test(text) ||
+    /^\s*\}$/.test(text)
+  ) {
+    return "error"
+  }
+
+  // Warning patterns
+  if (lower.includes("warn") || lower.includes("deprecat")) {
+    return "warn"
+  }
+
+  if (lower.includes("debug")) {
+    return "debug"
+  }
+
+  return "info"
+}
+
+/**
+ * Parse a raw text line (non-JSON output).
+ * Returns null for empty lines.
+ * Preserves original ANSI codes in message for terminal passthrough.
+ */
+export function parseRaw(line: string): LogEntry | null {
+  const trimmed = line.trim()
+  if (!trimmed) return null
+
+  // Strip ANSI only for level detection, preserve original in message
+  const cleaned = stripAnsi(trimmed)
+  if (!cleaned) return null
+
+  return {
+    level: detectLevel(cleaned),
+    message: trimmed, // Preserve original ANSI codes
+    fields: {},
+    timestamp: Date.now(),
+    raw: line,
+  }
+}
+
+/**
+ * Parse any log line (JSON or raw).
+ */
+export function parse(line: string): LogEntry | null {
+  return parseJson(line) ?? parseRaw(line)
+}

package/src/pipe/spawn.ts

@@ -0,0 +1,205 @@
+/**
+ * Process spawning with output capture and routing.
+ *
+ * Spawns a child process, captures stdout/stderr, parses each line,
+ * and routes to file and terminal with appropriate formatting.
+ */
+
+import { type ChildProcess, spawn as nodeSpawn } from "node:child_process"
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { createInterface } from "node:readline"
+import { setColorEnabled } from "../terminal/colors.ts"
+import { formatFile, formatTerminal } from "./format.ts"
+import { parse } from "./parse.ts"
+import type { PipedEntry } from "./types.ts"
+
+/**
+ * Find monorepo root by looking for package.json with workspaces.
+ * Falls back to start directory.
+ */
+function findMonorepoRoot(startDir: string): string {
+  let dir = startDir
+  while (dir !== dirname(dir)) {
+    const pkgPath = join(dir, "package.json")
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"))
+        if (pkg.workspaces) {
+          return dir
+        }
+      } catch {
+        // Invalid JSON, continue searching
+      }
+    }
+    dir = dirname(dir)
+  }
+  return startDir
+}
+
+export type PipeOptions = {
+  /** Short name for display and log file (e.g., "api", "web") */
+  name: string
+  /** Command to run */
+  cmd: string
+  /** Command arguments */
+  args: string[]
+  /** Working directory */
+  cwd?: string
+  /**
+   * Log file path. Defaults to `.logs/{name}.log` in monorepo root.
+   * If relative, resolved from cwd.
+   */
+  logFile?: string
+  /** Terminal width for truncation (auto-detected if not specified) */
+  width?: number
+  /** Additional environment variables */
+  env?: Record<string, string>
+  /** Callback for each parsed log entry */
+  onLog?: (entry: PipedEntry) => void
+  /** Callback on process exit */
+  onExit?: (code: number | null) => void
+}
+
+export type PipeHandle = {
+  /** The spawned child process */
+  child: ChildProcess
+  /** Send SIGTERM to the process */
+  stop: () => void
+  /** Promise that resolves when process exits */
+  wait: () => Promise<number | null>
+}
+
+/**
+ * Spawn a process with output piping.
+ *
+ * - Captures stdout/stderr line by line
+ * - Parses each line (JSON or raw)
+ * - Writes full content to log file
+ * - Writes truncated colored output to terminal
+ */
+export function pipe(options: PipeOptions): PipeHandle {
+  // Enable colors for dexter output (override NO_COLOR from parent shell)
+  setColorEnabled(true)
+
+  const cwd = options.cwd ?? process.cwd()
+  const monorepoRoot = findMonorepoRoot(cwd)
+
+  // Default log file: {name}.log in monorepo root
+  const logFile = options.logFile ?? join(monorepoRoot, `${options.name}.log`)
+  const logFilePath = logFile.startsWith("/") ? logFile : resolve(cwd, logFile)
+
+  // Display name is just the short name (e.g., "api", "web")
+  const displayName = options.name
+
+  // Ensure directory exists and truncate file
+  try {
+    mkdirSync(dirname(logFilePath), { recursive: true })
+  } catch {
+    // dir exists
+  }
+  writeFileSync(logFilePath, "")
+
+  let lineNumber = 0
+
+  // Remove NO_COLOR to avoid conflict with our color handling
+  const { NO_COLOR: _, ...cleanEnv } = process.env
+
+  // Get terminal width for output truncation
+  // Priority: explicit option > stdout.columns > COLUMNS env > default
+  let terminalWidth = options.width
+  if (!terminalWidth) {
+    if (process.stdout.columns && process.stdout.columns > 0) {
+      terminalWidth = process.stdout.columns
+    } else if (process.env.COLUMNS) {
+      terminalWidth = parseInt(process.env.COLUMNS, 10) || 120
+    } else {
+      terminalWidth = 120
+    }
+  }
+
+  const child = nodeSpawn(options.cmd, options.args, {
+    cwd,
+    stdio: ["inherit", "pipe", "pipe"],
+    env: {
+      ...cleanEnv,
+      // Pass terminal width to child for proper truncation
+      COLUMNS: String(terminalWidth),
+      // Enable colors in child processes (vite, etc.)
+      FORCE_COLOR: "1",
+      // Enable colors in dexter's output
+      DEXTER_COLOR: "1",
+      ...options.env,
+      // Signal to apps: output JSON for parsing, don't write own files
+      LOG_FORMAT: "json",
+      DEV_RUNNER: "1",
+    },
+  })
+
+  const handleLine = (line: string) => {
+    const parsed = parse(line)
+    if (!parsed) return
+
+    lineNumber++
+
+    const entry: PipedEntry = {
+      ...parsed,
+      source: options.name,
+      logFile: displayName,
+      lineNumber,
+    }
+
+    // Write to file (full content, source of truth)
+    const fileLine = formatFile(entry)
+    appendFileSync(logFilePath, `${fileLine}\n`)
+
+    // Write to terminal (truncated, colored)
+    const terminalLine = formatTerminal(entry, { width: terminalWidth })
+    process.stdout.write(`${terminalLine}\n`)
+
+    // Callback
+    options.onLog?.(entry)
+  }
+
+  // Capture stdout
+  if (child.stdout) {
+    const rl = createInterface({ input: child.stdout })
+    rl.on("line", handleLine)
+  }
+
+  // Capture stderr
+  if (child.stderr) {
+    const rl = createInterface({ input: child.stderr })
+    rl.on("line", handleLine)
+  }
+
+  // Exit handling
+  const exitPromise = new Promise<number | null>((resolve) => {
+    child.on("exit", (code) => {
+      options.onExit?.(code)
+      resolve(code)
+    })
+  })
+
+  // Forward signals
+  const forwardSignal = (signal: NodeJS.Signals) => {
+    process.on(signal, () => child.kill(signal))
+  }
+  forwardSignal("SIGINT")
+  forwardSignal("SIGTERM")
+
+  return {
+    child,
+    stop: () => child.kill("SIGTERM"),
+    wait: () => exitPromise,
+  }
+}
+
+/**
+ * Spawn and wait for exit (convenience wrapper).
+ */
+export async function pipeAndWait(options: PipeOptions): Promise<number> {
+  const handle = pipe(options)
+  const code = await handle.wait()
+  return code ?? 0
+}

package/src/pipe/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Pipe module types.
+ */
+
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal"
+
+export type LogEntry = {
+  /** Log level */
+  level: LogLevel
+  /** Main message */
+  message: string
+  /** Structured fields (from JSON logs) */
+  fields: Record<string, unknown>
+  /** Unix timestamp ms */
+  timestamp: number
+  /** Original raw line */
+  raw: string
+}
+
+export type PipedEntry = LogEntry & {
+  /** Source identifier (e.g., "dimas-server") */
+  source: string
+  /** Log file path */
+  logFile: string
+  /** Line number in log file */
+  lineNumber: number
+}

package/src/terminal/colors.ts

@@ -0,0 +1,95 @@
+/**
+ * ANSI terminal colors with NO_COLOR/FORCE_COLOR support.
+ *
+ * Priority:
+ * 1. DEXTER_COLOR=1 → enabled (dexter override)
+ * 2. NO_COLOR set → disabled (accessibility)
+ * 3. FORCE_COLOR=1 → enabled
+ * 4. TTY detection → enabled if TTY
+ * 5. Default → enabled (dev-friendly default)
+ *
+ * https://no-color.org/
+ */
+
+let _colorEnabled: boolean | null = null
+
+function isColorEnabled(): boolean {
+  if (_colorEnabled !== null) return _colorEnabled
+
+  // Dexter-specific override (highest priority)
+  if (process.env.DEXTER_COLOR === "1") {
+    _colorEnabled = true
+    return true
+  }
+
+  // Explicit disable
+  if (process.env.NO_COLOR && process.env.NO_COLOR !== "0") {
+    _colorEnabled = false
+    return false
+  }
+
+  // Explicit enable
+  if (process.env.FORCE_COLOR === "1") {
+    _colorEnabled = true
+    return true
+  }
+
+  // TTY detection
+  if (process.stdout.isTTY === true) {
+    _colorEnabled = true
+    return true
+  }
+  if (process.stdout.isTTY === false) {
+    _colorEnabled = false
+    return false
+  }
+
+  // Default: enable for better dev experience
+  _colorEnabled = true
+  return true
+}
+
+/** Enable or disable colors programmatically */
+export function setColorEnabled(enabled: boolean): void {
+  _colorEnabled = enabled
+}
+
+/** Raw ANSI codes */
+export const reset = "\x1b[0m"
+export const bold = "\x1b[1m"
+export const dim = "\x1b[2m"
+export const red = "\x1b[31m"
+export const green = "\x1b[32m"
+export const yellow = "\x1b[33m"
+export const blue = "\x1b[34m"
+export const magenta = "\x1b[35m"
+export const cyan = "\x1b[36m"
+export const gray = "\x1b[90m"
+
+/**
+ * Wrap text with color code and reset (respects color enabled).
+ */
+export const wrap = (colorCode: string) => (text: string) => (isColorEnabled() ? `${colorCode}${text}${reset}` : text)
+
+export const c = {
+  reset,
+  bold,
+  dim,
+  red: wrap(red),
+  green: wrap(green),
+  yellow: wrap(yellow),
+  blue: wrap(blue),
+  magenta: wrap(magenta),
+  cyan: wrap(cyan),
+  gray: wrap(gray),
+  dimmed: wrap(dim),
+  bolded: wrap(bold),
+}
+
+/**
+ * Strip ANSI escape codes from string.
+ * Uses Bun's native Zig implementation (6-57x faster than regex).
+ */
+export function stripAnsi(str: string): string {
+  return Bun.stripANSI(str)
+}

package/src/terminal/index.ts

@@ -0,0 +1,16 @@
+export {
+  blue,
+  bold,
+  c,
+  cyan,
+  dim,
+  gray,
+  green,
+  magenta,
+  red,
+  reset,
+  setColorEnabled,
+  stripAnsi,
+  wrap,
+  yellow,
+} from "./colors.ts"

package/src/version.ts

@@ -0,0 +1 @@
+export const version = "0.1.0"