pi-image-tools 1.3.0 → 1.4.0

package/src/providers/provider-helpers.ts

@@ -0,0 +1,196 @@
+import { buildNamespaceWrappedCommand, defaultCommandExists, type CommandExists } from "../shell-environment.js";
+import {
+  defaultCommandRunner,
+  MAX_BUFFER_BYTES,
+  READ_TIMEOUT_MS,
+  type CommandResult,
+  type CommandRunner,
+} from "./command-runner.js";
+import type {
+  ClipboardImageProvider,
+  ClipboardProviderContext,
+  ClipboardReadResult,
+  ProviderCapabilities,
+} from "./types.js";
+
+// Re-export the symbols command-based providers reference in their read
+// overrides and option types. Routing every concrete provider's import
+// through this one module — the shared `CommandRunnerProviderOptions`
+// interface, the `LIST_TYPES_TIMEOUT_MS` constant, and the result types —
+// keeps their import blocks short and avoids duplicated multi-line import
+// boilerplate across providers.
+export type { CommandExists } from "../shell-environment.js";
+export type { CommandResult, CommandRunner } from "./command-runner.js";
+export { LIST_TYPES_TIMEOUT_MS } from "./command-runner.js";
+export type { ClipboardProviderContext, ClipboardReadResult } from "./types.js";
+
+/**
+ * Minimal read-result shape shared by command-based and PowerShell-based
+ * clipboard providers. Both `CommandResult` (Buffer stdout) and
+ * `PowerShellCommandResult` (string stdout) satisfy this structural contract.
+ */
+interface ProviderReadResult {
+  missingCommand: boolean;
+  ok: boolean;
+  stdout: { length: number };
+}
+
+/** Result returned when the provider's command is not installed. */
+export function providerUnavailable(): { available: false; image: null } {
+  return { available: false, image: null };
+}
+
+/** Result returned when the clipboard is available but holds no image. */
+export function providerEmptyImage(): { available: true; image: null } {
+  return { available: true, image: null };
+}
+
+/** Result returned when a provider successfully read an image. */
+export function providerImageResult(bytes: Uint8Array, mimeType: string): ClipboardReadResult {
+  return { available: true, image: { bytes, mimeType } };
+}
+
+/**
+ * Shared `isAvailable` implementation for providers that delegate to an
+ * external command whose presence is verified via `commandExists`.
+ */
+export function createCommandAvailabilityChecker(
+  commandName: string,
+  commandExists: CommandExists = defaultCommandExists,
+): (context: ClipboardProviderContext) => boolean {
+  return (context: ClipboardProviderContext): boolean => {
+    try {
+      return commandExists(commandName, context);
+    } catch {
+      return false;
+    }
+  };
+}
+
+/**
+ * Maps a command read result to the standard unavailable/empty sentinel.
+ * Returns `null` when the caller should continue processing the result.
+ */
+export function mapProviderReadFallback(
+  result: ProviderReadResult,
+  requireNonEmptyStdout = true,
+): { available: false; image: null } | { available: true; image: null } | null {
+  if (result.missingCommand) {
+    return providerUnavailable();
+  }
+
+  const isEmpty = !result.ok || (requireNonEmptyStdout && result.stdout.length === 0);
+  return isEmpty ? providerEmptyImage() : null;
+}
+
+/**
+ * Parses a command's stdout — a newline-separated list of MIME types as
+ * emitted by `wl-paste --list-types` / `xclip -t TARGETS -o` — into a
+ * trimmed, non-empty list. Shared by the Linux command-based providers so
+ * the parse chain is not duplicated per provider.
+ */
+export function parseMimeTypeList(stdout: Buffer): string[] {
+  return stdout
+    .toString("utf8")
+    .split(/\r?\n/)
+    .map((mimeType) => mimeType.trim())
+    .filter((mimeType) => mimeType.length > 0);
+}
+
+/** Options shared by namespace-wrapped (macOS) command providers. */
+export interface NamespacedCommandProviderOptions {
+  priority?: number;
+  commandRunner?: CommandRunner;
+  commandExists?: CommandExists;
+}
+
+/** Options shared by plain command-runner (Linux) providers. */
+export interface CommandRunnerProviderOptions {
+  priority?: number;
+  commandRunner?: CommandRunner;
+}
+
+/**
+ * Base for macOS providers that read the clipboard via a namespace-wrapped
+ * command (osascript/pngpaste). Encapsulates the commandRunner/commandExists
+ * wiring, the command-availability check, and the shared read preamble
+ * (namespace wrap -> run -> fallback), so concrete providers only describe
+ * their command args and how to turn stdout into an image.
+ */
+export abstract class NamespacedCommandProvider implements ClipboardImageProvider {
+  readonly capabilities: ProviderCapabilities;
+  private readonly commandRunner: CommandRunner;
+  private readonly commandExists: CommandExists;
+  private readonly isAvailableFn: (context: ClipboardProviderContext) => boolean;
+
+  constructor(
+    capabilities: ProviderCapabilities,
+    private readonly commandName: string,
+    options: NamespacedCommandProviderOptions = {},
+  ) {
+    this.capabilities = capabilities;
+    this.commandRunner = options.commandRunner ?? defaultCommandRunner;
+    this.commandExists = options.commandExists ?? defaultCommandExists;
+    this.isAvailableFn = createCommandAvailabilityChecker(this.commandName, this.commandExists);
+  }
+
+  isAvailable(context: ClipboardProviderContext): boolean {
+    return this.isAvailableFn(context);
+  }
+
+  read(context: ClipboardProviderContext): ClipboardReadResult {
+    const wrapped = buildNamespaceWrappedCommand(this.commandName, this.buildArgs(), context, this.commandExists);
+    const result = this.commandRunner(wrapped.command, wrapped.args, {
+      environment: context.environment,
+      maxBuffer: MAX_BUFFER_BYTES,
+      timeout: READ_TIMEOUT_MS,
+    });
+
+    const fallback = mapProviderReadFallback(result);
+    if (fallback) {
+      return fallback;
+    }
+
+    return this.readFromResult(result);
+  }
+
+  protected abstract buildArgs(): readonly string[];
+  protected abstract readFromResult(result: CommandResult): ClipboardReadResult;
+}
+
+/**
+ * Base for Linux providers that read the clipboard via a fixed command (no
+ * namespace wrapping). Provides the commandRunner field, an always-available
+ * `isAvailable`, and a shared `runCommand` helper so concrete providers only
+ * implement `read`.
+ */
+export abstract class CommandRunnerProvider implements ClipboardImageProvider {
+  readonly capabilities: ProviderCapabilities;
+  protected readonly commandRunner: CommandRunner;
+
+  constructor(capabilities: ProviderCapabilities, options: CommandRunnerProviderOptions = {}) {
+    this.capabilities = capabilities;
+    this.commandRunner = options.commandRunner ?? defaultCommandRunner;
+  }
+
+  isAvailable(_context: ClipboardProviderContext): boolean {
+    return true;
+  }
+
+  protected runCommand(
+    command: string,
+    args: readonly string[],
+    context: ClipboardProviderContext,
+    timeout: number = READ_TIMEOUT_MS,
+  ): CommandResult {
+    return this.commandRunner(command, args, {
+      environment: context.environment,
+      maxBuffer: MAX_BUFFER_BYTES,
+      timeout,
+    });
+  }
+
+  abstract read(context: ClipboardProviderContext): ClipboardReadResult;
+}
+
+export type { ClipboardImageProvider };

