@doriandev/devcc 0.1.2

package/src/devcc/system/SystemMonitor.ts

@@ -0,0 +1,207 @@
+import { statfs } from "node:fs/promises"
+import { arch, cpus, freemem, homedir, hostname, loadavg, platform, release, totalmem, uptime } from "node:os"
+import { TypedEmitter } from "../core/events.js"
+import { exec } from "../utils/exec.js"
+
+export interface CpuSample {
+  idle: number
+  total: number
+}
+
+export interface DiskUsage {
+  total: number
+  free: number
+  used: number
+  ratio: number
+}
+
+export interface SystemMetrics {
+  /** 0..1, averaged across cores since the previous sample. */
+  cpu: number
+  memoryTotal: number
+  memoryFree: number
+  memoryUsed: number
+  memoryRatio: number
+  loadAverage: [number, number, number]
+  /** Host uptime in milliseconds. */
+  uptimeMs: number
+  /** devcc's own uptime in milliseconds. */
+  processUptimeMs: number
+  disk: DiskUsage | null
+  sampledAt: Date
+}
+
+export interface HostInfo {
+  hostname: string
+  platform: string
+  release: string
+  arch: string
+  cpuModel: string
+  cpuCount: number
+  totalMemory: number
+  home: string
+  runtime: string
+  nodeVersion: string
+}
+
+/** Versions of external tools; populated lazily so startup is never blocked. */
+export interface ToolVersions {
+  git: string | null
+  docker: string | null
+  packageManager: string | null
+}
+
+export type SystemMonitorEvents = {
+  "system:metrics": [SystemMetrics]
+  "system:tools": [ToolVersions]
+}
+
+/** Aggregate `os.cpus()` times into idle/total counters. */
+export function sampleCpu(cpuInfos: ReturnType<typeof cpus> = cpus()): CpuSample {
+  let idle = 0
+  let total = 0
+  for (const cpu of cpuInfos) {
+    idle += cpu.times.idle
+    total += cpu.times.user + cpu.times.nice + cpu.times.sys + cpu.times.idle + cpu.times.irq
+  }
+  return { idle, total }
+}
+
+/**
+ * CPU utilisation between two samples, as a 0..1 ratio.
+ * Returns 0 when the samples are identical (no elapsed time).
+ */
+export function cpuUsageBetween(previous: CpuSample, current: CpuSample): number {
+  const idleDelta = current.idle - previous.idle
+  const totalDelta = current.total - previous.total
+  if (totalDelta <= 0) return 0
+  const usage = 1 - idleDelta / totalDelta
+  return Math.max(0, Math.min(1, usage))
+}
+
+export function detectRuntime(): string {
+  const bunVersion = (globalThis as { Bun?: { version: string } }).Bun?.version
+  if (bunVersion) return `bun ${bunVersion}`
+  return `node ${process.versions.node}`
+}
+
+export interface SystemMonitorOptions {
+  rootDir: string
+  intervalMs?: number
+}
+
+/**
+ * Samples host metrics on a timer using Node APIs only.
+ *
+ * The one exception is tool versions (`git`, `docker`), which have no API; those
+ * are read once, lazily, off the startup path.
+ */
+export class SystemMonitor extends TypedEmitter<SystemMonitorEvents> {
+  private timer: NodeJS.Timeout | null = null
+  private previousSample: CpuSample = sampleCpu()
+  private metrics: SystemMetrics | null = null
+  private tools: ToolVersions = { git: null, docker: null, packageManager: null }
+  private readonly intervalMs: number
+  private readonly startedAt = Date.now()
+
+  constructor(private readonly options: SystemMonitorOptions) {
+    super()
+    this.intervalMs = options.intervalMs ?? 1_500
+  }
+
+  getMetrics(): SystemMetrics | null {
+    return this.metrics
+  }
+
+  getTools(): ToolVersions {
+    return this.tools
+  }
+
+  getHostInfo(): HostInfo {
+    const cpuList = cpus()
+    return {
+      hostname: hostname(),
+      platform: platform(),
+      release: release(),
+      arch: arch(),
+      cpuModel: cpuList[0]?.model.trim() ?? "unknown",
+      cpuCount: cpuList.length,
+      totalMemory: totalmem(),
+      home: homedir(),
+      runtime: detectRuntime(),
+      nodeVersion: process.versions.node,
+    }
+  }
+
+  start(): void {
+    if (this.timer) return
+    void this.sample()
+    this.timer = setInterval(() => void this.sample(), this.intervalMs)
+    this.timer.unref?.()
+  }
+
+  stop(): void {
+    if (!this.timer) return
+    clearInterval(this.timer)
+    this.timer = null
+  }
+
+  async sample(): Promise<SystemMetrics> {
+    const current = sampleCpu()
+    const cpu = cpuUsageBetween(this.previousSample, current)
+    this.previousSample = current
+
+    const total = totalmem()
+    const free = freemem()
+    const [one = 0, five = 0, fifteen = 0] = loadavg()
+
+    const metrics: SystemMetrics = {
+      cpu,
+      memoryTotal: total,
+      memoryFree: free,
+      memoryUsed: total - free,
+      memoryRatio: total > 0 ? (total - free) / total : 0,
+      loadAverage: [one, five, fifteen],
+      uptimeMs: uptime() * 1000,
+      processUptimeMs: Date.now() - this.startedAt,
+      disk: await this.readDisk(),
+      sampledAt: new Date(),
+    }
+
+    this.metrics = metrics
+    this.emit("system:metrics", metrics)
+    return metrics
+  }
+
+  /** Read tool versions once. Safe to call repeatedly; results are cached. */
+  async refreshTools(packageManager: string): Promise<ToolVersions> {
+    const [git, docker, pm] = await Promise.all([
+      versionOf("git", ["--version"], /git version (\S+)/u),
+      versionOf("docker", ["--version"], /Docker version ([^,\s]+)/u),
+      versionOf(packageManager, ["--version"], /(\S+)/u),
+    ])
+    this.tools = { git, docker, packageManager: pm }
+    this.emit("system:tools", this.tools)
+    return this.tools
+  }
+
+  private async readDisk(): Promise<DiskUsage | null> {
+    try {
+      const stats = await statfs(this.options.rootDir)
+      const total = Number(stats.blocks) * Number(stats.bsize)
+      const free = Number(stats.bavail) * Number(stats.bsize)
+      if (!Number.isFinite(total) || total <= 0) return null
+      const used = total - free
+      return { total, free, used, ratio: used / total }
+    } catch {
+      return null
+    }
+  }
+}
+
+async function versionOf(command: string, args: string[], pattern: RegExp): Promise<string | null> {
+  const result = await exec(command, args, { timeoutMs: 3_000 })
+  if (!result.ok) return null
+  const text = result.stdout.trim().split("\n")[0] ?? ""
+  return pattern.exec(text)?.[1] ?? (text === "" ? null : text)
+}

