pi-image-tools 1.3.0 → 1.4.0

package/src/image-preview.ts

@@ -19,6 +19,7 @@ import type { DebugLogger } from "./debug-logger.js";
 import { getErrorMessage } from "./errors.js";
 import { getBase64DecodedByteLength, assertImageWithinByteLimit } from "./image-size.js";
 import { mimeTypeToExtension } from "./image-mime.js";
+import { logPreviewEvent, logPreviewHandlerError } from "./preview-logging.js";
 import { runBufferedCommand, runPowerShellCommandAsync, type BufferedCommandResult, type PowerShellCommandResult, type RunPowerShellCommandOptions } from "./powershell.js";
 import { buildSixelRenderLines, ensureCompleteSixelSequence } from "./sixel-protocol.js";
 import {
@@ -130,14 +131,28 @@ const sixelAvailabilityState: SixelAvailability = {
   available: false,
 };
 
+function resolveSixelAvailabilityState(
+  forceRefresh: boolean,
+  useCache: boolean,
+): SixelAvailability {
+  return useCache ? sixelAvailabilityState : { checked: false, available: false };
+}
+
+function shouldShortCircuitSixelCheck(
+  state: SixelAvailability,
+  forceRefresh: boolean,
+): boolean {
+  return state.checked && !forceRefresh;
+}
+
 async function ensureSixelModuleAvailable(
   forceRefresh = false,
   powerShellRunner: SixelPowerShellRunner = runPowerShellCommandAsync,
 ): Promise<SixelAvailability> {
   const useCache = powerShellRunner === runPowerShellCommandAsync;
-  const state: SixelAvailability = useCache ? sixelAvailabilityState : { checked: false, available: false };
+  const state = resolveSixelAvailabilityState(forceRefresh, useCache);
 
-  if (state.checked && !forceRefresh) {
+  if (shouldShortCircuitSixelCheck(state, forceRefresh)) {
     return state;
   }
 
@@ -185,9 +200,9 @@ async function ensureLinuxSixelConverterAvailable(
   processRunner: SixelProcessRunner = runBufferedCommand,
 ): Promise<SixelAvailability> {
   const useCache = processRunner === runBufferedCommand;
-  const state: SixelAvailability = useCache ? sixelAvailabilityState : { checked: false, available: false };
+  const state = resolveSixelAvailabilityState(forceRefresh, useCache);
 
-  if (state.checked && !forceRefresh) {
+  if (shouldShortCircuitSixelCheck(state, forceRefresh)) {
     return state;
   }
 
@@ -335,7 +350,9 @@ Write-Output $rendered
   } finally {
     try {
       rmSync(tempBaseDir, { recursive: true, force: true });
-    } catch {
+    } catch (error) {
+      // Temp-directory cleanup is best-effort; the OS reclaims leftover dirs.
+      void error;
     }
   }
 }
@@ -415,18 +432,6 @@ export type BuildPreviewItemsOptions = TerminalImageWidthOptions & {
   sixelPowerShellRunner?: SixelPowerShellRunner;
 };
 
-function logSixelEvent(
-  logger: DebugLogger | undefined,
-  event: string,
-  fields: Record<string, unknown> = {},
-): void {
-  try {
-    logger?.log(event, fields);
-  } catch {
-    // Debug logging is best-effort and must never block image rendering.
-  }
-}
-
 export async function buildPreviewItems(
   images: readonly ImagePayload[],
   options: BuildPreviewItemsOptions = {},
@@ -445,7 +450,7 @@ export async function buildPreviewItems(
     ? await ensureSixelConverterAvailable(false, platform, processRunner, powerShellRunner)
     : undefined;
 
-  logSixelEvent(options.logger, "image-preview.sixel.detected", {
+  logPreviewEvent(options.logger, "image-preview.sixel.detected", {
     attemptSixel,
     available: sixelState?.available ?? false,
     converter: sixelState?.converter ?? null,
@@ -460,7 +465,7 @@ export async function buildPreviewItems(
     if (attemptSixel && sixelState?.available && sixelState.converter) {
       const conversion = await convertImageToSixelSequence(image, sixelState.converter, processRunner, powerShellRunner);
       if (conversion.sequence) {
-        logSixelEvent(options.logger, "image-preview.sixel.converted", {
+        logPreviewEvent(options.logger, "image-preview.sixel.converted", {
           converter: sixelState.converter,
           mimeType: image.mimeType,
           rows,
@@ -476,7 +481,7 @@ export async function buildPreviewItems(
         continue;
       }
 
-      logSixelEvent(options.logger, "image-preview.sixel.conversion_failed", {
+      logPreviewEvent(options.logger, "image-preview.sixel.conversion_failed", {
         converter: sixelState.converter,
         mimeType: image.mimeType,
         error: conversion.error ?? "unknown",
@@ -513,18 +518,6 @@ export interface RegisterImagePreviewDisplayOptions {
   logger?: DebugLogger;
 }
 
-function logPreviewHandlerError(
-  logger: DebugLogger | undefined,
-  event: string,
-  error: unknown,
-): void {
-  try {
-    logger?.log(event, { error: getErrorMessage(error) });
-  } catch {
-    // Debug logging is best-effort inside Pi event handlers.
-  }
-}
-
 export function registerImagePreviewDisplay(
   pi: ExtensionAPI,
   options: RegisterImagePreviewDisplayOptions = {},

package/src/image-size.ts

@@ -1,63 +1,62 @@
-export const IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR = "PI_IMAGE_TOOLS_MAX_IMAGE_BYTES";
-export const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
-
-function parseMaxImageBytes(environment: NodeJS.ProcessEnv): number {
-  const rawValue = environment[IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR]?.trim();
-  if (!rawValue) {
-    return DEFAULT_MAX_IMAGE_BYTES;
-  }
-
-  const parsed = Number(rawValue);
-  if (!Number.isFinite(parsed) || parsed < 1) {
-    throw new Error(
-      `${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} must be a positive byte count when set.`,
-    );
-  }
-
-  return Math.floor(parsed);
-}
-
-export function getMaxImageBytes(environment: NodeJS.ProcessEnv = process.env): number {
-  return parseMaxImageBytes(environment);
-}
-
-export function formatByteLimit(bytes: number): string {
-  if (bytes < 1024) {
-    return `${bytes} B`;
-  }
-
-  const units = ["KB", "MB", "GB"] as const;
-  let value = bytes / 1024;
-  let unitIndex = 0;
-
-  while (value >= 1024 && unitIndex < units.length - 1) {
-    value /= 1024;
-    unitIndex += 1;
-  }
-
-  return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unitIndex]}`;
-}
-
-export function assertImageWithinByteLimit(
-  sizeBytes: number,
-  label: string,
-  environment: NodeJS.ProcessEnv = process.env,
-): void {
-  const maxImageBytes = getMaxImageBytes(environment);
-  if (sizeBytes > maxImageBytes) {
-    throw new Error(
-      `${label} is too large (${formatByteLimit(sizeBytes)}). The pi-image-tools limit is ${formatByteLimit(maxImageBytes)}. Set ${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} to a larger byte count if needed.`,
-    );
-  }
-}
-
-export function getBase64DecodedByteLength(base64Data: string): number {
-  const normalized = base64Data.trim().replace(/^data:[^,]*,/, "").replace(/\s/g, "");
-  if (normalized.length === 0) {
-    return 0;
-  }
-
-  const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
-  return Math.max(0, Math.floor((normalized.length * 3) / 4) - padding);
-}
-
+export const IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR = "PI_IMAGE_TOOLS_MAX_IMAGE_BYTES";
+export const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+
+function parseMaxImageBytes(environment: NodeJS.ProcessEnv): number {
+  const rawValue = environment[IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR]?.trim();
+  if (!rawValue) {
+    return DEFAULT_MAX_IMAGE_BYTES;
+  }
+
+  const parsed = Number(rawValue);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new Error(
+      `${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} must be a positive byte count when set.`,
+    );
+  }
+
+  return Math.floor(parsed);
+}
+
+export function getMaxImageBytes(environment: NodeJS.ProcessEnv = process.env): number {
+  return parseMaxImageBytes(environment);
+}
+
+export function formatByteLimit(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+
+  const units = ["KB", "MB", "GB"] as const;
+  let value = bytes / 1024;
+  let unitIndex = 0;
+
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+
+  return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unitIndex]}`;
+}
+
+export function assertImageWithinByteLimit(
+  sizeBytes: number,
+  label: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): void {
+  const maxImageBytes = getMaxImageBytes(environment);
+  if (sizeBytes > maxImageBytes) {
+    throw new Error(
+      `${label} is too large (${formatByteLimit(sizeBytes)}). The pi-image-tools limit is ${formatByteLimit(maxImageBytes)}. Set ${IMAGE_TOOLS_MAX_IMAGE_BYTES_ENV_VAR} to a larger byte count if needed.`,
+    );
+  }
+}
+
+export function getBase64DecodedByteLength(base64Data: string): number {
+  const normalized = base64Data.trim().replace(/^data:[^,]*,/, "").replace(/\s/g, "");
+  if (normalized.length === 0) {
+    return 0;
+  }
+
+  return Buffer.from(normalized, "base64").length;
+}
+

package/src/image-transcode.ts

@@ -0,0 +1,206 @@
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+
+import { normalizeMimeType } from "./image-mime.js";
+import type { ClipboardImage } from "./types.js";
+
+const DEFAULT_PRIMARY_TRANSCODE_TOOL = "magick";
+const LEGACY_UNIX_TRANSCODE_TOOL = "convert";
+const ALLOWED_TRANSCODE_TOOLS = new Set([DEFAULT_PRIMARY_TRANSCODE_TOOL, LEGACY_UNIX_TRANSCODE_TOOL]);
+
+/**
+ * Maximum wall-clock time for a single ImageMagick invocation. Bounded so a
+ * malformed input cannot hang the extension indefinitely; well above what a
+ * typical clipboard-sized image needs to convert.
+ */
+const TRANSCODE_TIMEOUT_MS = 30_000;
+
+/**
+ * Maximum buffered output from ImageMagick. PNG re-encoding of a typical
+ * Windows screenshot is well under 5 MB; 64 MB gives us several orders of
+ * magnitude of headroom while still bounding memory.
+ */
+const TRANSCODE_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
+/**
+ * MIME types that the major model providers (Anthropic, OpenAI, Bedrock, Gemini)
+ * accept as image input. Anything outside this set must be transcoded before
+ * being attached to a user message, otherwise providers return errors such as
+ * "Unknown image type: image/bmp".
+ *
+ * Distinct from `SUPPORTED_IMAGE_MIME_TYPES` in `./image-mime.ts`, which
+ * describes formats the *clipboard providers* know how to read (including
+ * `image/bmp`). The two sets serve opposite ends of the pipeline.
+ */
+export const MODEL_PROVIDER_IMAGE_MIME_TYPES: ReadonlySet<string> = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+]);
+
+/**
+ * Aliases and legacy MIME spellings that providers or clipboard sources may
+ * emit. Canonicalization keeps supported formats on the fast path and gives
+ * ImageMagick stable input format names for formats that need transcoding.
+ */
+const MIME_ALIASES: ReadonlyMap<string, string> = new Map([
+  ["image/jpg", "image/jpeg"],
+  ["image/pjpeg", "image/jpeg"],
+  ["image/x-png", "image/png"],
+  ["image/x-bmp", "image/bmp"],
+  ["image/x-ms-bmp", "image/bmp"],
+  ["image/tif", "image/tiff"],
+]);
+
+const IMAGE_MAGICK_INPUT_FORMAT_BY_MIME_TYPE: ReadonlyMap<string, string> = new Map([
+  ["image/bmp", "bmp"],
+  ["image/tiff", "tiff"],
+  ["image/svg+xml", "svg"],
+  ["image/heic", "heic"],
+  ["image/heif", "heif"],
+  ["image/avif", "avif"],
+]);
+
+function getDefaultTranscodeTools(platform?: NodeJS.Platform): readonly string[] {
+  if (platform === "win32") {
+    // Windows ships C:\Windows\System32\convert.exe, which is unrelated to
+    // ImageMagick and can produce confusing failures. Prefer the modern
+    // ImageMagick 7 `magick` launcher by default on Windows; callers that know
+    // they have an ImageMagick `convert` on PATH can still pass `tools`.
+    return [DEFAULT_PRIMARY_TRANSCODE_TOOL];
+  }
+
+  return [DEFAULT_PRIMARY_TRANSCODE_TOOL, LEGACY_UNIX_TRANSCODE_TOOL];
+}
+
+function isAllowedTranscodeTool(tool: string): boolean {
+  return ALLOWED_TRANSCODE_TOOLS.has(tool.trim().toLowerCase());
+}
+
+function describeTranscodeTools(tools: readonly string[]): string {
+  const uniqueTools = [...new Set(tools.length > 0 ? tools : [DEFAULT_PRIMARY_TRANSCODE_TOOL])];
+  if (uniqueTools.length === 1) {
+    return `\`${uniqueTools[0]}\``;
+  }
+
+  const quotedTools = uniqueTools.map((tool) => `\`${tool}\``);
+  return `${quotedTools.slice(0, -1).join(", ")} or ${quotedTools[quotedTools.length - 1]}`;
+}
+
+function imageMagickInputFormatForMimeType(canonicalMimeType: string): string {
+  const mappedFormat = IMAGE_MAGICK_INPUT_FORMAT_BY_MIME_TYPE.get(canonicalMimeType);
+  if (mappedFormat) {
+    return mappedFormat;
+  }
+
+  if (!canonicalMimeType.startsWith("image/")) {
+    return "";
+  }
+
+  const subtype = canonicalMimeType.slice("image/".length);
+  return subtype.split("+")[0] ?? "";
+}
+
+function isMissingCommandError(error: Error): boolean {
+  return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function canonicalizeMimeType(mimeType: string): string {
+  const normalized = normalizeMimeType(mimeType);
+  return MIME_ALIASES.get(normalized) ?? normalized;
+}
+
+export interface TranscodeRunner {
+  (
+    command: string,
+    args: readonly string[],
+    input: Uint8Array,
+  ): SpawnSyncReturns<Buffer>;
+}
+
+const defaultTranscodeRunner: TranscodeRunner = (command, args, input) =>
+  spawnSync(command, args as string[], { // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- command is validated by isAllowedTranscodeTool before the default runner is reached; args are fixed ImageMagick stdin/stdout specs and shell is disabled.
+    input: Buffer.from(input),
+    maxBuffer: TRANSCODE_MAX_BUFFER_BYTES,
+    timeout: TRANSCODE_TIMEOUT_MS,
+    windowsHide: true,
+  });
+
+export interface TranscodeOptions {
+  /** Override the spawn implementation. Mainly for tests. */
+  runner?: TranscodeRunner;
+  /** Override the list of candidate ImageMagick executables. */
+  tools?: readonly string[];
+  /** Platform used to choose safe default ImageMagick executable fallbacks. */
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Ensure a clipboard image is in a MIME type accepted by model providers.
+ *
+ * Images already in a supported format are returned with a canonicalized MIME
+ * (lower-cased, parameters stripped, `image/jpg` upgraded to `image/jpeg`) and
+ * otherwise unchanged bytes. Other formats (most notably `image/bmp`, which is
+ * what WSLg exposes for Windows clipboard images on the Wayland clipboard, and
+ * `image/tiff` from some macOS sources) are piped through ImageMagick and
+ * re-encoded as PNG.
+ *
+ * Throws if the source format is unsupported and no ImageMagick binary
+ * (`magick` or the legacy `convert`) is available, or if the conversion fails.
+ */
+export function transcodeToSupportedFormat(
+  image: ClipboardImage,
+  options: TranscodeOptions = {},
+): ClipboardImage {
+  const canonicalMimeType = canonicalizeMimeType(image.mimeType);
+
+  if (MODEL_PROVIDER_IMAGE_MIME_TYPES.has(canonicalMimeType)) {
+    // Fast path: bytes are already in a provider-accepted format.
+    // Return the canonicalized MIME so downstream consumers don't have to
+    // worry about parameters/casing/aliases.
+    return canonicalMimeType === image.mimeType
+      ? image
+      : { bytes: image.bytes, mimeType: canonicalMimeType };
+  }
+
+  const runner = options.runner ?? defaultTranscodeRunner;
+  const platform = options.platform ?? process.platform;
+  const tools = options.tools ?? getDefaultTranscodeTools(platform);
+
+  const inputFormat = imageMagickInputFormatForMimeType(canonicalMimeType);
+  const inputSpec = inputFormat.length > 0 ? `${inputFormat}:-` : "-";
+
+  const failures: string[] = [];
+  for (const tool of tools) {
+    if (!isAllowedTranscodeTool(tool)) {
+      throw new Error(`Transcode tool "${tool}" is not an allowed ImageMagick executable. Allowed tools: ${describeTranscodeTools([...ALLOWED_TRANSCODE_TOOLS])}.`);
+    }
+    const result = runner(tool, [inputSpec, "png:-"], image.bytes);
+    if (result.error) {
+      failures.push(`${tool}: ${result.error.message}`);
+      if (isMissingCommandError(result.error)) {
+        continue;
+      }
+      break;
+    }
+    if (result.status !== 0 || !result.stdout || result.stdout.length === 0) {
+      const stderr = result.stderr ? result.stderr.toString("utf8").trim() : "";
+      failures.push(`${tool} exited with status ${result.status}${stderr ? `: ${stderr}` : ""}`);
+      break;
+    }
+    return {
+      bytes: new Uint8Array(result.stdout),
+      mimeType: "image/png",
+    };
+  }
+
+  const detail = failures.length > 0
+    ? ` (${failures.join("; ")})`
+    : tools.length === 0
+      ? " (no transcode tools configured)"
+      : "";
+  throw new Error(
+    `Clipboard image is in unsupported format "${image.mimeType}" and could not be transcoded to PNG. ` +
+      `Install ImageMagick (${describeTranscodeTools(tools)}) so pi-image-tools can convert images that providers don't accept natively.${detail}`,
+  );
+}

package/src/index.ts

@@ -26,39 +26,32 @@ type ImagePreviewModule = typeof import("./image-preview.js");
 type InlineUserPreviewModule = typeof import("./inline-user-preview.js");
 type RecentImagesModule = typeof import("./recent-images.js");
 
-let clipboardModulePromise: Promise<ClipboardModule> | undefined;
-let imagePreviewModulePromise: Promise<ImagePreviewModule> | undefined;
-let inlineUserPreviewModulePromise: Promise<InlineUserPreviewModule> | undefined;
-let recentImagesModulePromise: Promise<RecentImagesModule> | undefined;
+const lazyModules = new Map<string, Promise<unknown>>();
 const imagePreviewDisplayRegistrations = new WeakSet<ExtensionAPI>();
 const inlineUserPreviewRegistrations = new WeakSet<ExtensionAPI>();
 const previewRegistrationPromises = new WeakMap<ExtensionAPI, Promise<void>>();
 
-function loadClipboardModule(): Promise<ClipboardModule> {
-  clipboardModulePromise ??= import("./clipboard.js");
-  return clipboardModulePromise;
-}
-
-function loadImagePreviewModule(): Promise<ImagePreviewModule> {
-  imagePreviewModulePromise ??= import("./image-preview.js");
-  return imagePreviewModulePromise;
-}
-
-function loadInlineUserPreviewModule(): Promise<InlineUserPreviewModule> {
-  inlineUserPreviewModulePromise ??= import("./inline-user-preview.js");
-  return inlineUserPreviewModulePromise;
-}
+/**
+ * Lazily import and cache a module by key. The factory uses a literal
+ * `import("./path.js")` so TypeScript keeps full module-type inference; the
+ * key retains a single in-flight promise per module across calls.
+ */
+function loadModule<T>(key: string, factory: () => Promise<T>): Promise<T> {
+  const cached = lazyModules.get(key);
+  if (cached !== undefined) {
+    return cached as Promise<T>;
+  }
 
-function loadRecentImagesModule(): Promise<RecentImagesModule> {
-  recentImagesModulePromise ??= import("./recent-images.js");
-  return recentImagesModulePromise;
+  const promise = factory();
+  lazyModules.set(key, promise);
+  return promise;
 }
 
 async function ensureImagePreviewDisplayRegistered(
   pi: ExtensionAPI,
   logger: DebugLogger,
 ): Promise<ImagePreviewModule> {
-  const module = await loadImagePreviewModule();
+  const module = await loadModule<ImagePreviewModule>("image-preview", () => import("./image-preview.js"));
   if (!imagePreviewDisplayRegistrations.has(pi)) {
     imagePreviewDisplayRegistrations.add(pi);
     module.registerImagePreviewDisplay(pi, { logger });
@@ -68,12 +61,12 @@ async function ensureImagePreviewDisplayRegistered(
 
 async function ensurePreviewRegistrations(pi: ExtensionAPI, logger: DebugLogger): Promise<void> {
   let registrationPromise = previewRegistrationPromises.get(pi);
-  if (!registrationPromise) {
+  if (registrationPromise === undefined) {
     registrationPromise = (async () => {
       await ensureImagePreviewDisplayRegistered(pi, logger);
 
       if (!inlineUserPreviewRegistrations.has(pi)) {
-        const module = await loadInlineUserPreviewModule();
+        const module = await loadModule<InlineUserPreviewModule>("inline-user-preview", () => import("./inline-user-preview.js"));
         inlineUserPreviewRegistrations.add(pi);
         module.registerInlineUserImagePreview(pi, { logger });
       }
@@ -116,7 +109,7 @@ function removeAttachmentIndicators(text: string): string {
 
 async function cacheImageForRecentPicker(ctx: PasteContext, image: ClipboardImage): Promise<void> {
   try {
-    const { persistImageToRecentCache } = await loadRecentImagesModule();
+    const { persistImageToRecentCache } = await loadModule<RecentImagesModule>("recent-images", () => import("./recent-images.js"));
     persistImageToRecentCache(image);
   } catch (error) {
     if (ctx.hasUI) {
@@ -206,6 +199,9 @@ async function showRecentSelectionPreview(
 
 export default function imageToolsExtension(pi: ExtensionAPI): void {
   const config = loadImageToolsConfig();
+  if (!config.enabled) {
+    return;
+  }
   const logger = DebugLogger.create(config);
   const pendingImages: PendingImage[] = [];
 
@@ -230,7 +226,7 @@ export default function imageToolsExtension(pi: ExtensionAPI): void {
     }
 
     try {
-      const { readClipboardImage } = await loadClipboardModule();
+      const { readClipboardImage } = await loadModule<ClipboardModule>("clipboard", () => import("./clipboard.js"));
       const image = await readClipboardImage();
       if (!image) {
         ctx.ui.notify("No image found in clipboard.", "warning");
@@ -261,7 +257,7 @@ export default function imageToolsExtension(pi: ExtensionAPI): void {
         formatRecentImageLabel,
         getRecentImageCacheDirectory,
         loadRecentImage,
-      } = await loadRecentImagesModule();
+      } = await loadModule<RecentImagesModule>("recent-images", () => import("./recent-images.js"));
       const discovery = discoverRecentImages();
       if (discovery.candidates.length === 0) {
         ctx.ui.notify(