package/src/providers/registry.ts

@@ -1,88 +1,88 @@
-import type {
-  ClipboardImageProvider,
-  ClipboardProviderContext,
-  ClipboardReadResult,
-} from "./types.js";
-import type { ClipboardImage } from "../types.js";
-
-export interface ClipboardProviderAttempt {
-  providerId: string;
-  available: boolean;
-  imageFound: boolean;
-  skipped: boolean;
-}
-
-export interface ClipboardProviderRegistryReadResult {
-  image: ClipboardImage | null;
-  attempts: ClipboardProviderAttempt[];
-}
-
-function supportsPlatform(provider: ClipboardImageProvider, platform: NodeJS.Platform): boolean {
-  const { platforms } = provider.capabilities;
-  return platforms === "*" || platforms.includes(platform);
-}
-
-function byPriority(left: ClipboardImageProvider, right: ClipboardImageProvider): number {
-  return left.capabilities.priority - right.capabilities.priority;
-}
-
-export class ClipboardProviderRegistry {
-  private readonly providers: ClipboardImageProvider[] = [];
-
-  constructor(providers: readonly ClipboardImageProvider[] = []) {
-    for (const provider of providers) {
-      this.register(provider);
-    }
-  }
-
-  register(provider: ClipboardImageProvider): this {
-    this.providers.push(provider);
-    return this;
-  }
-
-  getProviders(platform: NodeJS.Platform): ClipboardImageProvider[] {
-    return this.providers.filter((provider) => supportsPlatform(provider, platform)).sort(byPriority);
-  }
-
-  async getEligible(context: ClipboardProviderContext): Promise<ClipboardImageProvider[]> {
-    const eligible: ClipboardImageProvider[] = [];
-    for (const provider of this.getProviders(context.platform)) {
-      if (await provider.isAvailable(context)) {
-        eligible.push(provider);
-      }
-    }
-
-    return eligible;
-  }
-
-  async read(context: ClipboardProviderContext): Promise<ClipboardProviderRegistryReadResult> {
-    const attempts: ClipboardProviderAttempt[] = [];
-
-    for (const provider of this.getProviders(context.platform)) {
-      const isAvailable = await provider.isAvailable(context);
-      if (!isAvailable) {
-        attempts.push({
-          providerId: provider.capabilities.id,
-          available: false,
-          imageFound: false,
-          skipped: true,
-        });
-        continue;
-      }
-
-      const result: ClipboardReadResult = await provider.read(context);
-      attempts.push({
-        providerId: provider.capabilities.id,
-        available: result.available,
-        imageFound: result.image !== null,
-        skipped: false,
-      });
-
-      if (result.image) {
-        return { image: result.image, attempts };
-      }
-    }
-
-    return { image: null, attempts };
-  }
-}
+import type {
+  ClipboardImageProvider,
+  ClipboardProviderContext,
+  ClipboardReadResult,
+} from "./types.js";
+import type { ClipboardImage } from "../types.js";
+
+export interface ClipboardProviderAttempt {
+  providerId: string;
+  available: boolean;
+  imageFound: boolean;
+  skipped: boolean;
+}
+
+export interface ClipboardProviderRegistryReadResult {
+  image: ClipboardImage | null;
+  attempts: ClipboardProviderAttempt[];
+}
+
+function supportsPlatform(provider: ClipboardImageProvider, platform: NodeJS.Platform): boolean {
+  const { platforms } = provider.capabilities;
+  return platforms === "*" || platforms.includes(platform);
+}
+
+function byPriority(left: ClipboardImageProvider, right: ClipboardImageProvider): number {
+  return left.capabilities.priority - right.capabilities.priority;
+}
+
+export class ClipboardProviderRegistry {
+  private readonly providers: ClipboardImageProvider[] = [];
+
+  constructor(providers: readonly ClipboardImageProvider[] = []) {
+    for (const provider of providers) {
+      this.register(provider);
+    }
+  }
+
+  register(provider: ClipboardImageProvider): this {
+    this.providers.push(provider);
+    return this;
+  }
+
+  getProviders(platform: NodeJS.Platform): ClipboardImageProvider[] {
+    return this.providers.filter((provider) => supportsPlatform(provider, platform)).sort(byPriority);
+  }
+
+  async getEligible(context: ClipboardProviderContext): Promise<ClipboardImageProvider[]> {
+    const eligible: ClipboardImageProvider[] = [];
+    for (const provider of this.getProviders(context.platform)) {
+      if (await provider.isAvailable(context)) {
+        eligible.push(provider);
+      }
+    }
+
+    return eligible;
+  }
+
+  async read(context: ClipboardProviderContext): Promise<ClipboardProviderRegistryReadResult> {
+    const attempts: ClipboardProviderAttempt[] = [];
+
+    for (const provider of this.getProviders(context.platform)) {
+      const isAvailable = await provider.isAvailable(context);
+      if (!isAvailable) {
+        attempts.push({
+          providerId: provider.capabilities.id,
+          available: false,
+          imageFound: false,
+          skipped: true,
+        });
+        continue;
+      }
+
+      const result: ClipboardReadResult = await provider.read(context);
+      attempts.push({
+        providerId: provider.capabilities.id,
+        available: result.available,
+        imageFound: result.image !== null,
+        skipped: false,
+      });
+
+      if (result.image) {
+        return { image: result.image, attempts };
+      }
+    }
+
+    return { image: null, attempts };
+  }
+}

