@alumbwe/anvil 1.0.0

package/src/utils/detect-shell.ts

@@ -0,0 +1,116 @@
+import { execSync } from 'child_process'
+
+import { getCliEnv } from './env'
+
+import type { CliEnv } from '../types/env'
+
+type KnownShell =
+  | 'bash'
+  | 'zsh'
+  | 'fish'
+  | 'cmd.exe'
+  | 'powershell'
+  | 'unknown'
+
+type ShellName = KnownShell | string
+
+let cachedShell: ShellName | null = null
+
+const SHELL_ALIASES: Record<string, KnownShell> = {
+  bash: 'bash',
+  zsh: 'zsh',
+  fish: 'fish',
+  cmd: 'cmd.exe',
+  'cmd.exe': 'cmd.exe',
+  pwsh: 'powershell',
+  powershell: 'powershell',
+  'powershell.exe': 'powershell',
+}
+
+export function detectShell(env: CliEnv = getCliEnv()): ShellName {
+  if (cachedShell) {
+    return cachedShell
+  }
+
+  const detected =
+    detectFromEnvironment(env) ?? detectViaParentProcessInspection() ?? 'unknown'
+  cachedShell = detected
+  return detected
+}
+
+function detectFromEnvironment(env: CliEnv): ShellName | null {
+  const candidates: Array<string | undefined> = []
+
+  if (process.platform === 'win32') {
+    candidates.push(env.COMSPEC, env.SHELL)
+  } else {
+    candidates.push(env.SHELL)
+  }
+
+  for (const candidate of candidates) {
+    const normalized = normalizeCandidate(candidate)
+    if (normalized) {
+      return normalized
+    }
+  }
+
+  return null
+}
+
+function detectViaParentProcessInspection(): ShellName | null {
+  try {
+    if (process.platform === 'win32') {
+      const parentProcess = execSync(
+        'wmic process get ParentProcessId,CommandLine',
+        { stdio: 'pipe' },
+      )
+        .toString()
+        .toLowerCase()
+
+      if (parentProcess.includes('powershell')) return 'powershell'
+      if (parentProcess.includes('cmd.exe')) return 'cmd.exe'
+    } else {
+      const parentProcess = execSync(`ps -p ${process.ppid} -o comm=`, {
+        stdio: 'pipe',
+      })
+        .toString()
+        .trim()
+      const normalized = normalizeCandidate(parentProcess)
+      if (normalized) return normalized
+    }
+  } catch {
+    // Ignore inspection errors
+  }
+
+  return null
+}
+
+function normalizeCandidate(value?: string | null): ShellName | null {
+  if (!value) {
+    return null
+  }
+
+  const trimmed = value.trim()
+  if (!trimmed) {
+    return null
+  }
+
+  const lower = trimmed.toLowerCase()
+  const parts = lower.split(/[/\\]/)
+  const last = parts.pop() ?? lower
+  const base = last.endsWith('.exe') ? last.slice(0, -4) : last
+
+  if (SHELL_ALIASES[base]) {
+    return SHELL_ALIASES[base]
+  }
+
+  if (SHELL_ALIASES[last]) {
+    return SHELL_ALIASES[last]
+  }
+
+  if (base.endsWith('sh')) {
+    return base
+  }
+
+  return null
+}

package/src/utils/directory-browser.ts

