@alumbwe/anvil 1.0.0

package/src/types/chat.ts

@@ -0,0 +1,241 @@
+import type { ChatTheme } from './theme-system'
+import type { ToolName } from '@anvil/sdk'
+import type { ReactNode } from 'react'
+
+/**
+ * isCollapsed/userOpened are duplicated across block types intentionally - each UI
+ * element tracks collapse state independently for different defaults and to persist
+ * user intent vs programmatic state.
+ */
+
+export type ChatVariant = 'ai' | 'user' | 'agent' | 'error'
+
+export type ThinkingCollapseState = 'expanded' | 'preview' | 'hidden'
+
+export type TextContentBlock = {
+  type: 'text'
+  content: string
+  color?: string
+  marginTop?: number
+  marginBottom?: number
+  status?: 'running' | 'complete'
+  textType?: 'reasoning' | 'text'
+  isCollapsed?: boolean
+  thinkingId?: string
+  userOpened?: boolean
+  /** True if this is a reasoning block from a <think> tag that hasn't been closed yet */
+  thinkingOpen?: boolean
+  thinkingCollapseState?: ThinkingCollapseState
+}
+/** Renders dynamic React content. NOT serializable - don't use for persistent data. */
+export type HtmlContentBlock = {
+  type: 'html'
+  marginTop?: number
+  marginBottom?: number
+  render: (context: { textColor: string; theme: ChatTheme }) => ReactNode
+}
+export type ToolContentBlock = {
+  type: 'tool'
+  toolCallId: string
+  toolName: ToolName
+  input: any
+  output?: string
+  outputRaw?: unknown
+  agentId?: string
+  includeToolCall?: boolean
+  isCollapsed?: boolean
+  userOpened?: boolean
+}
+export type AgentContentBlock = {
+  type: 'agent'
+  agentId: string
+  agentName: string
+  agentType: string
+  content: string
+  status: 'running' | 'complete' | 'failed' | 'cancelled'
+  blocks?: ContentBlock[]
+  initialPrompt?: string
+  params?: Record<string, any>
+  isCollapsed?: boolean
+  userOpened?: boolean
+  /** The spawn_agents tool call ID that created this block, used to match results */
+  spawnToolCallId?: string
+  /** The index within the spawn_agents call, used to match the correct result */
+  spawnIndex?: number
+}
+export type AgentListContentBlock = {
+  type: 'agent-list'
+  id: string
+  agents: Array<{ id: string; displayName: string }>
+  agentsDir: string
+  isCollapsed?: boolean
+  userOpened?: boolean
+}
+export type ModeDividerContentBlock = {
+  type: 'mode-divider'
+  mode: string
+}
+
+export type PlanContentBlock = {
+  type: 'plan'
+  content: string
+}
+
+export type AskUserContentBlock = {
+  type: 'ask-user'
+  toolCallId: string
+  questions: Array<{
+    question: string
+    header?: string
+    options: Array<{
+      label: string
+      description?: string
+    }>
+    multiSelect?: boolean
+    validation?: {
+      maxLength?: number
+      minLength?: number
+      pattern?: string
+      patternError?: string
+    }
+  }>
+  answers?: Array<{
+    questionIndex: number
+    selectedOption?: string
+    selectedOptions?: string[]
+    otherText?: string
+  }>
+  skipped?: boolean
+}
+
+export type ImageContentBlock = {
+  type: 'image'
+  image: string // base64 encoded
+  mediaType: string
+  filename?: string
+  size?: number
+  width?: number
+  height?: number
+  isCollapsed?: boolean
+  userOpened?: boolean
+}
+
+export type ImageAttachment = {
+  filename: string
+  path: string
+  size?: number
+}
+
+export type TextAttachment = {
+  id: string
+  content: string
+  preview: string
+  charCount: number
+}
+
+export type FileAttachment = {
+  path: string
+  filename: string
+  isDirectory: boolean
+  note?: string
+}
+
+export type ContentBlock =
+  | AgentContentBlock
+  | AgentListContentBlock
+  | AskUserContentBlock
+  | HtmlContentBlock
+  | ImageContentBlock
+  | ModeDividerContentBlock
+  | TextContentBlock
+  | ToolContentBlock
+  | PlanContentBlock
+
+export type AgentMessage = {
+  agentName: string
+  agentType: string
+  responseCount: number
+  subAgentCount?: number
+}
+
+export type ChatMessageMetadata = {
+  /** Working directory where a bash command was executed */
+  bashCwd?: string
+  /** UI-only marker for a response created in this process. Restored messages
+   * strip it so ads are never fetched retroactively into settled history. */
+  allowInlineAds?: boolean
+  /** Whether this message/agent is collapsed in the UI */
+  isCollapsed?: boolean
+  /** Whether the user manually opened this collapsed item */
+  userOpened?: boolean
+  /** RunState stored after completion */
+  runState?: unknown
+}
+
+export type ChatMessage = {
+  id: string
+  variant: ChatVariant
+  content: string
+  blocks?: ContentBlock[]
+  timestamp: string
+  parentId?: string
+  agent?: AgentMessage
+  isCompletion?: boolean
+  credits?: number
+  completionTime?: string
+  isComplete?: boolean
+  metadata?: ChatMessageMetadata
+  validationErrors?: Array<{ id: string; message: string }>
+  /**
+   * UI-only runtime error displayed in UserErrorBanner (not sent to LLM).
+   * Set by setError() when an error occurs during message streaming.
+   * Can be cleared by clearUserError() when starting a new successful interaction.
+   */
+  userError?: string
+  attachments?: ImageAttachment[]
+  textAttachments?: TextAttachment[]
+  fileAttachments?: FileAttachment[]
+}
+
+// Type guard functions for safe type narrowing
+export function isTextBlock(block: ContentBlock): block is TextContentBlock {
+  return block.type === 'text'
+}
+
+export function isToolBlock(block: ContentBlock): block is ToolContentBlock {
+  return block.type === 'tool'
+}
+
+export function isAgentBlock(block: ContentBlock): block is AgentContentBlock {
+  return block.type === 'agent'
+}
+
+export function isHtmlBlock(block: ContentBlock): block is HtmlContentBlock {
+  return block.type === 'html'
+}
+
+export function isAgentListBlock(
+  block: ContentBlock,
+): block is AgentListContentBlock {
+  return block.type === 'agent-list'
+}
+
+export function isPlanBlock(block: ContentBlock): block is PlanContentBlock {
+  return block.type === 'plan'
+}
+
+export function isModeDividerBlock(
+  block: ContentBlock,
+): block is ModeDividerContentBlock {
+  return block.type === 'mode-divider'
+}
+
+export function isAskUserBlock(
+  block: ContentBlock,
+): block is AskUserContentBlock {
+  return block.type === 'ask-user'
+}
+
+export function isImageBlock(block: ContentBlock): block is ImageContentBlock {
+  return block.type === 'image'
+}