package/src/providers/types.ts

@@ -1,24 +1,24 @@
-import type { ClipboardImage } from "../types.js";
-
-export interface ClipboardReadResult {
-  available: boolean;
-  image: ClipboardImage | null;
-}
-
-export interface ClipboardProviderContext {
-  platform: NodeJS.Platform;
-  environment: NodeJS.ProcessEnv;
-}
-
-export interface ProviderCapabilities {
-  readonly id: string;
-  readonly name: string;
-  readonly platforms: readonly NodeJS.Platform[] | "*";
-  readonly priority: number;
-}
-
-export interface ClipboardImageProvider {
-  readonly capabilities: ProviderCapabilities;
-  isAvailable(context: ClipboardProviderContext): boolean | Promise<boolean>;
-  read(context: ClipboardProviderContext): ClipboardReadResult | Promise<ClipboardReadResult>;
-}
+import type { ClipboardImage } from "../types.js";
+
+export interface ClipboardReadResult {
+  available: boolean;
+  image: ClipboardImage | null;
+}
+
+export interface ClipboardProviderContext {
+  platform: NodeJS.Platform;
+  environment: NodeJS.ProcessEnv;
+}
+
+export interface ProviderCapabilities {
+  readonly id: string;
+  readonly name: string;
+  readonly platforms: readonly NodeJS.Platform[] | "*";
+  readonly priority: number;
+}
+
+export interface ClipboardImageProvider {
+  readonly capabilities: ProviderCapabilities;
+  isAvailable(context: ClipboardProviderContext): boolean | Promise<boolean>;
+  read(context: ClipboardProviderContext): ClipboardReadResult | Promise<ClipboardReadResult>;
+}