@@ -0,0 +1,72 @@
+import { readdirSync, statSync } from 'fs'
+import path from 'path'
+
+export type DirectoryEntry = {
+  name: string
+  path: string
+  isParent: boolean
+  isGitRepo: boolean
+}
+
+/**
+ * Get directory entries for a given path, including parent directory option.
+ * Skips hidden directories (those starting with '.').
+ */
+export function getDirectories(dirPath: string): DirectoryEntry[] {
+  const entries: DirectoryEntry[] = []
+
+  // Add parent directory option if not at filesystem root
+  const parentDir = path.dirname(dirPath)
+  if (parentDir !== dirPath) {
+    entries.push({
+      name: '..',
+      path: parentDir,
+      isParent: true,
+      isGitRepo: false,
+    })
+  }
+
+  try {
+    const items = readdirSync(dirPath)
+    for (const item of items) {
+      // Skip hidden directories
+      if (item.startsWith('.')) continue
+
+      const fullPath = path.join(dirPath, item)
+      try {
+        const stat = statSync(fullPath)
+        if (stat.isDirectory()) {
+          entries.push({
+            name: item,
+            path: fullPath,
+            isParent: false,
+            isGitRepo: hasGitDirectory(fullPath),
+          })
+        }
+      } catch {
+        // Skip items we can't stat
+      }
+    }
+  } catch {
+    // If we can't read the directory, just return parent option
+  }
+
+  // Sort non-parent entries alphabetically (case-insensitive)
+  const parentEntry = entries.find((e) => e.isParent)
+  const childEntries = entries.filter((e) => !e.isParent)
+  childEntries.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()))
+
+  return parentEntry ? [parentEntry, ...childEntries] : childEntries
+}
+
+/**
+ * Check if a directory contains a .git subdirectory.
+ */
+export function hasGitDirectory(dirPath: string): boolean {
+  try {
+    const gitPath = path.join(dirPath, '.git')
+    return statSync(gitPath).isDirectory()
+  } catch {
+    return false
+  }
+}

package/src/utils/engagement.ts

@@ -0,0 +1,55 @@
+import { AnalyticsEvent } from '@anvil/common/constants/analytics-events'
+import {
+  EngagementTracker,
+  createEngagementSessionId,
+} from '@anvil/common/util/engagement-tracker'
+
+import { subscribeToActivity } from './activity-tracker'
+import { trackEvent } from './analytics'
+
+/**
+ * CLI engaged-time heartbeat. Reuses the existing activity-tracker (keystrokes,
+ * mouse movement, prompt submits already call `reportActivity()`) as the
+ * presence signal, and emits one `PRODUCT_ACTIVE_MINUTE` per active minute with
+ * `surface: 'cli'`. There is no tab/visibility concept in a terminal, so the
+ * surface is always "present"; idleness alone gates the count.
+ */
+
+let tracker: EngagementTracker | undefined
+let unsubscribeActivity: (() => void) | undefined
+
+export function startEngagementTracking(): void {
+  if (tracker) {
+    return
+  }
+
+  const sessionId = createEngagementSessionId()
+
+  tracker = new EngagementTracker({
+    emit: () =>
+      trackEvent(AnalyticsEvent.PRODUCT_ACTIVE_MINUTE, {
+        surface: 'cli',
+        engagement_session_id: sessionId,
+      }),
+    // Unref the timer so the heartbeat never keeps the process alive on exit.
+    scheduler: {
+      setInterval: (fn: () => void, ms: number) => {
+        const t = setInterval(fn, ms)
+        t.unref?.()
+        return t
+      },
+      clearInterval: (t: unknown) =>
+        clearInterval(t as ReturnType<typeof setInterval>),
+    },
+  })
+
+  unsubscribeActivity = subscribeToActivity(() => tracker?.recordActivity())
+  tracker.start()
+}
+
+export function stopEngagementTracking(): void {
+  unsubscribeActivity?.()
+  unsubscribeActivity = undefined
+  tracker?.stop()
+  tracker = undefined
+}

package/src/utils/env.ts

