@alumbwe/anvil 1.0.0

package/src/utils/exit-cleanly.ts

@@ -0,0 +1,86 @@
+import { flushAnalytics } from './analytics'
+import { IS_FREEBUFF } from './constants'
+import { stopEngagementTracking } from './engagement'
+import { endFreebuffSessionBestEffort } from './freebuff-session-api'
+import { drainClientLogs } from './log-shipper'
+import { withTimeout } from './terminal-color-detection'
+
+const EXIT_CLEANUP_TIMEOUT_MS = 1_000
+
+type ExitCliDependencies = {
+  isFreebuff: boolean
+  cleanupLocal: () => void
+  stopEngagementTracking: () => void
+  flushAnalytics: () => Promise<void>
+  drainClientLogs: () => Promise<void>
+  endFreebuffSession: () => Promise<void>
+  waitForRemoteCleanup: (tasks: Promise<void>[]) => Promise<void>
+  exit: (code: number) => void
+}
+
+let localExitCleanup: (() => void) | undefined
+
+/** Register the synchronous renderer/terminal finalizer once it is available. */
+export function registerExitCleanup(cleanup: () => void): void {
+  localExitCleanup = cleanup
+}
+
+/**
+ * Build an idempotent exit request. Exported for dependency-injected tests;
+ * production uses the singleton below so competing exit triggers converge.
+ */
+export function createExitCliCleanly(deps: ExitCliDependencies) {
+  let exitPromise: Promise<void> | undefined
+
+  return (exitCode = 0): Promise<void> => {
+    if (exitPromise) return exitPromise
+
+    // Start on the next microtask so exitPromise is assigned before any cleanup
+    // callback can re-enter this function.
+    exitPromise = Promise.resolve().then(async () => {
+      try {
+        deps.cleanupLocal()
+      } catch {
+        // Cleanup is best-effort; never strand the process in a half-exited UI.
+      }
+      if (deps.isFreebuff) {
+        try {
+          deps.stopEngagementTracking()
+        } catch {}
+      }
+
+      const remoteTasks = [
+        Promise.resolve().then(deps.flushAnalytics),
+        Promise.resolve().then(deps.drainClientLogs),
+      ]
+      if (deps.isFreebuff) {
+        remoteTasks.push(Promise.resolve().then(deps.endFreebuffSession))
+      }
+
+      try {
+        await deps.waitForRemoteCleanup(remoteTasks)
+      } finally {
+        deps.exit(exitCode)
+      }
+    })
+
+    return exitPromise
+  }
+}
+
+export const exitCliCleanly = createExitCliCleanly({
+  isFreebuff: IS_FREEBUFF,
+  cleanupLocal: () => localExitCleanup?.(),
+  stopEngagementTracking,
+  flushAnalytics,
+  drainClientLogs,
+  endFreebuffSession: endFreebuffSessionBestEffort,
+  waitForRemoteCleanup: async (tasks) => {
+    await withTimeout(
+      Promise.allSettled(tasks),
+      EXIT_CLEANUP_TIMEOUT_MS,
+      undefined,
+    )
+  },
+  exit: (code) => process.exit(code),
+})

package/src/utils/feedback-helpers.ts

