pi-image-tools 1.3.1 → 1.4.0

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

@@ -6,6 +6,14 @@ 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;
@@ -40,7 +48,17 @@ function toBuffer(value: unknown): Buffer {
 }
 
 export const defaultCommandRunner: CommandRunner = (command, args, options) => {
-  const result = spawnSync(command, [...args], {
+  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"],

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

@@ -1,101 +1,62 @@
-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";
-
-const PNGF_SCRIPT = `try
-  set imageData to the clipboard as «class PNGf»
-  return imageData
-on error
-  return ""
-end try`;
-
-export interface OsascriptPngfProviderOptions {
-  priority?: number;
-  commandRunner?: CommandRunner;
-  commandExists?: CommandExists;
-}
-
-function parseAppleScriptPngfData(stdout: Buffer): Uint8Array | null {
-  const text = stdout.toString("utf8").trim();
-  if (text.length === 0) {
-    return null;
-  }
-
-  const match = text.match(/«data\s+PNGf([0-9a-fA-F\s]+)»/i);
-  if (!match) {
-    return null;
-  }
-
-  const hex = match[1]?.replace(/\s+/g, "") ?? "";
-  if (hex.length === 0 || hex.length % 2 !== 0) {
-    return null;
-  }
-
-  const bytes = Buffer.from(hex, "hex");
-  return bytes.length > 0 ? new Uint8Array(bytes) : null;
-}
-
-export class OsascriptPngfProvider implements ClipboardImageProvider {
-  readonly capabilities;
-  private readonly commandRunner: CommandRunner;
-  private readonly commandExists: CommandExists;
-
-  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(
-      "osascript",
-      ["-e", PNGF_SCRIPT],
-      context,
-      this.commandExists,
-    );
-    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 };
-    }
-
-    const bytes = parseAppleScriptPngfData(result.stdout);
-    if (!bytes) {
-      return { available: true, image: null };
-    }
-
-    return {
-      available: true,
-      image: {
-        bytes,
-        mimeType: "image/png",
-      },
-    };
-  }
-}
+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»
+  return imageData
+on error
+  return ""
+end try`;
+
+export interface OsascriptPngfProviderOptions {
+  priority?: number;
+  commandRunner?: CommandRunner;
+  commandExists?: CommandExists;
+}
+
+function parseAppleScriptPngfData(stdout: Buffer): Uint8Array | null {
+  const text = stdout.toString("utf8").trim();
+  if (text.length === 0) {
+    return null;
+  }
+
+  const match = text.match(/«data\s+PNGf([0-9a-fA-F\s]+)»/i);
+  if (!match) {
+    return null;
+  }
+
+  const hex = match[1]?.replace(/\s+/g, "") ?? "";
+  if (hex.length === 0 || hex.length % 2 !== 0) {
+    return null;
+  }
+
+  const bytes = Buffer.from(hex, "hex");
+  return bytes.length > 0 ? new Uint8Array(bytes) : null;
+}
+
+export class OsascriptPngfProvider extends NamespacedCommandProvider {
+  constructor(options: OsascriptPngfProviderOptions = {}) {
+    super(
+      {
+        id: "mac-osascript-pngf",
+        name: "osascript PNGf",
+        platforms: ["darwin"],
+        priority: options.priority ?? 30,
+      },
+      "osascript",
+      options,
+    );
+  }
+
+  protected buildArgs(): readonly string[] {
+    return ["-e", PNGF_SCRIPT];
+  }
+
+  protected readFromResult(result: CommandResult): ClipboardReadResult {
+    const bytes = parseAppleScriptPngfData(result.stdout);
+    if (!bytes) {
+      return providerEmptyImage();
+    }
+
+    return providerImageResult(bytes, "image/png");
+  }
+}

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

@@ -1,77 +1,38 @@
-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";
-
-const PUBLIC_PNG_SCRIPT = `ObjC.import('AppKit');
-const pasteboard = $.NSPasteboard.generalPasteboard;
-const data = pasteboard.dataForType('public.png');
-if (!data) {
-  $.exit(2);
-}
-$.NSFileHandle.fileHandleWithStandardOutput.writeData(data);`;
-
-export interface OsascriptPublicPngProviderOptions {
-  priority?: number;
-  commandRunner?: CommandRunner;
-  commandExists?: CommandExists;
-}
-
-export class OsascriptPublicPngProvider implements ClipboardImageProvider {
-  readonly capabilities;
-  private readonly commandRunner: CommandRunner;
-  private readonly commandExists: CommandExists;
-
-  constructor(options: OsascriptPublicPngProviderOptions = {}) {
-    this.capabilities = {
-      id: "mac-osascript-public-png",
-      name: "osascript public.png",
-      platforms: ["darwin"],
-      priority: options.priority ?? 20,
-    };
-    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(
-      "osascript",
-      ["-l", "JavaScript", "-e", PUBLIC_PNG_SCRIPT],
-      context,
-      this.commandExists,
-    );
-    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 };
-    }
-
-    return {
-      available: true,
-      image: {
-        bytes: new Uint8Array(result.stdout),
-        mimeType: "image/png",
-      },
-    };
-  }
-}
+import { NamespacedCommandProvider, providerImageResult, type ClipboardReadResult, type CommandExists, type CommandResult, type CommandRunner } from "./provider-helpers.js";
+
+const PUBLIC_PNG_SCRIPT = `ObjC.import('AppKit');
+const pasteboard = $.NSPasteboard.generalPasteboard;
+const data = pasteboard.dataForType('public.png');
+if (!data) {
+  $.exit(2);
+}
+$.NSFileHandle.fileHandleWithStandardOutput.writeData(data);`;
+
+export interface OsascriptPublicPngProviderOptions {
+  priority?: number;
+  commandRunner?: CommandRunner;
+  commandExists?: CommandExists;
+}
+
+export class OsascriptPublicPngProvider extends NamespacedCommandProvider {
+  constructor(options: OsascriptPublicPngProviderOptions = {}) {
+    super(
+      {
+        id: "mac-osascript-public-png",
+        name: "osascript public.png",
+        platforms: ["darwin"],
+        priority: options.priority ?? 20,
+      },
+      "osascript",
+      options,
+    );
+  }
+
+  protected buildArgs(): readonly string[] {
+    return ["-l", "JavaScript", "-e", PUBLIC_PNG_SCRIPT];
+  }
+
+  protected readFromResult(result: CommandResult): ClipboardReadResult {
+    return providerImageResult(new Uint8Array(result.stdout), "image/png");
+  }
+}

package/src/providers/mac-pngpaste.ts

@@ -1,69 +1,30 @@
-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";
-
-export interface PngpasteProviderOptions {
-  priority?: number;
-  commandRunner?: CommandRunner;
-  commandExists?: CommandExists;
-}
-
-export class PngpasteProvider implements ClipboardImageProvider {
-  readonly capabilities;
-  private readonly commandRunner: CommandRunner;
-  private readonly commandExists: CommandExists;
-
-  constructor(options: PngpasteProviderOptions = {}) {
-    this.capabilities = {
-      id: "mac-pngpaste",
-      name: "pngpaste",
-      platforms: ["darwin"],
-      priority: options.priority ?? 10,
-    };
-    this.commandRunner = options.commandRunner ?? defaultCommandRunner;
-    this.commandExists = options.commandExists ?? defaultCommandExists;
-  }
-
-  isAvailable(context: ClipboardProviderContext): boolean {
-    try {
-      return this.commandExists("pngpaste", context);
-    } catch {
-      return false;
-    }
-  }
-
-  read(context: ClipboardProviderContext): ClipboardReadResult {
-    const wrapped = buildNamespaceWrappedCommand(
-      "pngpaste",
-      ["-"],
-      context,
-      this.commandExists,
-    );
-    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 };
-    }
-
-    return {
-      available: true,
-      image: {
-        bytes: new Uint8Array(result.stdout),
-        mimeType: "image/png",
-      },
-    };
-  }
-}
+import { NamespacedCommandProvider, providerImageResult, type ClipboardReadResult, type CommandExists, type CommandResult, type CommandRunner } from "./provider-helpers.js";
+
+export interface PngpasteProviderOptions {
+  priority?: number;
+  commandRunner?: CommandRunner;
+  commandExists?: CommandExists;
+}
+
+export class PngpasteProvider extends NamespacedCommandProvider {
+  constructor(options: PngpasteProviderOptions = {}) {
+    super(
+      {
+        id: "mac-pngpaste",
+        name: "pngpaste",
+        platforms: ["darwin"],
+        priority: options.priority ?? 10,
+      },
+      "pngpaste",
+      options,
+    );
+  }
+
+  protected buildArgs(): readonly string[] {
+    return ["-"];
+  }
+
+  protected readFromResult(result: CommandResult): ClipboardReadResult {
+    return providerImageResult(new Uint8Array(result.stdout), "image/png");
+  }
+}