@@ -0,0 +1,92 @@
+/**
+ * CLI environment helper for dependency injection.
+ *
+ * This module provides CLI-specific env helpers that extend the base
+ * process env with CLI-specific vars for terminal/IDE detection.
+ */
+
+import { getBaseEnv } from '@anvil/common/env-process'
+
+import type { CliEnv } from '../types/env'
+
+/**
+ * Get CLI environment values.
+ * Composes from getBaseEnv() + CLI-specific vars.
+ */
+export const getCliEnv = (): CliEnv => ({
+  ...getBaseEnv(),
+
+  // Windows system paths
+  SystemRoot: process.env.SystemRoot,
+
+  // Display server detection (Linux headless check)
+  DISPLAY: process.env.DISPLAY,
+  WAYLAND_DISPLAY: process.env.WAYLAND_DISPLAY,
+
+  // Terminal detection (for tmux/screen passthrough)
+  TERM: process.env.TERM,
+  TMUX: process.env.TMUX,
+  STY: process.env.STY,
+
+  // SSH/remote session detection
+  SSH_CLIENT: process.env.SSH_CLIENT,
+  SSH_TTY: process.env.SSH_TTY,
+  SSH_CONNECTION: process.env.SSH_CONNECTION,
+  CODESPACES: process.env.CODESPACES,
+
+  // Terminal detection
+  KITTY_WINDOW_ID: process.env.KITTY_WINDOW_ID,
+  SIXEL_SUPPORT: process.env.SIXEL_SUPPORT,
+  ZED_NODE_ENV: process.env.ZED_NODE_ENV,
+  ZED_TERM: process.env.ZED_TERM,
+  ZED_SHELL: process.env.ZED_SHELL,
+  COLORTERM: process.env.COLORTERM,
+
+  // VS Code family detection
+  VSCODE_THEME_KIND: process.env.VSCODE_THEME_KIND,
+  VSCODE_COLOR_THEME_KIND: process.env.VSCODE_COLOR_THEME_KIND,
+  VSCODE_GIT_IPC_HANDLE: process.env.VSCODE_GIT_IPC_HANDLE,
+  VSCODE_PID: process.env.VSCODE_PID,
+  VSCODE_CWD: process.env.VSCODE_CWD,
+  VSCODE_NLS_CONFIG: process.env.VSCODE_NLS_CONFIG,
+
+  // Cursor editor detection
+  CURSOR_PORT: process.env.CURSOR_PORT,
+  CURSOR: process.env.CURSOR,
+
+  // JetBrains IDE detection
+  JETBRAINS_REMOTE_RUN: process.env.JETBRAINS_REMOTE_RUN,
+  IDEA_INITIAL_DIRECTORY: process.env.IDEA_INITIAL_DIRECTORY,
+  IDE_CONFIG_DIR: process.env.IDE_CONFIG_DIR,
+  JB_IDE_CONFIG_DIR: process.env.JB_IDE_CONFIG_DIR,
+
+  // Editor preferences
+  VISUAL: process.env.VISUAL,
+  EDITOR: process.env.EDITOR,
+  ANVIL_CLI_EDITOR: process.env.ANVIL_CLI_EDITOR,
+  ANVIL_EDITOR: process.env.ANVIL_EDITOR,
+
+  // Theme preferences
+  OPEN_TUI_THEME: process.env.OPEN_TUI_THEME,
+  OPENTUI_THEME: process.env.OPENTUI_THEME,
+
+  // Binary build configuration
+  ANVIL_IS_BINARY: process.env.ANVIL_IS_BINARY,
+  ANVIL_CLI_VERSION: process.env.ANVIL_CLI_VERSION,
+  ANVIL_CLI_TARGET: process.env.ANVIL_CLI_TARGET,
+  ANVIL_RG_PATH: process.env.ANVIL_RG_PATH,
+  ANVIL_SCROLL_MULTIPLIER: process.env.ANVIL_SCROLL_MULTIPLIER,
+  ANVIL_PERF_TEST: process.env.ANVIL_PERF_TEST,
+  ANVIL_TRACE: process.env.ANVIL_TRACE,
+  ANVIL_LAUNCHER_PID: process.env.ANVIL_LAUNCHER_PID,
+  ANVIL_SHIP_LOGS: process.env.ANVIL_SHIP_LOGS,
+  ANVIL_NO_TERMINAL_WATCHDOG: process.env.ANVIL_NO_TERMINAL_WATCHDOG,
+  FREEBUFF_MODE: process.env.FREEBUFF_MODE,
+})
+
+/**
+ * Get the raw system process.env object.
+ * Use this when you need to pass the full environment to subprocesses
+ * or when you need to set environment variables at runtime.
+ */
+export const getSystemProcessEnv = (): NodeJS.ProcessEnv => process.env

package/src/utils/error-handling.ts