@@ -0,0 +1,103 @@
+import {
+  MAX_ERROR_ID_LENGTH,
+  MAX_ERROR_MESSAGE_LENGTH,
+  MAX_ERRORS,
+  MAX_RECENT_MESSAGES,
+} from '@anvil/common/constants/feedback'
+
+import type { ChatMessage } from '../types/chat'
+import type { FeedbackCategory } from '@anvil/common/constants/feedback'
+
+import type { FeedbackRequest } from '@anvil/common/schemas/feedback'
+
+export type RecentMessageSummary = NonNullable<
+  FeedbackRequest['recentMessages']
+>[number]
+
+function toRecentMessageSummary(m: ChatMessage): RecentMessageSummary {
+  return {
+    type: m.variant,
+    id: m.id,
+    ...(m.completionTime != null && { completionTime: m.completionTime }),
+    ...(m.credits != null && { credits: m.credits }),
+  }
+}
+
+export function buildMessageContext(
+  messages: ChatMessage[],
+  targetMessageId: string | null,
+): {
+  target: ChatMessage | null
+  recentMessages: RecentMessageSummary[]
+} {
+  if (!targetMessageId) {
+    const startIndex = Math.max(0, messages.length - MAX_RECENT_MESSAGES)
+    return { target: null, recentMessages: messages.slice(startIndex).map(toRecentMessageSummary) }
+  }
+
+  const target = messages.find((m: ChatMessage) => m.id === targetMessageId) ?? null
+
+  if (!target) {
+    return { target: null, recentMessages: [] }
+  }
+
+  const targetIndex = messages.indexOf(target)
+  const startIndex = Math.max(0, targetIndex - (MAX_RECENT_MESSAGES - 1))
+  return { target, recentMessages: messages.slice(startIndex, targetIndex + 1).map(toRecentMessageSummary) }
+}
+
+export interface BuildFeedbackPayloadParams {
+  text: string
+  feedbackCategory: FeedbackCategory
+  feedbackMessageId: string | null
+  target: ChatMessage | null
+  recentMessages: RecentMessageSummary[]
+  agentMode: string | null
+  sessionCreditsUsed: number | null
+  errors: Array<{ id: string; message: string }> | null
+  clientFeedbackId: string
+}
+
+export function buildFeedbackPayload(
+  params: BuildFeedbackPayloadParams,
+): FeedbackRequest {
+  const {
+    text,
+    feedbackCategory,
+    feedbackMessageId,
+    target,
+    recentMessages,
+    agentMode,
+    sessionCreditsUsed,
+    errors,
+    clientFeedbackId,
+  } = params
+
+  const hasMessageId = feedbackMessageId != null && feedbackMessageId !== ''
+  const feedbackType: 'message' | 'general' = hasMessageId ? 'message' : 'general'
+
+  const truncatedErrors = errors
+    ? errors.slice(0, MAX_ERRORS).map((e) => ({
+        id: e.id.slice(0, MAX_ERROR_ID_LENGTH),
+        message: e.message.slice(0, MAX_ERROR_MESSAGE_LENGTH),
+      }))
+    : null
+
+  return {
+    text,
+    category: feedbackCategory,
+    type: feedbackType,
+    clientFeedbackId,
+    source: 'cli',
+    ...(hasMessageId && { messageId: feedbackMessageId }),
+    ...(target?.variant != null && { messageVariant: target.variant }),
+    ...(target?.completionTime != null && target.completionTime !== '' && {
+      completionTime: target.completionTime,
+    }),
+    ...(target?.credits != null && { credits: target.credits }),
+    ...(agentMode != null && agentMode !== '' && { agentMode }),
+    ...(sessionCreditsUsed != null && { sessionCreditsUsed }),
+    ...(recentMessages.length > 0 && { recentMessages }),
+    ...(truncatedErrors && truncatedErrors.length > 0 && { errors: truncatedErrors }),
+  }
+}

package/src/utils/feedback-submission.ts

@@ -0,0 +1,22 @@
+export interface FeedbackSubmissionResolution {
+  isCurrentSubmission: boolean
+  shouldSettleSubmission: boolean
+}
+
+/**
+ * Decide whether an async feedback result should update local state.
+ *
+ * - current submission id => settle and apply full success path
+ * - null active id => feedback was closed while request was in-flight; still settle
+ * - different active id => a newer feedback session exists; ignore stale result
+ */
+export function resolveFeedbackSubmission(
+  activeClientFeedbackId: string | null,
+  submittedClientFeedbackId: string,
+): FeedbackSubmissionResolution {
+  const isCurrentSubmission = activeClientFeedbackId === submittedClientFeedbackId
+  return {
+    isCurrentSubmission,
+    shouldSettleSubmission: isCurrentSubmission || activeClientFeedbackId === null,
+  }
+}

package/src/utils/fetch-usage.ts

