@alumbwe/anvil 1.0.0

package/src/utils/validation-error-helpers.ts

@@ -0,0 +1,19 @@
+/**
+ * Constants and utilities for validation error handling
+ */
+
+/**
+ * Special error ID for network-related validation failures
+ */
+export const NETWORK_ERROR_ID = 'network_error'
+
+/**
+ * Filters out network errors from a list of validation errors.
+ * Network errors are treated separately from agent validation errors
+ * because they indicate connectivity issues rather than code problems.
+ */
+export function filterNetworkErrors(
+  errors: Array<{ id: string; message: string }>,
+): Array<{ id: string; message: string }> {
+  return errors.filter((error) => error.id !== NETWORK_ERROR_ID)
+}

package/src/utils/windows-terminal-health.ts

@@ -0,0 +1,124 @@
+import { AnalyticsEvent } from '@anvil/common/constants/analytics-events'
+
+import { getCliEnv } from './env'
+
+import type { LogRecordInput } from '@anvil/common/schemas/logs'
+
+type WindowsTerminalFailureEvent =
+  | AnalyticsEvent.TERMINAL_BROKER_SPAWN_FAILED
+  | AnalyticsEvent.TERMINAL_WATCHDOG_FAILED
+
+export type WindowsTerminalFailure = {
+  stage: 'spawn' | 'stdio' | 'completion' | 'bootstrap' | 'arming'
+  failureCode:
+    | 'failed_to_connect'
+    | 'enoent'
+    | 'eacces'
+    | 'eperm'
+    | 'epipe'
+    | 'invalid_response'
+    | 'protocol_missing'
+    | 'response_too_large'
+    | 'exit_nonzero'
+    | 'terminated'
+    | 'timeout'
+    | 'unknown'
+}
+
+type WindowsTerminalFailureProperties = WindowsTerminalFailure & {
+  version: string
+  platform: 'win32'
+}
+
+export type WindowsTerminalHealthDeliveryDeps = {
+  trackEvent?: (
+    event: WindowsTerminalFailureEvent,
+    properties: WindowsTerminalFailureProperties,
+  ) => boolean | void
+  getAnonymousId: () => string
+  enqueueClientLog: (record: LogRecordInput) => void
+  drainClientLogs: () => Promise<void>
+}
+
+export function sanitizeWindowsCliVersion(version: string): string {
+  return /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,31}$/.test(version)
+    ? version
+    : 'unknown'
+}
+
+/**
+ * Preserve the normal PostHog + Axiom mirror path when analytics is available.
+ * If analytics was not initialized, queue the same bounded event directly in
+ * the Axiom shipper before draining it.
+ */
+export async function deliverWindowsTerminalFailure(
+  event: WindowsTerminalFailureEvent,
+  properties: WindowsTerminalFailureProperties,
+  deps: WindowsTerminalHealthDeliveryDeps,
+): Promise<void> {
+  let queuedByAnalytics = false
+  if (deps.trackEvent) {
+    try {
+      queuedByAnalytics = deps.trackEvent(event, properties) !== false
+    } catch {
+      // Analytics initialization is best-effort; Axiom delivery is independent.
+    }
+  }
+
+  if (!queuedByAnalytics) {
+    try {
+      deps.enqueueClientLog({
+        level: 'info',
+        event,
+        message: event,
+        client_session_id: deps.getAnonymousId(),
+        data: properties,
+      })
+    } catch {
+      // Terminal-health reporting must never affect terminal behavior.
+    }
+  }
+
+  try {
+    await deps.drainClientLogs()
+  } catch {
+    // The shipper is best-effort and owns retry/drop behavior.
+  }
+}
+
+/**
+ * Emit a bounded Windows terminal-health failure and start its Axiom mirror
+ * immediately. Both terminal components use this path so their platform gate,
+ * version handling, privacy envelope, and delivery behavior cannot drift.
+ */
+export function reportWindowsTerminalFailure(
+  event: WindowsTerminalFailureEvent,
+  failure: WindowsTerminalFailure,
+): void {
+  const env = getCliEnv()
+  if (process.platform !== 'win32' || env.FREEBUFF_MODE !== 'true') return
+
+  const properties: WindowsTerminalFailureProperties = {
+    version: sanitizeWindowsCliVersion(env.ANVIL_CLI_VERSION ?? ''),
+    platform: 'win32',
+    stage: failure.stage,
+    failureCode: failure.failureCode,
+  }
+
+  void Promise.all([
+    import('./analytics').catch(() => null),
+    import('./anonymous-id'),
+    import('./log-shipper'),
+  ])
+    .then(([analytics, { getOrCreatePersistentAnonymousId }, logShipper]) => {
+      return deliverWindowsTerminalFailure(event, properties, {
+        trackEvent: analytics?.trackEvent,
+        getAnonymousId: getOrCreatePersistentAnonymousId,
+        enqueueClientLog: logShipper.enqueueClientLog,
+        drainClientLogs: logShipper.drainClientLogs,
+      })
+    })
+    .catch(() => {
+      // Telemetry is best-effort and must never affect terminal behavior.
+    })
+}