@@ -0,0 +1,255 @@
+import { FREEBUFF_PROVIDER_USAGE_ERROR_PATTERN } from '@anvil/common/constants/freebuff-errors'
+import { env } from '@anvil/common/env'
+import { extractApiErrorDetails } from '@anvil/common/util/error'
+import { formatFreebuffHardBlockedPrivacySignals } from '@anvil/common/util/freebuff-privacy'
+import { getFreebuffGateCode } from '@anvil/common/types/freebuff-session'
+
+import type { ChatMessage } from '../types/chat'
+import type {
+  FreebuffCountryBlockReason,
+  FreebuffGateCode,
+  FreebuffIpPrivacySignal,
+} from '@anvil/common/types/freebuff-session'
+
+import { IS_FREEBUFF } from './constants'
+
+const defaultAppUrl = env.NEXT_PUBLIC_ANVIL_APP_URL || 'https://codebuff.com'
+
+// Normalize unknown errors to a user-facing string.
+const extractErrorMessage = (error: unknown, fallback: string): string => {
+  if (typeof error === 'string') {
+    return error
+  }
+  if (error instanceof Error && error.message) {
+    return error.message + (error.stack ? `\n\n${error.stack}` : '')
+  }
+  if (error && typeof error === 'object' && 'message' in error) {
+    const candidate = (error as { message: unknown }).message
+    if (typeof candidate === 'string' && candidate.length > 0) {
+      return candidate
+    }
+  }
+  return fallback
+}
+
+/**
+ * Check if an error indicates the user is out of credits.
+ * Standardized on statusCode === 402 for payment required detection.
+ */
+export const isOutOfCreditsError = (error: unknown): boolean => {
+  if (
+    error &&
+    typeof error === 'object' &&
+    'statusCode' in error &&
+    (error as { statusCode: unknown }).statusCode === 402
+  ) {
+    return true
+  }
+  return false
+}
+
+/**
+ * Check if an error indicates free mode is not available in the user's country.
+ * Standardized on statusCode === 403 + error === 'free_mode_unavailable'.
+ */
+export const isFreeModeUnavailableError = (error: unknown): boolean => {
+  const details = getCliApiErrorDetails(error)
+  return (
+    details.statusCode === 403 &&
+    details.errorCode === 'free_mode_unavailable'
+  )
+}
+
+const getTopLevelApiErrorDetails = (
+  error: unknown,
+): {
+  statusCode?: number
+  errorCode?: string
+  message?: string
+  countryCode?: string
+  countryBlockReason?: string
+  ipPrivacySignals?: string[]
+} => {
+  if (!error || typeof error !== 'object') return {}
+  const statusCode = (error as { statusCode?: unknown }).statusCode
+  const status = (error as { status?: unknown }).status
+  const errorCode = (error as { error?: unknown }).error
+  const message = (error as { message?: unknown }).message
+  const countryCode = (error as { countryCode?: unknown }).countryCode
+  const countryBlockReason = (error as { countryBlockReason?: unknown })
+    .countryBlockReason
+  const ipPrivacySignals = (error as { ipPrivacySignals?: unknown })
+    .ipPrivacySignals
+  const resolvedStatusCode =
+    typeof statusCode === 'number'
+      ? statusCode
+      : typeof status === 'number'
+        ? status
+        : undefined
+
+  return {
+    ...(resolvedStatusCode !== undefined && { statusCode: resolvedStatusCode }),
+    ...(typeof errorCode === 'string' && { errorCode }),
+    ...(typeof message === 'string' && message.length > 0 && { message }),
+    ...(typeof countryCode === 'string' &&
+      countryCode.length > 0 && { countryCode }),
+    ...(typeof countryBlockReason === 'string' && { countryBlockReason }),
+    ...(Array.isArray(ipPrivacySignals) && {
+      ipPrivacySignals: ipPrivacySignals.filter(
+        (signal): signal is string => typeof signal === 'string',
+      ),
+    }),
+  }
+}
+
+const getCliApiErrorDetails = (error: unknown) => {
+  const parsed = extractApiErrorDetails(error)
+  const topLevel = getTopLevelApiErrorDetails(error)
+
+  return {
+    statusCode: topLevel.statusCode ?? parsed.statusCode,
+    errorCode: topLevel.errorCode ?? parsed.errorCode,
+    // Prefer responseBody messages over top-level HTTP status text.
+    message: parsed.message ?? topLevel.message,
+    countryCode: topLevel.countryCode ?? parsed.countryCode,
+    countryBlockReason:
+      topLevel.countryBlockReason ?? parsed.countryBlockReason,
+    ipPrivacySignals: topLevel.ipPrivacySignals ?? parsed.ipPrivacySignals,
+  }
+}
+
+export const getFreebuffRateLimitErrorMessage = (
+  error: unknown,
+): string | null => {
+  const details = getCliApiErrorDetails(error)
+  if (details.statusCode !== 429) return null
+  if (details.errorCode === 'free_mode_rate_limited') {
+    // Our own rate limiter's message is already user-facing and includes the
+    // retry countdown — show it verbatim.
+    return details.message ?? FREEBUFF_RATE_LIMIT_MESSAGE
+  }
+  // Other 429s (e.g. relayed upstream capacity errors) keep the branded
+  // message but include the server detail so users aren't left guessing.
+  // Only trust messages parsed from a server response body, or the curated
+  // message on an agent-run output object — top-level messages on raw thrown
+  // errors are HTTP status text or retry-wrapper noise.
+  const isRunOutputObject =
+    !!error &&
+    typeof error === 'object' &&
+    (error as { type?: unknown }).type === 'error'
+  const detail =
+    extractApiErrorDetails(error).message ??
+    (isRunOutputObject ? details.message : undefined)
+  if (detail && !/^too many requests\.?$/i.test(detail)) {
+    return `${FREEBUFF_RATE_LIMIT_MESSAGE} (${detail})`
+  }
+  return FREEBUFF_RATE_LIMIT_MESSAGE
+}
+
+/**
+ * Provider billing failures are an operator problem in Freebuff, not a reason
+ * to send a free user to Anvil's credit-purchase flow. Upstreams disagree
+ * on the status (observed as both 401 and 402), so retain the status check but
+ * also recognize the provider wording that can survive into an agent output.
+ */
+export const isFreebuffProviderUsageError = (error: unknown): boolean => {
+  const details = getCliApiErrorDetails(error)
+  const message = details.message ?? extractErrorMessage(error, '')
+  return (
+    details.statusCode === 402 ||
+    FREEBUFF_PROVIDER_USAGE_ERROR_PATTERN.test(message)
+  )
+}
+
+export const getCountryBlockFromFreeModeError = (
+  error: unknown,
+): {
+  countryCode: string
+  countryBlockReason?: FreebuffCountryBlockReason
+  ipPrivacySignals?: FreebuffIpPrivacySignal[]
+} | null => {
+  if (!isFreeModeUnavailableError(error)) return null
+  const errorDetails = getCliApiErrorDetails(error)
+  const countryCode =
+    typeof errorDetails.countryCode === 'string' &&
+    errorDetails.countryCode.length > 0
+      ? errorDetails.countryCode
+      : 'UNKNOWN'
+
+  return {
+    countryCode,
+    countryBlockReason:
+      typeof errorDetails.countryBlockReason === 'string'
+        ? (errorDetails.countryBlockReason as FreebuffCountryBlockReason)
+        : undefined,
+    ipPrivacySignals: errorDetails.ipPrivacySignals as
+      | FreebuffIpPrivacySignal[]
+      | undefined,
+  }
+}
+
+export const getFreeModeUnavailableErrorMessage = (
+  error: unknown,
+): string => {
+  const details = getCliApiErrorDetails(error)
+  const block = getCountryBlockFromFreeModeError(error)
+  if (block?.countryBlockReason === 'anonymous_network') {
+    return `${IS_FREEBUFF ? 'Freebuff' : 'Free mode'} cannot be used from ${formatFreebuffHardBlockedPrivacySignals(
+      block.ipPrivacySignals,
+    )} traffic. Please disable it and try again.`
+  }
+  return details.message ?? FREE_MODE_UNAVAILABLE_MESSAGE
+}
+
+/**
+ * The subset of the session gate the CLI has a recovery for. The codes and
+ * their statuses come from FREEBUFF_GATE_CODES (the shared wire contract, see
+ * docs/freebuff-session-admission.md); the narrowing is deliberate —
+ * `session_limit_reached` is the Desktop concurrent-tab cap, and the CLI runs
+ * one session per user, so it can never earn it and has no banner for it.
+ *
+ * The names keep their legacy waiting-room spelling for wire compatibility.
+ */
+export type FreebuffGateErrorKind = Exclude<
+  FreebuffGateCode,
+  'session_limit_reached'
+>
+
+export const getFreebuffGateErrorKind = (
+  error: unknown,
+): FreebuffGateErrorKind | null => {
+  if (!error || typeof error !== 'object') return null
+  const { error: errorCode, statusCode } = error as {
+    error?: unknown
+    statusCode?: unknown
+  }
+  if (typeof errorCode !== 'string') return null
+  const code = getFreebuffGateCode({
+    error: errorCode,
+    statusCode: typeof statusCode === 'number' ? statusCode : undefined,
+  })
+  return code && code !== 'session_limit_reached' ? code : null
+}
+
+export const OUT_OF_CREDITS_MESSAGE = `Out of credits. Please add credits at ${defaultAppUrl}/usage`
+
+export const FREEBUFF_RATE_LIMIT_MESSAGE =
+  'Freebuff is temporarily busy. Please try again in a moment.'
+
+export const FREE_MODE_UNAVAILABLE_MESSAGE = IS_FREEBUFF
+  ? 'Freebuff is not available in your country.'
+  : 'Free mode is not available in your country. You can use another mode to continue.'
+
+export const createErrorMessage = (
+  error: unknown,
+  aiMessageId: string,
+): Partial<ChatMessage> => {
+  const message = extractErrorMessage(error, 'Unknown error occurred')
+
+  return {
+    id: aiMessageId,
+    content: `**Error:** ${message}`,
+    blocks: undefined,
+    isComplete: true,
+  }
+}

