@jgardner04/ghost-mcp-server 1.13.5 → 1.14.0

package/src/services/__tests__/imageProcessingService.test.js

@@ -1,204 +1,175 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { mockDotenv } from '../../__tests__/helpers/testUtils.js';
-import { createMockContextLogger } from '../../__tests__/helpers/mockLogger.js';
-
-// Mock dotenv
-vi.mock('dotenv', () => mockDotenv());
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import sharp from 'sharp';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
 
-// Mock logger
+import { createMockContextLogger } from '../../__tests__/helpers/mockLogger.js';
 vi.mock('../../utils/logger.js', () => ({
   createContextLogger: createMockContextLogger(),
 }));
 
-// Mock sharp with chainable API
-const mockMetadata = vi.fn();
-const mockResize = vi.fn();
-const mockJpeg = vi.fn();
-const mockToFile = vi.fn();
-
-const createMockSharp = () => {
-  const instance = {
-    metadata: mockMetadata,
-    resize: mockResize,
-    jpeg: mockJpeg,
-  };
-
-  // Make methods chainable
-  mockResize.mockReturnValue(instance);
-  mockJpeg.mockReturnValue(instance);
-  instance.toFile = mockToFile;
-
-  return instance;
-};
-
-vi.mock('sharp', () => ({
-  default: vi.fn(() => createMockSharp()),
-}));
-
-// Mock fs
-vi.mock('fs', () => ({
-  default: {
-    existsSync: vi.fn(),
-  },
-}));
+// Import under test (real sharp, real filesystem)
+const { processImage } = await import('../imageProcessingService.js');
+
+const tmpRoot = path.join(os.tmpdir(), `ghost-mcp-img-test-${Date.now()}`);
+const fixtures = {};
+
+async function makeRasterFixture(format, width, height = width) {
+  const file = path.join(tmpRoot, `in-${format}-${width}.${format === 'jpeg' ? 'jpg' : format}`);
+  await sharp({
+    create: {
+      width,
+      height,
+      channels: format === 'png' ? 4 : 3,
+      background: { r: 10, g: 50, b: 150, alpha: 1 },
+    },
+  })
+    [format]()
+    .toFile(file);
+  return file;
+}
+
+beforeAll(async () => {
+  await fs.mkdir(tmpRoot, { recursive: true });
+
+  fixtures.pngSmall = await makeRasterFixture('png', 800);
+  fixtures.pngLarge = await makeRasterFixture('png', 2000);
+  fixtures.jpegSmall = await makeRasterFixture('jpeg', 800);
+  fixtures.jpegLarge = await makeRasterFixture('jpeg', 2000);
+  fixtures.webpSmall = await makeRasterFixture('webp', 800);
+  fixtures.webpLarge = await makeRasterFixture('webp', 2000);
+
+  // SVG: write minimal vector source
+  fixtures.svg = path.join(tmpRoot, 'in.svg');
+  await fs.writeFile(
+    fixtures.svg,
+    '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"><rect width="64" height="64" fill="#39f"/></svg>'
+  );
+
+  // GIF: sharp cannot reliably create animated GIFs across versions; use a
+  // known-valid 1x1 transparent GIF89a byte sequence for a deterministic fixture.
+  fixtures.gif = path.join(tmpRoot, 'in.gif');
+  await fs.writeFile(
+    fixtures.gif,
+    Buffer.from(
+      '47494638396101000100800000ffffff00000021f90401000001002c00000000010001000002024401003b',
+      'hex'
+    )
+  );
+
+  // ICO: minimal 1x1 ICO header (used only for passthrough byte comparison).
+  fixtures.ico = path.join(tmpRoot, 'in.ico');
+  await fs.writeFile(
+    fixtures.ico,
+    Buffer.from(
+      '00000100010001010000010020003000000016000000280000000100000002000000010020000000000004000000000000000000000000000000000000000000000000000000000000000000000000',
+      'hex'
+    )
+  );
+});
 
-// Mock path - use actual implementation but allow spying
-vi.mock('path', async () => {
-  const actual = await vi.importActual('path');
-  return {
-    default: actual.default,
-    ...actual,
-  };
+afterAll(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true });
 });
 
