automaker/apps/server/src/lib/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 fs from "fs/promises";
import path from "path";

/**
 * 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;

/**
 * Image data with base64 encoding and metadata
 */
export interface ImageData {
  base64: string;
  mimeType: string;
  filename: string;
  originalPath: string;
}

/**
 * Content block for image (Claude SDK format)
 */
export interface ImageContentBlock {
  type: "image";
  source: {
    type: "base64";
    media_type: string;
    data: string;
  };
}

/**
 * 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 fs.readFile(imagePath);
  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;
}