pi-image-tools 1.0.11 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [1.2.0] - 2026-05-22
+
+### Added
+- Added Linux Sixel previews through `img2sixel` detection and conversion when the converter is available on `PATH`.
+- Added asynchronous image preview conversion so user-message previews can fall back without blocking the TUI.
+
+### Changed
+- Updated Pi peer dependencies and runtime imports to the `@earendil-works` scope.
+- Improved preview setup diagnostics so missing Sixel converters report actionable fallback warnings.
+
+### Fixed
+- Hardened debug logging with redaction and asynchronous file writes while keeping logging disabled by default.
+
+## [1.1.0] - 2026-05-03
+
+### Added
+- Added centralized image MIME, image-size, PowerShell, and error utilities used by clipboard, preview, attachment, and recent-image flows.
+- Added size-limit enforcement for image attachments, recent-cache writes, recent-image loads, and Sixel preview conversion through `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES`.
+
+### Changed
+- Reworked recent-image caching to use an extension-owned cache directory with safe pruning that preserves user files.
+- Reworked Sixel preview rendering to use an existing PowerShell `Sixel` module only, normalize converter output into complete terminal sequences, and fall back to native previews with actionable warnings.
+- Reworked terminal image width resolution to honor Pi project/global `terminal.imageWidthCells` settings with a documented default fallback.
+
+### Fixed
+- Prevented extension debug logging from writing terminal output; debug events now remain file-based and disabled by default.
+- Preserved Sixel, Kitty, and iTerm inline image protocol rows during preview width fitting.
+
 ## [1.0.11] - 2026-04-25
 
 ### Changed

package/README.md

@@ -114,6 +114,7 @@ Pi's built-in image paste shortcut is not overridden by default. To keep the pre
 |----------|-------------|---------|
 | `PI_IMAGE_TOOLS_RECENT_DIRS` | Semicolon-separated directories to search for recent images | Platform defaults listed below |
 | `PI_IMAGE_TOOLS_RECENT_CACHE_DIR` | Custom cache directory for clipboard-pasted images | OS temp dir + `pi-image-tools/recent-cache` |
+| `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES` | Maximum accepted image payload size before attachment, recent-cache writes, and preview conversion | `20971520` (20 MB) |
 
 Example:
 
@@ -254,8 +255,10 @@ When you queue one or more images, the extension renders an inline preview insid
 
 Preview behavior:
 - up to **3 images** are previewed per message
-- Sixel rendering is attempted on Windows when available
+- Sixel rendering is attempted on Windows when the PowerShell `Sixel` module is already installed and on Linux when `img2sixel` is available on `PATH`
+- no PowerShell modules or Linux packages are installed automatically at runtime
 - native TUI image rendering is used as the fallback
+- image payloads over `PI_IMAGE_TOOLS_MAX_IMAGE_BYTES` are rejected before attachment, recent-cache writes, or Sixel conversion
 - inline width fitting now preserves Sixel, Kitty, and iTerm image protocol rows instead of truncating them like plain text
 
 ### Clipboard readers
@@ -285,11 +288,16 @@ pi-image-tools/
 │   ├── clipboard.ts            # Cross-platform clipboard image reading
 │   ├── config.ts               # Runtime config loading and validation
 │   ├── debug-logger.ts         # File-based debug logging
+│   ├── errors.ts               # Shared error normalization
+│   ├── image-mime.ts           # Shared image MIME and extension mapping
+│   ├── image-size.ts           # Shared image byte-size limits
 │   ├── recent-images.ts        # Recent image discovery and cache management
 │   ├── image-preview.ts        # Preview building and Sixel/native rendering
 │   ├── inline-user-preview.ts  # Inline preview patching for user messages
 │   ├── keybindings.ts          # Keyboard shortcut registration
-│   ├── temp-file.ts            # Temporary file management and cleanup
+│   ├── powershell.ts           # Shared PowerShell command runner
+│   ├── sixel-protocol.ts       # Sixel protocol normalization and render lines
+│   ├── terminal-image-width.ts # Terminal image width settings resolution
 │   └── types.ts                # Shared TypeScript types
 └── config/
     └── config.example.json     # Starter runtime config
