@doriandev/devcc 0.1.2

package/src/devcc/core/commands.ts

@@ -0,0 +1,140 @@
+import type { DependencyService } from "../deps/DependencyService.js"
+import type { GitService } from "../git/GitService.js"
+import type { LogStore } from "../logs/LogBuffer.js"
+import type { ProcessManager } from "../processes/ProcessManager.js"
+import type { ServiceManager } from "../services/ServiceManager.js"
+import type { ProjectEntry } from "../projects/ProjectRegistry.js"
+import type { SystemMonitor } from "../system/SystemMonitor.js"
+import { fuzzyFilter } from "../utils/fuzzy.js"
+import type { AppStore, NotificationLevel, ViewId } from "./state.js"
+
+/**
+ * Everything a command is allowed to touch.
+ *
+ * Commands are the single extension point: the palette, the keymap and any
+ * user-provided config entry all end up here, so a new capability only has to
+ * be registered once.
+ */
+export interface CommandContext {
+  store: AppStore
+  processes: ProcessManager
+  services: ServiceManager
+  git: GitService
+  logs: LogStore
+  system: SystemMonitor
+  deps: DependencyService
+
+  navigate: (view: ViewId) => void
+  notify: (level: NotificationLevel, message: string, detail?: string) => void
+  /** Modal yes/no. Resolves false when dismissed. */
+  confirm: (title: string, message: string) => Promise<boolean>
+  /** Modal single-line prompt. Resolves null when cancelled. */
+  prompt: (title: string, placeholder?: string) => Promise<string | null>
+  /** Open the in-app manual. */
+  showHelp: () => void
+  runScript: (name: string) => Promise<void>
+  /** Update one dependency to `version`, after confirmation. */
+  updateDependency: (name: string, version: string) => Promise<void>
+  /** Projects the switcher can offer, current one first. */
+  listProjects: () => ProjectEntry[]
+  /** Projects currently open, in the order they were opened. */
+  openProjects: () => ProjectEntry[]
+  /** Open a project (or bring an open one to the front) without closing others. */
+  switchProject: (path: string) => Promise<void>
+  /** Close an open project, stopping what devcc started there. Defaults to the current one. */
+  closeProject: (path?: string) => Promise<void>
+  quit: () => void
+}
+
+export interface CommandDefinition {
+  id: string
+  title: string
+  category?: string
+  /** Displayed hint, e.g. `r`. Key handling itself lives in the keymap. */
+  shortcut?: string
+  keywords?: string[]
+  /** Hide the command when it cannot apply right now. */
+  when?: (context: CommandContext) => boolean
+  /** Ask for confirmation before running. Used for destructive operations. */
+  confirm?: { title: string; message: string }
+  execute: (context: CommandContext) => Promise<void> | void
+}
+
+export interface CommandRegistryEvents {
+  changed: []
+}
+
+/**
+ * Central command registry. Ids are unique; re-registering an id replaces it,
+ * which is what lets project config override a built-in.
+ */
+export class CommandRegistry {
+  private readonly commands = new Map<string, CommandDefinition>()
+
+  register(command: CommandDefinition): void {
+    this.commands.set(command.id, command)
+  }
+
+  registerAll(commands: readonly CommandDefinition[]): void {
+    for (const command of commands) this.register(command)
+  }
+
+  unregister(id: string): boolean {
+    return this.commands.delete(id)
+  }
+
+  /** Drop every command. Used when the dashboard reattaches to another project. */
+  clear(): void {
+    this.commands.clear()
+  }
+
+  has(id: string): boolean {
+    return this.commands.has(id)
+  }
+
+  get(id: string): CommandDefinition | undefined {
+    return this.commands.get(id)
+  }
+
+  list(): CommandDefinition[] {
+    return [...this.commands.values()]
+  }
+
+  /** Commands whose `when` guard passes right now. */
+  available(context: CommandContext): CommandDefinition[] {
+    return this.list().filter((command) => (command.when ? safeWhen(command, context) : true))
+  }
+
+  /** Fuzzy search over `category title keywords`. */
+  search(query: string, context: CommandContext, limit = 40): CommandDefinition[] {
+    const candidates = this.available(context)
+    return fuzzyFilter(candidates, query, searchText, limit).map((match) => match.item)
+  }
+
+  /**
+   * Run a command by id, honouring its `confirm` guard.
+   * Returns false when the command does not exist or the user declined.
+   */
+  async run(id: string, context: CommandContext): Promise<boolean> {
+    const command = this.commands.get(id)
+    if (!command) return false
+    if (command.confirm) {
+      const confirmed = await context.confirm(command.confirm.title, command.confirm.message)
+      if (!confirmed) return false
+    }
+    await command.execute(context)
+    return true
+  }
+}
+
+export function searchText(command: CommandDefinition): string {
+  return [command.category, command.title, ...(command.keywords ?? [])].filter(Boolean).join(" ")
+}
+
+function safeWhen(command: CommandDefinition, context: CommandContext): boolean {
+  try {
+    return command.when?.(context) ?? true
+  } catch {
+    return false
+  }
+}