-// Import after mocks are set up
-import { processImage } from '../imageProcessingService.js';
-import sharp from 'sharp';
-import fs from 'fs';
-
-describe('imageProcessingService', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    // Reset mock implementations
-    mockMetadata.mockResolvedValue({ width: 800, size: 100000 });
-    mockToFile.mockResolvedValue();
-    fs.existsSync.mockReturnValue(true);
+async function metaOf(file) {
+  return sharp(file).metadata();
+}
+
+describe('processImage — format passthrough', () => {
+  it('PNG <= 1200: preserves format and passes through unmodified', async () => {
+    const out = await processImage(fixtures.pngSmall, tmpRoot);
+    expect(path.extname(out).toLowerCase()).toBe('.png');
+    const m = await metaOf(out);
+    expect(m.format).toBe('png');
+    expect(m.width).toBe(800);
   });
 
-  describe('Input Validation', () => {
-    it('should accept valid inputPath and outputDir', async () => {
-      const inputPath = '/tmp/test-image.jpg';
-      const outputDir = '/tmp/output';
-
-      await processImage(inputPath, outputDir);
-
-      expect(sharp).toHaveBeenCalledWith(inputPath);
-      expect(mockToFile).toHaveBeenCalled();
-    });
-
-    it('should reject missing inputPath', async () => {
-      await expect(processImage(undefined, '/tmp/output')).rejects.toThrow(
-        'Invalid processing parameters'
-      );
-      expect(sharp).not.toHaveBeenCalled();
-    });
-
-    it('should reject missing outputDir', async () => {
-      await expect(processImage('/tmp/test.jpg', undefined)).rejects.toThrow(
-        'Invalid processing parameters'
-      );
-      expect(sharp).not.toHaveBeenCalled();
-    });
+  it('PNG > 1200: resized but still PNG (no JPEG conversion)', async () => {
+    const out = await processImage(fixtures.pngLarge, tmpRoot);
+    expect(path.extname(out).toLowerCase()).toBe('.png');
+    const m = await metaOf(out);
+    expect(m.format).toBe('png');
+    expect(m.width).toBe(1200);
   });
 
-  describe('Path Security', () => {
-    it('should resolve paths correctly', async () => {
-      const inputPath = './relative/path/image.jpg';
-      const outputDir = './output';
-
-      await processImage(inputPath, outputDir);
-
-      expect(fs.existsSync).toHaveBeenCalledWith(expect.stringContaining('image.jpg'));
-      expect(mockToFile).toHaveBeenCalledWith(expect.stringContaining('output'));
-    });
-
-    it('should throw error when input file does not exist', async () => {
-      fs.existsSync.mockReturnValue(false);
-
-      await expect(processImage('/tmp/nonexistent.jpg', '/tmp/output')).rejects.toThrow(
-        'Input file does not exist'
-      );
-      expect(sharp).not.toHaveBeenCalled();
-    });
+  it('JPEG <= 1200: passes through as JPEG', async () => {
+    const out = await processImage(fixtures.jpegSmall, tmpRoot);
+    expect(path.extname(out).toLowerCase()).toMatch(/\.jpe?g$/);
+    const m = await metaOf(out);
+    expect(m.format).toBe('jpeg');
+    expect(m.width).toBe(800);
   });
 
-  describe('Image Processing', () => {
-    it('should not resize image when width <= MAX_WIDTH (1200)', async () => {
-      mockMetadata.mockResolvedValue({ width: 1000, size: 100000 });
-
-      await processImage('/tmp/small-image.jpg', '/tmp/output');
-
-      expect(mockResize).not.toHaveBeenCalled();
-      expect(mockJpeg).toHaveBeenCalledWith({ quality: 80 });
-      expect(mockToFile).toHaveBeenCalled();
-    });
-
-    it('should resize image when width > MAX_WIDTH (1200)', async () => {
-      mockMetadata.mockResolvedValue({ width: 2000, size: 200000 });
-
-      await processImage('/tmp/large-image.jpg', '/tmp/output');
-
-      expect(mockResize).toHaveBeenCalledWith({ width: 1200 });
-      expect(mockJpeg).toHaveBeenCalledWith({ quality: 80 });
-      expect(mockToFile).toHaveBeenCalled();
-    });
-
-    it('should generate output filename with timestamp and processed prefix', async () => {
-      const inputPath = '/tmp/test-photo.jpg';
-      const outputDir = '/tmp/output';
-
-      // Mock Date.now to get predictable filename
-      const mockTimestamp = 1234567890;
-      vi.spyOn(Date, 'now').mockReturnValue(mockTimestamp);
+  it('JPEG > 1200: resized as JPEG', async () => {
+    const out = await processImage(fixtures.jpegLarge, tmpRoot);
+    const m = await metaOf(out);
+    expect(m.format).toBe('jpeg');
+    expect(m.width).toBe(1200);
+  });
 
-      await processImage(inputPath, outputDir);
+  it('WEBP <= 1200: passes through as WEBP', async () => {
+    const out = await processImage(fixtures.webpSmall, tmpRoot);
+    const m = await metaOf(out);
+    expect(m.format).toBe('webp');
+    expect(m.width).toBe(800);
+  });
 
-      expect(mockToFile).toHaveBeenCalledWith(
-        expect.stringMatching(/processed-1234567890-test-photo\.jpg$/)
-      );
+  it('WEBP > 1200: resized as WEBP', async () => {
+    const out = await processImage(fixtures.webpLarge, tmpRoot);
+    const m = await metaOf(out);
+    expect(m.format).toBe('webp');
+    expect(m.width).toBe(1200);
+  });
 
-      vi.restoreAllMocks();
-    });
+  it('SVG: passthrough — output bytes identical to input (never touched by sharp)', async () => {
+    const out = await processImage(fixtures.svg, tmpRoot);
+    expect(path.extname(out).toLowerCase()).toBe('.svg');
+    const [a, b] = await Promise.all([fs.readFile(fixtures.svg), fs.readFile(out)]);
+    expect(a.equals(b)).toBe(true);
+  });
 
-    it('should convert image to JPEG with quality setting of 80', async () => {
-      await processImage('/tmp/image.png', '/tmp/output');
+  it('GIF: passthrough — output bytes identical to input (animation-safe)', async () => {
+    const out = await processImage(fixtures.gif, tmpRoot);
+    expect(path.extname(out).toLowerCase()).toBe('.gif');
+    const [a, b] = await Promise.all([fs.readFile(fixtures.gif), fs.readFile(out)]);
+    expect(a.equals(b)).toBe(true);
+  });
 
-      expect(mockJpeg).toHaveBeenCalledWith({ quality: 80 });
-      expect(mockToFile).toHaveBeenCalled();
-    });
+  it('ICO: passthrough — output bytes identical to input', async () => {
+    const out = await processImage(fixtures.ico, tmpRoot, { purpose: 'icon' });
+    expect(path.extname(out).toLowerCase()).toBe('.ico');
+    const [a, b] = await Promise.all([fs.readFile(fixtures.ico), fs.readFile(out)]);
+    expect(a.equals(b)).toBe(true);
+  });
 
-    it('should handle images with multiple dots in filename', async () => {
-      const inputPath = '/tmp/my.test.image.png';
-      const outputDir = '/tmp/output';
-      const mockTimestamp = 9999999999;
-      vi.spyOn(Date, 'now').mockReturnValue(mockTimestamp);
+  it('output path is distinct from input path', async () => {
+    const out = await processImage(fixtures.pngSmall, tmpRoot);
+    expect(out).not.toBe(fixtures.pngSmall);
+  });
+});
 
-      await processImage(inputPath, outputDir);
+describe('processImage — validation & errors', () => {
+  it('rejects missing inputPath', async () => {
+    await expect(processImage(undefined, tmpRoot)).rejects.toThrow(/Invalid processing parameters/);
+  });
 
-      expect(mockToFile).toHaveBeenCalledWith(
-        expect.stringMatching(/processed-9999999999-my\.test\.image\.jpg$/)
-      );
+  it('rejects missing outputDir', async () => {
+    await expect(processImage(fixtures.pngSmall, undefined)).rejects.toThrow(
+      /Invalid processing parameters/
+    );
+  });
 
-      vi.restoreAllMocks();
-    });
+  it('throws when input file does not exist', async () => {
+    await expect(processImage('/nonexistent/xyz.png', tmpRoot)).rejects.toThrow(
+      /Input file does not exist/
+    );
   });
 
-  describe('Error Handling', () => {
-    it('should catch and re-throw sharp processing failures', async () => {
-      const processingError = new Error('Sharp processing failed');
-      mockMetadata.mockRejectedValue(processingError);
-
-      await expect(processImage('/tmp/corrupt.jpg', '/tmp/output')).rejects.toThrow(
-        'Image processing failed: Sharp processing failed'
-      );
-    });
-
-    it('should include original error message in re-thrown error', async () => {
-      const originalMessage = 'Input buffer contains unsupported image format';
-      mockToFile.mockRejectedValue(new Error(originalMessage));
-
-      await expect(processImage('/tmp/bad-format.dat', '/tmp/output')).rejects.toThrow(
-        `Image processing failed: ${originalMessage}`
-      );
-    });
-
-    it('should handle errors during JPEG conversion', async () => {
-      const conversionError = new Error('JPEG conversion failed');
-      mockToFile.mockRejectedValue(conversionError);
-
-      await expect(processImage('/tmp/image.jpg', '/tmp/output')).rejects.toThrow(
-        'Image processing failed: JPEG conversion failed'
-      );
-    });
+  it('wraps sharp failures with context', async () => {
+    const bogus = path.join(tmpRoot, 'bogus.png');
+    await fs.writeFile(bogus, 'not an image');
+    await expect(processImage(bogus, tmpRoot)).rejects.toThrow(/Image processing failed/);
   });
 });

package/src/services/__tests__/images.test.js

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { mockGhostApiModule } from '../../__tests__/helpers/mockGhostApi.js';
+import { createMockContextLogger } from '../../__tests__/helpers/mockLogger.js';
+import { mockDotenv } from '../../__tests__/helpers/testUtils.js';
+
+vi.mock('@tryghost/admin-api', () => mockGhostApiModule());
+vi.mock('dotenv', () => mockDotenv());
+vi.mock('../../utils/logger.js', () => ({
+  createContextLogger: createMockContextLogger(),
+}));
+
+// Stub path validation so these tests focus on argument shaping, not FS.
+vi.mock('../validators.js', () => ({
+  validators: { validateImagePath: vi.fn().mockResolvedValue(undefined) },
+}));
+
+import { uploadImage } from '../images.js';
+import { api } from '../ghostApiClient.js';
+import { ValidationError } from '../../errors/index.js';
+
+describe('images.uploadImage (domain module used by MCP server)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('forwards purpose and ref to the SDK', async () => {
+    const expected = { url: 'https://cdn/x.png', ref: 'original.png' };
+    api.images.upload.mockResolvedValue(expected);
+
+    const result = await uploadImage('/tmp/x.png', {
+      purpose: 'icon',
+      ref: 'original.png',
+    });
+
+    expect(result).toEqual(expected);
+    expect(api.images.upload).toHaveBeenCalledWith({
+      file: '/tmp/x.png',
+      purpose: 'icon',
+      ref: 'original.png',
+    });
+  });
+
+  it('omits purpose/ref when not provided', async () => {
+    api.images.upload.mockResolvedValue({ url: 'https://cdn/x.png' });
+    await uploadImage('/tmp/x.png');
+    expect(api.images.upload).toHaveBeenCalledWith({ file: '/tmp/x.png' });
+  });
+
+  it('accepts each allowed purpose value', async () => {
+    api.images.upload.mockResolvedValue({ url: 'https://cdn/x' });
+    for (const purpose of ['image', 'profile_image', 'icon']) {
+      await uploadImage('/tmp/x.png', { purpose });
+    }
+    expect(api.images.upload).toHaveBeenCalledTimes(3);
+  });
+
+  it('rejects unknown purpose', async () => {
+    await expect(uploadImage('/tmp/x.png', { purpose: 'banner' })).rejects.toBeInstanceOf(
+      ValidationError
+    );
+    expect(api.images.upload).not.toHaveBeenCalled();
+  });
+
+  it('rejects non-string ref', async () => {
+    await expect(uploadImage('/tmp/x.png', { ref: 42 })).rejects.toThrow(/must be a string/);
+  });
+
+  it('rejects ref longer than 200 chars', async () => {
+    await expect(uploadImage('/tmp/x.png', { ref: 'x'.repeat(201) })).rejects.toThrow(
+      /cannot exceed 200/
+    );
+  });
+
+  it('accepts ref of exactly 200 chars', async () => {
+    api.images.upload.mockResolvedValue({ url: 'https://cdn/x' });
+    await expect(uploadImage('/tmp/x.png', { ref: 'x'.repeat(200) })).resolves.toBeDefined();
+  });
+});

package/src/services/ghostService.js

@@ -148,24 +148,6 @@ const createPost = async (postData, options = { source: 'html' }) => {
   return handleApiRequest('posts', 'add', dataWithDefaults, options);
 };
 
-/**
- * Uploads an image to Ghost.
- * Requires the image file path.
- * @param {string} imagePath - The local path to the image file.
- * @returns {Promise<object>} The result from the image upload API call, typically includes the URL of the uploaded image.
- */
-const uploadImage = async (imagePath) => {
-  if (!imagePath) {
-    throw new Error('Image path is required for upload.');
-  }
-
-  // The Ghost Admin API expects an object with a 'file' property containing the path
-  const imageData = { file: imagePath };
-
-  // Use the handleApiRequest function for consistency
-  return handleApiRequest('images', 'upload', imageData);
-};
-
 /**
  * Creates a new tag in Ghost.
  * @param {object} tagData - Data for the new tag (e.g., { name: 'New Tag', slug: 'new-tag' }).
@@ -209,4 +191,4 @@ const getTags = async (options = {}) => {
 // Add other content management functions here (createTag, etc.)
 
 // Export the API client instance and any service functions
-export { api, getSiteInfo, handleApiRequest, createPost, uploadImage, createTag, getTags };
+export { api, getSiteInfo, handleApiRequest, createPost, createTag, getTags };

package/src/services/imageProcessingService.js

@@ -1,96 +1,140 @@
 import sharp from 'sharp';
 import path from 'path';
-import fs from 'fs';
-import Joi from 'joi';
+import fsp from 'fs/promises';
+import { z } from 'zod';
 import { createContextLogger } from '../utils/logger.js';
 
-// Define processing parameters (e.g., max width)
 const MAX_WIDTH = 1200;
-const OUTPUT_QUALITY = 80; // JPEG quality
+const JPEG_QUALITY = 80;
 
-/**
- * Processes an image: resizes if too large, ensures JPEG format (configurable).
- * @param {string} inputPath - Path to the original uploaded image.
- * @param {string} outputDir - Directory to save the processed image.
- * @returns {Promise<string>} Path to the processed image.
- */
-// Validation schema for processing parameters
-const processImageSchema = Joi.object({
-  inputPath: Joi.string().required(),
-  outputDir: Joi.string().required(),
+// Formats we re-encode via sharp when the image is oversized.
+// Everything else is passed through untouched to preserve fidelity
+// (SVG vectors, GIF animation, ICO, exotic formats).
+const RESIZABLE_FORMATS = new Set(['jpeg', 'png', 'webp']);
+
+const EXT_BY_FORMAT = {
+  jpeg: '.jpg',
+  png: '.png',
+  webp: '.webp',
+  gif: '.gif',
+  svg: '.svg',
+  // ICO has no sharp `format` name; detected by extension.
+};
+
+const processImageParamsSchema = z.object({
+  inputPath: z.string().min(1),
+  outputDir: z.string().min(1),
 });
 
-const processImage = async (inputPath, outputDir) => {
+const processImageOptsSchema = z
+  .object({
+    purpose: z.enum(['image', 'profile_image', 'icon']).optional(),
+  })
+  .optional();
+
+/**
+ * Process an image for upload to Ghost.
+ *
+ * Preserves the original format. Resizes (preserving format) only for
+ * raster formats sharp can safely re-encode — JPEG, PNG, WEBP — when
+ * wider than MAX_WIDTH. SVG, GIF, ICO, and unrecognized formats are
+ * copied byte-for-byte so vectors, animation frames, and icon metadata
+ * survive the round trip.
+ *
+ * @param {string} inputPath - Absolute path to the source image.
+ * @param {string} outputDir - Directory to write the processed file into.
+ * @param {{ purpose?: 'image'|'profile_image'|'icon' }} [opts]
+ * @returns {Promise<string>} Absolute path to the processed (or copied) file.
+ */
+export async function processImage(inputPath, outputDir, opts = {}) {
   const logger = createContextLogger('image-processing');
 
-  // Validate inputs to prevent path injection
-  const { error } = processImageSchema.validate({ inputPath, outputDir });
-  if (error) {
-    logger.error('Invalid processing parameters', {
-      error: error.details[0].message,
-      inputPath: inputPath ? path.basename(inputPath) : 'undefined',
-      outputDir: outputDir ? path.basename(outputDir) : 'undefined',
-    });
+  const params = processImageParamsSchema.safeParse({ inputPath, outputDir });
+  if (!params.success) {
     throw new Error('Invalid processing parameters');
   }
+  processImageOptsSchema.parse(opts);
 
-  // Ensure paths are safe
-  const resolvedInputPath = path.resolve(inputPath);
+  const resolvedInput = path.resolve(inputPath);
   const resolvedOutputDir = path.resolve(outputDir);
 
-  // Verify input file exists
-  if (!fs.existsSync(resolvedInputPath)) {
+  try {
+    await fsp.access(resolvedInput);
+  } catch {
     throw new Error('Input file does not exist');
   }
 
-  const filename = path.basename(resolvedInputPath);
-  const nameWithoutExt = filename.split('.').slice(0, -1).join('.');
-  // Use timestamp for unique output filename
+  const inputExt = path.extname(resolvedInput).toLowerCase();
+  const baseName = path.basename(resolvedInput, path.extname(resolvedInput));
   const timestamp = Date.now();
-  const outputFilename = `processed-${timestamp}-${nameWithoutExt}.jpg`;
-  const outputPath = path.join(resolvedOutputDir, outputFilename);
 
   try {
-    logger.info('Processing image', {
-      inputFile: path.basename(inputPath),
-      outputDir: path.basename(outputDir),
-    });
-    const image = sharp(inputPath);
+    // Non-raster passthrough: SVG and ICO are never handed to sharp.
+    // (sharp can read SVG but would rasterize it, destroying the vector.)
+    if (inputExt === '.svg' || inputExt === '.ico') {
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, inputExt);
+    }
+
+    const image = sharp(resolvedInput);
     const metadata = await image.metadata();
+    const format = metadata.format; // 'jpeg' | 'png' | 'webp' | 'gif' | 'svg' | ...
 
-    let processedImage = image;
+    // GIF: never re-encode — sharp would drop animation frames.
+    // SVG (if it slipped through by extension mismatch): also passthrough.
+    if (format === 'gif' || format === 'svg') {
+      const ext = EXT_BY_FORMAT[format] || inputExt || '';
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, ext);
+    }
 
-    // Resize if wider than MAX_WIDTH
-    if (metadata.width && metadata.width > MAX_WIDTH) {
-      logger.info('Resizing image', {
-        originalWidth: metadata.width,
-        targetWidth: MAX_WIDTH,
+    // Unknown / unsupported format: safest is passthrough.
+    if (!RESIZABLE_FORMATS.has(format)) {
+      logger.info('Unknown format, passing through', {
+        format,
         inputFile: path.basename(inputPath),
       });
-      processedImage = processedImage.resize({ width: MAX_WIDTH });
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, inputExt);
     }
 
-    // Convert to JPEG with specified quality
-    // You could add options for PNG/WebP etc. if needed
-    await processedImage.jpeg({ quality: OUTPUT_QUALITY }).toFile(outputPath);
+    const ext = EXT_BY_FORMAT[format];
+    const outputPath = path.join(resolvedOutputDir, `processed-${timestamp}-${baseName}${ext}`);
 
-    logger.info('Image processing completed', {
+    // Passthrough when no resize is needed — avoids generation loss.
+    if (!metadata.width || metadata.width <= MAX_WIDTH) {
+      await fsp.copyFile(resolvedInput, outputPath);
+      logger.info('Image within size limits, passthrough copy', {
+        format,
+        width: metadata.width,
+        inputFile: path.basename(inputPath),
+      });
+      return outputPath;
+    }
+
+    logger.info('Resizing image', {
+      format,
+      originalWidth: metadata.width,
+      targetWidth: MAX_WIDTH,
       inputFile: path.basename(inputPath),
-      outputFile: path.basename(outputPath),
-      originalSize: metadata.size,
-      quality: OUTPUT_QUALITY,
     });
+
+    // sharp picks the encoder from outputPath extension (EXT_BY_FORMAT),
+    // so only JPEG needs the explicit call here to set quality. PNG/WEBP
+    // would be redundant.
+    let pipeline = image.resize({ width: MAX_WIDTH });
+    if (format === 'jpeg') pipeline = pipeline.jpeg({ quality: JPEG_QUALITY });
+
+    await pipeline.toFile(outputPath);
     return outputPath;
   } catch (error) {
     logger.error('Image processing failed', {
       inputFile: path.basename(inputPath),
       error: error.message,
-      stack: error.stack,
     });
-    // If processing fails, maybe fall back to using the original?
-    // Or throw the error to fail the upload.
     throw new Error('Image processing failed: ' + error.message, { cause: error });
   }
-};
+}
 
-export { processImage };
+async function passthrough(inputPath, outputDir, baseName, timestamp, ext) {
+  const outputPath = path.join(outputDir, `processed-${timestamp}-${baseName}${ext}`);
+  await fsp.copyFile(inputPath, outputPath);
+  return outputPath;
+}