refactor: code cleanup for image support feature

- Remove dead code (validateTotalImageSize, MAX_TOTAL_SIZE)
- Make CLI processImageFile synchronous (no async needed)
- Simplify normalizeUserProvidedPath (consolidated unicode/shell escapes)
- Remove unnecessary clipboard image cleanup (OS handles temp files)
- Remove verbose logging from clipboard-image.ts
- Unexport internal functions (generateITerm2ImageSequence, generateKittyImageSequence)
- Add logging to silent catch blocks in image-thumbnail.ts and terminal-images.ts
- Extract magic numbers to named constants in image-card.tsx

Author: brandonkachen

cli/src/components/image-card.tsx

@@ -10,7 +10,13 @@ import {
   renderInlineImage,
 } from '../utils/terminal-images'
 
+// Image card display constants
 const MAX_FILENAME_LENGTH = 18
+const IMAGE_CARD_WIDTH = 22
+const THUMBNAIL_WIDTH = 18
+const THUMBNAIL_HEIGHT = 3
+const INLINE_IMAGE_WIDTH = 4
+const INLINE_IMAGE_HEIGHT = 3
 
 const BORDER_CHARS = {
   horizontal: '─',
@@ -75,8 +81,8 @@ export const ImageCard = ({
         const imageData = fs.readFileSync(image.path)
         const base64Data = imageData.toString('base64')
         const sequence = renderInlineImage(base64Data, {
-          width: 4,
-          height: 3,
+          width: INLINE_IMAGE_WIDTH,
+          height: INLINE_IMAGE_HEIGHT,
           filename: image.filename,
         })
         if (!cancelled) {
@@ -105,7 +111,7 @@ export const ImageCard = ({
         flexDirection: 'column',
         borderStyle: 'single',
         borderColor: theme.info,
-        width: 22,
+        width: IMAGE_CARD_WIDTH,
         padding: 0,
       }}
       customBorderChars={BORDER_CHARS}
@@ -131,8 +137,8 @@ export const ImageCard = ({
           ) : (
             <ImageThumbnail
               imagePath={image.path}
-              width={18}
-              height={3}
+              width={THUMBNAIL_WIDTH}
+              height={THUMBNAIL_HEIGHT}
               fallback={<text style={{ fg: theme.info }}>🖼️</text>}
             />
           )}

cli/src/hooks/use-send-message.ts

@@ -491,8 +491,9 @@ export const useSendMessage = ({
 
       // Process all images for SDK
       const projectRoot = getProjectRoot()
-      const imagePartsPromises = uniqueImagePaths.map((imagePath) =>
-        processImageFile(imagePath, projectRoot).then((result) => {
+      const validImageParts = uniqueImagePaths
+        .map((imagePath) => {
+          const result = processImageFile(imagePath, projectRoot)
           if (result.success && result.imagePart) {
             return {
               type: 'image' as const,
@@ -510,13 +511,8 @@ export const useSendMessage = ({
             )
           }
           return null
-        }),
-      )
-
-      const imagePartsResults = await Promise.all(imagePartsPromises)
-      const validImageParts = imagePartsResults.filter(
-        (part): part is NonNullable<typeof part> => part !== null,
-      )
+        })
+        .filter((part): part is NonNullable<typeof part> => part !== null)
 
       // Build message content array for SDK
       let messageContent: MessageContent[] | undefined

cli/src/utils/clipboard-image.ts

@@ -3,8 +3,6 @@ import { existsSync, mkdirSync, writeFileSync } from 'fs'
 import path from 'path'
 import os from 'os'
 
-import { logger } from './logger'
-
 export interface ClipboardImageResult {
   success: boolean
   imagePath?: string
@@ -54,8 +52,7 @@ function hasImageMacOS(): boolean {
            output.includes('public.png') ||
            output.includes('public.tiff') ||
            output.includes('public.jpeg')
-  } catch (error) {
-    logger.debug({ error }, 'Failed to check macOS clipboard')
+  } catch {
     return false
   }
 }
@@ -155,8 +152,7 @@ function hasImageLinux(): boolean {
     return output.includes('image/png') || 
            output.includes('image/jpeg') || 
            output.includes('image/tiff')
-  } catch (error) {
-    logger.debug({ error }, 'Failed to check Linux clipboard')
+  } catch {
     return false
   }
 }
@@ -220,8 +216,7 @@ function hasImageWindows(): boolean {
     })
 
     return result.stdout?.trim() === 'true'
-  } catch (error) {
-    logger.debug({ error }, 'Failed to check Windows clipboard')
+  } catch {
     return false
   }
 }
@@ -292,8 +287,6 @@ export function hasClipboardImage(): boolean {
 export function readClipboardImage(): ClipboardImageResult {
   const platform = process.platform
 
-  logger.debug({ platform }, 'Reading clipboard image')
-  
   switch (platform) {
     case 'darwin':
       return readImageMacOS()

cli/src/utils/image-handler.ts

@@ -30,60 +30,28 @@ export const SUPPORTED_IMAGE_EXTENSIONS = new Set([
 
 // Size limits - balanced to prevent message truncation while allowing reasonable images
 const MAX_FILE_SIZE = 2 * 1024 * 1024 // 2MB - allow larger files for compression
-const MAX_TOTAL_SIZE = 5 * 1024 * 1024 // 5MB total
 const MAX_BASE64_SIZE = 150 * 1024 // 150KB max for base64 (backend limit ~760KB, so safe margin)
 
+/**
+ * Normalizes a user-provided file path by handling escape sequences.
+ * Handles:
+ * - Shell-escaped special characters: "my\ file.png" -> "my file.png"
+ * - Unicode escapes: "\u{202f}" or "\u202f" -> actual unicode char (from terminal copy/paste)
+ */
 function normalizeUserProvidedPath(filePath: string): string {
   let normalized = filePath
 
-  normalized = normalized.replace(
-    /\\u\{([0-9a-fA-F]+)\}/g,
-    (match, codePoint) => {
-      const value = Number.parseInt(codePoint, 16)
-      if (Number.isNaN(value)) {
-        return match
-      }
-      try {
-        return String.fromCodePoint(value)
-      } catch {
-        return match
-      }
-    },
-  )
-
-  normalized = normalized.replace(
-    /\\u([0-9a-fA-F]{4})/g,
-    (match, codePoint) => {
-      const value = Number.parseInt(codePoint, 16)
-      if (Number.isNaN(value)) {
-        return match
-      }
-      try {
-        return String.fromCodePoint(value)
-      } catch {
-        return match
-      }
-    },
-  )
-
-  normalized = normalized.replace(
-    /\\x([0-9a-fA-F]{2})/g,
-    (match, codePoint) => {
-      const value = Number.parseInt(codePoint, 16)
-      if (Number.isNaN(value)) {
-        return match
-      }
-      return String.fromCharCode(value)
-    },
-  )
-
-  normalized = normalized.replace(/\\([ \t"'(){}\[\]])/g, (match, char) => {
-    if (char === '\\') {
-      return '\\'
-    }
-    return char
+  // Handle unicode escape sequences (e.g., from terminal copy/paste)
+  // Format: \u{XXXX} or \uXXXX
+  normalized = normalized.replace(/\\u\{([0-9a-fA-F]+)\}|\\u([0-9a-fA-F]{4})/g, (_, bracedCode, shortCode) => {
+    const code = bracedCode || shortCode
+    const value = Number.parseInt(code, 16)
+    return Number.isNaN(value) ? _ : String.fromCodePoint(value)
   })
 
+  // Handle shell-escaped special characters (e.g., spaces in paths)
+  normalized = normalized.replace(/\\([ \t"'(){}\[\]])/g, '$1')
+
   return normalized
 }
 
@@ -138,10 +106,10 @@ export function resolveFilePath(filePath: string, cwd: string): string {
 /**
  * Processes an image file and converts it to base64 for upload
  */
-export async function processImageFile(
+export function processImageFile(
   filePath: string,
   cwd: string,
-): Promise<ImageUploadResult> {
+): ImageUploadResult {
   try {
     const resolvedPath = resolveFilePath(filePath, cwd)
 
@@ -257,27 +225,6 @@ export async function processImageFile(
   }
 }
 
-/**
- * Validates total size of multiple images
- */
-export function validateTotalImageSize(imageParts: Array<{ size?: number }>): {
-  valid: boolean
-  error?: string
-} {
-  const totalSize = imageParts.reduce((sum, part) => sum + (part.size || 0), 0)
-
-  if (totalSize > MAX_TOTAL_SIZE) {
-    const totalMB = (totalSize / (1024 * 1024)).toFixed(1)
-    const maxMB = (MAX_TOTAL_SIZE / (1024 * 1024)).toFixed(1)
-    return {
-      valid: false,
-      error: `Total image size too large: ${totalMB}MB (max ${maxMB}MB)`,
-    }
-  }
-
-  return { valid: true }
-}
-
 /**
  * Extracts image file paths from user input using @path syntax and auto-detection
  */

cli/src/utils/image-thumbnail.ts

@@ -5,6 +5,8 @@
 
 import { Jimp } from 'jimp'
 
+import { logger } from './logger'
+
 export interface ThumbnailPixel {
   r: number
   g: number
@@ -31,16 +33,16 @@ export async function extractThumbnailColors(
 ): Promise<ThumbnailData | null> {
   try {
     const image = await Jimp.read(imagePath)
-    
+
     // Resize to target dimensions (height * 2 because we use half-blocks)
     const resizedHeight = targetHeight * 2
     image.resize({ w: targetWidth, h: resizedHeight })
-    
+
     const width = image.width
     const height = image.height
-    
+
     const pixels: ThumbnailPixel[][] = []
-    
+
     for (let y = 0; y < height; y++) {
       const row: ThumbnailPixel[] = []
       for (let x = 0; x < width; x++) {
@@ -53,9 +55,16 @@ export async function extractThumbnailColors(
       }
       pixels.push(row)
     }
-    
+
     return { width, height, pixels }
-  } catch {
+  } catch (error) {
+    logger.warn(
+      {
+        imagePath,
+        error: error instanceof Error ? error.message : String(error),
+      },
+      'Failed to extract thumbnail colors from image',
+    )
     return null
   }
 }

cli/src/utils/terminal-images.ts

@@ -6,6 +6,8 @@
 
 import terminalImage from 'terminal-image'
 
+import { logger } from './logger'
+
 export type TerminalImageProtocol = 'iterm2' | 'kitty' | 'sixel' | 'none'
 
 let cachedProtocol: TerminalImageProtocol | null = null
@@ -58,7 +60,7 @@ export function supportsInlineImages(): boolean {
  * @param base64Data - Base64 encoded image data
  * @param options - Display options
  */
-export function generateITerm2ImageSequence(
+function generateITerm2ImageSequence(
   base64Data: string,
   options: {
     width?: number | string // cells or 'auto'
@@ -114,7 +116,7 @@ export function generateITerm2ImageSequence(
  * @param base64Data - Base64 encoded image data
  * @param options - Display options
  */
-export function generateKittyImageSequence(
+function generateKittyImageSequence(
   base64Data: string,
   options: {
     width?: number // cells
@@ -248,7 +250,11 @@ export async function renderAnsiBlockImage(
       preserveAspectRatio: true,
     })
     return result
-  } catch {
+  } catch (error) {
+    logger.debug(
+      { error: error instanceof Error ? error.message : String(error) },
+      'Failed to render ANSI block image from buffer',
+    )
     return ''
   }
 }
@@ -275,7 +281,11 @@ export async function renderAnsiBlockImageFromFile(
       preserveAspectRatio: true,
     })
     return result
-  } catch {
+  } catch (error) {
+    logger.debug(
+      { filePath, error: error instanceof Error ? error.message : String(error) },
+      'Failed to render ANSI block image from file',
+    )
     return ''
   }
 }