pi-image-tools 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 1.0.0
+
+- Standardized repository layout to `src/` + root shim entrypoint.
+- Added TypeScript/Bundler project config, package metadata, and publish whitelist.
+- Added standard docs, license, and config template/runtime placeholder files.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MasuRii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# pi-image-tools
+
+Image attachment and preview extension for the **Pi coding agent**.
+
+This extension focuses on one workflow: quickly attach a clipboard image (or pick a recent screenshot) to the message you are about to send, and then render an inline preview in the TUI chat.
+
+> **Windows-only:** `pi-image-tools` only registers commands/shortcuts on Windows (`win32`). On macOS/Linux it does nothing.
+
+![pi-image-tools](asset/pi-image-tools.png)
+
+## Features
+
+- Paste images into your next message:
+  - `/paste-image clipboard` (default) reads an image from the clipboard and queues it for the next send.
+  - `/paste-image recent` opens a picker for recent screenshots/images and queues the selected file.
+- Keyboard shortcuts for fast paste:
+  - `alt+v`
+  - `ctrl+alt+v`
+- Inline image preview in the chat after you send your message (up to **3** images previewed per message).
+- Recent-images support:
+  - Searches common Windows screenshot locations by default.
+  - Caches images you pasted from clipboard so they also show up in the recent picker.
+- Preview modes:
+  - **Sixel** (preferred on Windows) when the PowerShell `Sixel` module is available.
+  - **Native** fallback rendering when Sixel conversion is unavailable.
+
+## Installation
+
+### Local extension folder
+
+Place this folder in:
+
+- Global: `~/.pi/agent/extensions/pi-image-tools`
+- Project: `.pi/extensions/pi-image-tools`
+
+Pi auto-discovers these paths.
+
+### As an npm package
+
+```bash
+pi install npm:pi-image-tools
+```
+
+Or from git:
+
+```bash
+pi install git:github.com/MasuRii/pi-image-tools
+```
+
+## Usage
+
+### Paste from clipboard
+
+Command:
+
+```text
+/paste-image clipboard
+```
+
+Notes:
+
+- `/paste-image` (with no args) behaves the same as `/paste-image clipboard`.
+- The extension inserts a marker into your draft (`[󰈟 Image Attached]`). When you send, that marker is removed and the queued image(s) are attached to the outgoing message.
+- If you remove all markers from your draft before sending, the pending queued images are discarded.
+
+### Paste from recent images
+
+```text
+/paste-image recent
+```
+
+This opens an interactive picker (requires Pi’s interactive TUI mode). The extension searches for recent images and shows a list like:
+
+```text
+01. Screenshot 2026-03-02 142233.png • 2m ago • 412 KB • C:\Users\...\Pictures\Screenshots\...
+```
+
+After selection, the image is queued for your next send.
+
+### Shortcuts
+
+These shortcuts are equivalent to `/paste-image clipboard`:
+
+- `alt+v`
+- `ctrl+alt+v`
+
+## Recent images: what gets searched
+
+`/paste-image recent` searches Windows paths in this order:
+
+1. The **recent cache directory** (images you pasted via clipboard are cached here).
+2. If configured via environment, the directories from `PI_IMAGE_TOOLS_RECENT_DIRS`.
+3. Otherwise, these defaults:
+   - `~/Pictures/Screenshots`
+   - `~/OneDrive/Pictures/Screenshots`
+   - `~/Desktop` (only files with screenshot-like names such as `Screenshot*`, `Snip*`, `IMG_*`, etc.)
+
+Supported file types: `.png`, `.jpg`/`.jpeg`, `.webp`, `.gif`, `.bmp`.
+
+### Environment variables
+
+- `PI_IMAGE_TOOLS_RECENT_DIRS`
+  - Semicolon-separated list of directories to search (Windows-style):
+    - Example: `C:\Users\you\Pictures\Screenshots;D:\Shares\Screens`
+- `PI_IMAGE_TOOLS_RECENT_CACHE_DIR`
+  - Overrides where clipboard-pasted images are cached.
+  - Default: `%TEMP%\pi-image-tools\recent-cache`
+
+## Preview rendering (native vs Sixel)
+
+When Pi displays a user message that contains image attachments, `pi-image-tools` renders an inline preview block under the message.
+
+- **Sixel preview (Windows):**
+  - The extension tries to detect (and, if missing, install) the PowerShell module `Sixel` under the current user.
+  - It then converts the image to a Sixel escape sequence via PowerShell and renders it inline.
+- **Native preview fallback:**
+  - If Sixel is unavailable or conversion fails, the extension renders via `@mariozechner/pi-tui`’s `Image` component.
+  - When a fallback is used, a warning line may be shown under the preview (and a one-time warning notification can appear on session start).
+
+Limit: only the first **3** images in a message are previewed.
+
+## Dependencies / PowerShell notes
+
+### Clipboard access
+
+- **Optional native module:** `@mariozechner/clipboard` (declared as an optional dependency).
+  - If it is available, `pi-image-tools` uses it first.
+- **PowerShell fallback (Windows):** if the native module is unavailable, the extension calls `powershell.exe` to read an image from the clipboard using .NET (`System.Windows.Forms.Clipboard`).
+
+### Sixel module
+
+- Sixel preview uses the **PowerShell module** `Sixel`.
+- `pi-image-tools` attempts to install it automatically (CurrentUser scope) using either `Install-Module` or `Install-PSResource` (depending on what your PowerShell supports).
+
+If your environment blocks module installation, you can install it manually (in a PowerShell prompt):
+
+```powershell
+Install-Module -Name Sixel -Scope CurrentUser -Force -AllowClobber
+```
+
+## Configuration
+
+Runtime config is stored at:
+
+```text
+~/.pi/agent/extensions/pi-image-tools/config.json
+```
+
+A starter file is included as:
+
+```text
+config/config.example.json
+```
+
+Currently the template only contains:
+
+```json
+{ "enabled": true }
+```
+
+## Troubleshooting
+
+### Nothing happens on `/paste-image` or shortcuts
+
+- This extension is **Windows-only**. On non-Windows platforms it does not register `/paste-image`.
+
+### “/paste-image recent requires interactive TUI mode.”
+
+- The recent picker uses an interactive selection UI. Run Pi in interactive mode (TUI) and retry.
+
+### “No image found in clipboard.”
+
+- Confirm you copied an actual image (not just a file path or text).
+- If clipboard reads are failing in general, PowerShell may be restricted by policy or your environment may not allow access to `System.Windows.Forms.Clipboard`.
+
+### Recent picker is empty
+
+- By default only a few directories are searched. Configure additional directories via `PI_IMAGE_TOOLS_RECENT_DIRS`.
+- Clipboard-pasted images are cached under `%TEMP%\pi-image-tools\recent-cache` (override with `PI_IMAGE_TOOLS_RECENT_CACHE_DIR`).
+
+### Preview shows a warning about Sixel
+
+- The extension falls back to native preview when the `Sixel` PowerShell module is missing or cannot be installed.
+- Install the module manually (see above) and restart Pi.
+
+## Development
+
+```bash
+npm run build
+npm run lint
+npm run test
+npm run check
+```
+
+## Project layout
+
+- `index.ts` - root Pi auto-discovery entrypoint
+- `src/commands.ts` - `/paste-image` command registration and argument handling
+- `src/keybindings.ts` - `alt+v` / `ctrl+alt+v` shortcut registration
+- `src/clipboard.ts` - clipboard image read (optional native module + PowerShell fallback)
+- `src/recent-images.ts` - recent discovery + cache management (`PI_IMAGE_TOOLS_RECENT_DIRS`, `PI_IMAGE_TOOLS_RECENT_CACHE_DIR`)
+- `src/image-preview.ts` - preview item building, Sixel conversion, and message renderer
+- `src/inline-user-preview.ts` - patches Pi TUI message rendering to show inline previews
+
+## License
+
+MIT