package/src/utils/word-wrap-utils.ts

@@ -0,0 +1,53 @@
+function cursorUp(params: {
+  lineStarts: number[]
+  cursorPosition: number
+  desiredIndex: number
+}): number {
+  const { lineStarts, cursorPosition, desiredIndex } = params
+  const lineIndex = lineStarts.findLastIndex((start) => start <= cursorPosition)
+
+  if (lineIndex === -1 || lineIndex === 0) {
+    return 0
+  }
+
+  const prevLineStart = lineStarts[lineIndex - 1]
+  const prevLineEndExclusive = lineStarts[lineIndex] - 1
+
+  return Math.min(prevLineEndExclusive, prevLineStart + desiredIndex)
+}
+
+function cursorDown(params: {
+  lineStarts: number[]
+  cursorPosition: number
+  desiredIndex: number
+}): number {
+  const { lineStarts, cursorPosition, desiredIndex } = params
+  const lineIndex = lineStarts.findLastIndex((start) => start <= cursorPosition)
+
+  if (lineIndex === -1 || lineIndex === lineStarts.length - 1) {
+    return Infinity
+  }
+
+  return Math.min(
+    (lineStarts[lineIndex + 2] ?? Infinity) - 1,
+    lineStarts[lineIndex + 1] + desiredIndex,
+  )
+}
+
+export function calculateNewCursorPosition(params: {
+  cursorPosition: number
+  lineStarts: number[]
+  cursorIsChar: boolean
+  direction: 'up' | 'down'
+  desiredIndex: number
+}): number {
+  const { direction } = params
+  if (direction === 'up') {
+    return cursorUp(params)
+  }
+  if (direction === 'down') {
+    return cursorDown(params)
+  }
+  direction satisfies never
+  throw new Error(`Invalid direction: ${direction}`)
+}

package/src/utils/write-file-atomic.ts

@@ -0,0 +1,54 @@
+import * as fs from 'fs'
+import { randomUUID } from 'node:crypto'
+
+// Unique per-write temp suffix. A plain `${pid}.tmp` collides when a sync
+// exit-flush and an async checkpoint write target the same file concurrently
+// (both share the pid): they'd write and rename the SAME temp path, tearing
+// each other's output. A random component makes every write self-contained.
+function tempPathFor(filePath: string): string {
+  return `${filePath}.${process.pid}.${randomUUID()}.tmp`
+}
+
+/**
+ * Write a file atomically: write to a temp file in the same directory, then
+ * rename over the target. Chat files grow to multiple MB and are rewritten on
+ * every agent step, so a plain writeFileSync interrupted by a crash/kill
+ * leaves truncated JSON that hides the chat from /history.
+ */
+export function writeFileAtomic(filePath: string, data: string): void {
+  const tmpPath = tempPathFor(filePath)
+  try {
+    fs.writeFileSync(tmpPath, data)
+    fs.renameSync(tmpPath, filePath)
+  } catch (error) {
+    try {
+      fs.unlinkSync(tmpPath)
+    } catch {
+      // Ignore cleanup errors; the original error is what matters
+    }
+    throw error
+  }
+}
+
+/**
+ * Async counterpart to writeFileAtomic. Used by the in-flight checkpoint writer
+ * so serializing + flushing a multi-MB transcript doesn't block the CLI's
+ * render/input thread. Same tmp-then-rename atomicity guarantee.
+ */
+export async function writeFileAtomicAsync(
+  filePath: string,
+  data: string,
+): Promise<void> {
+  const tmpPath = tempPathFor(filePath)
+  try {
+    await fs.promises.writeFile(tmpPath, data)
+    await fs.promises.rename(tmpPath, filePath)
+  } catch (error) {
+    try {
+      await fs.promises.unlink(tmpPath)
+    } catch {
+      // Ignore cleanup errors; the original error is what matters
+    }
+    throw error
+  }
+}

package/src/utils/yield-to-event-loop.ts

@@ -0,0 +1,9 @@
+/**
+ * Yield to the event loop so pending React state updates and microtasks can flush
+ * before continuing. Useful after enqueuing UI changes that should render
+ * before the next step of an async flow.
+ */
+export const yieldToEventLoop = (): Promise<void> =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, 0)
+  })