automaker/libs/utils/src/image-handler.ts

/**
 * Image handling utilities for processing image files
 *
 * Provides utilities for:
 * - MIME type detection based on file extensions
 * - Base64 encoding of image files
 * - Content block generation for Claude SDK format
 * - Path resolution (relative/absolute)
 */

import { secureFs } from '@automaker/platform';
import path from 'path';
import type { ImageData, ImageContentBlock } from '@automaker/types';

/**
 * MIME type mapping for image file extensions
 */
const IMAGE_MIME_TYPES: Record<string, string> = {
  '.jpg': 'image/jpeg',
  '.jpeg': 'image/jpeg',
  '.png': 'image/png',
  '.gif': 'image/gif',
  '.webp': 'image/webp',
} as const;

/**
 * Get MIME type for an image file based on extension
 *
 * @param imagePath - Path to the image file
 * @returns MIME type string (defaults to "image/png" for unknown extensions)
 */
export function getMimeTypeForImage(imagePath: string): string {
  const ext = path.extname(imagePath).toLowerCase();
  return IMAGE_MIME_TYPES[ext] || 'image/png';
}

/**
 * Read an image file and convert to base64 with metadata
 *
 * @param imagePath - Path to the image file
 * @returns Promise resolving to image data with base64 encoding
 * @throws Error if file cannot be read
 */
export async function readImageAsBase64(imagePath: string): Promise<ImageData> {
  const imageBuffer = (await secureFs.readFile(imagePath)) as Buffer;
  const base64Data = imageBuffer.toString('base64');
  const mimeType = getMimeTypeForImage(imagePath);

  return {
    base64: base64Data,
    mimeType,
    filename: path.basename(imagePath),
    originalPath: imagePath,
  };
}

/**
 * Convert image paths to content blocks (Claude SDK format)
 * Handles both relative and absolute paths
 *
 * @param imagePaths - Array of image file paths
 * @param workDir - Optional working directory for resolving relative paths
 * @returns Promise resolving to array of image content blocks
 */
export async function convertImagesToContentBlocks(
  imagePaths: string[],
  workDir?: string
): Promise<ImageContentBlock[]> {
  const blocks: ImageContentBlock[] = [];

  for (const imagePath of imagePaths) {
    try {
      // Resolve to absolute path if needed
      const absolutePath =
        workDir && !path.isAbsolute(imagePath) ? path.join(workDir, imagePath) : imagePath;

      const imageData = await readImageAsBase64(absolutePath);

      blocks.push({
        type: 'image',
        source: {
          type: 'base64',
          media_type: imageData.mimeType,
          data: imageData.base64,
        },
      });
    } catch (error) {
      console.error(`[ImageHandler] Failed to load image ${imagePath}:`, error);
      // Continue processing other images
    }
  }

  return blocks;
}

/**
 * Build a list of image paths for text prompts
 * Formats image paths as a bulleted list for inclusion in text prompts
 *
 * @param imagePaths - Array of image file paths
 * @returns Formatted string with image paths, or empty string if no images
 */
export function formatImagePathsForPrompt(imagePaths: string[]): string {
  if (imagePaths.length === 0) {
    return '';
  }

  let text = '\n\nAttached images:\n';
  for (const imagePath of imagePaths) {
    text += `- ${imagePath}\n`;
  }
  return text;
}