@alumbwe/anvil 1.0.0

package/src/utils/recent-projects.ts

@@ -0,0 +1,156 @@
+import fs from 'fs'
+import path from 'path'
+
+import { getConfigDir } from './auth'
+import { logger } from './logger'
+
+const MAX_RECENT_PROJECTS = 10
+
+export interface RecentProject {
+  path: string
+  lastOpened: number
+}
+
+/**
+ * Get the recent projects file path
+ */
+export const getRecentProjectsPath = (): string => {
+  return path.join(getConfigDir(), 'recent-projects.json')
+}
+
+/**
+ * Load recent projects from file system
+ * @returns Array of recent projects, sorted by most recent first
+ */
+export const loadRecentProjects = (): RecentProject[] => {
+  const recentProjectsPath = getRecentProjectsPath()
+
+  if (!fs.existsSync(recentProjectsPath)) {
+    return []
+  }
+
+  try {
+    const fileContent = fs.readFileSync(recentProjectsPath, 'utf8')
+    const parsed = JSON.parse(fileContent)
+
+    if (!Array.isArray(parsed)) {
+      return []
+    }
+
+    // Validate and filter entries
+    const validProjects = parsed.filter(
+      (item): item is RecentProject =>
+        typeof item === 'object' &&
+        item !== null &&
+        typeof item.path === 'string' &&
+        typeof item.lastOpened === 'number',
+    )
+
+    // Filter out projects that no longer exist on disk
+    const existingProjects = validProjects.filter((project) => {
+      try {
+        return fs.existsSync(project.path)
+      } catch {
+        return false
+      }
+    })
+
+    // Sort by most recent first
+    return existingProjects.sort((a, b) => b.lastOpened - a.lastOpened)
+  } catch (error) {
+    logger.debug(
+      { error: error instanceof Error ? error.message : String(error) },
+      'Error reading recent projects',
+    )
+    return []
+  }
+}
+
+/**
+ * Clear all recent projects
+ */
+export const clearRecentProjects = (): void => {
+  const recentProjectsPath = getRecentProjectsPath()
+
+  try {
+    if (fs.existsSync(recentProjectsPath)) {
+      fs.writeFileSync(recentProjectsPath, JSON.stringify([], null, 2))
+    }
+  } catch (error) {
+    logger.debug(
+      { error: error instanceof Error ? error.message : String(error) },
+      'Error clearing recent projects',
+    )
+  }
+}
+
+/**
+ * Remove a specific project from the recent projects list
+ */
+export const removeRecentProject = (projectPath: string): void => {
+  const recentProjectsPath = getRecentProjectsPath()
+
+  try {
+    const existingProjects = loadRecentProjects()
+    const filteredProjects = existingProjects.filter(
+      (p) => p.path !== projectPath,
+    )
+
+    fs.writeFileSync(
+      recentProjectsPath,
+      JSON.stringify(filteredProjects, null, 2),
+    )
+  } catch (error) {
+    logger.debug(
+      { error: error instanceof Error ? error.message : String(error) },
+      'Error removing recent project',
+    )
+  }
+}
+
+/**
+ * Save a project to the recent projects list.
+ * Updates the timestamp if the project already exists, otherwise adds it.
+ * Keeps only the most recent MAX_RECENT_PROJECTS projects.
+ * Validates that the path exists before saving.
+ */
+export const saveRecentProject = (projectPath: string): void => {
+  // Validate path exists before saving
+  if (!fs.existsSync(projectPath)) {
+    logger.debug({ projectPath }, 'Skipping save for non-existent project path')
+    return
+  }
+
+  const configDir = getConfigDir()
+  const recentProjectsPath = getRecentProjectsPath()
+
+  try {
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true })
+    }
+
+    // Load existing projects
+    const existingProjects = loadRecentProjects()
+
+    // Remove the project if it already exists (we'll add it back at the top)
+    const filteredProjects = existingProjects.filter(
+      (p) => p.path !== projectPath,
+    )
+
+    // Add the new/updated project at the beginning
+    const updatedProjects: RecentProject[] = [
+      { path: projectPath, lastOpened: Date.now() },
+      ...filteredProjects,
+    ].slice(0, MAX_RECENT_PROJECTS)
+
+    fs.writeFileSync(
+      recentProjectsPath,
+      JSON.stringify(updatedProjects, null, 2),
+    )
+  } catch (error) {
+    logger.debug(
+      { error: error instanceof Error ? error.message : String(error) },
+      'Error saving recent project',
+    )
+  }
+}