@@ -0,0 +1,76 @@
+import { getAuthToken } from './auth'
+import { getApiClient } from './anvil-api'
+import { logger } from './logger'
+import { useChatStore } from '../state/chat-store'
+
+import type { AnvilApiClient } from './anvil-api'
+import type { Logger } from '@anvil/common/types/contracts/logger'
+
+export interface FetchAndUpdateUsageParams {
+  showBanner?: boolean
+  getAuthToken?: () => string | undefined
+  getChatStore?: () => {
+    sessionCreditsUsed: number
+    setInputMode: (mode: 'usage' | 'default') => void
+  }
+  logger?: Logger
+  apiClient?: AnvilApiClient
+}
+
+/**
+ * Fetches current usage data from the API and updates the chat store.
+ * If `showBanner` is true, makes the usage banner visible after updating.
+ * Returns true if successful, false otherwise.
+ */
+export async function fetchAndUpdateUsage(
+  params: FetchAndUpdateUsageParams = {},
+): Promise<boolean> {
+  const {
+    showBanner = false,
+    getAuthToken: getAuthTokenFn = getAuthToken,
+    getChatStore = () => useChatStore.getState(),
+    logger: loggerInstance = logger,
+    apiClient: providedApiClient,
+  } = params
+
+  const authToken = getAuthTokenFn()
+  const chatStore = getChatStore()
+
+  if (!authToken) {
+    loggerInstance.debug('Cannot fetch usage: not authenticated')
+    return false
+  }
+
+  const apiClient =
+    providedApiClient ?? getApiClient()
+
+  try {
+    const response = await apiClient.usage()
+
+    if (!response.ok) {
+      loggerInstance.error(
+        { status: response.status, errorText: response.error },
+        'Usage request failed',
+      )
+      return false
+    }
+
+    // Note: This function is deprecated. Use useUsageQuery hook instead.
+    // We no longer update the store here since usage data is managed by TanStack Query.
+
+    if (showBanner) {
+      chatStore.setInputMode('usage')
+    }
+
+    return true
+  } catch (error) {
+    loggerInstance.error(
+      {
+        error: error instanceof Error ? error.message : String(error),
+        errorStack: error instanceof Error ? error.stack : undefined,
+      },
+      'Error fetching usage',
+    )
+    return false
+  }
+}

package/src/utils/fingerprint.ts