package/src/utils/error-messages.ts

@@ -0,0 +1,62 @@
+import { sanitizeErrorMessage, getErrorStatusCode } from '@anvil/sdk'
+
+/**
+ * Formats an unknown error into a user-facing markdown string.
+ *
+ * The goal is to provide clear, consistent messaging across the CLI.
+ */
+export function formatErrorForDisplay(error: unknown, fallbackTitle: string): string {
+  const statusCode = getErrorStatusCode(error)
+
+  // Authentication-specific messaging based on statusCode
+  if (statusCode === 401) {
+    return `${fallbackTitle}: Authentication failed. Please check your API key.`
+  }
+  if (statusCode === 403) {
+    return `${fallbackTitle}: Access forbidden. You do not have permission to access this resource.`
+  }
+
+  // Network/server error messaging based on statusCode
+  if (statusCode !== undefined) {
+    if (statusCode === 408) {
+      return `${fallbackTitle}: Request timed out. Please check your internet connection.`
+    }
+    if (statusCode === 503) {
+      return `${fallbackTitle}: Service unavailable. The server may be down.`
+    }
+    if (statusCode >= 500) {
+      return `${fallbackTitle}: Server error. Please try again later.`
+    }
+    if (statusCode === 429) {
+      return `${fallbackTitle}: Rate limited. Please try again later.`
+    }
+  }
+
+  // Generic Error instance
+  if (error instanceof Error) {
+    const message = error.message || 'An unexpected error occurred.'
+    return `${fallbackTitle}: ${message}`
+  }
+
+  // Try sanitizeErrorMessage for other cases
+  const safeMessage = sanitizeErrorMessage(error)
+  return `${fallbackTitle}: ${safeMessage}`
+}
+
+/**
+ * Formats a retry banner message for offline / retry scenarios.
+ *
+ * Example output:
+ *   "⚠️ Network error: Server error. Please try again later. • 3 messages will retry when connection is restored"
+ */
+export function formatRetryBannerMessage(error: unknown, pendingCount: number): string {
+  const baseTitle = 'Network error'
+  const formatted = formatErrorForDisplay(error, baseTitle)
+
+  const suffix =
+    pendingCount > 0
+      ? ` • ${pendingCount} message${pendingCount === 1 ? '' : 's'} will retry when connection is restored`
+      : ''
+
+  return `⚠️ ${formatted}${suffix}`
+}