pi-image-tools 1.0.11 → 1.2.0

package/src/image-preview.ts

@@ -1,9 +1,8 @@
-import { spawnSync } from "node:child_process";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   calculateImageRows,
   Container,
@@ -13,8 +12,14 @@ import {
   Spacer,
   Text,
   type Component,
-} from "@mariozechner/pi-tui";
-
+} from "@earendil-works/pi-tui";
+
+import { isRecord } from "./config.js";
+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 { runBufferedCommand, runPowerShellCommandAsync, type BufferedCommandResult, type PowerShellCommandResult, type RunPowerShellCommandOptions } from "./powershell.js";
 import { buildSixelRenderLines, ensureCompleteSixelSequence } from "./sixel-protocol.js";
 import {
   DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS,
@@ -26,6 +31,8 @@ export const IMAGE_PREVIEW_CUSTOM_TYPE = "pi-image-tools-preview";
 const MAX_IMAGES_PER_MESSAGE = 3;
 const POWER_SHELL_TIMEOUT_MS = 120_000;
 const POWER_SHELL_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
+const LINUX_SIXEL_TIMEOUT_MS = 120_000;
+const LINUX_SIXEL_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
 const FORCE_SIXEL_ENV_VAR = "PI_IMAGE_TOOLS_FORCE_SIXEL";
 const DISABLE_SIXEL_ENV_VAR = "PI_IMAGE_TOOLS_DISABLE_SIXEL";
 
@@ -35,9 +42,22 @@ export type ImagePayload = {
   mimeType: string;
 };
 
+type SixelConverter = "powershell-sixel" | "img2sixel";
+type SixelProcessRunner = (
+  command: string,
+  args: readonly string[],
+  options: { timeout: number; maxBuffer: number; windowsHide?: boolean },
+) => Promise<BufferedCommandResult>;
+
+type SixelPowerShellRunner = (
+  script: string,
+  options: RunPowerShellCommandOptions,
+) => Promise<PowerShellCommandResult>;
+
 type SixelAvailability = {
   checked: boolean;
   available: boolean;
+  converter?: SixelConverter;
   version?: string;
   reason?: string;
 };
@@ -77,22 +97,6 @@ function normalizeText(value: unknown): string {
   return typeof value === "string" ? value.trim() : "";
 }
 
-function getErrorMessage(error: unknown): string {
-  if (error instanceof Error && error.message.trim()) {
-    return error.message;
-  }
-
-  return "Unknown error";
-}
-
-function toRecord(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return {};
-  }
-
-  return value as Record<string, unknown>;
-}
-
 function normalizeEnvValue(value: string | undefined): string {
   return typeof value === "string" ? value.trim().toLowerCase() : "";
 }