package/src/devcc/utils/errors.ts

@@ -0,0 +1,64 @@
+/**
+ * A single, consistent error model for everything Dev Command Center does.
+ *
+ * Every failure that reaches the UI is normalised into a `DevccError` so the
+ * notification centre, the log file and the diagnostics panel can all render it
+ * the same way.
+ */
+
+export type DevccErrorScope =
+  "config" | "process" | "script" | "git" | "docker" | "service" | "system" | "command" | "internal"
+
+export interface DevccErrorOptions {
+  scope: DevccErrorScope
+  /** Short, user facing summary. Shown in the notification area. */
+  message: string
+  /** Longer text (command output, stack, ...) shown when the error is inspected. */
+  detail?: string
+  cause?: unknown
+  /** Whether the application can keep running normally. Defaults to `true`. */
+  recoverable?: boolean
+}
+
+export class DevccError extends Error {
+  readonly scope: DevccErrorScope
+  readonly detail?: string
+  readonly recoverable: boolean
+
+  constructor(options: DevccErrorOptions) {
+    super(options.message, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = "DevccError"
+    this.scope = options.scope
+    this.detail = options.detail
+    this.recoverable = options.recoverable ?? true
+  }
+}
+
+/** Best-effort message extraction from an unknown thrown value. */
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message
+  if (typeof error === "string") return error
+  try {
+    return JSON.stringify(error)
+  } catch {
+    return String(error)
+  }
+}
+
+/** Stack (or message) of an unknown thrown value, for the log file. */
+export function errorDetail(error: unknown): string | undefined {
+  if (error instanceof DevccError) return error.detail ?? error.stack
+  if (error instanceof Error) return error.stack
+  return undefined
+}
+
+/** Normalise anything thrown into a `DevccError` without losing information. */
+export function toDevccError(error: unknown, scope: DevccErrorScope, fallbackMessage?: string): DevccError {
+  if (error instanceof DevccError) return error
+  return new DevccError({
+    scope,
+    message: fallbackMessage ? `${fallbackMessage}: ${errorMessage(error)}` : errorMessage(error),
+    detail: errorDetail(error),
+    cause: error,
+  })
+}

