@doriandev/devcc 0.1.2

package/src/devcc/app/App.ts

@@ -0,0 +1,1463 @@
+import { BoxRenderable, createCliRenderer, type CliRenderer, type KeyEvent } from "@opentui/core"
+import { existsSync } from "node:fs"
+import { basename, join, resolve } from "node:path"
+import { ConfirmDialog, PromptDialog } from "../components/ConfirmDialog.js"
+import { Footer, type KeyHint } from "../components/Footer.js"
+import { Header } from "../components/Header.js"
+import { HelpOverlay } from "../components/HelpOverlay.js"
+import type { Overlay } from "../components/Overlay.js"
+import { Sidebar } from "../components/Sidebar.js"
+import { CommandPalette } from "../components/CommandPalette.js"
+import { ProjectPicker } from "../components/ProjectPicker.js"
+import { CommandRegistry, type CommandContext } from "../core/commands.js"
+import { loadConfig, type CommandConfigEntry, type ResolvedConfig } from "../core/config.js"
+import { Subscriptions } from "../core/events.js"
+import {
+  createInitialSelection,
+  createInitialState,
+  NARROW_WIDTH,
+  setSelection,
+  shallowArrayEqual,
+  Store,
+  updateUi,
+  VIEW_IDS,
+  type AppState,
+  type Notification,
+  type NotificationLevel,
+  type ProjectState,
+  type ScriptRun,
+  type ViewId,
+} from "../core/state.js"
+import { DependencyService, updateArgs } from "../deps/DependencyService.js"
+import { GitService } from "../git/GitService.js"
+import {
+  buildProjectList,
+  defaultSearchDirs,
+  discoverProjects,
+  readRecents,
+  recordRecent,
+  type ProjectEntry,
+} from "../projects/ProjectRegistry.js"
+import { LogStore, MAX_LOG_LINES } from "../logs/LogBuffer.js"
+import { ALL_SOURCES } from "../logs/merge.js"
+import { isActive } from "../processes/ManagedProcess.js"
+import { ProcessManager } from "../processes/ProcessManager.js"
+import { DockerService } from "../services/docker.js"
+import { detectNodeServices, PortService } from "../services/node.js"
+import { OllamaService } from "../services/ollama.js"
+import { PostgresService } from "../services/postgres.js"
+import { RedisService } from "../services/redis.js"
+import { ServiceManager } from "../services/ServiceManager.js"
+import { SystemMonitor } from "../system/SystemMonitor.js"
+import { errorMessage, toDevccError } from "../utils/errors.js"
+import { createLogger, type Logger } from "../utils/logger.js"
+import { detectPackageManager, readPackageJson, readScripts, runScriptArgs } from "../utils/packageManager.js"
+import { fuzzyFilter } from "../utils/fuzzy.js"
+import { findProjectRoot } from "../utils/paths.js"
+import { DependenciesView } from "../views/DependenciesView.js"
+import { GitView } from "../views/GitView.js"
+import { LogsView } from "../views/LogsView.js"
+import { OverviewView } from "../views/OverviewView.js"
+import { ProcessesView } from "../views/ProcessesView.js"
+import { ScriptsView, scriptProcessId } from "../views/ScriptsView.js"
+import { ServicesView } from "../views/ServicesView.js"
+import { SettingsView } from "../views/SettingsView.js"
+import { SystemView } from "../views/SystemView.js"
+import type { View, ViewDeps } from "../views/View.js"
+import { createBuiltinCommands, createConfigCommands, createScriptCommands } from "./builtinCommands.js"
+import { HELP_SECTIONS, VIEW_SHORTCUTS } from "./keymap.js"
+import { theme } from "./theme.js"
+
+export interface AppOptions {
+  /** Directory to treat as the project. Defaults to the detected project root. */
+  cwd?: string
+  /** Injected by tests; production creates its own renderer. */
+  renderer?: CliRenderer
+}
+
+const LOG_UPDATE_THROTTLE_MS = 80
+
+/**
+ * The application shell.
+ *
+ * Owns the renderer, the long-lived services and the single source of truth
+ * (`Store`). Backends emit events, the shell folds them into state, and views
+ * react to the slices they care about - views never call a backend's internals
+ * or poll for changes.
+ */
+/**
+ * Everything scoped to one project.
+ *
+ * Switching projects means disposing one of these and building another; the
+ * renderer, the views and the store survive, so the UI never blinks.
+ */
+interface ProjectSession {
+  rootDir: string
+  config: ResolvedConfig
+  logger: Logger
+  logs: LogStore
+  processes: ProcessManager
+  services: ServiceManager
+  git: GitService
+  system: SystemMonitor
+  deps: DependencyService
+  project: ProjectState
+  scripts: { name: string; command: string }[]
+  /** Script runs belong to the project they ran in, not to the store. */
+  scriptRuns: Record<string, ScriptRun>
+  /** Backend -> store wiring, disposed when the project is closed. */
+  wiring: Subscriptions
+  /** Pollers that only run while this project is the active one. */
+  timers: NodeJS.Timeout[]
+}
+
+export class App {
+  private renderer!: CliRenderer
+  /** Torn down only when the app exits. */
+  private readonly subscriptions = new Subscriptions()
+  /** App-level timers (clock, uptime tick). */
+  private timers: NodeJS.Timeout[] = []
+  private readonly views = new Map<ViewId, View>()
+
+  private store!: Store<AppState>
+  /** Every open project, keyed by root directory. All keep their processes alive. */
+  private readonly sessions = new Map<string, ProjectSession>()
+  /** The project the views are showing. */
+  private session!: ProjectSession
+  /** Stable across project switches; repopulated per session. */
+  private readonly commands = new CommandRegistry()
+  private context!: CommandContext
+
+  // Session services are reached through getters so the ~60 call sites below
+  // keep working unchanged when the session is swapped out.
+  private get logger(): Logger {
+    return this.session.logger
+  }
+  private get logs(): LogStore {
+    return this.session.logs
+  }
+  private get processes(): ProcessManager {
+    return this.session.processes
+  }
+  private get services(): ServiceManager {
+    return this.session.services
+  }
+  private get git(): GitService {
+    return this.session.git
+  }
+  private get system(): SystemMonitor {
+    return this.session.system
+  }
+  private get deps(): DependencyService {
+    return this.session.deps
+  }
+  private get config(): ResolvedConfig {
+    return this.session.config
+  }
+
+  private header!: Header
+  private footer!: Footer
+  private sidebar!: Sidebar
+  private contentBox!: BoxRenderable
+  private bodyBox!: BoxRenderable
+  private palette!: CommandPalette
+  private projectPicker!: ProjectPicker
+  private confirmDialog!: ConfirmDialog
+  private promptDialog!: PromptDialog
+  private helpOverlay!: HelpOverlay
+
+  private activeView: ViewId = "overview"
+  private viewDirty = false
+  private logUpdateTimer: NodeJS.Timeout | null = null
+  private notificationSeq = 0
+  private switching = false
+  private shuttingDown = false
+  private exitResolver: (() => void) | null = null
+
+  constructor(private readonly options: AppOptions = {}) {}
+
+  /**
+   * Bootstrap services, build the UI and start background polling.
+   * Returns as soon as the first frame is ready; slower work continues behind it.
+   */
+  async start(): Promise<void> {
+    await this.bootstrap()
+    await this.mount()
+    this.startAppTimers()
+    this.startSessionBackground(this.session)
+  }
+
+  /** Boot the dashboard and resolve when the user quits. */
+  async run(): Promise<void> {
+    await this.start()
+    return new Promise<void>((resolve) => {
+      this.exitResolver = resolve
+    })
+  }
+
+  // ---------------------------------------------------------------------
+  // Bootstrap
+  // ---------------------------------------------------------------------
+
+  private async bootstrap(): Promise<void> {
+    const rootDir = this.options.cwd ?? findProjectRoot()
+    this.session = await this.createSession(rootDir)
+    this.sessions.set(this.session.rootDir, this.session)
+
+    this.store = new Store<AppState>(createInitialState(this.session.project, 80, 24))
+    this.store.patch({ scripts: { available: this.session.scripts, runs: {} } })
+    this.context = this.createCommandContext()
+
+    this.registerSessionCommands()
+    this.reportConfigIssues()
+  }
+
+  /**
+   * Build every project-scoped service for `rootDir`.
+   *
+   * Nothing here touches the renderer or the store, which is what makes it
+   * reusable for switching projects at runtime.
+   */
+  private async createSession(rootDir: string): Promise<ProjectSession> {
+    const packageJson = readPackageJson(rootDir)
+    const packageManager = detectPackageManager({
+      rootDir,
+      packageJson,
+      userAgent: process.env.npm_config_user_agent,
+    })
+
+    const loaded = await loadConfig(rootDir)
+    const config = loaded.config
+
+    const logger = createLogger(rootDir, config.logLevel)
+    logger.log("info", "app", "opening project", { rootDir, packageManager: packageManager.manager })
+
+    const logs = new LogStore(config.maxLogLines ?? MAX_LOG_LINES)
+    const system = new SystemMonitor({ rootDir, intervalMs: config.refresh.system })
+
+    const processes = new ProcessManager({ logs, logger: logger.child("processes"), rootDir })
+    processes.registerAll(config.processes)
+
+    const services = new ServiceManager({
+      logger: logger.child("services"),
+      intervalMs: config.refresh.services,
+    })
+    services.registerAll([
+      new DockerService({ rootDir }),
+      new PostgresService(),
+      new RedisService(),
+      new OllamaService(),
+      ...detectNodeServices(packageJson),
+      ...config.services.map(
+        (entry) =>
+          new PortService({
+            id: entry.id,
+            name: entry.name,
+            port: entry.port,
+            host: entry.host,
+            healthPath: entry.healthPath,
+            category: entry.category,
+          }),
+      ),
+    ])
+
+    const git = new GitService({ rootDir, logger: logger.child("git") })
+    const deps = new DependencyService({
+      rootDir,
+      manager: packageManager.manager,
+      logger: logger.child("deps"),
+    })
+
+    const project: ProjectState = {
+      name: config.name ?? (typeof packageJson?.name === "string" ? packageJson.name : basename(rootDir)),
+      rootDir,
+      packageManager,
+      configPath: loaded.filePath,
+      configIssues: loaded.issues,
+      host: system.getHostInfo(),
+      tools: { git: null, docker: null, packageManager: null },
+    }
+
+    const recentError = recordRecent(rootDir)
+    if (recentError) logger.log("debug", "app", "could not record recent project", recentError)
+
+    return {
+      rootDir,
+      config,
+      logger,
+      logs,
+      processes,
+      services,
+      git,
+      system,
+      deps,
+      project,
+      scripts: readScripts(packageJson),
+      scriptRuns: {},
+      wiring: new Subscriptions(),
+      timers: [],
+    }
+  }
+
+  /** Rebuild the command registry for the current session. */
+  private registerSessionCommands(): void {
+    this.commands.clear()
+    this.commands.registerAll(createBuiltinCommands())
+    this.commands.registerAll(createScriptCommands(this.session.scripts))
+    this.commands.registerAll(
+      createConfigCommands(this.config.commands, (entry) => this.runConfigCommand(entry)),
+    )
+  }
+
+  private reportConfigIssues(): void {
+    for (const issue of this.session.project.configIssues) {
+      this.pushNotification("warn", `Config: ${issue}`)
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // UI construction
+  // ---------------------------------------------------------------------
+
+  private async mount(): Promise<void> {
+    this.renderer =
+      this.options.renderer ??
+      (await createCliRenderer({
+        // Ctrl+C is handled by the app so processes get a chance to stop.
+        exitOnCtrlC: false,
+        targetFps: 30,
+        backgroundColor: theme.background,
+      }))
+
+    const root = new BoxRenderable(this.renderer, {
+      width: "100%",
+      height: "100%",
+      flexDirection: "column",
+      backgroundColor: theme.background,
+    })
+    this.renderer.root.add(root)
+
+    this.header = new Header(this.renderer)
+    this.footer = new Footer(this.renderer)
+    this.sidebar = new Sidebar(this.renderer)
+
+    this.bodyBox = new BoxRenderable(this.renderer, {
+      flexGrow: 1,
+      flexDirection: "row",
+      backgroundColor: "transparent",
+    })
+    this.contentBox = new BoxRenderable(this.renderer, {
+      flexGrow: 1,
+      flexDirection: "column",
+      backgroundColor: "transparent",
+    })
+
+    this.bodyBox.add(this.sidebar.box)
+    this.bodyBox.add(this.contentBox)
+
+    root.add(this.header.box)
+    root.add(this.bodyBox)
+    root.add(this.footer.box)
+
+    const deps: ViewDeps = { ctx: this.renderer, app: this.context, commands: this.commands }
+    const views: View[] = [
+      new OverviewView(deps),
+      new ProcessesView(deps),
+      new ServicesView(deps),
+      new ScriptsView(deps),
+      new GitView(deps),
+      new LogsView(deps),
+      new DependenciesView(deps),
+      new SystemView(deps),
+      new SettingsView(deps),
+    ]
+    for (const view of views) {
+      this.views.set(view.id, view)
+      this.contentBox.add(view.box)
+    }
+
+    this.palette = new CommandPalette(this.renderer)
+    this.projectPicker = new ProjectPicker(this.renderer)
+    this.confirmDialog = new ConfirmDialog(this.renderer)
+    this.promptDialog = new PromptDialog(this.renderer)
+    this.helpOverlay = new HelpOverlay(this.renderer, HELP_SECTIONS)
+    for (const overlay of this.overlays()) {
+      this.renderer.root.add(overlay.box)
+    }
+
+    this.handleResize(this.renderer.width, this.renderer.height)
+    this.setView("overview")
+    this.wireEvents()
+    this.renderAll()
+  }
+
+  // ---------------------------------------------------------------------
+  // Event wiring
+  // ---------------------------------------------------------------------
+
+  private wireEvents(): void {
+    // --- Renderer -------------------------------------------------------
+    const onResize = () => this.handleResize(this.renderer.width, this.renderer.height)
+    this.renderer.on("resize", onResize)
+    this.subscriptions.add(() => this.renderer.off("resize", onResize))
+
+    const onKey = (key: KeyEvent) => this.handleKey(key)
+    this.renderer.keyInput.on("keypress", onKey)
+    this.subscriptions.add(() => this.renderer.keyInput.off("keypress", onKey))
+
+    this.wireSession(this.session)
+    this.wireStoreToUi()
+
+    // --- Signals ---------------------------------------------------------
+    const onSignal = (signal: NodeJS.Signals) => {
+      this.logger.log("info", "app", "received signal", { signal })
+      void this.quit()
+    }
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+      process.on(signal, onSignal)
+      this.subscriptions.add(() => process.off(signal, onSignal))
+    }
+  }
+
+  /**
+   * Subscribe to one session's backends.
+   *
+   * Every open project is wired, so background projects keep tracking their
+   * processes and capturing logs. Only the *active* project mirrors its state
+   * into the store; the others surface nothing but notifications, prefixed
+   * with the project name so you know where a crash happened.
+   */
+  private wireSession(session: ProjectSession): void {
+    const { store } = this
+    const { wiring, processes, services, git, system, logs, deps } = session
+    const active = () => this.session === session
+    const notify = (level: NotificationLevel, message: string, detail?: string) =>
+      this.pushNotification(level, active() ? message : `[${session.project.name}] ${message}`, detail)
+
+    const syncProcesses = () => {
+      if (active()) store.patch({ processes: processes.list() })
+      this.refreshSidebarProjects()
+    }
+    processes.on("process:changed", syncProcesses)
+    processes.on("process:list", syncProcesses)
+    processes.on("process:exit", (process) => {
+      this.finishScriptRun(session, process.id, process.exitCode ?? 0)
+      syncProcesses()
+    })
+    processes.on("process:error", (error) => notify("error", error.message, error.detail))
+    processes.on("process:retry", (managed, delayMs) => {
+      notify(
+        "warn",
+        `${managed.name} crashed; restarting in ${Math.round(delayMs / 100) / 10}s (attempt ${managed.crashRestarts})`,
+      )
+      syncProcesses()
+    })
+    processes.on("process:ready", (managed) => {
+      if (managed.readinessTimedOut)
+        notify("warn", `${managed.name}: readiness check timed out; reported as running`)
+    })
+    wiring.add(() => processes.removeAllListeners())
+
+    services.on("service:list", (list) => {
+      if (active()) store.patch({ services: list })
+    })
+    services.on("service:error", (error) => notify("error", error.message, error.detail))
+    wiring.add(() => services.removeAllListeners())
+
+    git.on("git:changed", (snapshot) => {
+      if (active()) store.patch({ git: snapshot })
+    })
+    git.on("git:error", (error) => notify("error", error.message, error.detail))
+    wiring.add(() => git.removeAllListeners())
+
+    system.on("system:metrics", (metrics) => {
+      if (active()) store.patch({ system: metrics })
+    })
+    system.on("system:tools", (tools) => {
+      session.project = { ...session.project, tools }
+      if (active()) store.setState((state) => ({ ...state, project: { ...state.project, tools } }))
+    })
+    wiring.add(() => system.removeAllListeners())
+
+    logs.on("log:sources", (sources) => {
+      if (!active()) return
+      store.setState((state) => ({
+        ...state,
+        logSources: sources,
+        ui: { ...state.ui, logSource: state.ui.logSource ?? sources[0]?.id ?? null },
+      }))
+    })
+    logs.on("log:append", (id) => {
+      if (!active() || this.activeView !== "logs") return
+      const current = store.getState().ui.logSource
+      if (current === id || current === ALL_SOURCES) this.scheduleLogUpdate()
+    })
+    logs.on("log:clear", () => {
+      if (active()) this.markViewDirty()
+    })
+    wiring.add(() => logs.removeAllListeners())
+
+    deps.on("deps:changed", (snapshot) => {
+      if (active()) store.patch({ dependencies: snapshot })
+    })
+    deps.on("deps:error", (error) => notify("error", error.message, error.detail))
+    wiring.add(() => deps.removeAllListeners())
+  }
+
+  /** Store -> UI watchers. App-level: they outlive any single project. */
+  private wireStoreToUi(): void {
+    const { store } = this
+    this.subscriptions.add(
+      store.watch(
+        (state) => state.ui.view,
+        (view) => this.setView(view),
+      ),
+    )
+    this.subscriptions.add(
+      store.watch(
+        (state) => state.ui.clock,
+        () => this.header.update(store.getState()),
+      ),
+    )
+    this.subscriptions.add(
+      store.watch(
+        (state) => state.ui.sidebarVisible,
+        (visible) => {
+          this.sidebar.box.visible = visible
+        },
+      ),
+    )
+    this.subscriptions.add(
+      store.watch(
+        (state) => state.notifications[0],
+        (notification) => this.showNotification(notification),
+      ),
+    )
+
+    // Domain slices that force the active view to re-render.
+    const markDirty = () => this.markViewDirty()
+    this.subscriptions.add(store.watch((state) => state.processes, markDirty, shallowArrayEqual))
+    this.subscriptions.add(store.watch((state) => state.services, markDirty, shallowArrayEqual))
+    this.subscriptions.add(store.watch((state) => state.git, markDirty))
+    this.subscriptions.add(store.watch((state) => state.dependencies, markDirty))
+    this.subscriptions.add(store.watch((state) => state.projects, markDirty, shallowArrayEqual))
+    this.subscriptions.add(store.watch((state) => state.system, markDirty))
+    this.subscriptions.add(store.watch((state) => state.scripts, markDirty))
+    this.subscriptions.add(store.watch((state) => state.logSources, markDirty, shallowArrayEqual))
+    this.subscriptions.add(store.watch((state) => state.notifications, markDirty, shallowArrayEqual))
+    this.subscriptions.add(store.watch((state) => state.ui.selection, markDirty))
+    this.subscriptions.add(store.watch((state) => state.ui.logSource, markDirty))
+    this.subscriptions.add(store.watch((state) => state.ui.logFollow, markDirty))
+    this.subscriptions.add(store.watch((state) => state.ui.width, markDirty))
+    this.subscriptions.add(store.watch((state) => state.ui.height, markDirty))
+
+    // Definitions registered during bootstrap predate these listeners, so seed
+    // the store with the current snapshots once.
+    store.patch({
+      processes: this.processes.list(),
+      services: this.services.list(),
+      logSources: this.logs.sources(),
+    })
+    store.setState((state) => ({
+      ...state,
+      ui: { ...state.ui, logSource: state.ui.logSource ?? this.logs.sources()[0]?.id ?? null },
+    }))
+  }
+
+  /**
+   * Kick off background work after the first frame.
+   * Nothing here blocks the UI: the dashboard is usable while it runs.
+   */
+  private startAppTimers(): void {
+    const clockTimer = setInterval(
+      () => updateUi(this.store, { clock: new Date() }),
+      this.config.refresh.clock,
+    )
+    // Processes report their own state changes; this timer only refreshes the
+    // uptime column.
+    const uptimeTimer = setInterval(() => {
+      if (this.activeView === "processes" || this.activeView === "overview") this.markViewDirty()
+    }, 1_000)
+    this.timers = [clockTimer, uptimeTimer]
+    for (const timer of this.timers) timer.unref?.()
+  }
+
+  /**
+   * Pollers for one project. Only the active project polls git, services and
+   * system metrics - background projects merely keep their processes alive.
+   */
+  private startSessionBackground(session: ProjectSession): void {
+    this.stopSessionBackground(session)
+    session.system.start()
+
+    const gitTimer = setInterval(() => void session.git.refresh(), session.config.refresh.git)
+    gitTimer.unref?.()
+    session.timers.push(gitTimer)
+
+    void session.git.refresh()
+    void session.services.detectAll().then(() => session.services.start())
+    void session.system.refreshTools(session.project.packageManager.manager)
+    if (!session.processes.list().some((entry) => entry.startedAt)) {
+      // Autostart only the first time a project is opened, never on reactivation.
+      void session.processes.startAutoStart()
+    }
+  }
+
+  private stopSessionBackground(session: ProjectSession): void {
+    for (const timer of session.timers) clearInterval(timer)
+    session.timers = []
+    session.system.stop()
+    session.services.stop()
+  }
+
+  // ---------------------------------------------------------------------
+  // Rendering
+  // ---------------------------------------------------------------------
+
+  private renderAll(): void {
+    const state = this.store.getState()
+    this.header.update(state)
+    this.footer.setWidth(state.ui.width)
+    this.sidebar.setActive(state.ui.view)
+    this.updateFooterHints()
+    this.views.get(this.activeView)?.update(state)
+  }
+
+  private markViewDirty(): void {
+    if (this.viewDirty) return
+    this.viewDirty = true
+    queueMicrotask(() => {
+      this.viewDirty = false
+      this.views.get(this.activeView)?.update(this.store.getState())
+    })
+  }
+
+  /** Log output can arrive in bursts; coalesce redraws. */
+  private scheduleLogUpdate(): void {
+    if (this.logUpdateTimer) return
+    this.logUpdateTimer = setTimeout(() => {
+      this.logUpdateTimer = null
+      this.views.get(this.activeView)?.update(this.store.getState())
+    }, LOG_UPDATE_THROTTLE_MS)
+    this.logUpdateTimer.unref?.()
+  }
+
+  private setView(view: ViewId): void {
+    if (this.views.size === 0) return
+    const previous = this.views.get(this.activeView)
+    if (previous && this.activeView !== view) {
+      previous.box.visible = false
+      previous.onDeactivate()
+    }
+
+    this.activeView = view
+    const next = this.views.get(view)
+    if (next) {
+      next.box.visible = true
+      next.onActivate(this.store.getState())
+      next.update(this.store.getState())
+    }
+
+    this.sidebar.setActive(view)
+    this.updateFooterHints()
+  }
+
+  private updateFooterHints(): void {
+    const view = this.views.get(this.activeView)
+    const hints: KeyHint[] = view?.hints() ?? []
+    this.footer.setHints([...hints, { keys: "q", label: "quit" }])
+  }
+
+  private overlays(): Overlay[] {
+    return [this.palette, this.projectPicker, this.confirmDialog, this.promptDialog, this.helpOverlay]
+  }
+
+  /** Stop every app-level timer and every session's pollers. */
+  private stopBackground(): void {
+    for (const timer of this.timers) clearInterval(timer)
+    this.timers = []
+    if (this.logUpdateTimer) {
+      clearTimeout(this.logUpdateTimer)
+      this.logUpdateTimer = null
+    }
+    for (const session of this.sessions.values()) this.stopSessionBackground(session)
+  }
+
+  private handleResize(width: number, height: number): void {
+    const sidebarVisible = width >= NARROW_WIDTH
+    updateUi(this.store, { width, height, sidebarVisible })
+    // Applied directly as well as through the watcher: the first resize happens
+    // while the UI is still being assembled, before the watchers exist.
+    this.sidebar.box.visible = sidebarVisible
+    this.footer.setWidth(width)
+    for (const overlay of this.overlays()) {
+      overlay.layout(width, height)
+    }
+    this.header.update(this.store.getState())
+  }
+
+  // ---------------------------------------------------------------------
+  // Input
+  // ---------------------------------------------------------------------
+
+  private handleKey(key: KeyEvent): void {
+    if (this.shuttingDown) return
+
+    // Ctrl+C always means "quit cleanly".
+    if (key.ctrl && key.name === "c") {
+      key.preventDefault()
+      key.stopPropagation()
+      void this.quit()
+      return
+    }
+
+    if (this.confirmDialog.pending) {
+      this.handleConfirmKey(key)
+      return
+    }
+    if (this.promptDialog.pending) {
+      this.handlePromptKey(key)
+      return
+    }
+    if (this.projectPicker.visible) {
+      this.handleProjectPickerKey(key)
+      return
+    }
+    if (this.palette.visible) {
+      this.handlePaletteKey(key)
+      return
+    }
+    if (this.helpOverlay.visible) {
+      key.preventDefault()
+      if (key.name === "escape" || key.name === "q" || key.name === "?" || key.name === "f1")
+        this.closeOverlays()
+      else if (key.name === "j" || key.name === "down") this.helpOverlay.scroll(1)
+      else if (key.name === "k" || key.name === "up") this.helpOverlay.scroll(-1)
+      return
+    }
+
+    // A few bindings are global no matter which pane is focused. Shifted letters
+    // arrive as the lowercase name plus `shift`, so match on that.
+    // ctrl+k is the manual; the palette is `/`.
+    if (key.ctrl && key.name === "k") {
+      key.preventDefault()
+      this.openHelp()
+      return
+    }
+    if (key.ctrl && key.name === "p") {
+      key.preventDefault()
+      this.openProjectPicker()
+      return
+    }
+    if (key.ctrl && key.name === "o") {
+      key.preventDefault()
+      this.cycleProject(key.shift ? -1 : 1)
+      return
+    }
+    if (key.shift && key.name === "r") {
+      key.preventDefault()
+      void this.commands.run("app.refresh", this.context)
+      return
+    }
+
+    const state = this.store.getState()
+
+    // Views get first refusal so `s`/`r`/`d` mean the right thing per pane.
+    const view = this.views.get(this.activeView)
+    if (view?.handleKey(key, state)) {
+      key.preventDefault()
+      return
+    }
+
+    switch (key.name) {
+      case "q":
+        key.preventDefault()
+        void this.quit()
+        return
+      case "?":
+      case "f1":
+        key.preventDefault()
+        this.openHelp()
+        return
+      case "/":
+        key.preventDefault()
+        this.openPalette()
+        return
+      case "escape":
+        key.preventDefault()
+        this.closeOverlays()
+        return
+      case "tab":
+        key.preventDefault()
+        this.cycleView(key.shift ? -1 : 1)
+        return
+      case "left":
+      case "h":
+        key.preventDefault()
+        this.cycleView(-1)
+        return
+      case "right":
+        key.preventDefault()
+        this.cycleView(1)
+        return
+      case "up":
+        key.preventDefault()
+        this.moveSelection(-1)
+        return
+      case "down":
+        key.preventDefault()
+        this.moveSelection(1)
+        return
+      default:
+        break
+    }
+
+    const shortcutView = VIEW_SHORTCUTS[key.name]
+    if (shortcutView && !key.ctrl && !key.meta) {
+      key.preventDefault()
+      updateUi(this.store, { view: shortcutView })
+    }
+  }
+
+  private handleConfirmKey(key: KeyEvent): void {
+    key.preventDefault()
+    key.stopPropagation()
+    if (key.name === "y" || key.name === "return") this.confirmDialog.resolve(true)
+    else if (key.name === "n" || key.name === "escape" || key.name === "q") this.confirmDialog.resolve(false)
+  }
+
+  private handlePromptKey(key: KeyEvent): void {
+    if (key.name === "escape") {
+      key.preventDefault()
+      key.stopPropagation()
+      this.promptDialog.resolve(null)
+      return
+    }
+    if (key.name === "return") {
+      key.preventDefault()
+      key.stopPropagation()
+      this.promptDialog.submit()
+      return
+    }
+    // Everything else belongs to the focused input.
+  }
+
+  private handlePaletteKey(key: KeyEvent): void {
+    switch (key.name) {
+      case "escape":
+        key.preventDefault()
+        key.stopPropagation()
+        this.closeOverlays()
+        return
+      case "return": {
+        key.preventDefault()
+        key.stopPropagation()
+        const selected = this.palette.selected
+        this.closeOverlays()
+        if (selected) void this.runCommand(selected.id)
+        return
+      }
+      case "up":
+        key.preventDefault()
+        key.stopPropagation()
+        this.palette.move(-1)
+        return
+      case "down":
+        key.preventDefault()
+        key.stopPropagation()
+        this.palette.move(1)
+        return
+      default:
+        if (key.ctrl && (key.name === "n" || key.name === "p")) {
+          key.preventDefault()
+          key.stopPropagation()
+          this.palette.move(key.name === "n" ? 1 : -1)
+          return
+        }
+        // Let the input consume the key, then re-filter.
+        setTimeout(() => this.refreshPalette(), 0)
+    }
+  }
+
+  private handleProjectPickerKey(key: KeyEvent): void {
+    switch (key.name) {
+      case "escape":
+        key.preventDefault()
+        key.stopPropagation()
+        this.closeOverlays()
+        return
+      case "return": {
+        key.preventDefault()
+        key.stopPropagation()
+        const selected = this.projectPicker.selected
+        this.closeOverlays()
+        if (selected) void this.openProject(selected.path)
+        return
+      }
+      case "up":
+        key.preventDefault()
+        key.stopPropagation()
+        this.projectPicker.move(-1)
+        return
+      case "down":
+        key.preventDefault()
+        key.stopPropagation()
+        this.projectPicker.move(1)
+        return
+      default:
+        if (key.ctrl && (key.name === "n" || key.name === "p")) {
+          key.preventDefault()
+          key.stopPropagation()
+          this.projectPicker.move(key.name === "n" ? 1 : -1)
+          return
+        }
+        setTimeout(() => this.refreshProjectPicker(), 0)
+    }
+  }
+
+  private cycleView(direction: 1 | -1): void {
+    const index = VIEW_IDS.indexOf(this.store.getState().ui.view)
+    const next = (index + direction + VIEW_IDS.length) % VIEW_IDS.length
+    const view = VIEW_IDS[next]
+    if (view) updateUi(this.store, { view })
+  }
+
+  private moveSelection(delta: number): void {
+    const state = this.store.getState()
+    const current = state.ui.selection[state.ui.view]
+    setSelection(this.store, state.ui.view, Math.max(0, current + delta))
+  }
+
+  // ---------------------------------------------------------------------
+  // Overlays
+  // ---------------------------------------------------------------------
+
+  private openPalette(): void {
+    updateUi(this.store, { overlay: "palette" })
+    this.palette.open()
+    this.refreshPalette()
+  }
+
+  /** Scanning the filesystem is quick but not free, so do it on open. */
+  private openProjectPicker(): void {
+    const projects = this.listProjects()
+    this.store.patch({ projects })
+    updateUi(this.store, { overlay: "projects" })
+    this.projectPicker.open(this.session.rootDir)
+    this.refreshProjectPicker()
+  }
+
+  private refreshProjectPicker(): void {
+    if (!this.projectPicker.visible) return
+    const projects = this.store.getState().projects
+    const query = this.projectPicker.query
+    this.projectPicker.setResults(
+      query.trim() === ""
+        ? projects
+        : fuzzyFilter(projects, query, (entry) => `${entry.name} ${entry.path}`).map((m) => m.item),
+    )
+  }
+
+  private openHelp(): void {
+    updateUi(this.store, { overlay: "help" })
+    this.helpOverlay.show()
+  }
+
+  private refreshPalette(): void {
+    if (!this.palette.visible) return
+    this.palette.setResults(this.commands.search(this.palette.query, this.context))
+  }
+
+  private closeOverlays(): void {
+    this.palette.close()
+    this.projectPicker.close()
+    this.helpOverlay.hide()
+    updateUi(this.store, { overlay: "none" })
+  }
+
+  private async runCommand(id: string): Promise<void> {
+    try {
+      await this.commands.run(id, this.context)
+    } catch (error) {
+      const devccError = toDevccError(error, "command", `Command "${id}" failed`)
+      this.pushNotification("error", devccError.message, devccError.detail)
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // Notifications
+  // ---------------------------------------------------------------------
+
+  private pushNotification(level: NotificationLevel, message: string, detail?: string): void {
+    const notification: Notification = {
+      id: (this.notificationSeq += 1),
+      level,
+      message,
+      detail,
+      createdAt: new Date(),
+    }
+    this.logger.log(level === "error" ? "error" : level === "warn" ? "warn" : "info", "ui", message, detail)
+    this.store.setState((state) => ({
+      ...state,
+      notifications: [notification, ...state.notifications].slice(0, 200),
+    }))
+  }
+
+  private showNotification(notification: Notification | undefined): void {
+    if (!notification) {
+      this.footer.setStatus(null)
+      return
+    }
+    const prefix = notification.level === "error" || notification.level === "warn" ? "⚠ " : ""
+    this.footer.setStatus(
+      `${prefix}${notification.message}`,
+      notification.level === "error" ? "error" : notification.level === "success" ? "success" : "info",
+    )
+  }
+
+  // ---------------------------------------------------------------------
+  // Command context
+  // ---------------------------------------------------------------------
+
+  /**
+   * The context handed to commands and views.
+   *
+   * Built once and kept stable: session services are read through getters, so a
+   * project switch swaps the backends underneath every existing view without
+   * rebuilding the UI.
+   */
+  private createCommandContext(): CommandContext {
+    const context: CommandContext = {
+      store: this.store,
+      processes: this.processes,
+      services: this.services,
+      git: this.git,
+      logs: this.logs,
+      system: this.system,
+      deps: this.deps,
+      navigate: (view) => updateUi(this.store, { view }),
+      notify: (level, message, detail) => this.pushNotification(level, message, detail),
+      confirm: (title, message) => this.askConfirm(title, message),
+      prompt: (title, placeholder) => this.askPrompt(title, placeholder),
+      showHelp: () => this.openHelp(),
+      runScript: (name) => this.runScript(name),
+      updateDependency: (name, version) => this.updateDependency(name, version),
+      listProjects: () => this.listProjects(),
+      openProjects: () => this.openProjects(),
+      switchProject: (path) => this.openProject(path),
+      closeProject: (path) => this.closeProject(path),
+      quit: () => void this.quit(),
+    }
+
+    // Session services are swapped out on a project switch, so expose them as
+    // getters rather than snapshots taken at construction time.
+    Object.defineProperties(context, {
+      processes: { get: () => this.processes, enumerable: true },
+      services: { get: () => this.services, enumerable: true },
+      git: { get: () => this.git, enumerable: true },
+      logs: { get: () => this.logs, enumerable: true },
+      system: { get: () => this.system, enumerable: true },
+      deps: { get: () => this.deps, enumerable: true },
+    })
+
+    return context
+  }
+
+  private async askConfirm(title: string, message: string): Promise<boolean> {
+    updateUi(this.store, { overlay: "confirm" })
+    const answer = await this.confirmDialog.ask(title, message)
+    updateUi(this.store, { overlay: "none" })
+    return answer
+  }
+
+  private async askPrompt(title: string, placeholder?: string): Promise<string | null> {
+    updateUi(this.store, { overlay: "prompt" })
+    const answer = await this.promptDialog.ask(title, placeholder)
+    updateUi(this.store, { overlay: "none" })
+    return answer
+  }
+
+  // ---------------------------------------------------------------------
+  // Scripts and config commands
+  // ---------------------------------------------------------------------
+
+  /** Run a package.json script as a managed one-shot process. */
+  private async runScript(name: string): Promise<void> {
+    const state = this.store.getState()
+    const script = state.scripts.available.find((entry) => entry.name === name)
+    if (!script) {
+      this.pushNotification("warn", `No script named "${name}"`)
+      return
+    }
+
+    const id = scriptProcessId(name)
+    const manager = state.project.packageManager.manager
+
+    if (this.processes.isRunning(id)) {
+      this.pushNotification("warn", `${name} is already running`)
+      return
+    }
+
+    this.processes.register({
+      id,
+      name: `${manager} run ${name}`,
+      command: manager,
+      args: runScriptArgs(manager, name),
+      cwd: state.project.rootDir,
+      kind: "task",
+    })
+
+    const session = this.session
+    session.scriptRuns = {
+      ...session.scriptRuns,
+      [name]: { scriptName: name, processId: id, startedAt: new Date(), status: "running" },
+    }
+    this.store.setState((current) => ({
+      ...current,
+      scripts: { ...current.scripts, runs: session.scriptRuns },
+      ui: { ...current.ui, logSource: id },
+    }))
+
+    try {
+      await this.processes.start(id)
+      this.pushNotification("info", `Running ${manager} run ${name}`)
+    } catch (error) {
+      this.finishScriptRun(session, id, 1)
+      this.pushNotification("error", errorMessage(error))
+    }
+  }
+
+  private finishScriptRun(session: ProjectSession, processId: string, exitCode: number): void {
+    const entry = Object.values(session.scriptRuns).find((run) => run.processId === processId)
+    if (!entry || entry.status !== "running") return
+    session.scriptRuns = {
+      ...session.scriptRuns,
+      [entry.scriptName]: {
+        ...entry,
+        finishedAt: new Date(),
+        exitCode,
+        status: exitCode === 0 ? "succeeded" : "failed",
+      },
+    }
+    if (session === this.session) {
+      this.store.setState((state) => ({ ...state, scripts: { ...state.scripts, runs: session.scriptRuns } }))
+    }
+  }
+
+  private async runConfigCommand(entry: CommandConfigEntry): Promise<void> {
+    const id = `command:${entry.id}`
+    if (this.processes.isRunning(id)) {
+      this.pushNotification("warn", `${entry.title} is already running`)
+      return
+    }
+    this.processes.register({
+      id,
+      name: entry.title,
+      command: entry.command,
+      args: entry.args,
+      cwd: entry.cwd,
+      kind: "task",
+    })
+    updateUi(this.store, { logSource: id })
+    try {
+      await this.processes.start(id)
+      this.pushNotification("info", `Running ${entry.title}`)
+    } catch (error) {
+      this.pushNotification("error", errorMessage(error))
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // Projects
+  // ---------------------------------------------------------------------
+
+  /** Current project first, then recents, config entries and sibling directories. */
+  private listProjects(): ProjectEntry[] {
+    const current = this.session.rootDir
+    const searchDirs = [
+      ...this.config.projectSearchDirs.map((dir) => resolve(current, dir)),
+      ...defaultSearchDirs(current),
+    ]
+
+    return buildProjectList({
+      currentPath: current,
+      configured: this.config.projects,
+      recents: [...this.openProjects().filter((entry) => entry.path !== current), ...readRecents()],
+      discovered: discoverProjects({ searchDirs }),
+    })
+  }
+
+  /** Open projects in the order they were opened. */
+  private openProjects(): ProjectEntry[] {
+    return [...this.sessions.values()].map((session) => ({
+      path: session.rootDir,
+      name: session.project.name,
+      source: session === this.session ? "current" : "recent",
+      hasGit: session.git.getSnapshot().isRepository,
+      hasPackageJson: session.scripts.length > 0 || existsSync(join(session.rootDir, "package.json")),
+    }))
+  }
+
+  /**
+   * Open a project, or bring an already-open one to the front.
+   *
+   * Opening never stops anything: the previous project keeps running in the
+   * background with its processes and log capture intact. The renderer, views
+   * and store are shared; only the session behind them changes.
+   */
+  private async openProject(path: string): Promise<void> {
+    const target = resolve(path)
+    if (this.switching || this.shuttingDown) return
+    if (target === this.session.rootDir) {
+      this.pushNotification("info", "Already on that project")
+      return
+    }
+
+    const existing = this.sessions.get(target)
+    if (existing) {
+      this.activateSession(existing)
+      this.pushNotification("info", `Switched to ${existing.project.name}`)
+      return
+    }
+
+    if (!existsSync(target)) {
+      this.pushNotification("error", `No such directory: ${target}`)
+      return
+    }
+
+    this.switching = true
+    try {
+      this.footer.setStatus(`Opening ${basename(target)}…`)
+      const session = await this.createSession(target)
+      this.sessions.set(target, session)
+      this.wireSession(session)
+      this.activateSession(session)
+      this.reportConfigIssues()
+      this.pushNotification("success", `Opened ${session.project.name} (${this.sessions.size} open)`)
+    } catch (error) {
+      this.pushNotification("error", `Could not open project: ${errorMessage(error)}`)
+    } finally {
+      this.switching = false
+    }
+  }
+
+  /** Point the views at `session` and mirror its current state into the store. */
+  private activateSession(session: ProjectSession): void {
+    const previous = this.session
+    if (previous !== session) {
+      this.stopSessionBackground(previous)
+      previous.logger.log("info", "app", "deactivated", { next: session.project.name })
+    }
+
+    this.session = session
+    this.registerSessionCommands()
+
+    // Everything the store holds for a project is derivable from the session,
+    // so switching is a snapshot copy rather than a rebuild.
+    this.store.setState((state) => ({
+      ...state,
+      project: session.project,
+      processes: session.processes.list(),
+      services: session.services.list(),
+      scripts: { available: session.scripts, runs: session.scriptRuns },
+      git: session.git.getSnapshot(),
+      dependencies: session.deps.getSnapshot(),
+      system: session.system.getMetrics(),
+      logSources: session.logs.sources(),
+      projects: [],
+      ui: {
+        ...state.ui,
+        selection: createInitialSelection(),
+        logSource: session.logs.sources()[0]?.id ?? null,
+        logFollow: true,
+        overlay: "none",
+      },
+    }))
+
+    this.startSessionBackground(session)
+    this.refreshSidebarProjects()
+    this.renderAll()
+    session.logger.log("info", "app", "activated", { openProjects: this.sessions.size })
+  }
+
+  /**
+   * Close a project, stopping anything devcc started there (confirmed).
+   * The last open project cannot be closed - quit instead.
+   */
+  private async closeProject(path?: string): Promise<void> {
+    const target = resolve(path ?? this.session.rootDir)
+    const session = this.sessions.get(target)
+    if (!session) {
+      this.pushNotification("warn", "That project is not open")
+      return
+    }
+    if (this.sessions.size === 1) {
+      this.pushNotification("warn", "Cannot close the only open project; press q to quit")
+      return
+    }
+
+    const running = session.processes.list().filter((entry) => isActive(entry.status))
+    if (running.length > 0) {
+      const confirmed = await this.askConfirm(
+        `Close ${session.project.name} and stop ${running.length} running process(es)?`,
+        `${running.map((entry) => entry.name).join(", ")} will be stopped.`,
+      )
+      if (!confirmed) return
+    }
+
+    this.footer.setStatus(`Closing ${session.project.name}…`)
+    this.stopSessionBackground(session)
+    await session.processes.stopAll()
+    session.wiring.dispose()
+    this.sessions.delete(target)
+    session.logger.log("info", "app", "closed project")
+
+    if (session === this.session) {
+      const next = [...this.sessions.values()][0]
+      if (next) this.activateSession(next)
+    } else {
+      this.refreshSidebarProjects()
+    }
+    this.pushNotification("info", `Closed ${session.project.name}`)
+  }
+
+  /** `ctrl+o`: bring the next open project to the front. */
+  private cycleProject(direction: 1 | -1): void {
+    const sessions = [...this.sessions.values()]
+    if (sessions.length < 2) {
+      this.pushNotification("info", "Only one project is open; ctrl+p opens another")
+      return
+    }
+    const index = sessions.indexOf(this.session)
+    const next = sessions[(index + direction + sessions.length) % sessions.length]
+    if (next) this.activateSession(next)
+  }
+
+  /** Feed the rail the per-project running counts. */
+  private refreshSidebarProjects(): void {
+    this.sidebar.setProjects(
+      [...this.sessions.values()].map((session) => {
+        const list = session.processes.list()
+        return {
+          path: session.rootDir,
+          name: session.project.name,
+          running: list.filter((entry) => isActive(entry.status)).length,
+          attention: list.some((entry) => entry.status === "failed"),
+        }
+      }),
+      this.session.rootDir,
+    )
+  }
+
+  // ---------------------------------------------------------------------
+  // Dependencies
+  // ---------------------------------------------------------------------
+
+  /** Update a single package, gated by a confirmation (it rewrites the lockfile). */
+  private async updateDependency(name: string, version: string): Promise<void> {
+    const manager = this.session.project.packageManager.manager
+    const args = updateArgs(manager, name)
+
+    const confirmed = await this.askConfirm(
+      `Update ${name} to ${version}?`,
+      `Runs \`${manager} ${args.join(" ")}\`, which rewrites package.json and the lockfile.`,
+    )
+    if (!confirmed) return
+
+    const id = `deps:${name}`
+    if (this.processes.isRunning(id)) {
+      this.pushNotification("warn", `${name} is already being updated`)
+      return
+    }
+
+    this.processes.register({
+      id,
+      name: `${manager} update ${name}`,
+      command: manager,
+      args,
+      cwd: this.session.rootDir,
+      kind: "task",
+    })
+    updateUi(this.store, { logSource: id })
+
+    try {
+      await this.processes.start(id)
+      this.pushNotification("info", `Updating ${name}…`)
+    } catch (error) {
+      this.pushNotification("error", errorMessage(error))
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // Shutdown
+  // ---------------------------------------------------------------------
+
+  /**
+   * Graceful shutdown: stop timers and listeners, stop the processes devcc
+   * launched (never anything merely detected), then hand the terminal back.
+   */
+  async quit(): Promise<void> {
+    if (this.shuttingDown) return
+    this.shuttingDown = true
+    this.logger.log("info", "app", "shutting down")
+
+    this.footer.setStatus("Shutting down…")
+
+    this.stopBackground()
+
+    // Every open project, not just the visible one.
+    await Promise.all(
+      [...this.sessions.values()].map(async (session) => {
+        try {
+          await session.processes.stopAll()
+        } catch (error) {
+          session.logger.log("error", "app", "failed to stop processes", errorMessage(error))
+        }
+        session.wiring.dispose()
+      }),
+    )
+    this.subscriptions.dispose()
+
+    for (const view of this.views.values()) view.dispose()
+    this.views.clear()
+
+    try {
+      this.renderer.destroy()
+    } catch (error) {
+      this.logger.log("error", "app", "renderer teardown failed", errorMessage(error))
+    }
+
+    this.exitResolver?.()
+    this.exitResolver = null
+  }
+
+  /** Test hook: the store the UI is bound to. */
+  getStore(): Store<AppState> {
+    return this.store
+  }
+
+  /** Test hook: open/activate a project without driving the picker overlay. */
+  async switchProjectForTest(path: string): Promise<void> {
+    await this.openProject(path)
+  }
+
+  /** Test hook: close a project without the confirmation dialog when nothing runs. */
+  async closeProjectForTest(path: string): Promise<void> {
+    await this.closeProject(path)
+  }
+
+  /** Test hook: dependency-ordered start of the active project's processes. */
+  async startAllForTest(ids?: string[]): Promise<void> {
+    await this.processes.startAll(ids)
+  }
+
+  /** Test hook: root directories of every open project. */
+  openProjectPaths(): string[] {
+    return [...this.sessions.keys()]
+  }
+
+  /** Test hook: the log store backing the Logs view. */
+  getLogs(): LogStore {
+    return this.logs
+  }
+}