package/src/types/contracts/send-message.ts

@@ -0,0 +1,12 @@
+import type { PendingAttachment } from '../store'
+import type { AgentMode } from '../../utils/constants'
+import type { ChatMessage } from '../chat'
+
+export type PostUserMessageFn = (prev: ChatMessage[]) => ChatMessage[]
+
+export type SendMessageFn = (params: {
+  content: string
+  agentMode: AgentMode
+  postUserMessage?: PostUserMessageFn
+  attachments?: PendingAttachment[]
+}) => Promise<void>

package/src/types/env.ts

@@ -0,0 +1,98 @@
+/**
+ * CLI-specific environment variable types.
+ *
+ * Extends base types from common with CLI-specific vars for:
+ * - Terminal/IDE detection
+ * - Editor preferences
+ * - Binary build configuration
+ */
+
+import type { BaseEnv, ClientEnv } from '@anvil/common/types/contracts/env'
+
+/**
+ * CLI-specific env vars for terminal/IDE detection and editor preferences.
+ */
+export type CliEnv = BaseEnv & {
+  // Windows system paths
+  SystemRoot?: string
+
+  // Terminal detection (for tmux/screen passthrough)
+  TERM?: string
+  TMUX?: string
+  STY?: string
+
+  // SSH/remote session detection
+  SSH_CLIENT?: string
+  SSH_TTY?: string
+  SSH_CONNECTION?: string
+  CODESPACES?: string
+
+  // Display server detection (Linux headless check)
+  DISPLAY?: string
+  WAYLAND_DISPLAY?: string
+
+  // Terminal-specific
+  KITTY_WINDOW_ID?: string
+  SIXEL_SUPPORT?: string
+  ZED_NODE_ENV?: string
+  ZED_TERM?: string
+  ZED_SHELL?: string
+  COLORTERM?: string
+
+  // VS Code family detection
+  VSCODE_THEME_KIND?: string
+  VSCODE_COLOR_THEME_KIND?: string
+  VSCODE_GIT_IPC_HANDLE?: string
+  VSCODE_PID?: string
+  VSCODE_CWD?: string
+  VSCODE_NLS_CONFIG?: string
+
+  // Cursor editor detection
+  CURSOR_PORT?: string
+  CURSOR?: string
+
+  // JetBrains IDE detection
+  JETBRAINS_REMOTE_RUN?: string
+  IDEA_INITIAL_DIRECTORY?: string
+  IDE_CONFIG_DIR?: string
+  JB_IDE_CONFIG_DIR?: string
+
+  // Editor preferences
+  VISUAL?: string
+  EDITOR?: string
+  ANVIL_CLI_EDITOR?: string
+  ANVIL_EDITOR?: string
+
+  // Theme preferences
+  OPEN_TUI_THEME?: string
+  OPENTUI_THEME?: string
+
+  // Anvil CLI-specific (set during binary build)
+  ANVIL_IS_BINARY?: string
+  ANVIL_CLI_VERSION?: string
+  ANVIL_CLI_TARGET?: string
+  ANVIL_RG_PATH?: string
+  ANVIL_SCROLL_MULTIPLIER?: string
+  ANVIL_PERF_TEST?: string
+  ANVIL_TRACE?: string
+  ANVIL_LAUNCHER_PID?: string
+  // Toggle for mirroring CLI logs to the server's /api/logs sink (Axiom).
+  ANVIL_SHIP_LOGS?: string
+  // Set to 1/true to suppress the terminal-reset watchdog on machines where
+  // the PowerShell process shape conflicts with endpoint-security policy.
+  ANVIL_NO_TERMINAL_WATCHDOG?: string
+  FREEBUFF_MODE?: string
+}
+
+/**
+ * Full CLI env deps combining client env and CLI env.
+ */
+export type CliEnvDeps = {
+  clientEnv: ClientEnv
+  env: CliEnv
+}
+
+/**
+ * Function type for getting CLI env values.
+ */
+export type GetCliEnvFn = () => CliEnv