@@ -303,9 +311,14 @@ pi-image-tools/
 | Linux clipboard paste fails | Make sure you are in a graphical session and install `wl-clipboard` or `xclip` |
 | Recent picker is empty | Add directories via `PI_IMAGE_TOOLS_RECENT_DIRS` or paste images from clipboard first so they enter the recent cache |
 | `/paste-image recent` says it requires interactive mode | Run Pi in interactive TUI mode |
-| Sixel preview warning appears | On Windows, install the PowerShell `Sixel` module and restart Pi |
+| Sixel preview warning appears | On Linux, install `img2sixel` (for example from `libsixel-bin`); on Windows, install the PowerShell `Sixel` module and restart Pi |
 
-Manual Sixel installation:
+Manual Sixel installation examples:
+
+```bash
+# Debian/Ubuntu
+sudo apt install libsixel-bin
+```
 
 ```powershell
 Install-Module -Name Sixel -Scope CurrentUser -Force -AllowClobber

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-image-tools",
-  "version": "1.0.11",
+  "version": "1.2.0",
   "description": "Image attachment and rendering extension for Pi TUI",
   "type": "module",
   "main": "./index.ts",
@@ -16,10 +16,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
+    "typecheck": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noEmit",
+    "build": "npm run typecheck",
+    "lint": "npm run typecheck",
     "test": "node --test",
-    "check": "npm run lint && npm run test"
+    "check": "npm run build && npm run test"
   },
   "keywords": [
     "pi-package",
@@ -33,7 +34,9 @@
     "image-preview",
     "clipboard",
     "preview",
-    "windows"
+    "windows",
+    "linux",
+    "cross-platform"
   ],
   "author": "MasuRii",
   "license": "MIT",
@@ -57,10 +60,10 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.70.2",
-    "@mariozechner/pi-tui": "^0.70.2"
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@earendil-works/pi-tui": "^0.75.4"
   },
   "optionalDependencies": {
-    "@mariozechner/clipboard": "^0.3.3"
+    "@mariozechner/clipboard": "^0.3.6"
   }
 }

package/src/clipboard.ts

@@ -1,6 +1,9 @@
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
 
+import { isErrnoException } from "./errors.js";
+import { normalizeMimeType, selectPreferredImageMimeType, SUPPORTED_IMAGE_MIME_TYPES } from "./image-mime.js";
+import { runPowerShellCommand } from "./powershell.js";
 import type { ClipboardImage, ClipboardModule } from "./types.js";
 
 const require = createRequire(import.meta.url);
@@ -8,14 +11,6 @@ const require = createRequire(import.meta.url);
 const LIST_TYPES_TIMEOUT_MS = 1000;
 const READ_TIMEOUT_MS = 5000;
 const MAX_BUFFER_BYTES = 50 * 1024 * 1024;
-const SUPPORTED_IMAGE_MIME_TYPES = [
-  "image/png",
-  "image/jpeg",
-  "image/webp",
-  "image/gif",
-  "image/bmp",
-] as const;
-
 let cachedClipboardModule: ClipboardModule | null | undefined;
 
 interface CommandResult {
@@ -29,11 +24,7 @@ interface ClipboardReadResult {
   image: ClipboardImage | null;
 }
 
-function isErrnoException(error: Error): error is NodeJS.ErrnoException {
-  return "code" in error;
-}
-
-function hasGraphicalSession(platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): boolean {
+export function hasGraphicalSession(platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): boolean {
   return platform !== "linux" || Boolean(environment.DISPLAY || environment.WAYLAND_DISPLAY);
 }
 
@@ -41,27 +32,6 @@ function isWaylandSession(environment: NodeJS.ProcessEnv): boolean {
   return Boolean(environment.WAYLAND_DISPLAY) || environment.XDG_SESSION_TYPE === "wayland";
 }
 
-function normalizeMimeType(mimeType: string): string {
-  return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-}
-
-function selectPreferredImageMimeType(mimeTypes: readonly string[]): string | null {
-  const normalized = mimeTypes
-    .map((mimeType) => mimeType.trim())
-    .filter((mimeType) => mimeType.length > 0)
-    .map((mimeType) => ({ raw: mimeType, normalized: normalizeMimeType(mimeType) }));
-
-  for (const preferredMimeType of SUPPORTED_IMAGE_MIME_TYPES) {
-    const match = normalized.find((mimeType) => mimeType.normalized === preferredMimeType);
-    if (match) {
-      return match.raw;
-    }
-  }
-
-  const firstImage = normalized.find((mimeType) => mimeType.normalized.startsWith("image/"));
-  return firstImage?.raw ?? null;
-}
-
 function loadClipboardModule(
   platform: NodeJS.Platform = process.platform,
   environment: NodeJS.ProcessEnv = process.env,
@@ -141,10 +111,6 @@ function runCommand(
   };
 }
 
-function encodePowerShell(script: string): string {
-  return Buffer.from(script, "utf16le").toString("base64");
-}
-
 function readClipboardImageViaPowerShell(): ClipboardReadResult {
   const script = `
 $ErrorActionPreference = 'Stop'