package/config/config.example.json

@@ -0,0 +1,3 @@
+{
+  "enabled": true
+}

package/index.ts

@@ -0,0 +1,3 @@
+import imageToolsExtension from "./src/index.js";
+
+export default imageToolsExtension;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pi-image-tools",
+  "version": "1.0.0",
+  "description": "Image attachment and rendering extension for Pi TUI",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "node --test",
+    "check": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "image",
+    "clipboard",
+    "windows"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "*"
+  }
+}

package/src/clipboard.ts

@@ -0,0 +1,117 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+import type { ClipboardImage, ClipboardModule } from "./types.js";
+
+const require = createRequire(import.meta.url);
+
+let cachedClipboardModule: ClipboardModule | null | undefined;
+
+function loadClipboardModule(): ClipboardModule | null {
+  if (cachedClipboardModule !== undefined) {
+    return cachedClipboardModule;
+  }
+
+  try {
+    cachedClipboardModule = require("@mariozechner/clipboard") as ClipboardModule;
+  } catch {
+    cachedClipboardModule = null;
+  }
+
+  return cachedClipboardModule;
+}
+
+async function readClipboardImageViaNativeModule(): Promise<ClipboardImage | null> {
+  const clipboard = loadClipboardModule();
+  if (!clipboard || !clipboard.hasImage()) {
+    return null;
+  }
+
+  const imageData = await clipboard.getImageBinary();
+  if (!imageData || imageData.length === 0) {
+    return null;
+  }
+
+  const bytes = imageData instanceof Uint8Array ? imageData : Uint8Array.from(imageData);
+  return { bytes, mimeType: "image/png" };
+}
+
+function encodePowerShell(script: string): string {
+  return Buffer.from(script, "utf16le").toString("base64");
+}
+
+function readClipboardImageViaPowerShell(): ClipboardImage | null {
+  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: 6000,
+      maxBuffer: 50 * 1024 * 1024,
+      windowsHide: true,
+    },
+  );
+
+  if (result.error || result.status !== 0) {
+    return null;
+  }
+
+  const base64 = result.stdout.trim();
+  if (!base64) {
+    return null;
+  }
+
+  try {
+    const bytes = Buffer.from(base64, "base64");
+    if (bytes.length === 0) {
+      return null;
+    }
+    return { bytes: new Uint8Array(bytes), mimeType: "image/png" };
+  } catch {
+    return null;
+  }
+}
+
+export async function readClipboardImage(platform: NodeJS.Platform = process.platform): Promise<ClipboardImage | null> {
+  if (platform !== "win32") {
+    return null;
+  }
+
+  try {
+    return (await readClipboardImageViaNativeModule()) ?? readClipboardImageViaPowerShell();
+  } catch {
+    return readClipboardImageViaPowerShell();
+  }
+}