package/src/types/freebuff-session.ts

@@ -0,0 +1,17 @@
+export type { FreebuffSessionServerResponse } from '@anvil/common/types/freebuff-session'
+
+import type { FreebuffSessionServerResponse } from '@anvil/common/types/freebuff-session'
+
+/**
+ * CLI session shape. Most states are wire-level `/api/v1/freebuff/session`
+ * responses; `takeover_prompt` is local-only so startup can ask before POSTing
+ * and rotating another running CLI's instance id.
+ */
+export type FreebuffSessionResponse =
+  | FreebuffSessionServerResponse
+  | {
+      status: 'takeover_prompt'
+      model: string
+    }
+
+export type FreebuffSessionStatus = FreebuffSessionResponse['status']

package/src/types/function-params.ts

@@ -0,0 +1,28 @@
+import type { Prettify } from './utils'
+import type { UnionToIntersection } from 'bun-types/vendor/expect-type'
+
+type StripExact<T> = T extends infer U & { [x: string]: never } ? U : T
+
+type ParamsOfFunction<T> = T extends (params: infer C) => any ? StripExact<C> : never
+
+type IsUnion<T, U = T> = T extends any ? ([U] extends [T] ? false : true) : false
+type ParamsOfArray<T> = UnionToIntersection<
+  T extends [infer fn, ...infer rest]
+    ? ParamsOfFunction<fn> | ParamsOfArray<rest>
+    : {}
+>
+type ParamsOfUnion<T> = IsUnion<T> extends true
+  ? UnionToIntersection<ParamsOfFunction<T>>
+  : ParamsOfFunction<T>
+
+export type ParamsOf<T> = Prettify<
+  T extends any[] ? ParamsOfArray<T> : ParamsOfUnion<T>
+>
+
+export type OptionalFields<T, K extends keyof T> = Prettify<
+  Omit<T, K> & Partial<Pick<T, K>>
+>
+
+export type ParamsExcluding<T, K extends keyof ParamsOf<T>> = Prettify<
+  Omit<ParamsOf<T>, K>
+>