package/src/devcc/utils/exec.ts

@@ -0,0 +1,165 @@
+import { spawn, type SpawnOptions } from "node:child_process"
+import { connect } from "node:net"
+
+/**
+ * Small, safe process helpers.
+ *
+ * Everything goes through `spawn(executable, args[])` - never a shell string -
+ * so no caller can accidentally build an injectable command line.
+ */
+
+export interface ExecOptions {
+  cwd?: string
+  env?: NodeJS.ProcessEnv
+  /** Hard timeout in milliseconds. Defaults to 5s: nothing in the UI may hang. */
+  timeoutMs?: number
+  /** Bytes of stdout/stderr to retain. Defaults to 1 MiB. */
+  maxBuffer?: number
+  input?: string
+  signal?: AbortSignal
+}
+
+export interface ExecResult {
+  ok: boolean
+  code: number | null
+  signal: NodeJS.Signals | null
+  stdout: string
+  stderr: string
+  timedOut: boolean
+  durationMs: number
+  /** Set when the executable could not be spawned at all (e.g. ENOENT). */
+  spawnError?: Error
+}
+
+export const DEFAULT_EXEC_TIMEOUT_MS = 5_000
+
+/**
+ * Run a command and collect its output. Never rejects - inspect `ok`/`spawnError`.
+ */
+export function exec(
+  command: string,
+  args: readonly string[] = [],
+  options: ExecOptions = {},
+): Promise<ExecResult> {
+  const { cwd, env, timeoutMs = DEFAULT_EXEC_TIMEOUT_MS, maxBuffer = 1024 * 1024, input, signal } = options
+
+  return new Promise<ExecResult>((resolve) => {
+    const startedAt = Date.now()
+    const spawnOptions: SpawnOptions = {
+      cwd,
+      env: env ?? process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    }
+
+    let settled = false
+    let timedOut = false
+    let stdout = ""
+    let stderr = ""
+
+    const child = spawn(command, [...args], spawnOptions)
+
+    const finish = (result: Omit<ExecResult, "durationMs">) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      signal?.removeEventListener("abort", onAbort)
+      resolve({ ...result, durationMs: Date.now() - startedAt })
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill("SIGKILL")
+    }, timeoutMs)
+    timer.unref?.()
+
+    const onAbort = () => child.kill("SIGKILL")
+    signal?.addEventListener("abort", onAbort, { once: true })
+
+    child.stdout?.setEncoding("utf8")
+    child.stdout?.on("data", (chunk: string) => {
+      if (stdout.length < maxBuffer) stdout += chunk
+    })
+    child.stderr?.setEncoding("utf8")
+    child.stderr?.on("data", (chunk: string) => {
+      if (stderr.length < maxBuffer) stderr += chunk
+    })
+
+    child.on("error", (error: Error) => {
+      finish({ ok: false, code: null, signal: null, stdout, stderr, timedOut, spawnError: error })
+    })
+
+    child.on("close", (code, closeSignal) => {
+      finish({
+        ok: !timedOut && code === 0,
+        code,
+        signal: closeSignal,
+        stdout,
+        stderr,
+        timedOut,
+      })
+    })
+
+    if (input !== undefined) {
+      child.stdin?.end(input)
+    } else {
+      child.stdin?.end()
+    }
+  })
+}
+
+/** Convenience wrapper that returns trimmed stdout, or `null` when the command failed. */
+export async function execOutput(
+  command: string,
+  args: readonly string[] = [],
+  options: ExecOptions = {},
+): Promise<string | null> {
+  const result = await exec(command, args, options)
+  return result.ok ? result.stdout.trim() : null
+}
+
+/** True when `command --version` (or the given probe args) succeeds. */
+export async function commandExists(
+  command: string,
+  probeArgs: readonly string[] = ["--version"],
+): Promise<boolean> {
+  const result = await exec(command, probeArgs, { timeoutMs: 3_000 })
+  return result.ok
+}
+
+/** Open a TCP connection to check whether something is listening. */
+export function probeTcpPort(port: number, host = "127.0.0.1", timeoutMs = 700): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const socket = connect({ port, host })
+    let settled = false
+
+    const done = (value: boolean) => {
+      if (settled) return
+      settled = true
+      socket.destroy()
+      resolve(value)
+    }
+
+    socket.setTimeout(timeoutMs)
+    socket.once("connect", () => done(true))
+    socket.once("timeout", () => done(false))
+    socket.once("error", () => done(false))
+  })
+}
+
+/** Resolve a promise to a fallback value when it takes too long. */
+export function withTimeout<T>(promise: Promise<T>, timeoutMs: number, fallback: T): Promise<T> {
+  return new Promise<T>((resolve) => {
+    const timer = setTimeout(() => resolve(fallback), timeoutMs)
+    timer.unref?.()
+    promise
+      .then((value) => {
+        clearTimeout(timer)
+        resolve(value)
+      })
+      .catch(() => {
+        clearTimeout(timer)
+        resolve(fallback)
+      })
+  })
+}

