@pi-archimedes/image-paste 2.10.3 → 2.11.0

package/src/clipboard.ts

@@ -4,11 +4,24 @@ import { readFile } from "node:fs/promises";
 
 import { convertToPng } from "@earendil-works/pi-coding-agent";
 import { getNativeClipboard } from "@earendil-works/pi-tui";
+import { diag } from "@pi-archimedes/core/log";
 
 import type { ClipboardImage } from "./types.js";
 
 const LIST_TYPES_TIMEOUT_MS = 1000;
 const READ_TIMEOUT_MS = 5000;
+/**
+ * How long a read through the native clipboard helper may take before it counts
+ * as failed — the same budget one CLI read gets, because a hung X11/Wayland
+ * session blocks in exactly the same place a hung `wl-paste` does.
+ *
+ * The deadline cannot cancel the native call; what it bounds is how long the
+ * keypress waits for it. That matters more than a slow read would suggest: the
+ * `ctrl+v` handler in `index.ts` holds a `_pasting` mutex for the lifetime of a
+ * dispatch, so an unbounded read that never settles leaves that mutex held and
+ * every later `ctrl+v` a silent no-op until the session restarts.
+ */
+export const NATIVE_READ_TIMEOUT_MS = READ_TIMEOUT_MS;
 const MAX_BUFFER_BYTES = 50 * 1024 * 1024;
 const SUPPORTED_IMAGE_MIME_TYPES = [
   "image/png",
@@ -27,6 +40,42 @@ interface CommandResult {
 export interface ClipboardReadResult {
   available: boolean;
   image: ClipboardImage | null;
+  /** Set when a reader existed but did not answer inside the deadline. */
+  timeout?: Error;
+}
+
+/** A native clipboard read that outlived {@link NATIVE_READ_TIMEOUT_MS}. */
+class NativeReadTimeoutError extends Error {
+  constructor(operation: string) {
+    super(`${operation} timed out after ${NATIVE_READ_TIMEOUT_MS}ms`);
+    this.name = "NativeReadTimeoutError";
+  }
+}
+
+/**
+ * Give a native clipboard read a deadline. `undefined` (no helper, no such
+ * method) passes straight through; a rejection passes through unchanged, so a
+ * transfer failure still reads as a failure rather than as an empty clipboard.
+ */
+async function withinNativeReadDeadline<T>(
+  read: Promise<T> | undefined,
+  operation: string,
+): Promise<T | undefined> {
+  if (read === undefined) {
+    return undefined;
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await new Promise<T>((resolve, reject) => {
+      timer = setTimeout(() => reject(new NativeReadTimeoutError(operation)), NATIVE_READ_TIMEOUT_MS);
+      read.then(resolve, reject);
+    });
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
 }
 
 function isErrnoException(error: Error): error is NodeJS.ErrnoException {
@@ -76,7 +125,10 @@ export async function readClipboardImageViaNativeModule(
       return { available: false, image: null };
     }
 
-    const bytes = await native.getImage();
+    const bytes = await withinNativeReadDeadline(
+      native.getImage(),
+      "Native clipboard image read",
+    );
     if (!bytes || bytes.length === 0) {
       return { available: true, image: null };
     }
@@ -106,7 +158,14 @@ export async function readClipboardImageViaNativeModule(
         mimeType: "image/png",
       },
     };
-  } catch {
+  } catch (error) {
+    // A read that never answered is not the same event as a reader that is not
+    // installed, so it is carried out as a timeout rather than flattened into
+    // "unavailable": the caller reports the deadline, not "install a clipboard
+    // reader", and the keypress stops waiting.
+    if (error instanceof NativeReadTimeoutError) {
+      return { available: false, image: null, timeout: error };
+    }
     return { available: false, image: null };
   }
 }
@@ -198,7 +257,7 @@ try {
       if (stdout.length + data.length > MAX_BUFFER_BYTES) {
         if (!exceededMaxBuffer) {
           exceededMaxBuffer = true;
-          console.warn("[archimedes] Clipboard image exceeded maximum buffer size (50MB)");
+          diag("image-paste", "[archimedes] Clipboard image exceeded maximum buffer size (50MB)");
         }
         return;
       }
@@ -404,15 +463,263 @@ export async function readClipboardImage(options?: {
     return null;
   }
 
+  // Nothing answered. If the reason is that a helper never replied, say that —
+  // "install wl-clipboard or xclip" would be the wrong advice for a machine
+  // that has one and is not answering.
+  const timeout = readerResults.find((result) => result.timeout)?.timeout;
+  if (timeout) {
+    throw timeout;
+  }
+
   throw new Error(getUnavailableReaderMessage(platform));
 }
 
+// ── Copied files on the clipboard ───────────────────────────────────────────
+
+/**
+ * Read copied file paths (a file manager's "Copy" on macOS/Windows) off the
+ * clipboard — the same call pi makes, `getNativeClipboard()?.getFilePaths?.()`
+ * (`dist/utils/clipboard.js:83-86`), on the same public accessor used for
+ * images above.
+ *
+ * The optional call is load-bearing, not defensive noise: this package's peer
+ * floor is pi/pi-tui `>=0.86.0`, `getFilePaths` arrived later than that, and it
+ * is still optional in 1.2.0 (`pi-tui/dist/native-platform.d.ts:8`). Measured on
+ * this Linux box with pi-tui 1.2.0 installed: the X11 helper has no
+ * `getFilePaths` at all (`typeof helper.getFilePaths === "undefined"`), so this
+ * returns `null` there and the caller falls through to text — which is exactly
+ * what pi's own path branch does on Linux.
+ *
+ * A rejected transfer is *not* swallowed: pi lets it reach
+ * `handleClipboardPaste`'s catch and show a failure, and the caller here does
+ * the same, so a clipboard that failed to answer is distinguishable from one
+ * that answered "no files". A read that never answered at all is the one
+ * exception, and it is a deadline rather than a verdict — see
+ * {@link NATIVE_READ_TIMEOUT_MS}.
+ */
+export async function readClipboardFilePaths(): Promise<string[] | null> {
+  let paths: string[] | null | undefined;
+  try {
+    paths = await withinNativeReadDeadline(
+      getNativeClipboard()?.getFilePaths?.(),
+      "Clipboard file path read",
+    );
+  } catch (error) {
+    if (error instanceof NativeReadTimeoutError) {
+      // Unlike a transfer failure, which is passed up as pi passes it up, a read
+      // that never answered falls through to the text branch: the caller's next
+      // question ("is there text?") is independent of this one, and a hung path
+      // read should not cost the user a text paste. pi is still sitting in this
+      // call when we return.
+      return null;
+    }
+    throw error;
+  }
+  return paths?.length ? paths : null;
+}
+
+// ── Clipboard text ──────────────────────────────────────────────────────────
+
+interface TextReaderCommand {
+  command: string;
+  args: string[];
+}
+
+/**
+ * The command candidates for a plain-text read, in pi's order
+ * (`readClipboardText`, `dist/utils/clipboard.js:58-81`). pi's own function is
+ * not reachable from here — the package exports are `"."` and `"./rpc-entry"`
+ * and the root re-exports only `copyToClipboard` (`dist/index.d.ts:38`) — so
+ * this is a faithful re-implementation over the command runner this module
+ * already has, including the ordering reason: the native helper is the LAST
+ * resort, because on Wayland/X11 the CLI tools answer instantly while the X11
+ * helper can stall or fail on display auth. (Observed on this machine: the
+ * helper loads, then every read fails with `Invalid MIT-MAGIC-COOKIE-1 key`,
+ * while `wl-paste` returns text immediately.)
+ *
+ * No macOS/Windows candidates, deliberately: pi has none either — those
+ * platforms go straight to the native helper, so adding `pbpaste` here would be
+ * inventing a mechanism pi does not use.
+ */
+function textReaderCommands(
+  platform: NodeJS.Platform,
+  environment: NodeJS.ProcessEnv,
+): TextReaderCommand[] {
+  const commands: TextReaderCommand[] = [];
+  // Termux reports platform "android", not "linux" (pi's note, clipboard.js:61).
+  if (environment.TERMUX_VERSION) {
+    commands.push({ command: "termux-clipboard-get", args: [] });
+  }
+  if (platform === "linux") {
+    if (environment.WAYLAND_DISPLAY) {
+      commands.push({ command: "wl-paste", args: ["--no-newline", "--type", "text"] });
+    }
+    if (environment.DISPLAY) {
+      commands.push({ command: "xclip", args: ["-selection", "clipboard", "-out"] });
+      commands.push({ command: "xsel", args: ["--clipboard", "--output"] });
+    }
+  }
+  return commands;
+}
+
+/**
+ * Read plain text from the clipboard, or `null` when there is none.
+ *
+ * pi's semantics, candidate for candidate: a candidate that cannot run (missing
+ * binary, non-zero exit, timeout) is skipped, but the first one that exits
+ * cleanly *answers* — even with empty output, which means "the clipboard holds
+ * no text" and must not be retried somewhere else (pi:
+ * `if (bytes !== undefined) return bytes.toString("utf8") || null`). The native
+ * helper is the final fallback and its failures read as "no text".
+ */
+export async function readClipboardText(options?: {
+  environment?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+}): Promise<string | null> {
+  const environment = options?.environment ?? process.env;
+  const platform = options?.platform ?? process.platform;
+
+  for (const candidate of textReaderCommands(platform, environment)) {
+    const result = runCommand(candidate.command, candidate.args, READ_TIMEOUT_MS);
+    if (!result.ok) {
+      continue;
+    }
+    return result.stdout.toString("utf8") || null;
+  }
+
+  try {
+    // Bounded for the same reason as the other two native reads: a helper that
+    // stops answering must not hold the keypress (and the mutex) open. A
+    // timeout reads as "no text" here, which is what the catch already means.
+    const text = await withinNativeReadDeadline(
+      getNativeClipboard()?.getText?.(),
+      "Clipboard text read",
+    );
+    return text || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clipboard text prepared for `ctx.ui.pasteToEditor`.
+ *
+ * `pasteToEditor` is not an insert: it is pi's bracketed-paste wiring,
+ * `this.editor.handleInput("\x1b[200~" + text + "\x1b[201~")`
+ * (`dist/modes/interactive/interactive-mode.js:2075`). pi-tui ends a paste at
+ * the first `\x1b[201~` it finds and re-feeds the rest of the chunk to
+ * `handleInput` as if it had been typed
+ * (`pi-tui/dist/components/editor.js:569-590`), so an escape byte arriving
+ * *from the clipboard* closes the paste early: measured, the payload
+ * `"hi\u001b[201~!echo pwned\r"` left the draft holding `"hi\n"` — the rest of
+ * the clipboard gone. pi's own text branch cannot lose it, because it writes
+ * bytes with `insertTextAtCursor` (`interactive-mode.js:2528`), and the
+ * extension API exposes no insert route — `pasteToEditor` is the only way in.
+ *
+ * So the framing byte is dropped from clipboard content and everything else
+ * is preserved verbatim. The remaining control characters need no handling
+ * here: pi-tui's paste filter already removes characters below 0x20 except
+ * `\n` and normalises line endings (`editor.js:1069-1074`, `:953-955`), which
+ * is the same treatment a paste typed at the terminal gets. (The divergence
+ * from pi is that pi *stores* those bytes; measured, pi keeps
+ * `"hi\u0000wo\u0007"` where this route gives `"hiwo"`.)
+ */
+export function clipboardTextForEditor(text: string): string {
+  return text.includes("\u001b") ? text.replace(/\u001b/g, "") : text;
+}
+
+// ── pi's path-insertion spacing rule ────────────────────────────────────────
+
+/** Where the editor cursor sits, in the same shape pi's `getCursor()` returns. */
+export interface EditorCursor {
+  line: number;
+  col: number;
+}
+
+/**
+ * pi's shell-quoting helper, verbatim from
+ * `dist/modes/interactive/interactive-mode.js:166-171`:
+ *
+ * ```js
+ * function quoteIfNeeded(value) {
+ *     if (value.length > 0 && !/[^a-zA-Z0-9_\-./~:@]/.test(value)) {
+ *         return value;
+ *     }
+ *     return `'${value.replace(/'/g, `'\\''`)}'`;
+ * }
+ * ```
+ *
+ * Re-implemented rather than imported because pi keeps it module-private in the
+ * interactive-mode bundle (used at `:182` and `:2504`, exported nowhere), and
+ * a shell-quoting divergence between the two implementations is worse than this
+ * 5-line copy with the source quoted above.
+ */
+function quoteIfNeeded(value: string): string {
+  if (value.length > 0 && !/[^a-zA-Z0-9_\-./~:@]/.test(value)) {
+    return value;
+  }
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The text to insert for a batch of clipboard file paths, built from pi's
+ * `handleClipboardPaste` (`dist/modes/interactive/interactive-mode.js:2504-2511`),
+ * quoted here so a future reader can diff it against pi rather than re-derive it:
+ *
+ * ```js
+ * const paths = this.isBashMode ? filePaths.map(quoteIfNeeded).join(" ") : filePaths.join("\n");
+ * const cursor = this.editor.getCursor?.();
+ * const currentLine = cursor ? (this.editor.getText().split("\n")[cursor.line] ?? "") : "";
+ * const characterBeforeCursor = cursor && cursor.col > 0 ? currentLine[cursor.col - 1] : "";
+ * const characterAfterCursor = cursor ? currentLine[cursor.col] : "";
+ * const leadingSpace = characterBeforeCursor && !/\s/.test(characterBeforeCursor) ? " " : "";
+ * const trailingSpace = characterAfterCursor && !/\s/.test(characterAfterCursor) ? " " : "";
+ * this.editor.insertTextAtCursor?.(`${leadingSpace}${paths}${trailingSpace}`);
+ * ```
+ *
+ * `cursor` defaults to the end of the draft. That default is the honest limit
+ * of this package, not a convenience: `ExtensionUIContext` exposes
+ * `pasteToEditor`, `setEditorText` and `getEditorText`
+ * (`dist/core/extensions/types.d.ts:132-137`) and no cursor accessor, and there
+ * is no route to the live editor instance from an extension — so an extension
+ * can read the draft but not where the caret is inside it. Everything the rule
+ * can be asked for is exact (see the per-case tests); where the caret is not at
+ * the end of the draft, pi's trailing space is the one thing we cannot know,
+ * and the run-on it would prevent is pinned as a known limitation in
+ * `paste-dispatch.test.ts` rather than hidden.
+ *
+ * pi's `isBashMode` is the draft's `!` prefix (`:2470`), so it is derived from
+ * the same draft text here.
+ */
+export function buildPathInsertion(
+  paths: readonly string[],
+  editorText: string,
+  cursor?: EditorCursor,
+): string {
+  const lines = editorText.split("\n");
+  const lastLine = lines[lines.length - 1] ?? "";
+  const at: EditorCursor = cursor ?? { line: lines.length - 1, col: lastLine.length };
+  const isBashMode = editorText.trimStart().startsWith("!");
+  const joined = isBashMode ? paths.map(quoteIfNeeded).join(" ") : paths.join("\n");
+
+  const currentLine = lines[at.line] ?? "";
+  const characterBeforeCursor = at.col > 0 ? currentLine[at.col - 1] : "";
+  const characterAfterCursor = currentLine[at.col];
+  const leadingSpace = characterBeforeCursor && !/\s/.test(characterBeforeCursor) ? " " : "";
+  const trailingSpace = characterAfterCursor && !/\s/.test(characterAfterCursor) ? " " : "";
+  return `${leadingSpace}${joined}${trailingSpace}`;
+}
+
 // ── File-based image reading ────────────────────────────────────────────────
 
 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() ?? "");
+  const extension = path.toLowerCase().split(".").pop();
+  // The set is dotted (".png"); `split(".").pop()` returns the extension bare
+  // ("png"), so the dot has to be put back — comparing them as they were left
+  // every path (including a .png) reading as "not an image".
+  return extension !== undefined && IMAGE_EXTENSIONS.has(`.${extension}`);
 }
 
 export async function readFileAsImage(filePath: string): Promise<ClipboardImage | null> {

package/src/default-export.test.ts

@@ -1,5 +1,18 @@
-import { describe, expect, it, vi } from "vitest";
-import defaultExport from "./index.js";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+// The standalone session_start handler drives the native-paste restore, so the
+// wiring test mocks that module (hermetic: nothing may touch the real
+// ~/.pi/agent/keybindings.json from a unit test) and asserts the call. The
+// shortcut gate lives in the same module and is mocked to "suite keeps the key"
+// here so this file tests wiring only; the gate itself is tested, against real
+// settings, in shortcut-gate.test.ts.
+vi.mock("./keybinding-offer.js", () => ({
+  runNativePasteRestore: vi.fn(async () => ({ kind: "suppressed" })),
+  suiteMayClaimPasteKey: vi.fn(() => true),
+}));
+
+const { runNativePasteRestore } = await import("./keybinding-offer.js");
+const defaultExport = (await import("./index.js")).default;
 
 describe("image-paste default export (standalone factory)", () => {
 	it("is a function that registers paste + per-session lifecycle on the pi extension", () => {
@@ -38,4 +51,79 @@ describe("image-paste default export (standalone factory)", () => {
 		expect(() => (startHandler as (...a: unknown[]) => unknown)({}, { hasUI: true })).not.toThrow();
 		expect(() => (shutdownHandler as (...a: unknown[]) => unknown)({}, {})).not.toThrow();
 	});
+});
+
+// ── the standalone call site for restoreNativePaste (ADR 0030 amendment) ───
+//
+// A standalone install has no meta factory, so image-paste's OWN
+// session_start registration is what hands ctrl+v back when
+// archimedes.imagePaste.suppressNativePaste is false. The handler must be
+// registered at the top level of the factory — a handler nested inside another
+// session_start accumulates on /reload (AGENTS.md).
+describe("image-paste default export — native-paste restore call site", () => {
+	beforeEach(() => {
+		vi.mocked(runNativePasteRestore).mockClear();
+	});
+
+	it("registers its session_start handler at the top level of the factory (never nested)", async () => {
+		const on = vi.fn();
+		defaultExport({ on, registerShortcut: vi.fn(), registerMessageRenderer: vi.fn() } as any);
+
+		// Registered during the factory call itself — before any session ran.
+		const countStarts = () =>
+			on.mock.calls.filter((c: Array<unknown>) => c[0] === "session_start").length;
+		const registeredByFactory = countStarts();
+		expect(registeredByFactory).toBeGreaterThanOrEqual(1);
+
+		// …and running sessions must not register MORE of them. A `pi.on`
+		// nested inside a session_start handler adds one handler per session on
+		// every /reload (AGENTS.md), which a plain "was it registered" check
+		// cannot see — the nested version registers exactly one at factory time
+		// too. This is the half of the claim that has teeth.
+		const startHandler = on.mock.calls.find((c: Array<unknown>) => c[0] === "session_start")?.[1] as (
+			event: unknown,
+			ctx: unknown,
+		) => unknown;
+		await startHandler({}, { hasUI: true });
+		await startHandler({}, { hasUI: true });
+		expect(countStarts(), "a session_start handler registered another one (nested)").toBe(
+			registeredByFactory,
+		);
+		// One call per session is the other half of the same promise.
+		expect(runNativePasteRestore).toHaveBeenCalledTimes(2);
+	});
+
+	it("runs the restore once per session_start with that session's ctx", async () => {
+		const on = vi.fn();
+		defaultExport({ on, registerShortcut: vi.fn(), registerMessageRenderer: vi.fn() } as any);
+
+		const startHandler = on.mock.calls.find((c: Array<unknown>) => c[0] === "session_start")?.[1] as (
+			event: unknown,
+			ctx: unknown,
+		) => unknown;
+		const ctx = { hasUI: true, mode: "tui" };
+		await startHandler({}, ctx);
+
+		expect(runNativePasteRestore).toHaveBeenCalledTimes(1);
+		expect(vi.mocked(runNativePasteRestore).mock.calls[0]?.[0]).toBe(ctx);
+	});
+
+	it("session_start still resolves when the restore rejects (a broken keybindings.json must not kill the session)", async () => {
+		vi.mocked(runNativePasteRestore).mockRejectedValueOnce(new Error("boom"));
+		const on = vi.fn();
+		defaultExport({ on, registerShortcut: vi.fn(), registerMessageRenderer: vi.fn() } as any);
+
+		const startHandler = on.mock.calls.find((c: Array<unknown>) => c[0] === "session_start")?.[1] as (
+			event: unknown,
+			ctx: unknown,
+		) => Promise<void>;
+
+		let thrown: unknown = null;
+		try {
+			await startHandler({}, { hasUI: true });
+		} catch (error) {
+			thrown = error;
+		}
+		expect(thrown).toBeNull();
+	});
 });