package/src/providers/wl-paste.ts

@@ -1,81 +1,46 @@
+import { CommandRunnerProvider, providerEmptyImage, providerImageResult, providerUnavailable, LIST_TYPES_TIMEOUT_MS, parseMimeTypeList, type CommandRunnerProviderOptions, type ClipboardProviderContext, type ClipboardReadResult } from "./provider-helpers.js";
 import { normalizeMimeType, selectPreferredImageMimeType } from "../image-mime.js";
-import {
-  defaultCommandRunner,
-  LIST_TYPES_TIMEOUT_MS,
-  MAX_BUFFER_BYTES,
-  READ_TIMEOUT_MS,
-  type CommandRunner,
-} from "./command-runner.js";
-import type { ClipboardImageProvider, ClipboardProviderContext, ClipboardReadResult } from "./types.js";
 
-export interface WlPasteProviderOptions {
-  priority?: number;
-  commandRunner?: CommandRunner;
-}
-
-export class WlPasteProvider implements ClipboardImageProvider {
-  readonly capabilities;
-  private readonly commandRunner: CommandRunner;
-
-  constructor(options: WlPasteProviderOptions = {}) {
-    this.capabilities = {
-      id: "wl-paste",
-      name: "wl-paste",
-      platforms: ["linux"],
-      priority: options.priority ?? 10,
-    };
-    this.commandRunner = options.commandRunner ?? defaultCommandRunner;
-  }
-
-  isAvailable(_context: ClipboardProviderContext): boolean {
-    return true;
+export class WlPasteProvider extends CommandRunnerProvider {
+  constructor(options: CommandRunnerProviderOptions = {}) {
+    super(
+      {
+        id: "wl-paste",
+        name: "wl-paste",
+        platforms: ["linux"],
+        priority: options.priority ?? 10,
+      },
+      options,
+    );
   }
 
   read(context: ClipboardProviderContext): ClipboardReadResult {
-    const listTypes = this.commandRunner("wl-paste", ["--list-types"], {
-      environment: context.environment,
-      maxBuffer: MAX_BUFFER_BYTES,
-      timeout: LIST_TYPES_TIMEOUT_MS,
-    });
+    const listTypes = this.runCommand("wl-paste", ["--list-types"], context, LIST_TYPES_TIMEOUT_MS);
     if (listTypes.missingCommand) {
-      return { available: false, image: null };
+      return providerUnavailable();
     }
 
     if (!listTypes.ok) {
-      return { available: true, image: null };
+      return providerEmptyImage();
     }
 
-    const mimeTypes = listTypes.stdout
-      .toString("utf8")
-      .split(/\r?\n/)
-      .map((mimeType) => mimeType.trim())
-      .filter((mimeType) => mimeType.length > 0);
+    const mimeTypes = parseMimeTypeList(listTypes.stdout);
 
     const selectedMimeType = selectPreferredImageMimeType(mimeTypes);
     if (!selectedMimeType) {
-      return { available: true, image: null };
+      return providerEmptyImage();
     }
 
-    const imageData = this.commandRunner(
+    const imageData = this.runCommand(
       "wl-paste",
       ["--type", selectedMimeType, "--no-newline"],
-      {
-        environment: context.environment,
-        maxBuffer: MAX_BUFFER_BYTES,
-        timeout: READ_TIMEOUT_MS,
-      },
+      context,
     );
 
     if (!imageData.ok || imageData.stdout.length === 0) {
-      return { available: true, image: null };
+      return providerEmptyImage();
     }
 
-    return {
-      available: true,
-      image: {
-        bytes: new Uint8Array(imageData.stdout),
-        mimeType: normalizeMimeType(selectedMimeType),
-      },
-    };
+    return providerImageResult(new Uint8Array(imageData.stdout), normalizeMimeType(selectedMimeType));
   }
 }

package/src/providers/xclip.ts

@@ -1,58 +1,32 @@
+import { CommandRunnerProvider, providerEmptyImage, providerImageResult, providerUnavailable, LIST_TYPES_TIMEOUT_MS, parseMimeTypeList, type CommandRunnerProviderOptions, type ClipboardProviderContext, type ClipboardReadResult } from "./provider-helpers.js";
 import { normalizeMimeType, selectPreferredImageMimeType, SUPPORTED_IMAGE_MIME_TYPES } from "../image-mime.js";
-import {
-  defaultCommandRunner,
-  LIST_TYPES_TIMEOUT_MS,
-  MAX_BUFFER_BYTES,
-  READ_TIMEOUT_MS,
-  type CommandRunner,
-} from "./command-runner.js";
-import type { ClipboardImageProvider, ClipboardProviderContext, ClipboardReadResult } from "./types.js";
 
-export interface XclipProviderOptions {
-  priority?: number;
-  commandRunner?: CommandRunner;
-}
-
-export class XclipProvider implements ClipboardImageProvider {
-  readonly capabilities;
-  private readonly commandRunner: CommandRunner;
-
-  constructor(options: XclipProviderOptions = {}) {
-    this.capabilities = {
-      id: "xclip",
-      name: "xclip",
-      platforms: ["linux"],
-      priority: options.priority ?? 20,
-    };
-    this.commandRunner = options.commandRunner ?? defaultCommandRunner;
-  }
-
-  isAvailable(_context: ClipboardProviderContext): boolean {
-    return true;
+export class XclipProvider extends CommandRunnerProvider {
+  constructor(options: CommandRunnerProviderOptions = {}) {
+    super(
+      {
+        id: "xclip",
+        name: "xclip",
+        platforms: ["linux"],
+        priority: options.priority ?? 20,
+      },
+      options,
+    );
   }
 
   read(context: ClipboardProviderContext): ClipboardReadResult {
-    const targets = this.commandRunner(
+    const targets = this.runCommand(
       "xclip",
       ["-selection", "clipboard", "-t", "TARGETS", "-o"],
-      {
-        environment: context.environment,
-        maxBuffer: MAX_BUFFER_BYTES,
-        timeout: LIST_TYPES_TIMEOUT_MS,
-      },
+      context,
+      LIST_TYPES_TIMEOUT_MS,
     );
 
     if (targets.missingCommand) {
-      return { available: false, image: null };
+      return providerUnavailable();
     }
 
-    const advertisedMimeTypes = targets.ok
-      ? targets.stdout
-          .toString("utf8")
-          .split(/\r?\n/)
-          .map((mimeType) => mimeType.trim())
-          .filter((mimeType) => mimeType.length > 0)
-      : [];
+    const advertisedMimeTypes = targets.ok ? parseMimeTypeList(targets.stdout) : [];
 
     const preferredMimeType =
       advertisedMimeTypes.length > 0 ? selectPreferredImageMimeType(advertisedMimeTypes) : null;
@@ -61,27 +35,17 @@ export class XclipProvider implements ClipboardImageProvider {
       : [...SUPPORTED_IMAGE_MIME_TYPES];
 
     for (const mimeType of mimeTypesToTry) {
-      const imageData = this.commandRunner(
+      const imageData = this.runCommand(
         "xclip",
         ["-selection", "clipboard", "-t", mimeType, "-o"],
-        {
-          environment: context.environment,
-          maxBuffer: MAX_BUFFER_BYTES,
-          timeout: READ_TIMEOUT_MS,
-        },
+        context,
       );
 
       if (imageData.ok && imageData.stdout.length > 0) {
-        return {
-          available: true,
-          image: {
-            bytes: new Uint8Array(imageData.stdout),
-            mimeType: normalizeMimeType(mimeType),
-          },
-        };
+        return providerImageResult(new Uint8Array(imageData.stdout), normalizeMimeType(mimeType));
       }
     }
 
-    return { available: true, image: null };
+    return providerEmptyImage();
   }
 }