package/src/devcc/utils/format.ts

@@ -0,0 +1,83 @@
+/** Formatting helpers shared by the views. Pure functions, easy to test. */
+
+export function formatBytes(bytes: number, fractionDigits = 1): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "-"
+  const units = ["B", "KB", "MB", "GB", "TB", "PB"]
+  let value = bytes
+  let unit = 0
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+  const digits = unit === 0 ? 0 : fractionDigits
+  return `${value.toFixed(digits)} ${units[unit]}`
+}
+
+/** Bytes rendered in GB without a unit suffix, for `7.2 / 36 GB` style pairs. */
+export function toGigabytes(bytes: number, fractionDigits = 1): string {
+  return (bytes / 1024 ** 3).toFixed(fractionDigits)
+}
+
+export function formatPercent(ratio: number, fractionDigits = 0): string {
+  if (!Number.isFinite(ratio)) return "-"
+  return `${(ratio * 100).toFixed(fractionDigits)}%`
+}
+
+/** Compact duration: `4s`, `2m 10s`, `1h 04m`, `3d 02h`. */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "-"
+  const seconds = Math.floor(ms / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ${String(minutes % 60).padStart(2, "0")}m`
+  const days = Math.floor(hours / 24)
+  return `${days}d ${String(hours % 24).padStart(2, "0")}h`
+}
+
+export function formatClock(date: Date): string {
+  return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`
+}
+
+export function formatTimestamp(date: Date): string {
+  return (
+    `${String(date.getHours()).padStart(2, "0")}:` +
+    `${String(date.getMinutes()).padStart(2, "0")}:` +
+    `${String(date.getSeconds()).padStart(2, "0")}.` +
+    `${String(date.getMilliseconds()).padStart(3, "0")}`
+  )
+}
+
+/** Pad or truncate to an exact display width. */
+export function fit(text: string, width: number): string {
+  if (width <= 0) return ""
+  if (text.length === width) return text
+  if (text.length < width) return text.padEnd(width, " ")
+  if (width === 1) return "…"
+  return `${text.slice(0, width - 1)}…`
+}
+
+export function truncate(text: string, maxLength: number): string {
+  if (maxLength <= 0) return ""
+  if (text.length <= maxLength) return text
+  if (maxLength === 1) return "…"
+  return `${text.slice(0, maxLength - 1)}…`
+}
+
+/** Single-line preview of a possibly multi-line string. */
+export function singleLine(text: string, maxLength = 120): string {
+  return truncate(text.replace(/\s+/gu, " ").trim(), maxLength)
+}
+
+/** A small horizontal meter, e.g. `████░░░░░░`. */
+export function meter(ratio: number, width = 10, filledChar = "█", emptyChar = "░"): string {
+  if (width <= 0) return ""
+  const clamped = Math.max(0, Math.min(1, Number.isFinite(ratio) ? ratio : 0))
+  const filled = Math.round(clamped * width)
+  return filledChar.repeat(filled) + emptyChar.repeat(width - filled)
+}
+
+export function pluralise(count: number, singular: string, plural = `${singular}s`): string {
+  return `${count} ${count === 1 ? singular : plural}`
+}