package/src/devcc/core/config.ts

@@ -0,0 +1,405 @@
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import type { ProcessDefinition, ProcessKind, ReadinessCheck } from "../processes/ManagedProcess.js"
+import { errorMessage } from "../utils/errors.js"
+import type { LogLevel } from "../utils/logger.js"
+import { isLogLevel } from "../utils/logger.js"
+
+/** A command declared in project config: runs an executable and streams its logs. */
+export interface CommandConfigEntry {
+  id: string
+  title: string
+  category?: string
+  command: string
+  args?: string[]
+  cwd?: string
+  keywords?: string[]
+  /** Require a yes/no confirmation before running. */
+  confirm?: { title: string; message: string } | boolean
+}
+
+/** An extra port/HTTP endpoint to watch in the Services view. */
+export interface ServiceConfigEntry {
+  id: string
+  name: string
+  port: number
+  host?: string
+  healthPath?: string
+  category?: "container" | "database" | "runtime" | "ai" | "web"
+}
+
+export interface RefreshIntervals {
+  system?: number
+  services?: number
+  git?: number
+  clock?: number
+}
+
+export interface DevccConfig {
+  /** Overrides the project name shown in the header. */
+  name?: string
+  /**
+   * Extra project paths to offer in the project switcher, absolute or relative
+   * to this project. Recents and sibling directories are found automatically.
+   */
+  projects?: string[]
+  /** Extra directories to scan for sibling projects (default: the parent). */
+  projectSearchDirs?: string[]
+  processes?: ProcessDefinition[]
+  commands?: CommandConfigEntry[]
+  services?: ServiceConfigEntry[]
+  refresh?: RefreshIntervals
+  /** Cap for each log source's ring buffer. */
+  maxLogLines?: number
+  logLevel?: LogLevel
+}
+
+export type ResolvedConfig = Required<
+  Pick<DevccConfig, "processes" | "commands" | "services" | "projects" | "projectSearchDirs">
+> &
+  Omit<DevccConfig, "processes" | "commands" | "services" | "projects" | "projectSearchDirs"> & {
+    refresh: Required<RefreshIntervals>
+  }
+
+export const DEFAULT_REFRESH: Required<RefreshIntervals> = {
+  system: 1_500,
+  services: 5_000,
+  git: 8_000,
+  clock: 1_000,
+}
+
+export const EMPTY_CONFIG: ResolvedConfig = {
+  processes: [],
+  commands: [],
+  services: [],
+  projects: [],
+  projectSearchDirs: [],
+  refresh: DEFAULT_REFRESH,
+}
+
+/** Identity helper that gives config files full type checking and completion. */
+export function defineConfig(config: DevccConfig): DevccConfig {
+  return config
+}
+
+export const CONFIG_FILENAMES = [
+  ".devcc.ts",
+  "devcc.config.ts",
+  ".devcc.mts",
+  "devcc.config.mts",
+  ".devcc.js",
+  "devcc.config.js",
+  ".devcc.mjs",
+  "devcc.config.mjs",
+  ".devcc.json",
+] as const
+
+export function findConfigFile(
+  rootDir: string,
+  exists: (path: string) => boolean = existsSync,
+): string | null {
+  for (const name of CONFIG_FILENAMES) {
+    const path = join(rootDir, name)
+    if (exists(path)) return path
+  }
+  return null
+}
+
+export interface ValidationResult {
+  config: ResolvedConfig
+  issues: string[]
+}
+
+const PROCESS_KINDS: readonly ProcessKind[] = ["service", "task"]
+
+/**
+ * Validate and normalise a raw config object.
+ *
+ * Invalid entries are dropped with an explanatory issue rather than throwing:
+ * a typo in one process definition must not stop the dashboard from starting.
+ */
+export function validateConfig(raw: unknown): ValidationResult {
+  const issues: string[] = []
+  if (raw === null || typeof raw !== "object") {
+    return { config: { ...EMPTY_CONFIG }, issues: ["Config must export an object"] }
+  }
+
+  const input = raw as Record<string, unknown>
+  const seenProcessIds = new Set<string>()
+  const processes: ProcessDefinition[] = []
+
+  for (const [index, entry] of asArray(input.processes, "processes", issues).entries()) {
+    const record = asRecord(entry)
+    if (!record) {
+      issues.push(`processes[${index}] must be an object`)
+      continue
+    }
+    const id = asString(record.id)
+    const command = asString(record.command)
+    if (!id) {
+      issues.push(`processes[${index}] is missing "id"`)
+      continue
+    }
+    if (!command) {
+      issues.push(`processes[${index}] ("${id}") is missing "command"`)
+      continue
+    }
+    if (seenProcessIds.has(id)) {
+      issues.push(`processes[${index}] duplicates id "${id}"`)
+      continue
+    }
+    seenProcessIds.add(id)
+
+    const kind = asString(record.kind)
+    processes.push({
+      id,
+      name: asString(record.name) ?? id,
+      command,
+      args: asStringArray(record.args),
+      cwd: asString(record.cwd),
+      env: asStringRecord(record.env),
+      kind: kind && (PROCESS_KINDS as readonly string[]).includes(kind) ? (kind as ProcessKind) : "service",
+      autoStart: record.autoStart === true,
+      url: asString(record.url),
+      port: asPositiveInt(record.port),
+      killGraceMs: asPositiveInt(record.killGraceMs),
+      restartOnCrash: record.restartOnCrash === true,
+      maxCrashRestarts: asPositiveInt(record.maxCrashRestarts),
+      crashBackoffMs: asPositiveInt(record.crashBackoffMs),
+      maxCrashBackoffMs: asPositiveInt(record.maxCrashBackoffMs),
+      healthyAfterMs: asPositiveInt(record.healthyAfterMs),
+      dependsOn: asStringArray(record.dependsOn),
+      readiness: asReadiness(record.readiness, id, issues),
+    })
+  }
+
+  for (const definition of processes) {
+    for (const dependency of definition.dependsOn ?? []) {
+      if (!seenProcessIds.has(dependency)) {
+        issues.push(`processes "${definition.id}": dependsOn "${dependency}" is not a declared process`)
+      }
+    }
+  }
+
+  const seenCommandIds = new Set<string>()
+  const commands: CommandConfigEntry[] = []
+  for (const [index, entry] of asArray(input.commands, "commands", issues).entries()) {
+    const record = asRecord(entry)
+    if (!record) {
+      issues.push(`commands[${index}] must be an object`)
+      continue
+    }
+    const id = asString(record.id)
+    const command = asString(record.command)
+    if (!id || !command) {
+      issues.push(`commands[${index}] needs both "id" and "command"`)
+      continue
+    }
+    if (seenCommandIds.has(id)) {
+      issues.push(`commands[${index}] duplicates id "${id}"`)
+      continue
+    }
+    seenCommandIds.add(id)
+
+    const confirm = record.confirm
+    commands.push({
+      id,
+      title: asString(record.title) ?? id,
+      category: asString(record.category) ?? "Project",
+      command,
+      args: asStringArray(record.args),
+      cwd: asString(record.cwd),
+      keywords: asStringArray(record.keywords),
+      confirm:
+        confirm === true
+          ? true
+          : (() => {
+              const confirmRecord = asRecord(confirm)
+              const title = asString(confirmRecord?.title)
+              const message = asString(confirmRecord?.message)
+              return title && message ? { title, message } : undefined
+            })(),
+    })
+  }
+
+  const services: ServiceConfigEntry[] = []
+  const seenServiceIds = new Set<string>()
+  for (const [index, entry] of asArray(input.services, "services", issues).entries()) {
+    const record = asRecord(entry)
+    if (!record) {
+      issues.push(`services[${index}] must be an object`)
+      continue
+    }
+    const id = asString(record.id)
+    const port = asPositiveInt(record.port)
+    if (!id || port === undefined) {
+      issues.push(`services[${index}] needs "id" and a numeric "port"`)
+      continue
+    }
+    if (seenServiceIds.has(id)) {
+      issues.push(`services[${index}] duplicates id "${id}"`)
+      continue
+    }
+    seenServiceIds.add(id)
+    services.push({
+      id,
+      name: asString(record.name) ?? id,
+      port,
+      host: asString(record.host),
+      healthPath: asString(record.healthPath),
+      category: asServiceCategory(record.category),
+    })
+  }
+
+  const refreshInput = asRecord(input.refresh) ?? {}
+  const refresh: Required<RefreshIntervals> = {
+    system: asPositiveInt(refreshInput.system) ?? DEFAULT_REFRESH.system,
+    services: asPositiveInt(refreshInput.services) ?? DEFAULT_REFRESH.services,
+    git: asPositiveInt(refreshInput.git) ?? DEFAULT_REFRESH.git,
+    clock: asPositiveInt(refreshInput.clock) ?? DEFAULT_REFRESH.clock,
+  }
+
+  const logLevel = asString(input.logLevel)
+  if (logLevel && !isLogLevel(logLevel)) issues.push(`Unknown logLevel "${logLevel}"`)
+
+  return {
+    config: {
+      name: asString(input.name),
+      projects: asStringArray(input.projects) ?? [],
+      projectSearchDirs: asStringArray(input.projectSearchDirs) ?? [],
+      processes,
+      commands,
+      services,
+      refresh,
+      maxLogLines: asPositiveInt(input.maxLogLines),
+      logLevel: logLevel && isLogLevel(logLevel) ? logLevel : undefined,
+    },
+    issues,
+  }
+}
+
+export interface LoadedConfig extends ValidationResult {
+  filePath: string | null
+}
+
+/**
+ * Load project config if present.
+ *
+ * TypeScript config files are transpiled on the fly with jiti so `.devcc.ts`
+ * works identically under Bun and Node.
+ */
+export async function loadConfig(rootDir: string): Promise<LoadedConfig> {
+  const filePath = findConfigFile(rootDir)
+  if (!filePath) return { filePath: null, config: { ...EMPTY_CONFIG }, issues: [] }
+
+  try {
+    const raw = await importConfigModule(filePath)
+    const result = validateConfig(raw)
+    return { ...result, filePath }
+  } catch (error) {
+    return {
+      filePath,
+      config: { ...EMPTY_CONFIG },
+      issues: [`Failed to load ${filePath}: ${errorMessage(error)}`],
+    }
+  }
+}
+
+async function importConfigModule(filePath: string): Promise<unknown> {
+  if (filePath.endsWith(".json")) {
+    const { readFile } = await import("node:fs/promises")
+    return JSON.parse(await readFile(filePath, "utf8")) as unknown
+  }
+
+  const { createJiti } = await import("jiti")
+  const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false })
+  const loaded = await jiti.import(filePath)
+  return unwrapDefault(loaded)
+}
+
+function unwrapDefault(value: unknown): unknown {
+  const record = asRecord(value)
+  if (record && "default" in record) return unwrapDefault(record.default)
+  return value
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function asArray(value: unknown, field: string, issues: string[]): unknown[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) {
+    issues.push(`"${field}" must be an array`)
+    return []
+  }
+  return value
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const items = value.filter((item): item is string => typeof item === "string")
+  return items.length > 0 ? items : undefined
+}
+
+function asStringRecord(value: unknown): Record<string, string> | undefined {
+  const record = asRecord(value)
+  if (!record) return undefined
+  const entries = Object.entries(record).filter(
+    (entry): entry is [string, string] => typeof entry[1] === "string",
+  )
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined
+}
+
+function asPositiveInt(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined
+}
+
+/**
+ * Normalise a readiness block. `port` alone or `logPattern` alone is enough;
+ * a block with neither is dropped with an issue rather than silently waiting
+ * for nothing.
+ */
+function asReadiness(value: unknown, processId: string, issues: string[]): ReadinessCheck | undefined {
+  if (value === undefined) return undefined
+  const record = asRecord(value)
+  if (!record) {
+    issues.push(`processes "${processId}": readiness must be an object`)
+    return undefined
+  }
+  const port = asPositiveInt(record.port)
+  const logPattern = asString(record.logPattern)
+  if (port === undefined && logPattern === undefined) {
+    issues.push(`processes "${processId}": readiness needs a "port" or a "logPattern"`)
+    return undefined
+  }
+  if (logPattern !== undefined) {
+    try {
+      new RegExp(logPattern, "iu")
+    } catch {
+      issues.push(`processes "${processId}": readiness.logPattern is not a valid regex`)
+      return undefined
+    }
+  }
+  return {
+    port,
+    host: asString(record.host),
+    logPattern,
+    timeoutMs: asPositiveInt(record.timeoutMs),
+    intervalMs: asPositiveInt(record.intervalMs),
+  }
+}
+
+function asServiceCategory(value: unknown): ServiceConfigEntry["category"] {
+  const categories = ["container", "database", "runtime", "ai", "web"] as const
+  const name = asString(value)
+  return name && (categories as readonly string[]).includes(name)
+    ? (name as ServiceConfigEntry["category"])
+    : "web"
+}

package/src/devcc/core/events.ts

@@ -0,0 +1,41 @@
+import { EventEmitter } from "node:events"
+
+/**
+ * Typed event bus.
+ *
+ * Backend services (processes, git, docker, system) emit events; the app layer
+ * translates them into state updates; views read state. Views never call into
+ * the backends' internals directly.
+ */
+export type EventMap = Record<string, unknown[]>
+
+export class TypedEmitter<Events extends EventMap> extends EventEmitter<Events> {}
+
+/** A disposable subscription. Calling it twice is safe. */
+export type Unsubscribe = () => void
+
+/** Collects unsubscribe functions so a component can tear everything down at once. */
+export class Subscriptions {
+  private disposers: Unsubscribe[] = []
+
+  add(unsubscribe: Unsubscribe): Unsubscribe {
+    this.disposers.push(unsubscribe)
+    return unsubscribe
+  }
+
+  dispose(): void {
+    const disposers = this.disposers
+    this.disposers = []
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        // Teardown must never throw.
+      }
+    }
+  }
+
+  get size(): number {
+    return this.disposers.length
+  }
+}