package/src/types/react19-compat.d.ts

@@ -0,0 +1,19 @@
+/**
+ * React 19 compatibility shim for OpenTUI JSX types.
+ *
+ * OpenTUI's JSX namespace defines `type Element = React.ReactNode`.
+ * In React 19, `FunctionComponent` returns `ReactNode | Promise<ReactNode>`,
+ * but `Promise<ReactNode>` is not assignable to `ReactNode`.
+ *
+ * This augmentation adds a narrower call signature to `FunctionComponent`
+ * that returns just `ReactNode`. Due to TypeScript's interface merging rules,
+ * the later declaration's overloads have higher precedence, so the narrower
+ * signature is resolved first — fixing all `React.FC` JSX compatibility errors.
+ */
+import 'react'
+
+declare module 'react' {
+  interface FunctionComponent<P = {}> {
+    (props: P): ReactNode
+  }
+}

package/src/types/store.ts

@@ -0,0 +1,111 @@
+/** Types of banners that can appear at the top of the chat */
+export type TopBannerType = 'homeDir' | 'gitRoot' | null
+
+export type InputValue = {
+  text: string
+  cursorPosition: number
+  lastEditDueToNav: boolean
+}
+
+export type AskUserQuestion = {
+  question: string
+  header?: string
+  options:
+    | string[]
+    | Array<{
+        label: string
+        description?: string
+      }>
+  multiSelect?: boolean
+  validation?: {
+    maxLength?: number
+    minLength?: number
+    pattern?: string
+    patternError?: string
+  }
+}
+
+export type AnswerState = number | number[]
+
+export type AskUserState = {
+  toolCallId: string
+  questions: AskUserQuestion[]
+  selectedAnswers: AnswerState[] // Single-select: number (-1 = not answered), Multi-select: number[]
+  otherTexts: string[] // Custom text input for each question (empty string if not used)
+} | null
+
+export type PendingImageStatus = 'processing' | 'ready' | 'error'
+
+/** Image attachment with processed data */
+export type PendingImageAttachment = {
+  kind: 'image'
+  path: string
+  filename: string
+  status: PendingImageStatus
+  size?: number
+  width?: number
+  height?: number
+  note?: string // Display note: "compressed" | error message
+  processedImage?: {
+    base64: string
+    mediaType: string
+  }
+}
+
+/** Text attachment (large pasted text) */
+export type PendingTextAttachment = {
+  kind: 'text'
+  id: string
+  content: string
+  preview: string // First ~100 chars for display
+  charCount: number
+}
+
+/** File or folder attachment (dragged or copied from file manager) */
+export type PendingFileAttachment = {
+  kind: 'file'
+  id: string
+  path: string
+  filename: string
+  isDirectory: boolean
+  content: string
+  status: 'processing' | 'ready' | 'error'
+  note?: string // e.g. "3.2 KB" / "12 items" / error message
+}
+
+/** Unified attachment type with discriminator */
+export type PendingAttachment = PendingImageAttachment | PendingTextAttachment | PendingFileAttachment
+
+/** @deprecated Use PendingImageAttachment instead */
+export type PendingImage = PendingImageAttachment
+
+export type PendingBashMessage = {
+  id: string
+  command: string
+  stdout: string
+  stderr: string
+  exitCode: number
+  /** Whether the command is still running */
+  isRunning: boolean
+  startTime?: number
+  cwd?: string
+  /** Whether the message was already added to UI chat history (non-ghost mode) */
+  addedToHistory?: boolean
+}
+
+export type SuggestedFollowup = {
+  prompt: string
+  label?: string
+}
+
+export type SuggestedFollowupsState = {
+  /** The tool call ID that created these followups */
+  toolCallId: string
+  /** The list of followup suggestions */
+  followups: SuggestedFollowup[]
+  /** Set of indices that have been clicked */
+  clickedIndices: Set<number>
+}
+
+/** Map of toolCallId -> Set of clicked indices (persists across followup sets) */
+export type ClickedFollowupsMap = Map<string, Set<number>>