@@ -0,0 +1,245 @@
+/**
+ * Enhanced fingerprinting for CLI authentication.
+ *
+ * Uses hardware-based identifiers to create deterministic fingerprints,
+ * making it harder for users to game the system by creating multiple accounts.
+ *
+ * Falls back to legacy random fingerprints if enhanced fingerprinting fails.
+ */
+
+import { createHash, randomBytes } from 'node:crypto'
+import { cpus, networkInterfaces } from 'node:os'
+
+import { AnalyticsEvent } from '@anvil/common/constants/analytics-events'
+
+import { trackEvent } from './analytics'
+import { detectShell } from './detect-shell'
+import { logger } from './logger'
+
+// Lazy imports for optional dependencies
+let machineIdModule: typeof import('node-machine-id') | null = null
+let systeminformationModule: typeof import('systeminformation') | null = null
+
+async function getMachineId(): Promise<string> {
+  if (!machineIdModule) {
+    machineIdModule = await import('node-machine-id')
+  }
+  const id = await machineIdModule.machineId()
+  // Validate that we got a real machine ID, not an empty or placeholder value.
+  // Throwing here triggers the legacy fallback in calculateFingerprint().
+  if (!id || id === 'unknown' || id.length < 8) {
+    throw new Error('Invalid machine ID returned')
+  }
+  return id
+}
+
+async function getSystemInfo(): Promise<{
+  system: { manufacturer: string; model: string; serial: string; uuid: string }
+  cpu: { manufacturer: string; brand: string; cores: number; physicalCores: number }
+  os: { platform: string; distro: string; arch: string; hostname: string }
+}> {
+  try {
+    if (!systeminformationModule) {
+      systeminformationModule = await import('systeminformation')
+    }
+    const [systemInfo, cpuInfo, osInfo] = await Promise.all([
+      systeminformationModule.system(),
+      systeminformationModule.cpu(),
+      systeminformationModule.osInfo(),
+    ])
+    return {
+      system: {
+        manufacturer: systemInfo.manufacturer,
+        model: systemInfo.model,
+        serial: systemInfo.serial,
+        uuid: systemInfo.uuid,
+      },
+      cpu: {
+        manufacturer: cpuInfo.manufacturer,
+        brand: cpuInfo.brand,
+        cores: cpuInfo.cores,
+        physicalCores: cpuInfo.physicalCores,
+      },
+      os: {
+        platform: osInfo.platform,
+        distro: osInfo.distro,
+        arch: osInfo.arch,
+        hostname: osInfo.hostname,
+      },
+    }
+  } catch {
+    return {
+      system: { manufacturer: '', model: '', serial: '', uuid: '' },
+      cpu: { manufacturer: '', brand: '', cores: 0, physicalCores: 0 },
+      os: { platform: process.platform, distro: '', arch: process.arch, hostname: '' },
+    }
+  }
+}
+
+/**
+ * Generates an enhanced CLI fingerprint using hardware identifiers.
+ * This is deterministic - the same machine will always produce the same fingerprint.
+ * Throws if machine ID cannot be obtained (to trigger legacy fallback).
+ */
+async function calculateEnhancedFingerprint(): Promise<string> {
+  // getMachineId will throw if it can't get a valid machine ID
+  const machineIdValue = await getMachineId()
+  
+  const [sysInfo, shell, networkInfo] = await Promise.all([
+    getSystemInfo(),
+    Promise.resolve(detectShell()),
+    Promise.resolve(networkInterfaces()),
+  ])
+
+  // Extract MAC addresses for additional uniqueness
+  const macAddresses = Object.values(networkInfo)
+    .flat()
+    .filter(
+      (iface) =>
+        iface && !iface.internal && iface.mac && iface.mac !== '00:00:00:00:00:00',
+    )
+    .map((iface) => iface!.mac)
+    .sort()
+
+  const fingerprintInfo = {
+    system: sysInfo.system,
+    cpu: sysInfo.cpu,
+    os: sysInfo.os,
+    runtime: {
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      shell,
+      cpuCount: cpus().length,
+    },
+    network: {
+      macAddresses,
+      interfaceCount: Object.keys(networkInfo).length,
+    },
+    machineId: machineIdValue,
+    fingerprintVersion: '2.0',
+  }
+
+  const fingerprintString = JSON.stringify(fingerprintInfo)
+  const fingerprintHash = createHash('sha256')
+    .update(fingerprintString)
+    .digest('base64url')
+
+  return `enhanced-${fingerprintHash}`
+}
+
+/**
+ * Generates a legacy fingerprint with a random suffix.
+ * Used as a fallback when enhanced fingerprinting fails.
+ */
+function calculateLegacyFingerprint(): string {
+  const randomSuffix = randomBytes(6).toString('base64url').substring(0, 8)
+  return `anvil-cli-${randomSuffix}`
+}
+
+/**
+ * Cached fingerprint promise. Populated on first call and reused for the
+ * process lifetime so every auth step in a session ships the same fingerprint
+ * to the server.
+ */
+let cachedFingerprintPromise: Promise<string> | null = null
+
+/**
+ * Returns the process-wide CLI fingerprint, computing it on first call.
+ * Safe to call from multiple places — the first caller wins and the rest
+ * await the same promise.
+ */
+export function getFingerprintId(): Promise<string> {
+  if (!cachedFingerprintPromise) {
+    cachedFingerprintPromise = calculateFingerprint()
+  }
+  return cachedFingerprintPromise
+}
+
+/**
+ * Main fingerprint function.
+ * Tries enhanced fingerprinting first, falls back to legacy if it fails.
+ */
+export async function calculateFingerprint(): Promise<string> {
+  try {
+    const fingerprint = await calculateEnhancedFingerprint()
+    logger.debug(
+      {
+        fingerprintType: 'enhanced_cli',
+        fingerprintId: fingerprint.substring(0, 20) + '...',
+      },
+      'Enhanced CLI fingerprint generated successfully',
+    )
+    trackEvent(AnalyticsEvent.FINGERPRINT_GENERATED, {
+      fingerprintType: 'enhanced_cli',
+      success: true,
+    })
+    return fingerprint
+  } catch (enhancedError) {
+    logger.info(
+      {
+        errorMessage:
+          enhancedError instanceof Error ? enhancedError.message : String(enhancedError),
+        fingerprintType: 'enhanced_failed_fallback',
+      },
+      'Enhanced CLI fingerprinting failed, using legacy fallback',
+    )
+
+    try {
+      const fingerprint = calculateLegacyFingerprint()
+      logger.debug(
+        {
+          fingerprintType: 'legacy_fallback',
+          fingerprintId: fingerprint,
+        },
+        'Legacy fingerprint generated successfully as fallback',
+      )
+      trackEvent(AnalyticsEvent.FINGERPRINT_GENERATED, {
+        fingerprintType: 'legacy',
+        success: true,
+        fallbackReason:
+          enhancedError instanceof Error ? enhancedError.message : 'unknown',
+      })
+      return fingerprint
+    } catch (legacyError) {
+      logger.error(
+        {
+          errorMessage:
+            legacyError instanceof Error ? legacyError.message : String(legacyError),
+          fingerprintType: 'failed',
+        },
+        'Both enhanced and legacy fingerprint generation failed',
+      )
+      throw new Error('Fingerprint generation failed')
+    }
+  }
+}
+
+/**
+ * Synchronous fingerprint generation (legacy only).
+ * Use this only when async is not possible (e.g., initial state).
+ * @deprecated Prefer calculateFingerprint() for hardware-based fingerprinting
+ */
+export function generateFingerprintIdSync(): string {
+  return calculateLegacyFingerprint()
+}
+
+/**
+ * Detects the fingerprint type from a fingerprint ID.
+ */
+export function getFingerprintType(
+  fingerprintId: string,
+): 'enhanced_cli' | 'legacy' | 'unknown' {
+  if (fingerprintId.startsWith('enhanced-')) {
+    return 'enhanced_cli'
+  }
+  // `codebuff-cli-` is kept for fingerprints issued by pre-Anvil installs.
+  if (
+    fingerprintId.startsWith('anvil-cli-') ||
+    fingerprintId.startsWith('codebuff-cli-') ||
+    fingerprintId.startsWith('legacy-')
+  ) {
+    return 'legacy'
+  }
+  return 'unknown'
+}

