automaker/libs/utils/README.md

@automaker/utils

Shared utility functions for AutoMaker.

Overview

This package provides common utility functions used across AutoMaker's server and UI. It includes error handling, logging, conversation utilities, image handling, and prompt building.

Installation

npm install @automaker/utils

Exports

Logger

Structured logging with context.

import { createLogger, LogLevel } from '@automaker/utils';

const logger = createLogger('MyComponent');
logger.info('Processing request');
logger.error('Failed to process:', error);
logger.debug('Debug information', { data });

Error Handler

Error classification and user-friendly messages.

import {
  isAbortError,
  isCancellationError,
  isAuthenticationError,
  classifyError,
  getUserFriendlyErrorMessage,
} from '@automaker/utils';

try {
  await operation();
} catch (error) {
  if (isAbortError(error)) {
    console.log('Operation was aborted');
  }

  const errorInfo = classifyError(error);
  const message = getUserFriendlyErrorMessage(error);
}

Conversation Utils

Message formatting and conversion.

import {
  extractTextFromContent,
  normalizeContentBlocks,
  formatHistoryAsText,
  convertHistoryToMessages,
} from '@automaker/utils';

const text = extractTextFromContent(contentBlocks);
const normalized = normalizeContentBlocks(content);
const formatted = formatHistoryAsText(messages);
const converted = convertHistoryToMessages(history);

Image Handler

Image processing for Claude prompts.

import {
  getMimeTypeForImage,
  readImageAsBase64,
  convertImagesToContentBlocks,
  formatImagePathsForPrompt,
} from '@automaker/utils';

const mimeType = getMimeTypeForImage('screenshot.png');
const base64 = await readImageAsBase64('/path/to/image.jpg');
const blocks = await convertImagesToContentBlocks(imagePaths, basePath);
const formatted = formatImagePathsForPrompt(imagePaths);

Prompt Builder

Build prompts with images for Claude.

import { buildPromptWithImages } from '@automaker/utils';

const result = await buildPromptWithImages({
  basePrompt: 'Analyze this screenshot',
  imagePaths: ['/path/to/screenshot.png'],
  basePath: '/project/path',
});

console.log(result.prompt); // Prompt with image references
console.log(result.images); // Image data for Claude

File System Utils

Common file system operations.

import { ensureDir, fileExists, readJsonFile, writeJsonFile } from '@automaker/utils';

await ensureDir('/path/to/dir');
const exists = await fileExists('/path/to/file');
const data = await readJsonFile('/config.json');
await writeJsonFile('/config.json', data);

Usage Example

import { createLogger, classifyError, buildPromptWithImages } from '@automaker/utils';

const logger = createLogger('FeatureExecutor');

async function executeWithImages(prompt: string, images: string[]) {
  try {
    logger.info('Building prompt with images');

    const result = await buildPromptWithImages({
      basePrompt: prompt,
      imagePaths: images,
      basePath: process.cwd(),
    });

    logger.debug('Prompt built successfully', { imageCount: result.images.length });
    return result;
  } catch (error) {
    const errorInfo = classifyError(error);
    logger.error('Failed to build prompt:', errorInfo.message);
    throw error;
  }
}

Dependencies

• @automaker/types - Type definitions

Used By

• @automaker/server
• @automaker/ui