@@ -102,87 +106,39 @@ function isTruthyEnvFlag(value: string | undefined): boolean {
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
 
-function shouldAttemptSixelRendering(): boolean {
-  if (process.platform !== "win32") {
+function shouldAttemptSixelRendering(
+  environment: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (isTruthyEnvFlag(environment[DISABLE_SIXEL_ENV_VAR])) {
     return false;
   }
 
-  if (isTruthyEnvFlag(process.env[DISABLE_SIXEL_ENV_VAR])) {
+  if (platform !== "win32" && platform !== "linux") {
     return false;
   }
 
-  if (isTruthyEnvFlag(process.env[FORCE_SIXEL_ENV_VAR])) {
+  if (isTruthyEnvFlag(environment[FORCE_SIXEL_ENV_VAR])) {
     return true;
   }
 
   return !getCapabilities().images;
 }
 
-function runPowerShellCommand(
-  script: string,
-  args: string[] = [],
-): { ok: boolean; stdout: string; stderr: string; reason?: string } {
-  if (process.platform !== "win32") {
-    return {
-      ok: false,
-      stdout: "",
-      stderr: "",
-      reason: "PowerShell-based Sixel rendering is only available on Windows.",
-    };
-  }
-
-  const result = spawnSync(
-    "powershell.exe",
-    [
-      "-NoProfile",
-      "-NonInteractive",
-      "-ExecutionPolicy",
-      "Bypass",
-      "-Command",
-      script,
-      ...args,
-    ],
-    {
-      encoding: "utf8",
-      timeout: POWER_SHELL_TIMEOUT_MS,
-      maxBuffer: POWER_SHELL_MAX_BUFFER_BYTES,
-      windowsHide: true,
-    },
-  );
-
-  if (result.error) {
-    return {
-      ok: false,
-      stdout: result.stdout ?? "",
-      stderr: result.stderr ?? "",
-      reason: getErrorMessage(result.error),
-    };
-  }
-
-  if (result.status !== 0) {
-    return {
-      ok: false,
-      stdout: result.stdout ?? "",
-      stderr: result.stderr ?? "",
-      reason: `PowerShell exited with code ${result.status}`,
-    };
-  }
-
-  return {
-    ok: true,
-    stdout: result.stdout ?? "",
-    stderr: result.stderr ?? "",
-  };
-}
-
 const sixelAvailabilityState: SixelAvailability = {
   checked: false,
   available: false,
 };
 
-function ensureSixelModuleAvailable(forceRefresh = false): SixelAvailability {
-  if (sixelAvailabilityState.checked && !forceRefresh) {
-    return sixelAvailabilityState;
+async function ensureSixelModuleAvailable(
+  forceRefresh = false,
+  powerShellRunner: SixelPowerShellRunner = runPowerShellCommandAsync,
+): Promise<SixelAvailability> {
+  const useCache = powerShellRunner === runPowerShellCommandAsync;
+  const state: SixelAvailability = useCache ? sixelAvailabilityState : { checked: false, available: false };
+
+  if (state.checked && !forceRefresh) {
+    return state;
   }
 
   const script = `
@@ -191,78 +147,114 @@ $ProgressPreference = 'SilentlyContinue'
 
 $module = Get-Module -ListAvailable -Name Sixel | Sort-Object Version -Descending | Select-Object -First 1
 if ($null -eq $module) {
-  try {
-    if (Get-Command Install-Module -ErrorAction SilentlyContinue) {
-      Install-Module -Name Sixel -Scope CurrentUser -Force -AllowClobber -Repository PSGallery -ErrorAction Stop | Out-Null
-    } elseif (Get-Command Install-PSResource -ErrorAction SilentlyContinue) {
-      Install-PSResource -Name Sixel -Scope CurrentUser -TrustRepository -Reinstall -Force -ErrorAction Stop | Out-Null
-    }
-  } catch {
-  }
-
-  $module = Get-Module -ListAvailable -Name Sixel | Sort-Object Version -Descending | Select-Object -First 1
-}
-
-if ($null -eq $module) {
-  Write-Error 'Sixel PowerShell module is unavailable.'
+  Write-Error 'Sixel PowerShell module is unavailable. Install the Sixel module manually to enable Sixel previews.'
 }
 
 Write-Output ('Sixel/' + $module.Version.ToString())
 `;
 
-  const result = runPowerShellCommand(script);
-  sixelAvailabilityState.checked = true;
+  const result = await powerShellRunner(script, {
+    timeout: POWER_SHELL_TIMEOUT_MS,
+    maxBuffer: POWER_SHELL_MAX_BUFFER_BYTES,
+  });
+  state.checked = true;
 
   if (!result.ok) {
     const stderr = normalizeText(result.stderr);
     const stdout = normalizeText(result.stdout);
-    sixelAvailabilityState.available = false;
-    sixelAvailabilityState.version = undefined;
-    sixelAvailabilityState.reason =
-      stderr || stdout || result.reason || "Failed to detect/install the Sixel PowerShell module.";
-    return sixelAvailabilityState;
+    state.available = false;
+    state.converter = undefined;
+    state.version = undefined;
+    state.reason =
+      stderr || stdout || result.reason || "Failed to detect the Sixel PowerShell module.";
+    return state;
   }
 
   const marker = normalizeText(result.stdout)
     .split(/\r?\n/)
     .find((line) => line.startsWith("Sixel/"));
-  sixelAvailabilityState.available = true;
-  sixelAvailabilityState.version = marker ? marker.slice("Sixel/".length) : undefined;
-  sixelAvailabilityState.reason = undefined;
-  return sixelAvailabilityState;
+  state.available = true;
+  state.converter = "powershell-sixel";
+  state.version = marker ? marker.slice("Sixel/".length) : undefined;
+  state.reason = undefined;
+  return state;
 }
 
-function extensionForImageMimeType(mimeType: string): string {
-  const normalized = mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-  switch (normalized) {
-    case "image/png":
-      return "png";
-    case "image/jpeg":
-      return "jpg";
-    case "image/webp":
-      return "webp";
-    case "image/gif":
-      return "gif";
-    case "image/bmp":
-      return "bmp";
-    case "image/tiff":
-      return "tiff";
-    default:
-      return "png";
+async function ensureLinuxSixelConverterAvailable(
+  forceRefresh = false,
+  processRunner: SixelProcessRunner = runBufferedCommand,
+): Promise<SixelAvailability> {
+  const useCache = processRunner === runBufferedCommand;
+  const state: SixelAvailability = useCache ? sixelAvailabilityState : { checked: false, available: false };
+
+  if (state.checked && !forceRefresh) {
+    return state;
   }
+
+  state.checked = true;
+
+  const result = await processRunner("img2sixel", ["--version"], {
+    timeout: 5_000,
+    maxBuffer: 1024 * 1024,
+  });
+
+  if (result.error) {
+    state.available = false;
+    state.converter = undefined;
+    state.version = undefined;
+    state.reason = isErrnoLike(result.error, "ENOENT")
+      ? "img2sixel is not installed. Install libsixel-bin or an equivalent package to enable Linux Sixel previews."
+      : getErrorMessage(result.error);
+    return state;
+  }
+
+  if (result.status !== 0) {
+    state.available = false;
+    state.converter = undefined;
+    state.version = undefined;
+    state.reason = normalizeText(result.stderr.toString("utf8")) || normalizeText(result.stdout.toString("utf8")) || "img2sixel detection failed.";
+    return state;
+  }
+
+  state.available = true;
+  state.converter = "img2sixel";
+  state.version = normalizeText(result.stdout.toString("utf8")).split(/\r?\n/)[0] || undefined;
+  state.reason = undefined;
+  return state;
+}
+
+function ensureSixelConverterAvailable(
+  forceRefresh = false,
+  platform: NodeJS.Platform = process.platform,
+  processRunner: SixelProcessRunner = runBufferedCommand,
+  powerShellRunner: SixelPowerShellRunner = runPowerShellCommandAsync,
+): Promise<SixelAvailability> {
+  if (platform === "linux") {
+    return ensureLinuxSixelConverterAvailable(forceRefresh, processRunner);
+  }
+
+  return ensureSixelModuleAvailable(forceRefresh, powerShellRunner);
+}
+
+function isErrnoLike(error: unknown, code: string): boolean {
+  return error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === code;
 }
 
 function escapePowerShellSingleQuoted(value: string): string {
   return value.replace(/'/g, "''");
 }
 
-function convertImageToSixelSequence(
+async function convertImageToSixelSequence(
   image: ImagePayload,
-): { sequence?: string; error?: string } {
+  converter: SixelConverter,
+  processRunner: SixelProcessRunner = runBufferedCommand,
+  powerShellRunner: SixelPowerShellRunner = runPowerShellCommandAsync,
+): Promise<{ sequence?: string; error?: string }> {
   const tempBaseDir = mkdtempSync(join(tmpdir(), "pi-image-tools-image-"));
-  const imagePath = join(tempBaseDir, `preview.${extensionForImageMimeType(image.mimeType)}`);
+  const imagePath = join(tempBaseDir, `preview.${mimeTypeToExtension(image.mimeType)}`);
 
   try {
+    assertImageWithinByteLimit(getBase64DecodedByteLength(image.data), "Preview image");
     const bytes = Buffer.from(image.data, "base64");
     if (bytes.length === 0) {
       return { error: "Image conversion failed: clipboard payload was empty." };
@@ -270,6 +262,33 @@ function convertImageToSixelSequence(
 
     writeFileSync(imagePath, bytes);
 
+    if (converter === "img2sixel") {
+      const result = await processRunner("img2sixel", [imagePath], {
+        timeout: LINUX_SIXEL_TIMEOUT_MS,
+        maxBuffer: LINUX_SIXEL_MAX_BUFFER_BYTES,
+      });
+
+      if (result.error) {
+        return { error: `Sixel conversion failed: ${getErrorMessage(result.error)}` };
+      }
+
+      if (result.status !== 0) {
+        const detail = normalizeText(result.stderr.toString("utf8")) || normalizeText(result.stdout.toString("utf8"));
+        return {
+          error: detail
+            ? `Sixel conversion failed: ${detail}`
+            : "Sixel conversion failed for an unknown reason.",
+        };
+      }
+
+      const normalized = ensureCompleteSixelSequence(result.stdout.toString("utf8"));
+      if (!normalized) {
+        return { error: "Sixel conversion produced empty output." };
+      }
+
+      return { sequence: normalized };
+    }
+
     const escapedPath = escapePowerShellSingleQuoted(imagePath);
 
     const script = `
@@ -292,7 +311,10 @@ if ([string]::IsNullOrWhiteSpace($rendered)) {
 Write-Output $rendered
 `;
 
-    const result = runPowerShellCommand(script);
+    const result = await powerShellRunner(script, {
+      timeout: POWER_SHELL_TIMEOUT_MS,
+      maxBuffer: POWER_SHELL_MAX_BUFFER_BYTES,
+    });
     if (!result.ok) {
       const detail = normalizeText(result.stderr) || normalizeText(result.stdout) || result.reason;
       return {
@@ -328,15 +350,22 @@ function estimateImageRows(image: ImagePayload, maxWidthCells: number): number {
 }
 
 function parseImagePreviewDetails(value: unknown): ImagePreviewDetails | null {
-  const record = toRecord(value);
-  const itemsRaw = record.items;
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const itemsRaw = value.items;
   if (!Array.isArray(itemsRaw)) {
     return null;
   }
 
   const items: ImagePreviewItem[] = [];
   for (const raw of itemsRaw) {
-    const itemRecord = toRecord(raw);
+    if (!isRecord(raw)) {
+      continue;
+    }
+
+    const itemRecord = raw;
     const protocol = itemRecord.protocol === "sixel" ? "sixel" : "native";
     const mimeType = typeof itemRecord.mimeType === "string" ? itemRecord.mimeType : "image/png";
     const rows =
@@ -378,47 +407,93 @@ function parseImagePreviewDetails(value: unknown): ImagePreviewDetails | null {
   return { items };
 }
 
-export type BuildPreviewItemsOptions = TerminalImageWidthOptions;
+export type BuildPreviewItemsOptions = TerminalImageWidthOptions & {
+  environment?: NodeJS.ProcessEnv;
+  logger?: DebugLogger;
+  platform?: NodeJS.Platform;
+  sixelProcessRunner?: SixelProcessRunner;
+  sixelPowerShellRunner?: SixelPowerShellRunner;
+};
 
-export function buildPreviewItems(
+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 = {},
-): ImagePreviewItem[] {
+): Promise<ImagePreviewItem[]> {
   const selectedImages = images.slice(0, MAX_IMAGES_PER_MESSAGE);
   if (selectedImages.length === 0) {
     return [];
   }
 
   const maxWidthCells = resolveTerminalImageWidthCells(options);
-  const attemptSixel = shouldAttemptSixelRendering();
-  const sixelState = attemptSixel ? ensureSixelModuleAvailable() : undefined;
+  const platform = options.platform ?? process.platform;
+  const processRunner = options.sixelProcessRunner ?? runBufferedCommand;
+  const powerShellRunner = options.sixelPowerShellRunner ?? runPowerShellCommandAsync;
+  const attemptSixel = shouldAttemptSixelRendering(options.environment, platform);
+  const sixelState = attemptSixel
+    ? await ensureSixelConverterAvailable(false, platform, processRunner, powerShellRunner)
+    : undefined;
+
+  logSixelEvent(options.logger, "image-preview.sixel.detected", {
+    attemptSixel,
+    available: sixelState?.available ?? false,
+    converter: sixelState?.converter ?? null,
+    reason: sixelState?.reason ?? null,
+    platform,
+  });
 
-  return selectedImages.map((image) => {
+  const items: ImagePreviewItem[] = [];
+  for (const image of selectedImages) {
     const rows = estimateImageRows(image, maxWidthCells);
 
-    if (attemptSixel && sixelState?.available) {
-      const conversion = convertImageToSixelSequence(image);
+    if (attemptSixel && sixelState?.available && sixelState.converter) {
+      const conversion = await convertImageToSixelSequence(image, sixelState.converter, processRunner, powerShellRunner);
       if (conversion.sequence) {
-        return {
+        logSixelEvent(options.logger, "image-preview.sixel.converted", {
+          converter: sixelState.converter,
+          mimeType: image.mimeType,
+          rows,
+          maxWidthCells,
+        });
+        items.push({
           protocol: "sixel",
           mimeType: image.mimeType,
           rows,
           maxWidthCells,
           sixelSequence: conversion.sequence,
-        };
+        });
+        continue;
       }
 
-      return {
+      logSixelEvent(options.logger, "image-preview.sixel.conversion_failed", {
+        converter: sixelState.converter,
+        mimeType: image.mimeType,
+        error: conversion.error ?? "unknown",
+      });
+
+      items.push({
         protocol: "native",
         mimeType: image.mimeType,
         rows,
         maxWidthCells,
         data: image.data,
         warning: conversion.error,
-      };
+      });
+      continue;
     }
 
-    return {
+    items.push({
       protocol: "native",
       mimeType: image.mimeType,
       rows,
@@ -426,13 +501,34 @@ export function buildPreviewItems(
       data: image.data,
       warning:
         attemptSixel && sixelState && !sixelState.available
-          ? `Sixel preview unavailable: ${sixelState.reason || "missing PowerShell Sixel module."}`
+          ? `Sixel preview unavailable: ${sixelState.reason || "missing Sixel converter."}`
           : undefined,
-    };
-  });
+    });
+  }
+
+  return items;
+}
+
+export interface RegisterImagePreviewDisplayOptions {
+  logger?: DebugLogger;
 }
 
-export function registerImagePreviewDisplay(pi: ExtensionAPI): void {
+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 = {},
+): void {
   let warnedSixelSetup = false;
 
   pi.registerMessageRenderer<ImagePreviewDetails>(
@@ -481,17 +577,21 @@ export function registerImagePreviewDisplay(pi: ExtensionAPI): void {
   );
 
   pi.on("session_start", async (_event, ctx) => {
-    if (!shouldAttemptSixelRendering()) {
-      return;
-    }
+    try {
+      if (!shouldAttemptSixelRendering()) {
+        return;
+      }
 
-    const availability = ensureSixelModuleAvailable();
-    if (!availability.available && !warnedSixelSetup && ctx.hasUI) {
-      warnedSixelSetup = true;
-      ctx.ui.notify(
-        `Image preview fallback active: ${availability.reason || "Sixel module unavailable."}`,
-        "warning",
-      );
+      const availability = await ensureSixelConverterAvailable();
+      if (!availability.available && !warnedSixelSetup && ctx.hasUI) {
+        warnedSixelSetup = true;
+        ctx.ui.notify(
+          `Image preview fallback active: ${availability.reason || "Sixel module unavailable."}`,
+          "warning",
+        );
+      }
+    } catch (error) {
+      logPreviewHandlerError(options.logger, "image-preview.session_start_failed", error);
     }
   });
 }

package/src/image-size.ts

@@ -0,0 +1,63 @@
+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);
+}
+