@pi-archimedes/image-paste 0.2.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@pi-archimedes/image-paste",
+  "version": "0.2.0",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "description": "Clipboard image paste for pi-archimedes",
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.ts",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.1.0",
+    "@earendil-works/pi-tui": ">=0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/clipboard.ts

@@ -0,0 +1,417 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+import type { ClipboardImage } from "./types.js";
+
+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 ClipboardModule {
+  hasImage: () => boolean;
+  getImageBinary: () => Promise<Array<number> | Uint8Array>;
+}
+
+interface CommandResult {
+  ok: boolean;
+  stdout: Buffer;
+  missingCommand: boolean;
+}
+
+interface ClipboardReadResult {
+  available: boolean;
+  image: ClipboardImage | null;
+}
+
+function isErrnoException(error: Error): error is NodeJS.ErrnoException {
+  return "code" in error;
+}
+
+function hasGraphicalSession(platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): boolean {
+  return platform !== "linux" || Boolean(environment.DISPLAY || environment.WAYLAND_DISPLAY);
+}
+
+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,
+): ClipboardModule | null {
+  if (cachedClipboardModule !== undefined) {
+    return cachedClipboardModule;
+  }
+
+  if (environment.TERMUX_VERSION || !hasGraphicalSession(platform, environment)) {
+    cachedClipboardModule = null;
+    return cachedClipboardModule;
+  }
+
+  try {
+    cachedClipboardModule = require("@mariozechner/clipboard") as ClipboardModule;
+  } catch {
+    cachedClipboardModule = null;
+  }
+
+  return cachedClipboardModule;
+}
+
+async function readClipboardImageViaNativeModule(
+  platform: NodeJS.Platform,
+  environment: NodeJS.ProcessEnv,
+): Promise<ClipboardReadResult> {
+  const clipboard = loadClipboardModule(platform, environment);
+  if (!clipboard) {
+    return { available: false, image: null };
+  }
+
+  if (!clipboard.hasImage()) {
+    return { available: true, image: null };
+  }
+
+  const imageData = await clipboard.getImageBinary();
+  if (!imageData || imageData.length === 0) {
+    return { available: true, image: null };
+  }
+
+  const bytes = imageData instanceof Uint8Array ? imageData : Uint8Array.from(imageData);
+  return {
+    available: true,
+    image: {
+      bytes,
+      mimeType: "image/png",
+    },
+  };
+}
+
+function runCommand(
+  command: string,
+  args: string[],
+  timeout: number,
+): CommandResult {
+  const result = spawnSync(command, args, {
+    timeout,
+    maxBuffer: MAX_BUFFER_BYTES,
+  });
+
+  if (result.error) {
+    return {
+      ok: false,
+      stdout: Buffer.alloc(0),
+      missingCommand: isErrnoException(result.error) && result.error.code === "ENOENT",
+    };
+  }
+
+  const stdout = Buffer.isBuffer(result.stdout)
+    ? result.stdout
+    : Buffer.from(result.stdout ?? "", typeof result.stdout === "string" ? "utf8" : undefined);
+
+  return {
+    ok: result.status === 0,
+    stdout,
+    missingCommand: false,
+  };
+}
+
+function encodePowerShell(script: string): string {
+  return Buffer.from(script, "utf16le").toString("base64");
+}
+
+function readClipboardImageViaPowerShell(): ClipboardReadResult {
+  const script = `
+$ErrorActionPreference = 'Stop'
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+if (-not [System.Windows.Forms.Clipboard]::ContainsImage()) {
+  return
+}
+
+$image = [System.Windows.Forms.Clipboard]::GetImage()
+if ($null -eq $image) {
+  return
+}
+
+$stream = New-Object System.IO.MemoryStream
+try {
+  $image.Save($stream, [System.Drawing.Imaging.ImageFormat]::Png)
+  [System.Convert]::ToBase64String($stream.ToArray())
+} finally {
+  $stream.Dispose()
+  $image.Dispose()
+}
+`;
+
+  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,
+    },
+  );
+
+  if (result.error) {
+    return {
+      available: !isErrnoException(result.error) || result.error.code !== "ENOENT",
+      image: null,
+    };
+  }
+
+  if (result.status !== 0) {
+    return { available: true, image: null };
+  }
+
+  const base64 = result.stdout.trim();
+  if (!base64) {
+    return { available: true, image: null };
+  }
+
+  try {
+    const bytes = Buffer.from(base64, "base64");
+    if (bytes.length === 0) {
+      return { available: true, image: null };
+    }
+
+    return {
+      available: true,
+      image: {
+        bytes: new Uint8Array(bytes),
+        mimeType: "image/png",
+      },
+    };
+  } catch {
+    return { available: true, image: null };
+  }
+}
+
+function readClipboardImageViaWlPaste(): ClipboardReadResult {
+  const listTypes = runCommand("wl-paste", ["--list-types"], LIST_TYPES_TIMEOUT_MS);
+  if (listTypes.missingCommand) {
+    return { available: false, image: null };
+  }
+
+  if (!listTypes.ok) {
+    return { available: true, image: null };
+  }
+
+  const mimeTypes = listTypes.stdout
+    .toString("utf8")
+    .split(/\r?\n/)
+    .map((mimeType) => mimeType.trim())
+    .filter((mimeType) => mimeType.length > 0);
+
+  const selectedMimeType = selectPreferredImageMimeType(mimeTypes);
+  if (!selectedMimeType) {
+    return { available: true, image: null };
+  }
+
+  const imageData = runCommand(
+    "wl-paste",
+    ["--type", selectedMimeType, "--no-newline"],
+    READ_TIMEOUT_MS,
+  );
+
+  if (!imageData.ok || imageData.stdout.length === 0) {
+    return { available: true, image: null };
+  }
+
+  return {
+    available: true,
+    image: {
+      bytes: new Uint8Array(imageData.stdout),
+      mimeType: normalizeMimeType(selectedMimeType),
+    },
+  };
+}
+
+function readClipboardImageViaXclip(): ClipboardReadResult {
+  const targets = runCommand(
+    "xclip",
+    ["-selection", "clipboard", "-t", "TARGETS", "-o"],
+    LIST_TYPES_TIMEOUT_MS,
+  );
+
+  if (targets.missingCommand) {
+    return { available: false, image: null };
+  }
+
+  const advertisedMimeTypes = targets.ok
+    ? targets.stdout
+        .toString("utf8")
+        .split(/\r?\n/)
+        .map((mimeType) => mimeType.trim())
+        .filter((mimeType) => mimeType.length > 0)
+    : [];
+
+  const preferredMimeType =
+    advertisedMimeTypes.length > 0 ? selectPreferredImageMimeType(advertisedMimeTypes) : null;
+  const mimeTypesToTry = preferredMimeType
+    ? [preferredMimeType, ...SUPPORTED_IMAGE_MIME_TYPES]
+    : [...SUPPORTED_IMAGE_MIME_TYPES];
+
+  for (const mimeType of mimeTypesToTry) {
+    const imageData = runCommand(
+      "xclip",
+      ["-selection", "clipboard", "-t", mimeType, "-o"],
+      READ_TIMEOUT_MS,
+    );
+
+    if (imageData.ok && imageData.stdout.length > 0) {
+      return {
+        available: true,
+        image: {
+          bytes: new Uint8Array(imageData.stdout),
+          mimeType: normalizeMimeType(mimeType),
+        },
+      };
+    }
+  }
+
+  return { available: true, image: null };
+}
+
+function getUnavailableReaderMessage(platform: NodeJS.Platform): string {
+  switch (platform) {
+    case "linux":
+      return "No Linux clipboard image reader is available. Install wl-clipboard or xclip, or ensure @mariozechner/clipboard is installed.";
+    case "darwin":
+      return "No macOS clipboard image reader is available. Ensure @mariozechner/clipboard is installed.";
+    case "win32":
+      return "No Windows clipboard image reader is available. Ensure PowerShell is available or @mariozechner/clipboard is installed.";
+    default:
+      return `Clipboard image paste is not supported on platform: ${platform}`;
+  }
+}
+
+export async function readClipboardImage(options?: {
+  environment?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+}): Promise<ClipboardImage | null> {
+  const environment = options?.environment ?? process.env;
+  const platform = options?.platform ?? process.platform;
+
+  if (environment.TERMUX_VERSION) {
+    return null;
+  }
+
+  if (!hasGraphicalSession(platform, environment)) {
+    throw new Error("Clipboard image paste requires a graphical desktop session with DISPLAY or WAYLAND_DISPLAY.");
+  }
+
+  const readerResults: ClipboardReadResult[] = [];
+
+  const recordResult = (result: ClipboardReadResult): ClipboardImage | null => {
+    readerResults.push(result);
+    return result.image;
+  };
+
+  if (platform === "win32") {
+    const nativeImage = recordResult(await readClipboardImageViaNativeModule(platform, environment));
+    if (nativeImage) {
+      return nativeImage;
+    }
+
+    const powerShellImage = recordResult(readClipboardImageViaPowerShell());
+    if (powerShellImage) {
+      return powerShellImage;
+    }
+  } else if (platform === "linux") {
+    const sessionReaders = isWaylandSession(environment)
+      ? [readClipboardImageViaWlPaste, readClipboardImageViaXclip]
+      : [readClipboardImageViaXclip, readClipboardImageViaWlPaste];
+
+    for (const reader of sessionReaders) {
+      const image = recordResult(reader());
+      if (image) {
+        return image;
+      }
+    }
+
+    const nativeImage = recordResult(await readClipboardImageViaNativeModule(platform, environment));
+    if (nativeImage) {
+      return nativeImage;
+    }
+  } else {
+    const nativeImage = recordResult(await readClipboardImageViaNativeModule(platform, environment));
+    if (nativeImage) {
+      return nativeImage;
+    }
+  }
+
+  if (readerResults.some((result) => result.available)) {
+    return null;
+  }
+
+  throw new Error(getUnavailableReaderMessage(platform));
+}
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp"]);
+
+export function isImageFilePath(path: string): boolean {
+  return IMAGE_EXTENSIONS.has(path.toLowerCase().split(".").pop() ?? "");
+}
+
+export async function readFileAsImage(filePath: string): Promise<ClipboardImage | null> {
+  if (!existsSync(filePath)) return null;
+  const ext = filePath.toLowerCase().split(".").pop() ?? "";
+  const mimeMap: Record<string, string> = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg",
+    webp: "image/webp", gif: "image/gif", bmp: "image/bmp",
+  };
+  const mimeType = mimeMap[ext];
+  if (!mimeType) return null;
+  try {
+    const bytes = await readFile(filePath);
+    if (bytes.length === 0) return null;
+    return { bytes: new Uint8Array(bytes), mimeType };
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,190 @@
+import { randomUUID } from "node:crypto";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { KeyId } from "@earendil-works/pi-tui";
+
+import { readClipboardImage } from "./clipboard.js";
+import { registerImagePreview, sendPreviewMessage } from "./preview.js";
+import type { ClipboardImage, PendingImage, ImageMarker } from "./types.js";
+
+const MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024; // 20MB
+
+// ── Queue management ────────────────────────────────────────────
+
+interface ImageQueue {
+  images: PendingImage[];
+  markers: ImageMarker[];
+  nextIndex: number;
+}
+
+function createImageQueue(): ImageQueue {
+  return { images: [], markers: [], nextIndex: 1 };
+}
+
+// Marker key: the visible text WITHOUT trailing space (e.g. "[Image #1]")
+// This is used for both detection and replacement — consistent strategy.
+function markerKey(marker: ImageMarker): string {
+  return marker.text.trim();
+}
+
+function queueImage(
+  queue: ImageQueue,
+  image: ClipboardImage,
+  ctx: ExtensionContext,
+): ImageMarker {
+  const id = randomUUID();
+  const placeholder = `[Image #${queue.nextIndex}] `;
+
+  const pending: PendingImage = {
+    id,
+    base64: Buffer.from(image.bytes).toString("base64"),
+    mimeType: image.mimeType,
+  };
+  queue.images.push(pending);
+
+  const marker: ImageMarker = {
+    id,
+    text: placeholder,
+    index: queue.nextIndex,
+  };
+  queue.markers.push(marker);
+  queue.nextIndex += 1;
+
+  // Insert placeholder into editor
+  ctx.ui.pasteToEditor(placeholder);
+  return marker;
+}
+
+// ── Registration ────────────────────────────────────────────────
+
+function getImagePasteShortcuts(): KeyId[] {
+  if (process.platform === "win32") {
+    return ["alt+v", "ctrl+alt+v"] as KeyId[];
+  }
+  return ["ctrl+v", "alt+v", "ctrl+alt+v"] as KeyId[];
+}
+
+// Module-level state — registered once, queue reset per session
+let _ctx: ExtensionContext | null = null;
+let _queue: ImageQueue | null = null;
+let _pasting = false;
+
+export function registerImagePaste(pi: ExtensionAPI): void {
+  // Register preview renderer (once)
+  registerImagePreview(pi);
+
+  // Register shortcuts (once)
+  const pasteImage = async (): Promise<void> => {
+    if (_pasting) return; // Mutex: prevent concurrent paste operations
+    if (!_ctx || !_queue || !_ctx.hasUI) return;
+    _pasting = true;
+    try {
+      const image = await readClipboardImage();
+      if (!image) {
+        _ctx.ui.notify("No image found in clipboard.", "warning");
+        return;
+      }
+      if (image.bytes.length > MAX_FILE_SIZE_BYTES) {
+        _ctx.ui.notify(
+          `Image too large (${(image.bytes.length / 1024 / 1024).toFixed(1)}MB > 20MB).`,
+          "warning",
+        );
+        return;
+      }
+      queueImage(_queue, image, _ctx);
+      _ctx.ui.notify("Image attached from clipboard.", "info");
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : "Unknown error";
+      _ctx.ui.notify(`Image paste failed: ${msg}`, "warning");
+    } finally {
+      _pasting = false;
+    }
+  };
+
+  for (const shortcut of getImagePasteShortcuts()) {
+    pi.registerShortcut(shortcut, {
+      description: "Attach clipboard image to draft",
+      handler: pasteImage,
+    });
+  }
+
+  // Input event handler — attach images on submit (once)
+  pi.on("input", async (event) => {
+    if (event.source === "extension") {
+      return { action: "continue" as const };
+    }
+    if (!_queue || !_queue.markers.length || !_ctx) {
+      return { action: "continue" as const };
+    }
+
+    // ── Marker matching: use consistent key (trimmed text) ──
+    let hasMarkers = false;
+    for (const marker of _queue.markers) {
+      if (event.text.includes(markerKey(marker))) {
+        hasMarkers = true;
+        break;
+      }
+    }
+
+    if (!hasMarkers) {
+      // No markers found — clear queue (user removed them)
+      _queue.images.length = 0;
+      _queue.markers.length = 0;
+      _queue.nextIndex = 1;
+      return { action: "continue" as const };
+    }
+
+    // Match markers to images using trimmed key
+    const imagesToAttach: PendingImage[] = [];
+
+    for (const marker of _queue.markers) {
+      const key = markerKey(marker);
+      if (event.text.includes(key)) {
+        const pending = _queue.images.find((img) => img.id === marker.id);
+        if (pending) {
+          imagesToAttach.push(pending);
+        }
+      }
+    }
+
+    // Clear queue
+    _queue.images.length = 0;
+    _queue.markers.length = 0;
+    _queue.nextIndex = 1;
+
+    if (imagesToAttach.length === 0) {
+      return { action: "continue" as const };
+    }
+
+    // Send preview message for TUI display (images are invisible in user messages)
+    try {
+      sendPreviewMessage(pi, imagesToAttach);
+    } catch {
+      // Preview is optional — don't fail the submit
+    }
+
+    return {
+      action: "transform" as const,
+      text: event.text,
+      images: imagesToAttach.map((img) => ({
+        type: "image" as const,
+        data: img.base64,
+        mimeType: img.mimeType,
+      })),
+    };
+  });
+}
+
+// Called on session_start to initialize/reset the queue
+export function initImagePasteSession(ctx: ExtensionContext): void {
+  _ctx = ctx;
+  _queue = createImageQueue();
+}
+
+// Called on session_shutdown to clear state
+export function shutdownImagePaste(): void {
+  _ctx = null;
+  _queue = null;
+  _pasting = false;
+}

package/src/preview.ts

@@ -0,0 +1,66 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Image, Spacer, Text } from "@earendil-works/pi-tui";
+
+import type { PendingImage } from "./types.js";
+
+const CUSTOM_TYPE = "hephaestus-image-preview";
+
+interface PreviewDetails {
+  images: Array<{ data: string; mimeType: string }>;
+}
+
+export function registerImagePreview(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer<PreviewDetails>(CUSTOM_TYPE, (message, _options, theme) => {
+    try {
+      // Theme.fg is runtime-available but not exposed in the Theme type definition
+      const fg = (theme as any).fg as ((color: string, text: string) => string) | undefined;
+      if (!fg) return undefined;
+
+      // Extract image data from content array
+      const content = message.content;
+      if (!Array.isArray(content) || content.length === 0) return undefined;
+
+      const container = new Container();
+      container.addChild(new Spacer(1));
+
+      for (const item of content) {
+        if (item.type === "image") {
+          container.addChild(new Spacer(1));
+          container.addChild(
+            new Image(item.data, item.mimeType, {
+              fallbackColor: (text: string) => fg("toolOutput", text),
+            }, {
+              maxWidthCells: 60,
+            }),
+          );
+        }
+      }
+
+      return container;
+    } catch {
+      return undefined;
+    }
+  });
+}
+
+export function sendPreviewMessage(
+  pi: ExtensionAPI,
+  images: PendingImage[],
+): void {
+  if (images.length === 0) return;
+
+  // Send each image as a separate custom message with image in content
+  // This ensures pi renders the image inline using its built-in image support
+  for (const img of images) {
+    pi.sendMessage(
+      {
+        customType: CUSTOM_TYPE,
+        content: [
+          { type: "image" as const, data: img.base64, mimeType: img.mimeType },
+        ],
+        display: true,
+      },
+      { triggerTurn: false },
+    );
+  }
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+export interface ClipboardImage {
+  bytes: Uint8Array;
+  mimeType: string;  // "image/png", "image/jpeg", "image/webp", "image/gif"
+}
+
+export interface PendingImage {
+  id: string;         // UUID — unique per paste operation
+  base64: string;
+  mimeType: string;
+}
+
+export interface ImageMarker {
+  id: string;         // matches PendingImage.id
+  text: string;       // "[Image #N]" — the exact text inserted
+  index: number;      // 1-based insertion order (for N in "[Image #N]")
+}