package/src/utils/format-elapsed-time.ts

@@ -0,0 +1,33 @@
+/**
+ * Format elapsed seconds into a human-readable string.
+ *
+ * @param elapsedSeconds - Number of seconds elapsed (should be non-negative)
+ * @returns Formatted time string
+ *
+ * @example
+ * formatElapsedTime(30)    // "30s"
+ * formatElapsedTime(60)    // "1m"
+ * formatElapsedTime(90)    // "1m 30s"
+ * formatElapsedTime(3600)  // "1h"
+ * formatElapsedTime(3700)  // "1h 1m"
+ *
+ * Format rules:
+ * - Under 60 seconds: "Xs" (e.g., "45s")
+ * - 60-3599 seconds (1-59 minutes): "Xm" or "Xm Ys" (e.g., "1m", "12m 5s")
+ * - 3600+ seconds (1+ hours): "Xh" or "Xh Ym" (e.g., "1h", "2h 15m")
+ */
+export const formatElapsedTime = (elapsedSeconds: number): string => {
+  if (elapsedSeconds < 60) {
+    return `${elapsedSeconds}s`
+  }
+
+  const hours = Math.floor(elapsedSeconds / 3600)
+  const minutes = Math.floor((elapsedSeconds % 3600) / 60)
+  const seconds = elapsedSeconds % 60
+
+  if (hours > 0) {
+    return `${hours}h` + (minutes > 0 ? ` ${minutes}m` : '')
+  }
+
+  return `${minutes}m` + (seconds > 0 ? ` ${seconds}s` : '')
+}

package/src/utils/format-session-units.ts

@@ -0,0 +1,6 @@
+/** Premium-session counts come back from the server as `recentCount` units
+ *  that may be fractional (a long agent run can consume 1.3 sessions). Render
+ *  integers without a trailing `.0`, fractionals at one decimal — matches the
+ *  `limit` field which is always integer. */
+export const formatSessionUnits = (units: number): string =>
+  Number.isInteger(units) ? String(units) : units.toFixed(1)

package/src/utils/format-timeout.ts