package/src/commands.ts

@@ -0,0 +1,79 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import type { PasteImageCommandHandlers } from "./types.js";
+
+const SUBCOMMAND_CLIPBOARD = "clipboard";
+const SUBCOMMAND_RECENT = "recent";
+
+const ARGUMENT_COMPLETIONS = [
+  {
+    value: SUBCOMMAND_CLIPBOARD,
+    label: SUBCOMMAND_CLIPBOARD,
+    description: "Attach image from clipboard",
+  },
+  {
+    value: SUBCOMMAND_RECENT,
+    label: SUBCOMMAND_RECENT,
+    description: "Open recent images picker and attach selected image",
+  },
+  {
+    value: "help",
+    label: "help",
+    description: "Show usage",
+  },
+] as const;
+
+function parseArgs(args: string): string[] {
+  return args
+    .trim()
+    .split(/\s+/)
+    .map((token) => token.trim().toLowerCase())
+    .filter((token) => token.length > 0);
+}
+
+function usageMessage(): string {
+  return "Usage: /paste-image [clipboard|recent]";
+}
+
+export function registerPasteImageCommand(
+  pi: ExtensionAPI,
+  handlers: PasteImageCommandHandlers,
+): void {
+  pi.registerCommand("paste-image", {
+    description: "Attach an image from clipboard or use a recent-image picker",
+    getArgumentCompletions: (argumentPrefix) => {
+      const normalized = argumentPrefix.trim().toLowerCase();
+      if (!normalized) {
+        return [...ARGUMENT_COMPLETIONS];
+      }
+
+      const matches = ARGUMENT_COMPLETIONS.filter((item) => item.value.startsWith(normalized));
+      return matches.length > 0 ? matches.map((item) => ({ ...item })) : null;
+    },
+    handler: async (args, ctx) => {
+      const tokens = parseArgs(args);
+
+      if (tokens.length === 0 || tokens[0] === SUBCOMMAND_CLIPBOARD) {
+        await handlers.fromClipboard(ctx);
+        return;
+      }
+
+      if (tokens[0] === SUBCOMMAND_RECENT) {
+        if (tokens.length > 1) {
+          ctx.ui.notify(usageMessage(), "warning");
+          return;
+        }
+
+        await handlers.fromRecent(ctx);
+        return;
+      }
+
+      if (tokens[0] === "help") {
+        ctx.ui.notify(usageMessage(), "info");
+        return;
+      }
+
+      ctx.ui.notify(usageMessage(), "warning");
+    },
+  });
+}