package/src/devcc/utils/fuzzy.ts

@@ -0,0 +1,44 @@
+import { Fzf, type FzfResultItem } from "fzf"
+
+export interface FuzzyMatch<T> {
+  item: T
+  score: number
+  /** Indices of matched characters in the haystack, for highlighting. */
+  positions: number[]
+}
+
+/**
+ * `fzf`'s constructor overloads are expressed with a conditional tuple type
+ * that cannot be resolved through our own generic parameter. This narrow view
+ * of the constructor keeps the wrapper below fully typed for callers.
+ */
+type FzfConstructor = new <U>(
+  list: readonly U[],
+  options: { selector: (item: U) => string; limit?: number },
+) => { find(query: string): FzfResultItem<U>[] }
+
+const TypedFzf = Fzf as unknown as FzfConstructor
+
+/**
+ * Thin wrapper over the `fzf` package so the command palette and the script
+ * list share one ranking implementation (and one place to tune it).
+ */
+export function fuzzyFilter<T>(
+  items: readonly T[],
+  query: string,
+  selector: (item: T) => string,
+  limit = 50,
+): FuzzyMatch<T>[] {
+  if (items.length === 0) return []
+
+  if (query.trim() === "") {
+    return items.slice(0, limit).map((item) => ({ item, score: 0, positions: [] }))
+  }
+
+  const finder = new TypedFzf<T>(items, { selector, limit })
+  return finder.find(query).map((entry) => ({
+    item: entry.item,
+    score: entry.score,
+    positions: [...entry.positions].sort((a, b) => a - b),
+  }))
+}

package/src/devcc/utils/logger.ts