package/src/utils/renderer-cleanup.ts

@@ -0,0 +1,233 @@
+import { execFile } from 'child_process'
+
+import { resetTerminalTitle } from './terminal-title'
+import { stopActiveRun } from './active-run'
+import { getCliEnv } from './env'
+import { exitCliCleanly, registerExitCleanup } from './exit-cleanly'
+import { flushLiveChatState } from './run-state-storage'
+import { reportFatalErrorSync, writeTerminalControlSync } from './terminal-io'
+import { TERMINAL_RESET_SEQUENCES } from './terminal-reset-sequences'
+import { stopTerminalWatchdog } from './terminal-watchdog'
+
+import type { CliRenderer } from '@opentui/core'
+
+let renderer: CliRenderer | null = null
+let handlersInstalled = false
+let cleanupStarted = false
+
+function isProcessRunning(pid: number, onResult: (running: boolean) => void) {
+  if (process.platform === 'win32') {
+    execFile(
+      'tasklist',
+      ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'],
+      { windowsHide: true },
+      (error, stdout) => {
+        // A failed probe should never terminate a healthy CLI.
+        if (error) {
+          onResult(true)
+          return
+        }
+        onResult(new RegExp(`(?:^|\\D)${pid}(?:\\D|$)`).test(stdout))
+      },
+    )
+    return
+  }
+
+  try {
+    process.kill(pid, 0)
+    onResult(true)
+  } catch (error) {
+    onResult((error as NodeJS.ErrnoException).code === 'EPERM')
+  }
+}
+
+/**
+ * Reset terminal state by writing escape sequences to the controlling terminal.
+ * This is called after renderer.destroy() so buffered renderer output cannot
+ * land on the restored main screen after the reset.
+ *
+ * This is especially important on Windows where signals like SIGTERM and SIGHUP
+ * don't work, so we rely on the 'exit' event which is guaranteed to run.
+ */
+function resetTerminalState(): boolean {
+  try {
+    if (process.stdin.isTTY && process.stdin.setRawMode) {
+      process.stdin.setRawMode(false)
+    }
+  } catch {
+    // Ignore errors - stdin may already be closed
+  }
+  try {
+    // Reset terminal title to default
+    resetTerminalTitle()
+    if (!process.stdout.isTTY) return true
+
+    const resetCompletedSynchronously = writeTerminalControlSync(
+      TERMINAL_RESET_SEQUENCES,
+    )
+    if (!resetCompletedSynchronously) {
+      // Best-effort immediate reset. Keep the watchdog armed below so it can
+      // retry after this process exits if the buffered write is lost.
+      process.stdout.write(TERMINAL_RESET_SEQUENCES)
+    }
+    return resetCompletedSynchronously
+  } catch {
+    // Ignore errors - stdout may already be closed
+    return false
+  }
+}
+
+/**
+ * Destroy OpenTUI before resetting the terminal. destroy() can finalize
+ * synchronously or defer until an active frame finishes; in the deferred case,
+ * schedule the reset after the destroy event's remaining synchronous work.
+ */
+function destroyRendererAndResetTerminal(): boolean {
+  const activeRenderer = renderer
+  renderer = null
+  try {
+    if (!activeRenderer || activeRenderer.isDestroyed) {
+      return resetTerminalState()
+    }
+
+    let destroyReturned = false
+    let destroyFinalized = false
+    activeRenderer.once('destroy', () => {
+      destroyFinalized = true
+      if (destroyReturned) {
+        queueMicrotask(resetTerminalState)
+      }
+    })
+
+    activeRenderer.destroy()
+    destroyReturned = true
+    return destroyFinalized ? resetTerminalState() : false
+  } catch {
+    // A direct reset is still safe if renderer teardown itself failed.
+    return resetTerminalState()
+  }
+}
+
+/**
+ * Clean up the renderer by calling destroy().
+ * This resets terminal state to prevent garbled output after exit.
+ */
+function cleanup(): boolean {
+  if (cleanupStarted) {
+    // The process 'exit' handler deliberately reaches this branch to make the
+    // terminal reset the final write, even if destroy was deferred above.
+    return resetTerminalState()
+  }
+  cleanupStarted = true
+
+  // Finalize the active message before reading the live provider. This makes
+  // the synchronous flush include the interruption UI and prevents a late
+  // SDK callback from continuing to own the chat while shutdown proceeds.
+  try {
+    stopActiveRun('process-exit')
+  } catch {
+    // Continue restoring the terminal even if run finalization fails.
+  }
+
+  // Persist any in-flight chat state first (synchronous, best-effort) so
+  // closing the terminal or killing the process mid-run doesn't lose the turn.
+  try {
+    flushLiveChatState()
+  } catch {
+    // Persistence is best-effort during process teardown.
+  }
+
+  return destroyRendererAndResetTerminal()
+}
+
+/** Restore the terminal, report a fatal error synchronously, and exit. */
+export function exitCliWithFatalError(label: string, error: unknown): never {
+  const resetCompletedSynchronously = cleanup() || resetTerminalState()
+  if (resetCompletedSynchronously) {
+    stopTerminalWatchdog()
+  }
+  reportFatalErrorSync(label, error)
+  process.exit(1)
+}
+
+/**
+ * Install process-level signal handlers to ensure terminal cleanup on all exit scenarios.
+ * Call this once after creating the renderer in index.tsx.
+ *
+ * This handles:
+ * - SIGTERM (kill)
+ * - SIGHUP (terminal hangup)
+ * - SIGINT (Ctrl+C)
+ * - release launcher exit
+ * - beforeExit / exit events
+ * - uncaughtException / unhandledRejection
+ *
+ * Note: SIGKILL cannot be caught - it's an immediate termination signal.
+ */
+export function installProcessCleanupHandlers(cliRenderer: CliRenderer): void {
+  if (handlersInstalled) return
+  handlersInstalled = true
+  renderer = cliRenderer
+  registerExitCleanup(cleanup)
+
+  const handleExitRequest = () => {
+    void exitCliCleanly()
+  }
+
+  // A broad `taskkill node.exe` can kill the package's Node launcher without
+  // killing its Bun child. Polling avoids Bun's Windows behavior of terminating
+  // before JavaScript can handle a broken IPC channel or inherited pipe.
+  const launcherPid = Number(getCliEnv().ANVIL_LAUNCHER_PID)
+  if (
+    Number.isInteger(launcherPid) &&
+    launcherPid > 0 &&
+    launcherPid !== process.pid
+  ) {
+    let launcherCheckInFlight = false
+    const launcherMonitor = setInterval(() => {
+      if (launcherCheckInFlight) return
+      launcherCheckInFlight = true
+      isProcessRunning(launcherPid, (running) => {
+        launcherCheckInFlight = false
+        if (running) return
+        clearInterval(launcherMonitor)
+        handleExitRequest()
+      })
+    }, 500)
+    launcherMonitor.unref()
+  }
+
+  // SIGTERM - Default kill signal (e.g., `kill <pid>`)
+  process.on('SIGTERM', handleExitRequest)
+
+  // SIGHUP - Terminal hangup (e.g., closing the terminal window)
+  process.on('SIGHUP', handleExitRequest)
+
+  // SIGINT - Ctrl+C
+  process.on('SIGINT', handleExitRequest)
+
+  // beforeExit - Called when the event loop is empty and about to exit
+  process.on('beforeExit', () => {
+    cleanup()
+  })
+
+  // exit - Last chance to run synchronous cleanup code
+  process.on('exit', () => {
+    // Only silence the external fallback after the final reset bytes were
+    // synchronously accepted. If direct terminal access failed, leave it armed
+    // to repair the terminal after this process disappears.
+    if (cleanup()) {
+      stopTerminalWatchdog()
+    }
+  })
+
+  // uncaughtException - Safety net for unhandled errors
+  process.on('uncaughtException', (error) => {
+    exitCliWithFatalError('Uncaught exception', error)
+  })
+
+  // unhandledRejection - Safety net for unhandled promise rejections
+  process.on('unhandledRejection', (reason) => {
+    exitCliWithFatalError('Unhandled rejection', reason)
+  })
+}

package/src/utils/response-ad-positions.ts

@@ -0,0 +1 @@
+export * from '@anvil/common/util/response-ad-positions'