import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { fileURLToPath } from "node:url"; import { fauxAssistantMessage, fauxToolCall } from "@earendil-works/pi-ai"; import { convertToPng, copyToClipboard, createCodemodeExtension, initTheme, } from "@earendil-works/pi-coding-agent"; import { getNativeClipboard } from "@earendil-works/pi-tui"; import { Value } from "typebox/value"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { createPiSession, type PiSession, } from "../../../test/fixture/create-pi-session.ts"; import type { ClipboardParams, ClipboardValue } from "../clipboard.ts"; import clipboardExtension from "../index.ts"; vi.mock("@earendil-works/pi-coding-agent", async (original) => { const sdk = await original(); return { ...sdk, copyToClipboard: vi.fn(), convertToPng: vi.fn(sdk.convertToPng), }; }); vi.mock("@earendil-works/pi-tui", async (original) => ({ ...(await original()), getNativeClipboard: vi.fn(), })); const PNG = Buffer.from( "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aX1cAAAAASUVORK5CYII=", "base64", ); const native = { getText: vi.fn(), getImage: vi.fn(), getFilePaths: vi.fn() }; let fixture: PiSession | undefined; beforeEach(() => { vi.mocked(getNativeClipboard).mockReturnValue(native); native.getText.mockResolvedValue("private clipboard\r\n"); native.getImage.mockResolvedValue(PNG); native.getFilePaths.mockResolvedValue(["/private/file.txt"]); vi.mocked(copyToClipboard).mockResolvedValue(); }); afterEach(async () => { await fixture?.dispose(); fixture = undefined; vi.clearAllMocks(); }); async function start( pathLoaded = false, env: Record = {}, ) { initTheme("dark", false); fixture = await createPiSession({ extensionPaths: pathLoaded ? [fileURLToPath(new URL("../index.ts", import.meta.url))] : [], extensionFactories: [ ...(pathLoaded ? [] : [clipboardExtension]), createCodemodeExtension(), ], userSettings: { defaultTools: ["+codemode"] }, env: { WAYLAND_DISPLAY: undefined, XDG_SESSION_TYPE: undefined, DISPLAY: undefined, PI_CLIPBOARD_DEBUG: "0", ...env, }, }); const tool = fixture.extensions .flatMap((extension) => [...extension.tools.values()]) .find((entry) => entry.definition.name === "clipboard")?.definition; if (!tool) throw new Error("Clipboard tool missing"); const invoke = async ( params: ClipboardParams, mode: "tui" | "print" | "rpc" = "print", signal?: AbortSignal, ) => tool.execute("clipboard-test", params, signal, undefined, { ...fixture!.session.extensionRunner.createToolContext( "clipboard-test", signal, ), mode, }); return { tool, invoke }; } function value( result: Awaited>["invoke"]>>, ): ClipboardValue { return result.structuredContent as ClipboardValue; } describe("clipboard public contract", () => { it("loads through real Pi, supports direct and programmatic calls, and never accesses clipboard at startup", async () => { const { tool } = await start(true); expect(fixture!.errors).toEqual([]); expect(tool.exposure).toBe("direct"); expect(fixture!.session.getActiveToolNames()).toContain("clipboard"); expect(fixture!.session.getCallableToolNames()).toContain("clipboard"); expect(getNativeClipboard).not.toHaveBeenCalled(); expect(copyToClipboard).not.toHaveBeenCalled(); expect(tool.annotations).toMatchObject({ readOnlyHint: false, destructiveHint: true, }); }); it("uses strict action-dependent input schemas", async () => { const { tool } = await start(); for (const params of [ { action: "read" }, { action: "read", format: "image" }, { action: "copy", text: "" }, ]) expect(Value.Check(tool.parameters, params)).toBe(true); for (const params of [ { action: "copy" }, { action: "read", text: "unexpected" }, { action: "copy", text: "x", format: "text" }, { action: "read", format: "html" }, { action: "watch" }, ]) expect(Value.Check(tool.parameters, params)).toBe(false); }); it.each(["", "Unicode 界😀\t\r\n\n"])( "preserves text and validates structured output: %j", async (text) => { native.getText.mockResolvedValue(text); const { tool, invoke } = await start(); const result = await invoke({ action: "read" }); expect(value(result)).toEqual({ action: "read", format: "text", text, bytes: Buffer.byteLength(text), }); expect(Value.Check(tool.outputSchema!, result.structuredContent)).toBe( true, ); }, ); it("distinguishes absent content, unavailable backend, and sanitized transfer failures", async () => { const { invoke } = await start(); native.getText.mockResolvedValueOnce(null); expect(value(await invoke({ action: "read" }))).toMatchObject({ text: null, bytes: 0, }); native.getText.mockResolvedValueOnce(undefined); await expect(invoke({ action: "read" })).rejects.toThrow("unavailable"); native.getText.mockRejectedValueOnce(new Error("PRIVATE_RAW_ERROR")); await expect(invoke({ action: "read" })).rejects.not.toThrow( "PRIVATE_RAW_ERROR", ); vi.mocked(getNativeClipboard).mockReturnValueOnce(undefined); await expect(invoke({ action: "read" })).rejects.toThrow( "OSC 52 copy does not provide clipboard reading", ); }); it("copies exact text through Pi without returning copied contents", async () => { const { tool, invoke } = await start(); const text = "exact 😀\r\n"; const result = await invoke({ action: "copy", text }, "tui"); expect(copyToClipboard).toHaveBeenCalledExactlyOnceWith(text); expect(value(result)).toEqual({ action: "copy", bytes: Buffer.byteLength(text), }); expect(JSON.stringify(result)).not.toContain(text); expect(Value.Check(tool.outputSchema!, result.structuredContent)).toBe( true, ); await invoke({ action: "copy", text: "" }, "tui"); expect(copyToClipboard).toHaveBeenLastCalledWith(""); }); it.each(["print", "rpc"] as const)( "blocks %s copying before SDK terminal output", async (mode) => { const { invoke } = await start(); await expect( invoke({ action: "copy", text: "secret" }, mode), ).rejects.toThrow("interactive TUI"); expect(copyToClipboard).not.toHaveBeenCalled(); }, ); it("enforces byte and escaped-output limits without partial results or clipboard writes", async () => { const { invoke } = await start(); native.getText.mockResolvedValueOnce("é".repeat(16385)); await expect(invoke({ action: "read" })).rejects.toThrow("read limit"); native.getText.mockResolvedValueOnce("\0".repeat(10000)); await expect(invoke({ action: "read" })).rejects.toThrow("read limit"); await expect( invoke({ action: "copy", text: "é".repeat(32769) }, "tui"), ).rejects.toThrow("clipboard unchanged"); expect(copyToClipboard).not.toHaveBeenCalled(); }); it("returns PNG blocks for codemode image() without base64 in text content", async () => { const { tool, invoke } = await start(); const result = await invoke({ action: "read", format: "image" }); expect(value(result)).toEqual({ action: "read", format: "image", image: { type: "image", mimeType: "image/png", data: PNG.toString("base64"), }, bytes: PNG.length, }); expect( JSON.stringify(result.content.filter((part) => part.type === "text")), ).not.toContain(PNG.toString("base64")); expect(result.content).toContainEqual({ type: "image", mimeType: "image/png", data: PNG.toString("base64"), }); expect(Value.Check(tool.outputSchema!, result.structuredContent)).toBe( true, ); native.getImage.mockResolvedValueOnce(null); expect( value(await invoke({ action: "read", format: "image" })), ).toMatchObject({ image: null }); native.getImage.mockResolvedValueOnce(Buffer.alloc(4 * 1024 * 1024 + 1)); await expect(invoke({ action: "read", format: "image" })).rejects.toThrow( "4 MiB", ); }); it("rejects malformed PNGs instead of laundering them through passthrough", async () => { const { invoke } = await start(); native.getImage.mockResolvedValueOnce(PNG.subarray(0, 24)); await expect(invoke({ action: "read", format: "image" })).rejects.toThrow( "malformed", ); native.getImage.mockResolvedValueOnce(PNG.subarray(0, PNG.length - 12)); await expect(invoke({ action: "read", format: "image" })).rejects.toThrow( "malformed", ); expect(convertToPng).not.toHaveBeenCalled(); }); it("rejects PNG decode bombs declared in IHDR before any conversion", async () => { const { invoke } = await start(); const dimensions = Buffer.alloc(8); dimensions.writeUInt32BE(65535, 0); dimensions.writeUInt32BE(65535, 4); const bomb = Buffer.concat([ PNG.subarray(0, 8), Buffer.from([0, 0, 0, 13]), Buffer.from("IHDR", "latin1"), dimensions, Buffer.alloc(4), Buffer.from([ 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82, ]), ]); native.getImage.mockResolvedValueOnce(bomb); await expect(invoke({ action: "read", format: "image" })).rejects.toThrow( "pixel limit", ); expect(convertToPng).not.toHaveBeenCalled(); }); it("reports image conversion failure without exposing backend data", async () => { const { invoke } = await start(); native.getImage.mockResolvedValueOnce(Buffer.from("not-png")); vi.mocked(convertToPng).mockResolvedValueOnce(null); await expect(invoke({ action: "read", format: "image" })).rejects.toThrow( "convert", ); expect(convertToPng).toHaveBeenLastCalledWith( Buffer.from("not-png").toString("base64"), "application/octet-stream", ); }); it("returns file references without opening files, and rejects unsupported backends", async () => { const { tool, invoke } = await start(); const result = await invoke({ action: "read", format: "files" }); expect(value(result)).toMatchObject({ files: ["/private/file.txt"] }); expect(Value.Check(tool.outputSchema!, result.structuredContent)).toBe( true, ); native.getFilePaths.mockResolvedValueOnce( Array.from({ length: 129 }, () => "/x"), ); await expect(invoke({ action: "read", format: "files" })).rejects.toThrow( "limit", ); vi.mocked(getNativeClipboard).mockReturnValueOnce({ getText: native.getText, getImage: native.getImage, }); await expect(invoke({ action: "read", format: "files" })).rejects.toThrow( "currently supported on macOS", ); }); it("honors cancellation before dispatch and after native reads", async () => { const { invoke } = await start(); const controller = new AbortController(); controller.abort(new Error("PRIVATE_ABORT")); await expect( invoke({ action: "copy", text: "never" }, "tui", controller.signal), ).rejects.toThrow("cancelled"); expect(copyToClipboard).not.toHaveBeenCalled(); const pending = new AbortController(); native.getText.mockImplementationOnce(async () => { pending.abort(); return "discard"; }); await expect( invoke({ action: "read" }, "print", pending.signal), ).rejects.toThrow("cancelled"); }); it("bounds hung native backend reads with a deadline", async () => { const { invoke } = await start(); native.getText.mockImplementationOnce(() => new Promise(() => {})); await expect(invoke({ action: "read" })).rejects.toThrow("timed out"); }); it("cancels a hung native read promptly on abort", async () => { const { invoke } = await start(); let started = () => {}; const reading = new Promise((resolve) => { started = resolve; }); native.getText.mockImplementationOnce(() => { started(); return new Promise(() => {}); }); const controller = new AbortController(); const pending = invoke({ action: "read" }, "print", controller.signal); await reading; controller.abort(); await expect(pending).rejects.toThrow("cancelled"); }); it("hides contents in compact rows, reveals expanded text, and tolerates missing details", async () => { const { tool, invoke } = await start(); const result = await invoke({ action: "read" }); const theme = fixture!.session.extensionRunner.createContext().ui.theme; const context = { isError: false, showImages: false } as Parameters< NonNullable >[3]; const render = (expanded: boolean) => tool.renderResult!(result, { expanded, isPartial: false }, theme, context) .render(100) .join("\n"); expect(render(false)).not.toContain("private clipboard"); expect(render(false)).toContain("to expand"); expect(render(true)).toContain("private clipboard"); expect(() => tool.renderResult!( { content: [], details: undefined }, { expanded: false, isPartial: false }, theme, context, ).render(20), ).not.toThrow(); }); it.each(["text", "image"] as const)( "executes direct %s reads through real Pi without codemode", async (format) => { initTheme("dark", false); fixture = await createPiSession({ extensionFactories: [clipboardExtension], // Same isolation as start(): never reach the host's real clipboard tools. env: { WAYLAND_DISPLAY: undefined, XDG_SESSION_TYPE: undefined, DISPLAY: undefined, PI_CLIPBOARD_DEBUG: "0", }, }); expect(fixture.session.getActiveToolNames()).toContain("clipboard"); expect(fixture.session.getCallableToolNames()).not.toContain("codemode"); fixture.setResponses([ fauxAssistantMessage( fauxToolCall("clipboard", { action: "read", format }), { stopReason: "toolUse" }, ), fauxAssistantMessage("done"), ]); await fixture.session.prompt("Read the synthetic clipboard fixture."); const result = fixture.session.messages.find( (message) => message.role === "toolResult" && message.toolName === "clipboard", ); if (result?.role !== "toolResult") throw new Error("Missing direct clipboard result"); expect(result.isError).toBe(false); if (format === "image") expect(result.content).toContainEqual({ type: "image", mimeType: "image/png", data: PNG.toString("base64"), }); else expect(JSON.stringify(result.content)).toContain("private clipboard"); expect(fixture.errors).toEqual([]); }, ); it("returns typed clipboard data and image output through real codemode", async () => { await start(); fixture!.setResponses([ fauxAssistantMessage( fauxToolCall("codemode", { code: 'const textResult = await tools.clipboard({action:"read"}); text(textResult.text); const picture = await tools.clipboard({action:"read",format:"image"}); if(picture.image) image(picture.image);', }), { stopReason: "toolUse" }, ), fauxAssistantMessage("done"), ]); await fixture!.session.prompt("Read the synthetic clipboard fixture."); const result = fixture!.session.messages.find( (message) => message.role === "toolResult" && message.toolName === "codemode", ); expect(result?.role).toBe("toolResult"); if (result?.role !== "toolResult") throw new Error("Missing codemode result"); expect(result.isError).toBe(false); expect(result.content.some((part) => part.type === "image")).toBe(true); expect(JSON.stringify(result.content)).toContain("private clipboard"); expect(fixture!.errors).toEqual([]); }); it("writes only safe lifecycle diagnostics in the isolated test state directory", async () => { // Debug selection happens at import time, after the fixture applies env. await start(true, { PI_CLIPBOARD_DEBUG: "1" }); await fixture!.session.extensionRunner.emit({ type: "session_shutdown", reason: "quit", }); const directory = join( fixture!.env["XDG_STATE_HOME"]!, "pi-ext", "debug", "clipboard", ); const records = await vi.waitFor(async () => { const text = ( await Promise.all( ( await readdir(directory) ).map((name) => readFile(join(directory, name), "utf8")), ) ).join("\n"); expect(text).toContain("session.start"); expect(text).toContain("session.shutdown"); return text; }); expect(records).not.toContain("private clipboard"); }); }); // Exercise the real process boundary without touching the OS clipboard. describe.runIf(process.platform === "linux")( "Wayland clipboard command contract", () => { async function command(body: string) { await start(false, { WAYLAND_DISPLAY: "fake-wayland", DISPLAY: ":stale-x11", }); const bin = join(fixture!.cwd, "bin"); await mkdir(bin); const path = join(bin, "wl-paste"); await writeFile(path, `#!${process.execPath}\n${body}\n`); await chmod(path, 0o755); process.env["PATH"] = bin; const tool = fixture!.extensions[0]!.tools.get("clipboard")!.definition; return (signal?: AbortSignal, format: "text" | "image" = "text") => tool.execute( "wayland", { action: "read", format }, signal, undefined, fixture!.session.extensionRunner.createToolContext("wayland", signal), ); } it("preserves bytes and prefers UTF-8 offers without stale X11 fallback", async () => { const call = await command( 'if(process.argv.includes("--list-types")) process.stdout.write("text/plain;charset=iso-8859-1\\ntext/plain;charset=utf-8\\n"); else { if(!process.argv.includes("text/plain;charset=utf-8")) process.exit(2); process.stdout.write("wayland 界\\r\\n"); }', ); expect(value(await call())).toMatchObject({ text: "wayland 界\r\n" }); expect(getNativeClipboard).not.toHaveBeenCalled(); }); it("recognizes an empty selection, not arbitrary command failures", async () => { const call = await command( 'process.stderr.write("Nothing is copied\\n"); process.exit(1);', ); expect(value(await call())).toMatchObject({ text: null }); expect(getNativeClipboard).not.toHaveBeenCalled(); }); it("reports genuine backend failure without leaking stderr or reading X11", async () => { const call = await command( 'process.stderr.write("PRIVATE_BACKEND_FAILURE"); process.exit(1);', ); await expect(call()).rejects.toThrow("Wayland clipboard read failed"); expect(getNativeClipboard).not.toHaveBeenCalled(); }); it("does not read images as text or touch stale X11", async () => { const call = await command( 'if(process.argv.includes("--list-types")) process.stdout.write("image/png\\n"); else process.exit(2);', ); expect(value(await call())).toMatchObject({ text: null }); expect(getNativeClipboard).not.toHaveBeenCalled(); }); it("normalizes offered image MIME types and returns a PNG block", async () => { const call = await command( `if(process.argv.includes("--list-types")) process.stdout.write("IMAGE/PNG;source=test\\n"); else process.stdout.write(Buffer.from(${JSON.stringify(PNG.toString("base64"))}, "base64"));`, ); expect(value(await call(undefined, "image"))).toMatchObject({ image: { type: "image", mimeType: "image/png", data: PNG.toString("base64"), }, }); expect(getNativeClipboard).not.toHaveBeenCalled(); }); it("rejects unsupported text encodings instead of replacing characters", async () => { const call = await command( 'process.stdout.write("text/plain;charset=iso-8859-1\\n");', ); await expect(call()).rejects.toThrow("unsupported encoding"); }); it("rejects oversized process output without returning partial text", async () => { const call = await command( 'if(process.argv.includes("--list-types")) process.stdout.write("text/plain\\n"); else process.stdout.write("x".repeat(32769));', ); await expect(call()).rejects.toThrow("read limit"); }); it("cancels a pending clipboard command", async () => { const call = await command("setTimeout(() => {}, 10000);"); const controller = new AbortController(); const pending = call(controller.signal); setTimeout(() => controller.abort(), 30); await expect(pending).rejects.toThrow("cancelled"); }); }, );