@@ -0,0 +1,140 @@
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+/**
+ * Internal diagnostics logger.
+ *
+ * Writes to `.devcc/devcc.log` inside the project. Never writes to stdout/stderr
+ * while the TUI owns the terminal - that would corrupt the rendered frame.
+ */
+
+export const LOG_LEVELS = ["debug", "info", "warn", "error", "silent"] as const
+export type LogLevel = (typeof LOG_LEVELS)[number]
+
+const LEVEL_WEIGHT: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: 100,
+}
+
+export function isLogLevel(value: string): value is LogLevel {
+  return (LOG_LEVELS as readonly string[]).includes(value)
+}
+
+export interface LoggerOptions {
+  level?: LogLevel
+  filePath?: string | null
+  /** Extra sink, used by tests and by the in-app diagnostics panel. */
+  sink?: (line: string, level: LogLevel) => void
+}
+
+export class Logger {
+  private level: LogLevel
+  private filePath: string | null
+  private sink: ((line: string, level: LogLevel) => void) | undefined
+  private failed = false
+
+  constructor(options: LoggerOptions = {}) {
+    this.level = options.level ?? "info"
+    this.filePath = options.filePath ?? null
+    this.sink = options.sink
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level
+  }
+
+  getLevel(): LogLevel {
+    return this.level
+  }
+
+  getFilePath(): string | null {
+    return this.filePath
+  }
+
+  child(namespace: string): ScopedLogger {
+    return new ScopedLogger(this, namespace)
+  }
+
+  enabled(level: LogLevel): boolean {
+    return LEVEL_WEIGHT[level] >= LEVEL_WEIGHT[this.level]
+  }
+
+  log(level: LogLevel, namespace: string, message: string, data?: unknown): void {
+    if (!this.enabled(level) || level === "silent") return
+
+    const stamp = new Date().toISOString()
+    const suffix = data === undefined ? "" : ` ${safeSerialise(data)}`
+    const line = `${stamp} ${level.toUpperCase().padEnd(5)} [${namespace}] ${message}${suffix}`
+
+    this.sink?.(line, level)
+
+    if (!this.filePath || this.failed) return
+    try {
+      ensureLogDirectory(dirname(this.filePath))
+      appendFileSync(this.filePath, `${line}\n`, "utf8")
+    } catch {
+      // Never let logging take the app down; disable the file sink instead.
+      this.failed = true
+    }
+  }
+}
+
+export class ScopedLogger {
+  constructor(
+    private readonly logger: Logger,
+    private readonly namespace: string,
+  ) {}
+
+  debug(message: string, data?: unknown): void {
+    this.logger.log("debug", this.namespace, message, data)
+  }
+
+  info(message: string, data?: unknown): void {
+    this.logger.log("info", this.namespace, message, data)
+  }
+
+  warn(message: string, data?: unknown): void {
+    this.logger.log("warn", this.namespace, message, data)
+  }
+
+  error(message: string, data?: unknown): void {
+    this.logger.log("error", this.namespace, message, data)
+  }
+
+  child(namespace: string): ScopedLogger {
+    return this.logger.child(`${this.namespace}:${namespace}`)
+  }
+}
+
+/**
+ * Create `.devcc/` and self-ignore it, so devcc's own diagnostics never show up
+ * as untracked changes in the user's repository.
+ */
+function ensureLogDirectory(directory: string): void {
+  mkdirSync(directory, { recursive: true })
+  const ignorePath = join(directory, ".gitignore")
+  if (!existsSync(ignorePath)) writeFileSync(ignorePath, "*\n", "utf8")
+}
+
+function safeSerialise(data: unknown): string {
+  if (data instanceof Error) return `${data.name}: ${data.message}`
+  if (typeof data === "string") return data
+  try {
+    return JSON.stringify(data)
+  } catch {
+    return String(data)
+  }
+}
+
+export function defaultLogFilePath(rootDir: string): string {
+  return join(rootDir, ".devcc", "devcc.log")
+}
+
+export function createLogger(rootDir: string, level?: LogLevel): Logger {
+  const envLevel = process.env.DEVCC_LOG_LEVEL
+  const resolved: LogLevel = level ?? (envLevel && isLogLevel(envLevel) ? envLevel : "info")
+  return new Logger({ level: resolved, filePath: defaultLogFilePath(rootDir) })
+}