@@ -170,33 +136,18 @@ try {
 }
 `;
 
-  const result = spawnSync(
-    "powershell.exe",
-    [
-      "-NoProfile",
-      "-NonInteractive",
-      "-ExecutionPolicy",
-      "Bypass",
-      "-STA",
-      "-EncodedCommand",
-      encodePowerShell(script),
-    ],
-    {
-      encoding: "utf8",
-      timeout: READ_TIMEOUT_MS,
-      maxBuffer: MAX_BUFFER_BYTES,
-      windowsHide: true,
-    },
-  );
+  const result = runPowerShellCommand(script, {
+    encoded: true,
+    sta: true,
+    timeout: READ_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER_BYTES,
+  });
 
-  if (result.error) {
-    return {
-      available: !isErrnoException(result.error) || result.error.code !== "ENOENT",
-      image: null,
-    };
+  if (result.missingCommand) {
+    return { available: false, image: null };
   }
 
-  if (result.status !== 0) {
+  if (!result.ok) {
     return { available: true, image: null };
   }
 

package/src/commands.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import type { PasteImageCommandHandlers } from "./types.js";
 

package/src/config.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import type { KeyId } from "@mariozechner/pi-tui";
+import type { KeyId } from "@earendil-works/pi-tui";
 
 const CONFIG_FILE_NAME = "config.json";
 const EXTENSION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");

package/src/debug-logger.ts

@@ -1,30 +1,43 @@
-import { appendFileSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import { getExtensionRoot, type ImageToolsConfig } from "./config.js";
-
 const DEBUG_DIRECTORY_NAME = "debug";
 const DEBUG_LOG_FILE_NAME = "debug.log";
+const SECRET_KEYS = /api[_-]?key|authorization|token|secret|password/i;
 
 type DebugFields = Record<string, unknown>;
 
-function getErrorMessage(error: unknown): string {
-  if (error instanceof Error && error.message.trim().length > 0) {
-    return error.message;
-  }
+interface DebugLoggerCreateOptions {
+  extensionRoot?: string;
+}
 
-  return "Unknown error";
+function redactFields(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((entry) => redactFields(entry));
+  if (value && typeof value === "object") {
+    const output: Record<string, unknown> = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+      output[key] = SECRET_KEYS.test(key) ? "[REDACTED]" : redactFields(nestedValue);
+    }
+    return output;
+  }
+  return value;
 }
 
 export class DebugLogger {
+  private readonly debugDirectory: string | undefined;
   private readonly logPath: string | undefined;
+  private debugDirectoryReady = false;
+  private writeQueue: Promise<void> = Promise.resolve();
 
-  private constructor(private readonly enabled: boolean) {
-    this.logPath = enabled ? join(getExtensionRoot(), DEBUG_DIRECTORY_NAME, DEBUG_LOG_FILE_NAME) : undefined;
+  private constructor(private readonly enabled: boolean, extensionRoot = getExtensionRoot()) {
+    this.debugDirectory = enabled ? join(extensionRoot, DEBUG_DIRECTORY_NAME) : undefined;
+    this.logPath = this.debugDirectory ? join(this.debugDirectory, DEBUG_LOG_FILE_NAME) : undefined;
   }
 
-  static create(config: ImageToolsConfig): DebugLogger {
-    return new DebugLogger(config.debug);
+  static create(config: ImageToolsConfig, options: DebugLoggerCreateOptions = {}): DebugLogger {
+    return new DebugLogger(config.debug, options.extensionRoot);
   }
 
   log(event: string, fields: DebugFields = {}): void {
@@ -32,17 +45,38 @@ export class DebugLogger {
       return;
     }
 
-    const debugDirectory = join(getExtensionRoot(), DEBUG_DIRECTORY_NAME);
-
     try {
-      mkdirSync(debugDirectory, { recursive: true });
-      appendFileSync(
-        this.logPath,
-        `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...fields })}\n`,
-        "utf-8",
+      const redactedFields = redactFields(fields) as DebugFields;
+      const line = `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...redactedFields })}\n`;
+      this.writeQueue = this.writeQueue.then(
+        () => this.appendLine(line),
+        () => this.appendLine(line),
       );
-    } catch (error) {
-      throw new Error(`pi-image-tools debug logging failed at ${this.logPath}: ${getErrorMessage(error)}`);
+      void this.writeQueue.catch(() => undefined);
+    } catch {
+      // Debug logging must never affect extension behavior.
+    }
+  }
+
+  flush(): Promise<void> {
+    return this.writeQueue.catch(() => undefined);
+  }
+
+  private async appendLine(line: string): Promise<void> {
+    if (!this.logPath) {
+      return;
     }
+
+    this.ensureDebugDirectory();
+    await appendFile(this.logPath, line, "utf-8");
+  }
+
+  private ensureDebugDirectory(): void {
+    if (this.debugDirectoryReady || !this.debugDirectory) {
+      return;
+    }
+
+    mkdirSync(this.debugDirectory, { recursive: true });
+    this.debugDirectoryReady = true;
   }
 }

package/src/errors.ts

@@ -0,0 +1,11 @@
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  return "Unknown error";
+}
+
+export function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/src/image-mime.ts

@@ -0,0 +1,60 @@
+const PREFERRED_IMAGE_MIME_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+  "image/bmp",
+] as const;
+
+const MIME_TYPE_TO_EXTENSION = new Map<string, string>([
+  ["image/png", "png"],
+  ["image/jpeg", "jpg"],
+  ["image/webp", "webp"],
+  ["image/gif", "gif"],
+  ["image/bmp", "bmp"],
+  ["image/tiff", "tiff"],
+]);
+
+const EXTENSION_TO_MIME_TYPE = new Map<string, string>([
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".webp", "image/webp"],
+  [".gif", "image/gif"],
+  [".bmp", "image/bmp"],
+]);
+
+export const SUPPORTED_IMAGE_MIME_TYPES: readonly string[] = PREFERRED_IMAGE_MIME_TYPES;
+
+export function normalizeMimeType(mimeType: string): string {
+  return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
+}
+
+export function selectPreferredImageMimeType(mimeTypes: readonly string[]): string | null {
+  const normalized = mimeTypes
+    .map((mimeType) => mimeType.trim())
+    .filter((mimeType) => mimeType.length > 0)
+    .map((mimeType) => ({ raw: mimeType, normalized: normalizeMimeType(mimeType) }));
+
+  for (const preferredMimeType of SUPPORTED_IMAGE_MIME_TYPES) {
+    const match = normalized.find((mimeType) => mimeType.normalized === preferredMimeType);
+    if (match) {
+      return match.raw;
+    }
+  }
+
+  const firstImage = normalized.find((mimeType) => mimeType.normalized.startsWith("image/"));
+  return firstImage?.raw ?? null;
+}
+
+export function mimeTypeToExtension(mimeType: string, fallbackExtension = "png"): string {
+  return MIME_TYPE_TO_EXTENSION.get(normalizeMimeType(mimeType)) ?? fallbackExtension;
+}
+
+export function extensionToMimeType(fileNameOrExtension: string): string | null {
+  const extension = fileNameOrExtension.startsWith(".")
+    ? fileNameOrExtension.toLowerCase()
+    : `.${fileNameOrExtension.toLowerCase()}`;
+
+  return EXTENSION_TO_MIME_TYPE.get(extension) ?? null;
+}