@@ -0,0 +1,28 @@
+/**
+ * Formats a timeout value for display.
+ * - Returns "no timeout" for non-finite values (NaN, Infinity, -Infinity)
+ * - Returns "no timeout" for negative values (including -1)
+ * - Returns hours (e.g., "1h timeout") for values >= 3600 that are evenly divisible by 3600
+ * - Returns minutes (e.g., "2m timeout") for values >= 60 that are evenly divisible by 60
+ * - Returns seconds (e.g., "90s timeout") otherwise
+ * - Rounds floating point values to nearest integer
+ */
+export function formatTimeout(timeoutSeconds: number): string {
+  // Handle NaN, Infinity, -Infinity
+  if (!Number.isFinite(timeoutSeconds)) {
+    return 'no timeout'
+  }
+  // Handle all negative values (including -1)
+  if (timeoutSeconds < 0) {
+    return 'no timeout'
+  }
+  // Round floating point values
+  const rounded = Math.round(timeoutSeconds)
+  if (rounded >= 3600 && rounded % 3600 === 0) {
+    return `${rounded / 3600}h timeout`
+  }
+  if (rounded >= 60 && rounded % 60 === 0) {
+    return `${rounded / 60}m timeout`
+  }
+  return `${rounded}s timeout`
+}

package/src/utils/format-validation-errors-for-message.ts

@@ -0,0 +1,84 @@
+import path from 'path'
+
+import { formatValidationError } from './validation-error-formatting'
+
+import type { LocalAgentInfo } from './local-agent-registry'
+
+export type ValidationErrorForMessage = {
+  id: string
+  message: string
+}
+
+export interface FormatValidationErrorsOptions {
+  errors: ValidationErrorForMessage[]
+  loadedAgentsData?: {
+    agents: Array<{ id: string; displayName: string; filePath?: string }>
+    agentsDir: string
+  } | null
+}
+
+export interface FormattedValidationErrors {
+  text: string
+  filePathByAgentId: Map<string, string>
+}
+
+/**
+ * Formats validation errors for display in chat messages.
+ * Matches the formatting from the validation banner.
+ * Returns formatted text and a map of agent IDs to file paths for creating clickable links.
+ */
+export function formatValidationErrorsForMessage(
+  options: FormatValidationErrorsOptions,
+): FormattedValidationErrors {
+  const { errors, loadedAgentsData } = options
+
+  const filePathByAgentId = new Map<string, string>()
+
+  // Helper to normalize relative path (matching banner format)
+  const normalizeRelativePath = (filePath: string): string => {
+    if (!loadedAgentsData) return filePath
+    const relativeToAgentsDir = path.relative(
+      loadedAgentsData.agentsDir,
+      filePath,
+    )
+    const normalized = relativeToAgentsDir.replace(/\\/g, '/')
+    return `.agents/${normalized}`
+  }
+
+  // Get agent info by ID
+  const agentInfoById = new Map<string, LocalAgentInfo>(
+    (loadedAgentsData?.agents.map((agent) => [
+      agent.id,
+      agent as LocalAgentInfo,
+    ]) || []) as [string, LocalAgentInfo][],
+  )
+
+  const text = errors
+    .map((error, index) => {
+      const agentId = error.id.replace(/_\d+$/, '')
+      const agentInfo = agentInfoById.get(agentId)
+      const relativePath = agentInfo?.filePath
+        ? normalizeRelativePath(agentInfo.filePath)
+        : null
+
+      // Store file path for this agent ID to enable clickable links
+      if (agentInfo?.filePath) {
+        filePathByAgentId.set(agentId, agentInfo.filePath)
+      }
+
+      const { fieldName, message } = formatValidationError(error.message)
+      const errorMsg = fieldName ? `${fieldName}: ${message}` : message
+      const truncatedMsg = errorMsg.length > 68 ? errorMsg.substring(0, 65) + '...' : errorMsg
+
+      let output = index === 0 ? '' : '\n\n'
+      output += agentId
+      if (relativePath) {
+        output += ` (${relativePath})`
+      }
+      output += '\n  ' + truncatedMsg
+      return output
+    })
+    .join('')
+
+  return { text, filePathByAgentId }
+}