@doriandev/devcc 0.1.2

package/src/devcc/logs/LogBuffer.ts

@@ -0,0 +1,237 @@
+import { TypedEmitter } from "../core/events.js"
+
+/** Default cap for a single source's in-memory history. */
+export const MAX_LOG_LINES = 5_000
+
+export type LogStream = "stdout" | "stderr" | "system"
+
+export interface LogEntry {
+  /** Monotonic per-buffer sequence number; used for cheap "has it changed?" checks. */
+  seq: number
+  timestamp: Date
+  stream: LogStream
+  text: string
+}
+
+/**
+ * Fixed-capacity ring buffer.
+ *
+ * Memory is bounded by construction: once `capacity` lines are stored, each new
+ * line overwrites the oldest one. Nothing else in the app is allowed to retain
+ * log lines.
+ */
+export class LogBuffer {
+  private readonly entries: (LogEntry | undefined)[]
+  private writeIndex = 0
+  private count = 0
+  private nextSeq = 0
+  private pendingPartial = { stdout: "", stderr: "", system: "" }
+
+  constructor(
+    readonly id: string,
+    readonly capacity: number = MAX_LOG_LINES,
+  ) {
+    if (capacity <= 0) throw new RangeError("LogBuffer capacity must be > 0")
+    this.entries = new Array<LogEntry | undefined>(capacity)
+  }
+
+  get size(): number {
+    return this.count
+  }
+
+  /** Total lines ever written, including evicted ones. */
+  get totalWritten(): number {
+    return this.nextSeq
+  }
+
+  /** True when the oldest lines have been dropped. */
+  get truncated(): boolean {
+    return this.nextSeq > this.capacity
+  }
+
+  push(text: string, stream: LogStream = "stdout", timestamp: Date = new Date()): LogEntry {
+    const entry: LogEntry = { seq: this.nextSeq++, timestamp, stream, text: stripControlSequences(text) }
+    this.entries[this.writeIndex] = entry
+    this.writeIndex = (this.writeIndex + 1) % this.capacity
+    if (this.count < this.capacity) this.count += 1
+    return entry
+  }
+
+  /**
+   * Feed a raw chunk from a child process. Splits on newlines and holds back an
+   * unterminated trailing fragment until the rest arrives.
+   */
+  pushChunk(chunk: string, stream: LogStream = "stdout"): LogEntry[] {
+    const combined = this.pendingPartial[stream] + chunk
+    const parts = combined.split(/\r?\n/u)
+    this.pendingPartial[stream] = parts.pop() ?? ""
+    return parts.map((line) => this.push(stripTrailingCarriage(line), stream))
+  }
+
+  /** Flush a held-back partial line (call when the stream closes). */
+  flush(stream?: LogStream): LogEntry[] {
+    const streams: LogStream[] = stream ? [stream] : ["stdout", "stderr", "system"]
+    const flushed: LogEntry[] = []
+    for (const name of streams) {
+      const partial = this.pendingPartial[name]
+      if (partial.length > 0) {
+        this.pendingPartial[name] = ""
+        flushed.push(this.push(stripTrailingCarriage(partial), name))
+      }
+    }
+    return flushed
+  }
+
+  /** Entries in chronological order. */
+  toArray(): LogEntry[] {
+    const result: LogEntry[] = []
+    const start = this.count < this.capacity ? 0 : this.writeIndex
+    for (let i = 0; i < this.count; i += 1) {
+      const entry = this.entries[(start + i) % this.capacity]
+      if (entry) result.push(entry)
+    }
+    return result
+  }
+
+  /** The most recent `n` entries, chronologically ordered. */
+  tail(n: number): LogEntry[] {
+    if (n <= 0) return []
+    const all = this.toArray()
+    return all.slice(Math.max(0, all.length - n))
+  }
+
+  /** A window of the chronological history, used by the scrolling log viewer. */
+  slice(offset: number, length: number): LogEntry[] {
+    const all = this.toArray()
+    const start = Math.max(0, Math.min(offset, all.length))
+    return all.slice(start, start + Math.max(0, length))
+  }
+
+  clear(): void {
+    this.entries.fill(undefined)
+    this.writeIndex = 0
+    this.count = 0
+    this.pendingPartial = { stdout: "", stderr: "", system: "" }
+  }
+}
+
+export interface LogSource {
+  id: string
+  label: string
+}
+
+export type LogStoreEvents = {
+  "log:append": [string, LogEntry[]]
+  "log:clear": [string]
+  "log:sources": [LogSource[]]
+}
+
+/**
+ * Owns one `LogBuffer` per source (managed process, script run, or devcc itself)
+ * and announces changes so the Logs view can update without polling.
+ */
+export class LogStore extends TypedEmitter<LogStoreEvents> {
+  private readonly buffers = new Map<string, LogBuffer>()
+  private readonly labels = new Map<string, string>()
+
+  constructor(private readonly capacity: number = MAX_LOG_LINES) {
+    super()
+  }
+
+  register(id: string, label: string): LogBuffer {
+    const existing = this.buffers.get(id)
+    if (existing) {
+      if (this.labels.get(id) !== label) {
+        this.labels.set(id, label)
+        this.emit("log:sources", this.sources())
+      }
+      return existing
+    }
+    const buffer = new LogBuffer(id, this.capacity)
+    this.buffers.set(id, buffer)
+    this.labels.set(id, label)
+    this.emit("log:sources", this.sources())
+    return buffer
+  }
+
+  unregister(id: string): void {
+    if (this.buffers.delete(id)) {
+      this.labels.delete(id)
+      this.emit("log:sources", this.sources())
+    }
+  }
+
+  get(id: string): LogBuffer | undefined {
+    return this.buffers.get(id)
+  }
+
+  has(id: string): boolean {
+    return this.buffers.has(id)
+  }
+
+  sources(): LogSource[] {
+    return [...this.buffers.keys()].map((id) => ({ id, label: this.labels.get(id) ?? id }))
+  }
+
+  append(id: string, text: string, stream: LogStream = "system"): void {
+    const buffer = this.buffers.get(id) ?? this.register(id, id)
+    const entry = buffer.push(text, stream)
+    this.emit("log:append", id, [entry])
+  }
+
+  appendChunk(id: string, chunk: string, stream: LogStream): void {
+    const buffer = this.buffers.get(id) ?? this.register(id, id)
+    const entries = buffer.pushChunk(chunk, stream)
+    if (entries.length > 0) this.emit("log:append", id, entries)
+  }
+
+  flush(id: string): void {
+    const buffer = this.buffers.get(id)
+    if (!buffer) return
+    const entries = buffer.flush()
+    if (entries.length > 0) this.emit("log:append", id, entries)
+  }
+
+  clear(id: string): void {
+    this.buffers.get(id)?.clear()
+    this.emit("log:clear", id)
+  }
+
+  clearAll(): void {
+    for (const id of this.buffers.keys()) this.clear(id)
+  }
+}
+
+function stripTrailingCarriage(line: string): string {
+  return line.endsWith("\r") ? line.slice(0, -1) : line
+}
+
+const ESC = String.fromCharCode(27)
+const BEL = String.fromCharCode(7)
+/** CSI sequences (`ESC [ ... final`), including screen clears and cursor moves. */
+const CSI_SEQUENCE = new RegExp(`${ESC}\\[[0-?]*[ -/]*[@-~]`, "gu")
+/** OSC sequences (`ESC ] ... BEL` or `ESC ] ... ESC \\`), e.g. window titles and hyperlinks. */
+const OSC_SEQUENCE = new RegExp(`${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "gu")
+/**
+ * Two-byte escapes such as `ESC c` (reset) and `ESC 7`/`ESC 8` (save/restore
+ * cursor). Any printable after a bare ESC is an escape by definition.
+ */
+const SIMPLE_ESCAPE = new RegExp(`${ESC}[0-~]`, "gu")
+/** Remaining C0 controls apart from tab. Matching control characters is the point here. */
+// eslint-disable-next-line no-control-regex
+const C0_CONTROLS = /[\u0000-\u0008\u000b-\u001f\u007f]/gu
+
+/**
+ * Remove terminal control sequences from a captured line.
+ *
+ * Children are told `FORCE_COLOR=0`, but watchers such as `tsc --watch` still
+ * clear the screen and move the cursor; rendered verbatim those bytes would
+ * corrupt the viewer (or, in the merged stream, someone else's line).
+ */
+export function stripControlSequences(text: string): string {
+  return text
+    .replace(CSI_SEQUENCE, "")
+    .replace(OSC_SEQUENCE, "")
+    .replace(SIMPLE_ESCAPE, "")
+    .replace(C0_CONTROLS, "")
+}

package/src/devcc/logs/merge.ts

@@ -0,0 +1,87 @@
+import type { LogBuffer, LogEntry } from "./LogBuffer.js"
+
+/** A log line that knows which source it came from. */
+export interface SourcedLogEntry {
+  sourceId: string
+  entry: LogEntry
+}
+
+/** The synthetic source id that shows every buffer merged into one stream. */
+export const ALL_SOURCES = "*"
+
+/** Upper bound on how many lines the merged stream materialises at once. */
+export const MERGED_LIMIT = 2_000
+
+/**
+ * Merge the tails of several chronological buffers into one chronological
+ * stream, bounded by `limit` lines in total.
+ *
+ * Each buffer is already ordered, so taking the last `limit` of each and
+ * sorting once is both simple and cheap enough for a few thousand lines.
+ * Ties on timestamp fall back to sequence number, which is per-buffer, so a
+ * stable sort keeps the input order between buffers.
+ */
+export function mergeTails(buffers: readonly LogBuffer[], limit: number = MERGED_LIMIT): SourcedLogEntry[] {
+  if (limit <= 0) return []
+
+  const combined: SourcedLogEntry[] = []
+  for (const buffer of buffers) {
+    for (const entry of buffer.tail(limit)) combined.push({ sourceId: buffer.id, entry })
+  }
+
+  combined.sort((a, b) => {
+    const byTime = a.entry.timestamp.getTime() - b.entry.timestamp.getTime()
+    if (byTime !== 0) return byTime
+    if (a.sourceId === b.sourceId) return a.entry.seq - b.entry.seq
+    return 0
+  })
+
+  return combined.length > limit ? combined.slice(combined.length - limit) : combined
+}
+
+export interface LogFilter {
+  /** Case-insensitive substring, or a regular expression if it parses as one. */
+  query: string
+  /** Show only stderr lines. */
+  errorsOnly: boolean
+}
+
+export const EMPTY_LOG_FILTER: LogFilter = { query: "", errorsOnly: false }
+
+/**
+ * Compile a user query. Anything that fails to parse as a regex is treated as
+ * a literal, so typing `(` never breaks the view.
+ */
+export function compileQuery(query: string): ((text: string) => boolean) | null {
+  const trimmed = query.trim()
+  if (trimmed === "") return null
+
+  try {
+    const pattern = new RegExp(trimmed, "iu")
+    return (text) => pattern.test(text)
+  } catch {
+    const needle = trimmed.toLowerCase()
+    return (text) => text.toLowerCase().includes(needle)
+  }
+}
+
+export function filterEntries(entries: readonly SourcedLogEntry[], filter: LogFilter): SourcedLogEntry[] {
+  const matches = compileQuery(filter.query)
+  if (!matches && !filter.errorsOnly) return [...entries]
+
+  return entries.filter(({ entry }) => {
+    if (filter.errorsOnly && entry.stream !== "stderr") return false
+    return matches ? matches(entry.text) : true
+  })
+}
+
+export function isFilterActive(filter: LogFilter): boolean {
+  return filter.query.trim() !== "" || filter.errorsOnly
+}
+
+export function describeFilter(filter: LogFilter): string {
+  const parts: string[] = []
+  if (filter.query.trim() !== "") parts.push(`/${filter.query.trim()}/`)
+  if (filter.errorsOnly) parts.push("errors only")
+  return parts.join(" · ")
+}

package/src/devcc/processes/ManagedProcess.ts

@@ -0,0 +1,195 @@
+/**
+ * Types and pure helpers describing a process Dev Command Center knows about.
+ *
+ * `ownership` is the safety boundary: `"managed"` processes were launched by us
+ * and may be signalled; `"detected"` processes were merely observed on the host
+ * and must never be killed by devcc.
+ */
+
+export type ProcessStatus = "stopped" | "starting" | "running" | "stopping" | "failed"
+
+export type ProcessOwnership = "managed" | "detected"
+
+/** `service` processes are long-running; `task` processes are expected to exit. */
+export type ProcessKind = "service" | "task"
+
+export interface ProcessDefinition {
+  id: string
+  name: string
+  command: string
+  args?: string[]
+  cwd?: string
+  env?: Record<string, string>
+  kind?: ProcessKind
+  /** Start automatically when devcc launches. */
+  autoStart?: boolean
+  /** Informational URL shown next to the process (e.g. `localhost:3000`). */
+  url?: string
+  /** Port to probe for a readiness indicator. */
+  port?: number
+  /** Milliseconds to wait after SIGTERM before escalating to SIGKILL. */
+  killGraceMs?: number
+  /**
+   * Bring the process back up automatically when it exits non-zero.
+   * Opt-in per process: devcc never resurrects something you stopped yourself.
+   */
+  restartOnCrash?: boolean
+  /** Give up after this many consecutive crashes (default 5). */
+  maxCrashRestarts?: number
+  /** First backoff delay; doubles per consecutive crash (default 1000ms). */
+  crashBackoffMs?: number
+  /** Upper bound on the backoff delay (default 30000ms). */
+  maxCrashBackoffMs?: number
+  /**
+   * A run lasting at least this long is considered healthy, which resets the
+   * crash counter (default 30000ms).
+   */
+  healthyAfterMs?: number
+  /**
+   * Ids of processes that must be *ready* before this one starts. Used by
+   * "start all" and autostart to bring a stack up in order.
+   */
+  dependsOn?: string[]
+  /**
+   * How devcc decides the process is usable. Until it passes, the process is
+   * reported as `starting` rather than `running`. Without one, a process is
+   * considered ready the moment it has spawned.
+   */
+  readiness?: ReadinessCheck
+}
+
+export interface ReadinessCheck {
+  /** Ready once something accepts a TCP connection on this port. */
+  port?: number
+  host?: string
+  /** Ready once a line of output matches this regular expression. */
+  logPattern?: string
+  /** Give up waiting after this long and report `running` anyway (default 30000). */
+  timeoutMs?: number
+  /** How often to probe the port (default 250). */
+  intervalMs?: number
+}
+
+export const DEFAULT_READINESS = {
+  timeoutMs: 30_000,
+  intervalMs: 250,
+} as const
+
+export const DEFAULT_CRASH_POLICY = {
+  maxCrashRestarts: 5,
+  crashBackoffMs: 1_000,
+  maxCrashBackoffMs: 30_000,
+  healthyAfterMs: 30_000,
+} as const
+
+export interface ManagedProcess {
+  id: string
+  name: string
+  command: string
+  args?: string[]
+  cwd?: string
+  status: ProcessStatus
+  pid?: number
+  startedAt?: Date
+  exitCode?: number
+  /** Signal that terminated the process, when it was signalled. */
+  exitSignal?: string
+  stoppedAt?: Date
+  kind: ProcessKind
+  ownership: ProcessOwnership
+  url?: string
+  port?: number
+  /** How many times the user has restarted it this session. */
+  restarts: number
+  /** Consecutive automatic restarts since the last healthy run. */
+  crashRestarts: number
+  /** When an automatic restart is scheduled, the time it will happen. */
+  retryAt?: Date
+  /** True once devcc has given up automatically restarting this process. */
+  crashRestartsExhausted?: boolean
+  /** Last failure message, cleared on a successful start. */
+  lastError?: string
+  /** Ids this process waits for before starting. */
+  dependsOn: string[]
+  /** True once the readiness check has passed (or there is none). */
+  ready: boolean
+  /** Set when the readiness check timed out and the process was reported anyway. */
+  readinessTimedOut?: boolean
+}
+
+export const ACTIVE_STATUSES: readonly ProcessStatus[] = ["starting", "running", "stopping"]
+
+export function isActive(status: ProcessStatus): boolean {
+  return ACTIVE_STATUSES.includes(status)
+}
+
+const TRANSITIONS: Record<ProcessStatus, readonly ProcessStatus[]> = {
+  stopped: ["starting"],
+  starting: ["running", "failed", "stopping", "stopped"],
+  running: ["stopping", "stopped", "failed"],
+  stopping: ["stopped", "failed"],
+  failed: ["starting"],
+}
+
+/** Whether a status change is legal. Keeps the manager's bookkeeping honest. */
+export function canTransition(from: ProcessStatus, to: ProcessStatus): boolean {
+  if (from === to) return false
+  return TRANSITIONS[from].includes(to)
+}
+
+/** Build the initial snapshot for a definition. */
+export function createManagedProcess(
+  definition: ProcessDefinition,
+  ownership: ProcessOwnership = "managed",
+): ManagedProcess {
+  return {
+    id: definition.id,
+    name: definition.name,
+    command: definition.command,
+    args: definition.args ? [...definition.args] : undefined,
+    cwd: definition.cwd,
+    status: "stopped",
+    kind: definition.kind ?? "service",
+    ownership,
+    url: definition.url,
+    port: definition.port,
+    restarts: 0,
+    crashRestarts: 0,
+    dependsOn: definition.dependsOn ? [...definition.dependsOn] : [],
+    ready: false,
+  }
+}
+
+/**
+ * Exponential backoff for automatic restarts.
+ *
+ * `attempt` is 1-based: the first restart waits `base`, the second `2 * base`,
+ * and so on, capped at `max`. Keeping this a pure function makes the policy
+ * testable without spawning anything.
+ */
+export function crashBackoffDelay(
+  attempt: number,
+  base: number = DEFAULT_CRASH_POLICY.crashBackoffMs,
+  max: number = DEFAULT_CRASH_POLICY.maxCrashBackoffMs,
+): number {
+  if (attempt <= 0) return 0
+  const safeBase = Math.max(0, base)
+  const exponent = Math.min(attempt - 1, 30)
+  return Math.min(Math.max(0, max), safeBase * 2 ** exponent)
+}
+
+/** Whether a crashed process should be brought back up automatically. */
+export function shouldAutoRestart(
+  definition: Pick<ProcessDefinition, "restartOnCrash" | "maxCrashRestarts">,
+  snapshot: Pick<ManagedProcess, "crashRestarts">,
+): boolean {
+  if (!definition.restartOnCrash) return false
+  const limit = definition.maxCrashRestarts ?? DEFAULT_CRASH_POLICY.maxCrashRestarts
+  return snapshot.crashRestarts < limit
+}
+
+/** Human-readable one-liner of what will actually be executed. */
+export function describeCommand(process: Pick<ManagedProcess, "command" | "args">): string {
+  const args = process.args ?? []
+  return args.length > 0 ? `${process.command} ${args.join(" ")}` : process.command
+}