pi-image-tools 1.3.0 → 1.4.0

package/src/keybindings.ts

@@ -72,49 +72,51 @@ const LEGACY_KEYBINDING_NAME_MIGRATIONS: Record<string, string> = {
   deleteSessionNoninvasive: "app.session.deleteNoninvasive",
 };
 
-const APP_KEYBINDING_DEFAULTS: KeybindingDefaults = {
-  "app.interrupt": "escape",
-  "app.clear": "ctrl+c",
-  "app.exit": "ctrl+d",
-  "app.suspend": process.platform === "win32" ? [] : "ctrl+z",
-  "app.thinking.cycle": "shift+tab",
-  "app.model.cycleForward": "ctrl+p",
-  "app.model.cycleBackward": "shift+ctrl+p",
-  "app.model.select": "ctrl+l",
-  "app.tools.expand": "ctrl+o",
-  "app.thinking.toggle": "ctrl+t",
-  "app.session.toggleNamedFilter": "ctrl+n",
-  "app.editor.external": "ctrl+g",
-  "app.message.followUp": "alt+enter",
-  "app.message.dequeue": "alt+up",
-  "app.clipboard.pasteImage": process.platform === "win32" ? "alt+v" : "ctrl+v",
-  "app.session.new": [],
-  "app.session.tree": [],
-  "app.session.fork": [],
-  "app.session.resume": [],
-  "app.tree.foldOrUp": ["ctrl+left", "alt+left"],
-  "app.tree.unfoldOrDown": ["ctrl+right", "alt+right"],
-  "app.tree.editLabel": "shift+l",
-  "app.tree.toggleLabelTimestamp": "shift+t",
-  "app.session.togglePath": "ctrl+p",
-  "app.session.toggleSort": "ctrl+s",
-  "app.session.rename": "ctrl+r",
-  "app.session.delete": "ctrl+d",
-  "app.session.deleteNoninvasive": "ctrl+backspace",
-  "app.models.save": "ctrl+s",
-  "app.models.enableAll": "ctrl+a",
-  "app.models.clearAll": "ctrl+x",
-  "app.models.toggleProvider": "ctrl+p",
-  "app.models.reorderUp": "alt+up",
-  "app.models.reorderDown": "alt+down",
-  "app.tree.filter.default": "ctrl+d",
-  "app.tree.filter.noTools": "ctrl+t",
-  "app.tree.filter.userOnly": "ctrl+u",
-  "app.tree.filter.labeledOnly": "ctrl+l",
-  "app.tree.filter.all": "ctrl+a",
-  "app.tree.filter.cycleForward": "ctrl+o",
-  "app.tree.filter.cycleBackward": "shift+ctrl+o",
-};
+function getAppKeybindingDefaults(platform: NodeJS.Platform): KeybindingDefaults {
+  return {
+    "app.interrupt": "escape",
+    "app.clear": "ctrl+c",
+    "app.exit": "ctrl+d",
+    "app.suspend": platform === "win32" ? [] : "ctrl+z",
+    "app.thinking.cycle": "shift+tab",
+    "app.model.cycleForward": "ctrl+p",
+    "app.model.cycleBackward": "shift+ctrl+p",
+    "app.model.select": "ctrl+l",
+    "app.tools.expand": "ctrl+o",
+    "app.thinking.toggle": "ctrl+t",
+    "app.session.toggleNamedFilter": "ctrl+n",
+    "app.editor.external": "ctrl+g",
+    "app.message.followUp": "alt+enter",
+    "app.message.dequeue": "alt+up",
+    "app.clipboard.pasteImage": platform === "win32" ? "alt+v" : "ctrl+v",
+    "app.session.new": [],
+    "app.session.tree": [],
+    "app.session.fork": [],
+    "app.session.resume": [],
+    "app.tree.foldOrUp": ["ctrl+left", "alt+left"],
+    "app.tree.unfoldOrDown": ["ctrl+right", "alt+right"],
+    "app.tree.editLabel": "shift+l",
+    "app.tree.toggleLabelTimestamp": "shift+t",
+    "app.session.togglePath": "ctrl+p",
+    "app.session.toggleSort": "ctrl+s",
+    "app.session.rename": "ctrl+r",
+    "app.session.delete": "ctrl+d",
+    "app.session.deleteNoninvasive": "ctrl+backspace",
+    "app.models.save": "ctrl+s",
+    "app.models.enableAll": "ctrl+a",
+    "app.models.clearAll": "ctrl+x",
+    "app.models.toggleProvider": "ctrl+p",
+    "app.models.reorderUp": "alt+up",
+    "app.models.reorderDown": "alt+down",
+    "app.tree.filter.default": "ctrl+d",
+    "app.tree.filter.noTools": "ctrl+t",
+    "app.tree.filter.userOnly": "ctrl+u",
+    "app.tree.filter.labeledOnly": "ctrl+l",
+    "app.tree.filter.all": "ctrl+a",
+    "app.tree.filter.cycleForward": "ctrl+o",
+    "app.tree.filter.cycleBackward": "shift+ctrl+o",
+  };
+}
 
 export interface RegisterImagePasteKeybindingsOptions {
   config: ImageToolsConfig;
@@ -186,7 +188,7 @@ function normalizeUserKeybindings(rawConfig: Record<string, unknown> | undefined
   return userKeybindings;
 }
 
-function getBuiltinKeybindingDefaults(): KeybindingDefaults {
+function getBuiltinKeybindingDefaults(platform: NodeJS.Platform): KeybindingDefaults {
   const tuiDefaults: KeybindingDefaults = {};
   for (const [keybinding, definition] of Object.entries(TUI_KEYBINDINGS)) {
     tuiDefaults[keybinding] = definition.defaultKeys;
@@ -194,12 +196,12 @@ function getBuiltinKeybindingDefaults(): KeybindingDefaults {
 
   return {
     ...tuiDefaults,
-    ...APP_KEYBINDING_DEFAULTS,
+    ...getAppKeybindingDefaults(platform),
   };
 }
 
-function getConfiguredBuiltinShortcuts(): Set<string> {
-  const defaults = getBuiltinKeybindingDefaults();
+function getConfiguredBuiltinShortcuts(platform: NodeJS.Platform): Set<string> {
+  const defaults = getBuiltinKeybindingDefaults(platform);
   const userKeybindings = normalizeUserKeybindings(readKeybindingsConfig());
   const builtinShortcuts = new Set<string>();
 
@@ -224,8 +226,8 @@ function getImagePasteShortcutCandidates(platform: NodeJS.Platform): KeyId[] {
   return ["ctrl+v", "alt+v", "ctrl+alt+v"];
 }
 
-function removeBuiltinConflicts(shortcuts: readonly KeyId[]): KeyId[] {
-  const builtinShortcuts = getConfiguredBuiltinShortcuts();
+function removeBuiltinConflicts(shortcuts: readonly KeyId[], platform: NodeJS.Platform): KeyId[] {
+  const builtinShortcuts = getConfiguredBuiltinShortcuts(platform);
 
   return shortcuts.filter((shortcut) => !builtinShortcuts.has(normalizeShortcutKey(shortcut)));
 }
@@ -238,7 +240,7 @@ export function getImagePasteShortcuts(
     config.shortcuts.avoidBuiltinConflicts || config.shortcuts.suppressBuiltinConflictWarnings;
   const candidates = config.shortcuts.pasteImage ?? getImagePasteShortcutCandidates(platform);
 
-  return shouldAvoidBuiltinConflicts ? removeBuiltinConflicts(candidates) : [...candidates];
+  return shouldAvoidBuiltinConflicts ? removeBuiltinConflicts(candidates, platform) : [...candidates];
 }
 
 export function registerImagePasteKeybindings(

package/src/powershell.ts

@@ -31,6 +31,8 @@ export interface RunPowerShellCommandOptions {
   timeout: number;
 }
 
+const ALLOWED_BUFFERED_COMMANDS = new Set(["img2sixel", "powershell", "powershell.exe"]);
+
 function encodePowerShell(script: string): string {
   return Buffer.from(script, "utf16le").toString("base64");
 }
@@ -41,9 +43,20 @@ export function runBufferedCommand(
   options: RunBufferedCommandOptions,
 ): Promise<BufferedCommandResult> {
   return new Promise((resolve) => {
+    const normalizedCommand = command.trim().toLowerCase();
+    if (!ALLOWED_BUFFERED_COMMANDS.has(normalizedCommand)) {
+      resolve({
+        status: null,
+        stdout: Buffer.alloc(0),
+        stderr: Buffer.from(`Command is not allowlisted for pi-image-tools buffered execution: ${command}`),
+        error: new Error(`Command is not allowlisted for pi-image-tools buffered execution: ${command}`),
+      });
+      return;
+    }
+
     let child: ReturnType<typeof spawn>;
     try {
-      child = spawn(command, [...args], {
+      child = spawn(command, [...args], { // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- command is checked against ALLOWED_BUFFERED_COMMANDS immediately above; args are fixed by Sixel/Image preview code and shell is disabled.
         windowsHide: options.windowsHide,
       });
     } catch (error) {
@@ -124,27 +137,68 @@ export function runBufferedCommand(
   });
 }
 
-export function runPowerShellCommand(
+const POWERSHELL_NON_WINDOWS_REASON = "PowerShell is only available through pi-image-tools on Windows.";
+
+function nonWindowsPowerShellResult(): PowerShellCommandResult {
+  return {
+    ok: false,
+    stdout: "",
+    stderr: "",
+    missingCommand: false,
+    reason: POWERSHELL_NON_WINDOWS_REASON,
+  };
+}
+
+function buildPowerShellCommandArgs(
   script: string,
   options: RunPowerShellCommandOptions,
-): PowerShellCommandResult {
-  if (process.platform !== "win32") {
-    return {
-      ok: false,
-      stdout: "",
-      stderr: "",
-      missingCommand: false,
-      reason: "PowerShell is only available through pi-image-tools on Windows.",
-    };
-  }
-
-  const commandArgs = [
+): string[] {
+  return [
     "-NoProfile",
     "-NonInteractive",
     ...(options.sta ? ["-STA"] : []),
     ...(options.encoded ? ["-EncodedCommand", encodePowerShell(script)] : ["-Command", script]),
     ...(options.args ?? []),
   ];
+}
+
+function buildPowerShellResultFromError(
+  error: Error,
+  stdout: string,
+  stderr: string,
+): PowerShellCommandResult {
+  return {
+    ok: false,
+    stdout,
+    stderr,
+    missingCommand: isErrnoException(error) && error.code === "ENOENT",
+    reason: getErrorMessage(error),
+  };
+}
+
+function buildPowerShellResultFromStatus(
+  status: number | null,
+  stdout: string,
+  stderr: string,
+): PowerShellCommandResult {
+  return {
+    ok: status === 0,
+    stdout,
+    stderr,
+    missingCommand: false,
+    reason: status === 0 ? undefined : `PowerShell exited with code ${status}`,
+  };
+}
+
+export function runPowerShellCommand(
+  script: string,
+  options: RunPowerShellCommandOptions,
+): PowerShellCommandResult {
+  if (process.platform !== "win32") {
+    return nonWindowsPowerShellResult();
+  }
+
+  const commandArgs = buildPowerShellCommandArgs(script, options);
 
   const result = spawnSync("powershell.exe", commandArgs, {
     encoding: "utf8",
@@ -154,22 +208,18 @@ export function runPowerShellCommand(
   });
 
   if (result.error) {
-    return {
-      ok: false,
-      stdout: result.stdout ?? "",
-      stderr: result.stderr ?? "",
-      missingCommand: isErrnoException(result.error) && result.error.code === "ENOENT",
-      reason: getErrorMessage(result.error),
-    };
+    return buildPowerShellResultFromError(
+      result.error,
+      result.stdout ?? "",
+      result.stderr ?? "",
+    );
   }
 
-  return {
-    ok: result.status === 0,
-    stdout: result.stdout ?? "",
-    stderr: result.stderr ?? "",
-    missingCommand: false,
-    reason: result.status === 0 ? undefined : `PowerShell exited with code ${result.status}`,
-  };
+  return buildPowerShellResultFromStatus(
+    result.status,
+    result.stdout ?? "",
+    result.stderr ?? "",
+  );
 }
 
 export async function runPowerShellCommandAsync(
@@ -177,22 +227,10 @@ export async function runPowerShellCommandAsync(
   options: RunPowerShellCommandOptions,
 ): Promise<PowerShellCommandResult> {
   if (process.platform !== "win32") {
-    return {
-      ok: false,
-      stdout: "",
-      stderr: "",
-      missingCommand: false,
-      reason: "PowerShell is only available through pi-image-tools on Windows.",
-    };
+    return nonWindowsPowerShellResult();
   }
 
-  const commandArgs = [
-    "-NoProfile",
-    "-NonInteractive",
-    ...(options.sta ? ["-STA"] : []),
-    ...(options.encoded ? ["-EncodedCommand", encodePowerShell(script)] : ["-Command", script]),
-    ...(options.args ?? []),
-  ];
+  const commandArgs = buildPowerShellCommandArgs(script, options);
 
   const result = await runBufferedCommand("powershell.exe", commandArgs, {
     timeout: options.timeout,
@@ -203,20 +241,8 @@ export async function runPowerShellCommandAsync(
   const stderr = result.stderr.toString("utf8");
 
   if (result.error) {
-    return {
-      ok: false,
-      stdout,
-      stderr,
-      missingCommand: isErrnoException(result.error) && result.error.code === "ENOENT",
-      reason: getErrorMessage(result.error),
-    };
+    return buildPowerShellResultFromError(result.error, stdout, stderr);
   }
 
-  return {
-    ok: result.status === 0,
-    stdout,
-    stderr,
-    missingCommand: false,
-    reason: result.status === 0 ? undefined : `PowerShell exited with code ${result.status}`,
-  };
+  return buildPowerShellResultFromStatus(result.status, stdout, stderr);
 }

package/src/preview-logging.ts

@@ -0,0 +1,28 @@
+import type { DebugLogger } from "./debug-logger.js";
+import { getErrorMessage } from "./errors.js";
+
+/**
+ * Best-effort debug logging for Pi preview code.
+ *
+ * `DebugLogger.log` already swallows its own failures, and `getErrorMessage`
+ * never throws, so callers need no try/catch guard. Consolidating the call
+ * here keeps both preview renderers consistent and avoids duplicated guards.
+ */
+export function logPreviewEvent(
+  logger: DebugLogger | undefined,
+  event: string,
+  fields: Record<string, unknown> = {},
+): void {
+  logger?.log(event, fields);
+}
+
+/**
+ * Best-effort debug logging for a caught error inside a Pi event handler.
+ */
+export function logPreviewHandlerError(
+  logger: DebugLogger | undefined,
+  event: string,
+  error: unknown,
+): void {
+  logPreviewEvent(logger, event, { error: getErrorMessage(error) });
+}

package/src/providers/command-runner.ts

@@ -1,68 +1,86 @@
-import { spawnSync } from "node:child_process";
-
-import { isErrnoException } from "../errors.js";
-
-export const LIST_TYPES_TIMEOUT_MS = 1000;
-export const READ_TIMEOUT_MS = 5000;
-export const MAX_BUFFER_BYTES = 50 * 1024 * 1024;
-
-export interface CommandResult {
-  ok: boolean;
-  stdout: Buffer;
-  stderr: Buffer;
-  missingCommand: boolean;
-  status: number | null;
-}
-
-export interface CommandRunOptions {
-  environment?: NodeJS.ProcessEnv;
-  maxBuffer?: number;
-  timeout: number;
-  windowsHide?: boolean;
-}
-
-export type CommandRunner = (
-  command: string,
-  args: readonly string[],
-  options: CommandRunOptions,
-) => CommandResult;
-
-function toBuffer(value: unknown): Buffer {
-  if (Buffer.isBuffer(value)) {
-    return value;
-  }
-
-  if (value instanceof Uint8Array) {
-    return Buffer.from(value);
-  }
-
-  return Buffer.from(value === undefined || value === null ? "" : String(value), "utf8");
-}
-
-export const defaultCommandRunner: CommandRunner = (command, args, options) => {
-  const result = spawnSync(command, [...args], {
-    env: options.environment,
-    maxBuffer: options.maxBuffer ?? MAX_BUFFER_BYTES,
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: options.timeout,
-    windowsHide: options.windowsHide,
-  });
-
-  if (result.error) {
-    return {
-      ok: false,
-      stdout: toBuffer(result.stdout),
-      stderr: toBuffer(result.stderr),
-      missingCommand: isErrnoException(result.error) && result.error.code === "ENOENT",
-      status: result.status ?? null,
-    };
-  }
-
-  return {
-    ok: result.status === 0,
-    stdout: toBuffer(result.stdout),
-    stderr: toBuffer(result.stderr),
-    missingCommand: false,
-    status: result.status ?? null,
-  };
-};
+import { spawnSync } from "node:child_process";
+
+import { isErrnoException } from "../errors.js";
+
+export const LIST_TYPES_TIMEOUT_MS = 1000;
+export const READ_TIMEOUT_MS = 5000;
+export const MAX_BUFFER_BYTES = 50 * 1024 * 1024;
+
+const ALLOWED_CLIPBOARD_COMMANDS = new Set([
+  "osascript",
+  "pngpaste",
+  "reattach-to-user-namespace",
+  "wl-paste",
+  "xclip",
+]);
+
+export interface CommandResult {
+  ok: boolean;
+  stdout: Buffer;
+  stderr: Buffer;
+  missingCommand: boolean;
+  status: number | null;
+}
+
+export interface CommandRunOptions {
+  environment?: NodeJS.ProcessEnv;
+  maxBuffer?: number;
+  timeout: number;
+  windowsHide?: boolean;
+}
+
+export type CommandRunner = (
+  command: string,
+  args: readonly string[],
+  options: CommandRunOptions,
+) => CommandResult;
+
+function toBuffer(value: unknown): Buffer {
+  if (Buffer.isBuffer(value)) {
+    return value;
+  }
+
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value);
+  }
+
+  return Buffer.from(value === undefined || value === null ? "" : String(value), "utf8");
+}
+
+export const defaultCommandRunner: CommandRunner = (command, args, options) => {
+  if (!ALLOWED_CLIPBOARD_COMMANDS.has(command.trim().toLowerCase())) {
+    return {
+      ok: false,
+      stdout: Buffer.alloc(0),
+      stderr: Buffer.from(`Command is not allowlisted for clipboard image providers: ${command}`),
+      missingCommand: false,
+      status: null,
+    };
+  }
+
+  const result = spawnSync(command, [...args], { // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- command is checked against ALLOWED_CLIPBOARD_COMMANDS immediately above; provider args are fixed arrays and shell is disabled.
+    env: options.environment,
+    maxBuffer: options.maxBuffer ?? MAX_BUFFER_BYTES,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: options.timeout,
+    windowsHide: options.windowsHide,
+  });
+
+  if (result.error) {
+    return {
+      ok: false,
+      stdout: toBuffer(result.stdout),
+      stderr: toBuffer(result.stderr),
+      missingCommand: isErrnoException(result.error) && result.error.code === "ENOENT",
+      status: result.status ?? null,
+    };
+  }
+
+  return {
+    ok: result.status === 0,
+    stdout: toBuffer(result.stdout),
+    stderr: toBuffer(result.stderr),
+    missingCommand: false,
+    status: result.status ?? null,
+  };
+};

package/src/providers/mac-osascript-pngf.ts

@@ -1,11 +1,4 @@
-import { buildNamespaceWrappedCommand, defaultCommandExists, type CommandExists } from "../shell-environment.js";
-import {
-  defaultCommandRunner,
-  MAX_BUFFER_BYTES,
-  READ_TIMEOUT_MS,
-  type CommandRunner,
-} from "./command-runner.js";
-import type { ClipboardImageProvider, ClipboardProviderContext, ClipboardReadResult } from "./types.js";
+import { NamespacedCommandProvider, providerEmptyImage, providerImageResult, type ClipboardReadResult, type CommandExists, type CommandResult, type CommandRunner } from "./provider-helpers.js";
 
 const PNGF_SCRIPT = `try
   set imageData to the clipboard as «class PNGf»
@@ -40,62 +33,30 @@ function parseAppleScriptPngfData(stdout: Buffer): Uint8Array | null {
   return bytes.length > 0 ? new Uint8Array(bytes) : null;
 }
 
-export class OsascriptPngfProvider implements ClipboardImageProvider {
-  readonly capabilities;
-  private readonly commandRunner: CommandRunner;
-  private readonly commandExists: CommandExists;
-
+export class OsascriptPngfProvider extends NamespacedCommandProvider {
   constructor(options: OsascriptPngfProviderOptions = {}) {
-    this.capabilities = {
-      id: "mac-osascript-pngf",
-      name: "osascript PNGf",
-      platforms: ["darwin"],
-      priority: options.priority ?? 30,
-    };
-    this.commandRunner = options.commandRunner ?? defaultCommandRunner;
-    this.commandExists = options.commandExists ?? defaultCommandExists;
-  }
-
-  isAvailable(context: ClipboardProviderContext): boolean {
-    try {
-      return this.commandExists("osascript", context);
-    } catch {
-      return false;
-    }
-  }
-
-  read(context: ClipboardProviderContext): ClipboardReadResult {
-    const wrapped = buildNamespaceWrappedCommand(
+    super(
+      {
+        id: "mac-osascript-pngf",
+        name: "osascript PNGf",
+        platforms: ["darwin"],
+        priority: options.priority ?? 30,
+      },
       "osascript",
-      ["-e", PNGF_SCRIPT],
-      context,
-      this.commandExists,
+      options,
     );
-    const result = this.commandRunner(wrapped.command, wrapped.args, {
-      environment: context.environment,
-      maxBuffer: MAX_BUFFER_BYTES,
-      timeout: READ_TIMEOUT_MS,
-    });
-
-    if (result.missingCommand) {
-      return { available: false, image: null };
-    }
+  }
 
-    if (!result.ok || result.stdout.length === 0) {
-      return { available: true, image: null };
-    }
+  protected buildArgs(): readonly string[] {
+    return ["-e", PNGF_SCRIPT];
+  }
 
+  protected readFromResult(result: CommandResult): ClipboardReadResult {
     const bytes = parseAppleScriptPngfData(result.stdout);
     if (!bytes) {
-      return { available: true, image: null };
+      return providerEmptyImage();
     }
 
-    return {
-      available: true,
-      image: {
-        bytes,
-        mimeType: "image/png",
-      },
-    };
+    return providerImageResult(bytes, "image/png");
   }
 }