package/src/types/theme-system.ts

@@ -0,0 +1,144 @@
+export type ThemeName = 'dark' | 'light'
+
+export type MarkdownHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6
+
+// ThemeColor is always a resolved color string (never 'default' or undefined)
+export type ThemeColor = string
+
+export interface MarkdownThemeOverrides {
+  codeBackground?: string
+  codeHeaderFg?: string
+  inlineCodeFg?: string
+  codeTextFg?: string
+  headingFg?: Partial<Record<MarkdownHeadingLevel, string>>
+  listBulletFg?: string
+  blockquoteBorderFg?: string
+  blockquoteTextFg?: string
+  dividerFg?: string
+  codeMonochrome?: boolean
+  linkFg?: string
+}
+
+/**
+ * Semantic Color Theme Interface
+ * Inspired by Tailwind - uses semantic color roles instead of specific names
+ * This makes theming easier and more intuitive
+ */
+export interface ChatTheme {
+  /** Theme identifier ('dark' or 'light') */
+  name: ThemeName
+  // ============================================================================
+  // CORE SEMANTIC COLORS
+  // ============================================================================
+
+  /** Primary brand color - main actions, highlights, important elements */
+  primary: string
+
+  /** Secondary brand color - supporting elements, less emphasis */
+  secondary: string
+
+  /** Success color - checkmarks, completed states, positive feedback */
+  success: string
+
+  /** Error/danger color - errors, destructive actions, failures */
+  error: string
+
+  /** Warning color - cautions, alerts, validation issues */
+  warning: string
+
+  /** Info color - informational elements, hints */
+  info: string
+
+  /** Link color - hyperlinks, clickable references */
+  link: string
+
+  /** Directory color - folder/directory paths */
+  directory: string
+
+  // ============================================================================
+  // NEUTRAL SCALE
+  // ============================================================================
+
+  /** Default text color */
+  foreground: ThemeColor
+
+  /** Base background color */
+  background: string
+
+  /** Subdued/secondary text color */
+  muted: ThemeColor
+
+  /** Border and divider color */
+  border: string
+
+  /** Surface color for panels, cards, chrome */
+  surface: string
+
+  /** Hover state for interactive surfaces */
+  surfaceHover: string
+
+  // ============================================================================
+  // CONTEXT-SPECIFIC COLORS (Minimal - most use semantic colors)
+  // ============================================================================
+
+  // AI/User differentiation
+  /** AI message indicator line color */
+  aiLine: string
+
+  /** User message indicator line color */
+  userLine: string
+
+  // Agent backgrounds (specific states that don't map to semantics)
+  /** Agent toggle header background */
+  agentToggleHeaderBg: string
+
+  /** Agent toggle expanded background */
+  agentToggleExpandedBg: string
+
+  /** Agent focused background */
+  agentFocusedBg: string
+
+  /** Agent content background */
+  agentContentBg: string
+  /** Input text color */
+  inputFg: ThemeColor
+
+  /** Focused input text color */
+  inputFocusedFg: ThemeColor
+
+  // Mode toggles (distinct UI elements)
+  /** Fast mode toggle background */
+  modeFastBg: string
+
+  /** Fast mode toggle text */
+  modeFastText: string
+
+  /** Max mode toggle background */
+  modeMaxBg: string
+
+  /** Max mode toggle text */
+  modeMaxText: string
+
+  /** Plan mode toggle background */
+  modePlanBg: string
+
+  /** Plan mode toggle text */
+  modePlanText: string
+
+  // ============================================================================
+  // IMAGE CARD
+  // ============================================================================
+
+  /** Image card border color */
+  imageCardBorder: string
+
+  // ============================================================================
+  // MARKDOWN
+  // ============================================================================
+
+  /** Markdown-specific styling */
+  markdown?: MarkdownThemeOverrides
+
+  /** Text attributes (bold, dim, etc.) */
+  messageTextAttributes?: number
+}

package/src/types/utils.ts

@@ -0,0 +1,3 @@
+export type Prettify<T> = {
+  [K in keyof T]: T[K]
+} & {}