@llm-translate/cli 1.0.0-next.1

package/src/server/middleware/logger.ts

@@ -0,0 +1,90 @@
+import { createMiddleware } from 'hono/factory';
+import type { Context, Next } from 'hono';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface LoggerConfig {
+  json: boolean;
+}
+
+interface LogEntry {
+  timestamp: string;
+  requestId: string;
+  method: string;
+  path: string;
+  status: number;
+  duration: number;
+  userAgent?: string;
+}
+
+// ============================================================================
+// Logger Middleware
+// ============================================================================
+
+/**
+ * Request logging middleware with structured JSON output for containers
+ */
+export function createLoggerMiddleware(config: LoggerConfig) {
+  return createMiddleware(async (c: Context, next: Next) => {
+    const start = Date.now();
+    const requestId = generateRequestId();
+
+    // Store request ID for correlation in other middleware/handlers
+    c.set('requestId', requestId);
+
+    const method = c.req.method;
+    const path = c.req.path;
+
+    await next();
+
+    const duration = Date.now() - start;
+    const status = c.res.status;
+
+    if (config.json) {
+      // Structured JSON logging for container environments
+      const entry: LogEntry = {
+        timestamp: new Date().toISOString(),
+        requestId,
+        method,
+        path,
+        status,
+        duration,
+        userAgent: c.req.header('User-Agent'),
+      };
+      console.log(JSON.stringify(entry));
+    } else {
+      // Human-readable logging for development
+      const statusColor = getStatusColor(status);
+      console.log(`${statusColor}${status}\x1b[0m ${method} ${path} - ${duration}ms`);
+    }
+  });
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Generate a short unique request ID
+ */
+function generateRequestId(): string {
+  return Math.random().toString(36).substring(2, 10);
+}
+
+/**
+ * Get ANSI color code based on HTTP status
+ */
+function getStatusColor(status: number): string {
+  if (status >= 500) {
+    return '\x1b[31m'; // Red for server errors
+  }
+  if (status >= 400) {
+    return '\x1b[33m'; // Yellow for client errors
+  }
+  if (status >= 300) {
+    return '\x1b[36m'; // Cyan for redirects
+  }
+  return '\x1b[32m'; // Green for success
+}

package/src/server/routes/health.ts

@@ -0,0 +1,84 @@
+import { Hono } from 'hono';
+import type { HealthResponse } from '../types.js';
+import {
+  getAvailableProviders,
+  getProviderConfigFromEnv,
+} from '../../providers/registry.js';
+import type { ProviderName } from '../../types/index.js';
+
+// ============================================================================
+// Health Router
+// ============================================================================
+
+const healthRouter = new Hono();
+
+// Track server start time for uptime calculation
+const startTime = Date.now();
+
+/**
+ * GET /health - Comprehensive health check endpoint
+ * Suitable for k8s liveness/readiness probes
+ */
+healthRouter.get('/', async (c) => {
+  const providers = getAvailableProviders();
+
+  const providerStatus = providers.map((name: ProviderName) => {
+    const config = getProviderConfigFromEnv(name);
+
+    // Check if provider has required configuration
+    let available = false;
+    if (name === 'ollama') {
+      // Ollama doesn't require API key, just assumes server is running
+      available = true;
+    } else {
+      available = !!config.apiKey;
+    }
+
+    return { name, available };
+  });
+
+  const anyProviderAvailable = providerStatus.some((p) => p.available);
+
+  const response: HealthResponse = {
+    status: anyProviderAvailable ? 'healthy' : 'degraded',
+    version: process.env['npm_package_version'] ?? '0.1.0',
+    uptime: Math.floor((Date.now() - startTime) / 1000),
+    providers: providerStatus,
+  };
+
+  // Return 503 if no providers available (for k8s readiness probe)
+  const status = anyProviderAvailable ? 200 : 503;
+
+  return c.json(response, status);
+});
+
+/**
+ * GET /health/live - Simple liveness probe
+ * Returns 200 as long as the server is running
+ */
+healthRouter.get('/live', (c) => {
+  return c.json({ status: 'ok' });
+});
+
+/**
+ * GET /health/ready - Readiness probe
+ * Returns 200 if the server is ready to accept requests
+ */
+healthRouter.get('/ready', async (c) => {
+  const providers = getAvailableProviders();
+
+  // Check if at least one provider is configured
+  const hasConfiguredProvider = providers.some((name: ProviderName) => {
+    if (name === 'ollama') return true;
+    const config = getProviderConfigFromEnv(name);
+    return !!config.apiKey;
+  });
+
+  if (hasConfiguredProvider) {
+    return c.json({ status: 'ready' });
+  }
+
+  return c.json({ status: 'not_ready', reason: 'No providers configured' }, 503);
+});
+
+export { healthRouter };

package/src/server/routes/translate.ts

@@ -0,0 +1,210 @@
+import { Hono, type Context } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+import {
+  TranslateRequestSchema,
+  MODE_PRESETS,
+  type TranslateResponse,
+  type ErrorResponse,
+  type InlineGlossaryTerm,
+  type HonoVariables,
+} from '../types.js';
+import { createTranslationEngine } from '../../core/engine.js';
+import { loadConfig } from '../../services/config.js';
+import { TranslationError, ErrorCode } from '../../errors.js';
+import type { ResolvedGlossary, ResolvedGlossaryTerm } from '../../types/index.js';
+
+// ============================================================================
+// Translate Router
+// ============================================================================
+
+const translateRouter = new Hono<{ Variables: HonoVariables }>();
+
+/**
+ * POST /translate - Main translation endpoint
+ */
+translateRouter.post(
+  '/',
+  zValidator('json', TranslateRequestSchema, (result, c) => {
+    if (!result.success) {
+      const errors = result.error.errors.map((e) => ({
+        field: e.path.join('.'),
+        message: e.message,
+      }));
+
+      return c.json<ErrorResponse>(
+        {
+          error: 'Validation failed',
+          code: 'VALIDATION_ERROR',
+          details: { errors },
+        },
+        400
+      );
+    }
+    // Validation successful - continue to handler
+    return undefined;
+  }),
+  async (c) => {
+    const body = c.req.valid('json');
+    const requestId = c.get('requestId') ?? 'unknown';
+    const startTime = Date.now();
+
+    try {
+      // Load base config
+      const baseConfig = await loadConfig();
+
+      // Get mode presets
+      const modeConfig = MODE_PRESETS[body.mode ?? 'balanced'];
+
+      // Build config with overrides
+      const config = {
+        ...baseConfig,
+        languages: {
+          ...baseConfig.languages,
+          source: body.sourceLang,
+          targets: [body.targetLang],
+        },
+        provider: {
+          ...baseConfig.provider,
+          default: body.provider ?? baseConfig.provider.default,
+          model: body.model ?? baseConfig.provider.model,
+        },
+        quality: {
+          ...baseConfig.quality,
+          threshold: body.qualityThreshold ?? modeConfig.qualityThreshold,
+          maxIterations: body.maxIterations ?? modeConfig.maxIterations,
+        },
+      };
+
+      // Create engine (API mode doesn't use file cache)
+      const engine = createTranslationEngine({
+        config,
+        verbose: false,
+        noCache: true,
+      });
+
+      // Convert inline glossary to resolved format if provided
+      // Note: glossary support via inline terms will be implemented
+      // when TranslationEngine supports passing glossary directly
+      if (body.glossary && body.glossary.length > 0) {
+        // TODO: Pass glossary to engine when supported
+        convertInlineGlossary(body.glossary, body.sourceLang, body.targetLang);
+      }
+
+      // Translate content
+      const result = await engine.translateContent({
+        content: body.content,
+        sourceLang: body.sourceLang,
+        targetLang: body.targetLang,
+        format: body.format,
+        qualityThreshold: config.quality.threshold,
+        maxIterations: config.quality.maxIterations,
+        context: body.context,
+      });
+
+      const duration = Date.now() - startTime;
+
+      const response: TranslateResponse = {
+        translated: result.content,
+        quality: result.metadata.averageQuality,
+        iterations: result.metadata.totalIterations,
+        tokensUsed: {
+          input: result.metadata.tokensUsed.input,
+          output: result.metadata.tokensUsed.output,
+        },
+        glossaryCompliance: result.glossaryCompliance
+          ? {
+              applied: result.glossaryCompliance.applied,
+              missed: result.glossaryCompliance.missed,
+            }
+          : undefined,
+        duration,
+        provider: result.metadata.provider,
+        model: result.metadata.model,
+      };
+
+      return c.json(response, 200);
+    } catch (error) {
+      return handleTranslationError(c, error, requestId);
+    }
+  }
+);
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Convert inline glossary terms to resolved glossary format
+ */
+function convertInlineGlossary(
+  terms: InlineGlossaryTerm[],
+  sourceLang: string,
+  targetLang: string
+): ResolvedGlossary {
+  return {
+    metadata: {
+      name: 'inline',
+      sourceLang,
+      targetLang,
+      version: '1.0',
+    },
+    terms: terms.map(
+      (term): ResolvedGlossaryTerm => ({
+        source: term.source,
+        target: term.doNotTranslate ? term.source : term.target,
+        context: term.context,
+        caseSensitive: term.caseSensitive ?? false,
+        doNotTranslate: term.doNotTranslate ?? false,
+      })
+    ),
+  };
+}
+
+/**
+ * Handle translation errors and return appropriate HTTP response
+ */
+type StatusCode = 200 | 400 | 401 | 422 | 429 | 500 | 502;
+
+function handleTranslationError(
+  c: Context<{ Variables: HonoVariables }>,
+  error: unknown,
+  requestId: string
+): Response {
+  if (error instanceof TranslationError) {
+    const statusMap: Record<string, StatusCode> = {
+      [ErrorCode.PROVIDER_AUTH_FAILED]: 401,
+      [ErrorCode.PROVIDER_RATE_LIMITED]: 429,
+      [ErrorCode.PROVIDER_ERROR]: 502,
+      [ErrorCode.PROVIDER_NOT_FOUND]: 400,
+      [ErrorCode.QUALITY_THRESHOLD_NOT_MET]: 422,
+      [ErrorCode.GLOSSARY_INVALID]: 400,
+      [ErrorCode.GLOSSARY_NOT_FOUND]: 400,
+      [ErrorCode.CONFIG_INVALID]: 400,
+      [ErrorCode.UNSUPPORTED_FORMAT]: 400,
+    };
+
+    const status: StatusCode = statusMap[error.code] ?? 500;
+
+    return c.json<ErrorResponse>(
+      {
+        error: error.message,
+        code: error.code,
+        details: error.details,
+      },
+      status
+    );
+  }
+
+  // Unknown error
+  console.error(`[${requestId}] Translation error:`, error);
+
+  return c.json<ErrorResponse>(
+    {
+      error: 'Internal server error',
+      code: 'INTERNAL_ERROR',
+    },
+    500
+  );
+}
+
+export { translateRouter };

package/src/server/types.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+
+// ============================================================================
+// Request Validation Schemas
+// ============================================================================
+
+/**
+ * Translation mode enum
+ */
+export const TranslationModeSchema = z.enum(['fast', 'balanced', 'quality']);
+export type TranslationMode = z.infer<typeof TranslationModeSchema>;
+
+/**
+ * Inline glossary term schema (simplified for API)
+ */
+export const InlineGlossaryTermSchema = z.object({
+  source: z.string().min(1, 'Source term is required'),
+  target: z.string().min(1, 'Target term is required'),
+  context: z.string().optional(),
+  caseSensitive: z.boolean().optional(),
+  doNotTranslate: z.boolean().optional(),
+});
+
+export type InlineGlossaryTerm = z.infer<typeof InlineGlossaryTermSchema>;
+
+/**
+ * POST /translate request body schema
+ */
+export const TranslateRequestSchema = z.object({
+  content: z.string().min(1, 'Content is required'),
+  sourceLang: z
+    .string()
+    .min(2, 'Source language code must be at least 2 characters')
+    .max(10, 'Source language code must be at most 10 characters'),
+  targetLang: z
+    .string()
+    .min(2, 'Target language code must be at least 2 characters')
+    .max(10, 'Target language code must be at most 10 characters'),
+  format: z.enum(['markdown', 'html', 'text']).optional().default('text'),
+  glossary: z.array(InlineGlossaryTermSchema).optional(),
+  provider: z.enum(['claude', 'openai', 'ollama']).optional(),
+  model: z.string().optional(),
+  mode: TranslationModeSchema.optional().default('balanced'),
+  qualityThreshold: z.number().min(0).max(100).optional(),
+  maxIterations: z.number().min(1).max(10).optional(),
+  context: z.string().optional(),
+});
+
+export type TranslateRequest = z.infer<typeof TranslateRequestSchema>;
+
+// ============================================================================
+// Response Types
+// ============================================================================
+
+/**
+ * POST /translate response
+ */
+export interface TranslateResponse {
+  translated: string;
+  quality: number;
+  iterations: number;
+  tokensUsed: {
+    input: number;
+    output: number;
+  };
+  glossaryCompliance?: {
+    applied: string[];
+    missed: string[];
+  };
+  duration: number;
+  provider: string;
+  model: string;
+}
+
+/**
+ * GET /health response
+ */
+export interface HealthResponse {
+  status: 'healthy' | 'degraded';
+  version: string;
+  uptime: number;
+  providers: {
+    name: string;
+    available: boolean;
+  }[];
+}
+
+/**
+ * Error response format
+ */
+export interface ErrorResponse {
+  error: string;
+  code: string;
+  details?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Server Configuration
+// ============================================================================
+
+/**
+ * Server configuration options
+ */
+export interface ServerConfig {
+  port: number;
+  host: string;
+  enableAuth: boolean;
+  enableCors: boolean;
+  apiKey?: string;
+  jsonLogging?: boolean;
+}
+
+// ============================================================================
+// Hono Context Variables
+// ============================================================================
+
+/**
+ * Custom variables stored in Hono context
+ */
+export interface HonoVariables {
+  requestId: string;
+}
+
+// ============================================================================
+// Mode Presets
+// ============================================================================
+
+/**
+ * Mode configuration presets
+ */
+export const MODE_PRESETS: Record<
+  TranslationMode,
+  { qualityThreshold: number; maxIterations: number }
+> = {
+  fast: { qualityThreshold: 0, maxIterations: 1 },
+  balanced: { qualityThreshold: 75, maxIterations: 2 },
+  quality: { qualityThreshold: 85, maxIterations: 4 },
+};