pi-image-tools 1.0.9 → 1.0.11

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.0.11] - 2026-04-25
+
+### Changed
+- Avoid Pi's built-in image paste shortcut by default while preserving the previous primary shortcut when users disable or rebind `app.clipboard.pasteImage` (thanks to @danielcherubini for reporting this in PR #3).
+- Replaced the placeholder `enabled` config with validated `debug`, explicit `shortcuts.pasteImage`, configurable built-in conflict avoidance, and built-in warning suppression settings.
+- Removed obsolete packaged README image assets now that the README uses a GitHub-hosted image.
+
 ## [1.0.9] - 2026-04-01
 
 ### Changed
@@ -53,12 +60,8 @@
 - Rewrote README.md with professional documentation standards
 - Added comprehensive feature documentation, configuration reference, and usage examples
 
-## 1.0.1
-
-- Included `asset/` in the npm package whitelist so README image assets ship in the tarball.
-
 ## 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.
+- Added standard docs, license, and initial runtime config files.

package/README.md

@@ -1,5 +1,7 @@
 # 🖼️ pi-image-tools
 
+[![npm version](https://img.shields.io/npm/v/pi-image-tools?style=flat-square)](https://www.npmjs.com/package/pi-image-tools) [![License](https://img.shields.io/github/license/MasuRii/pi-image-tools?style=flat-square)](LICENSE)
+
 Image attachment and preview extension for the **Pi coding agent**.
 
 `pi-image-tools` lets you attach clipboard images or recent screenshots to your next user message, then preview them inline in the TUI before the message is sent.
@@ -36,7 +38,7 @@ Place this folder in one of these locations:
 
 | Scope | Path |
 |-------|------|
-| Global | `~/.pi/agent/extensions/pi-image-tools` |
+| Global default | `~/.pi/agent/extensions/pi-image-tools` (respects `PI_CODING_AGENT_DIR`) |
 | Project | `.pi/extensions/pi-image-tools` |
 
 Pi auto-discovers extensions in those paths.
@@ -93,8 +95,16 @@ Selecting an entry queues that image for your next message.
 
 | Platform | Shortcuts |
 |----------|-----------|
-| Windows | `Alt+V`, `Ctrl+Alt+V` |
-| Linux / macOS | `Ctrl+V`, `Alt+V`, `Ctrl+Alt+V` |
+| Windows | `Ctrl+Alt+V`; `Alt+V` when Pi's built-in `app.clipboard.pasteImage` shortcut is disabled or rebound |
+| Linux / macOS | `Alt+V`, `Ctrl+Alt+V`; `Ctrl+V` when Pi's built-in `app.clipboard.pasteImage` shortcut is disabled or rebound |
+
+Pi's built-in image paste shortcut is not overridden by default. To keep the previous primary shortcut behavior without startup conflict warnings, disable the built-in binding manually in `~/.pi/agent/keybindings.json`:
+
+```json
+{
+  "app.clipboard.pasteImage": []
+}
+```
 
 ## Configuration
 
@@ -116,19 +126,93 @@ $env:PI_IMAGE_TOOLS_RECENT_DIRS = "C:\Users\me\Pictures\Screenshots;D:\Shares\Sc
 A config file can be placed at:
 
 ```text
-~/.pi/agent/extensions/pi-image-tools/config.json
+Default global path: ~/.pi/agent/extensions/pi-image-tools/config.json
+Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-image-tools/config.json when PI_CODING_AGENT_DIR is set
 ```
 
 Starter template:
 
 ```json
 {
-  "enabled": true
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
 }
 ```
 
 See `config/config.example.json` for the same template.
 
+#### Debug logging
+
+Debug logging is disabled by default. Set `debug` to `true` to append debug events to `debug/debug.log` inside the extension directory:
+
+```json
+{
+  "debug": true,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+When `debug` is `false` or omitted, no debug log file is opened or written.
+
+#### Custom shortcuts
+
+Set `shortcuts.pasteImage` to choose the exact shortcuts registered by `pi-image-tools`. The value can be a single shortcut string or an array of shortcut strings. Add multiple entries when you want several key combinations to run the same paste-image action:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v", "alt+v", "ctrl+shift+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+A single shortcut is also valid:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": "ctrl+alt+v",
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+Config changes are applied the next time the extension loads, so restart Pi or reload extensions after editing `config.json`.
+
+Not every terminal can transmit every key combination to Pi. Triple-modifier shortcuts such as `ctrl+shift+alt+v` may be intercepted by the OS, terminal, shell, SSH, or tmux before Pi can see them. If a configured shortcut does not work, try a simpler shortcut such as `ctrl+alt+v`, `ctrl+shift+v`, `alt+p`, `f8`, or another function key.
+
+Keep `shortcuts.avoidBuiltinConflicts` set to `true` to skip configured paste-image shortcuts that overlap any effective Pi built-in shortcut. Keep `shortcuts.suppressBuiltinConflictWarnings` set to `true` when your goal is specifically to remove Pi's startup conflict warning noise. Both options use the same safe mechanism: `pi-image-tools` does not register the overlapping shortcut, so Pi has nothing to warn about. For example, `ctrl+p` is skipped because Pi uses it for built-in model/session actions.
+
+If both options are `false`, Pi handles conflicts itself. Non-reserved built-in conflicts may be taken over by `pi-image-tools`, but Pi can still print a startup warning. Reserved built-in shortcuts cannot be stolen through the extension shortcut API; Pi skips those registrations before `pi-image-tools` can handle them. To use a reserved Pi shortcut, rebind or disable the relevant built-in action in `~/.pi/agent/keybindings.json`, then restart Pi or reload extensions.
+
+Use an empty array to disable the extension's paste-image shortcuts while keeping `/paste-image` available:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": [],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+If `shortcuts.pasteImage` is omitted, `pi-image-tools` uses non-conflicting defaults and automatically restores the previous primary shortcut when Pi's built-in `app.clipboard.pasteImage` binding is disabled or rebound.
+
 ## Default recent-image search locations
 
 ### Windows
@@ -199,16 +283,16 @@ pi-image-tools/
 │   ├── index.ts                # Extension bootstrap and message flow
 │   ├── commands.ts             # /paste-image command registration
 │   ├── clipboard.ts            # Cross-platform clipboard image reading
+│   ├── config.ts               # Runtime config loading and validation
+│   ├── debug-logger.ts         # File-based debug logging
 │   ├── recent-images.ts        # Recent image discovery and cache management
 │   ├── image-preview.ts        # Preview building and Sixel/native rendering
 │   ├── inline-user-preview.ts  # Inline preview patching for user messages
 │   ├── keybindings.ts          # Keyboard shortcut registration
 │   ├── temp-file.ts            # Temporary file management and cleanup
 │   └── types.ts                # Shared TypeScript types
-├── config/
-│   └── config.example.json     # Starter runtime config
-└── asset/
-    └── pi-image-tools.png      # README preview image
+└── config/
+    └── config.example.json     # Starter runtime config
 ```
 
 ## Troubleshooting

package/config/config.example.json

@@ -1,3 +1,8 @@
-{
-  "enabled": true
-}
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-image-tools",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Image attachment and rendering extension for Pi TUI",
   "type": "module",
   "main": "./index.ts",
@@ -11,7 +11,6 @@
     "index.ts",
     "src",
     "config/config.example.json",
-    "asset",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -58,10 +57,10 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.64.0",
-    "@mariozechner/pi-tui": "^0.64.0"
+    "@mariozechner/pi-coding-agent": "^0.70.2",
+    "@mariozechner/pi-tui": "^0.70.2"
   },
   "optionalDependencies": {
-    "@mariozechner/clipboard": "^0.3.2"
+    "@mariozechner/clipboard": "^0.3.3"
   }
 }

package/src/config.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { KeyId } from "@mariozechner/pi-tui";
+
+const CONFIG_FILE_NAME = "config.json";
+const EXTENSION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export interface ImageToolsShortcutConfig {
+  avoidBuiltinConflicts: boolean;
+  suppressBuiltinConflictWarnings: boolean;
+  pasteImage?: KeyId[];
+}
+
+export interface ImageToolsConfig {
+  debug: boolean;
+  shortcuts: ImageToolsShortcutConfig;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function getExtensionRoot(): string {
+  return EXTENSION_ROOT;
+}
+
+export function getConfigPath(): string {
+  return join(getExtensionRoot(), CONFIG_FILE_NAME);
+}
+
+function formatConfigPath(path: string, property: string): string {
+  return `${path}${property.length > 0 ? ` property \"${property}\"` : ""}`;
+}
+
+function parseBoolean(value: unknown, property: string, path: string): boolean {
+  if (value === undefined) {
+    return false;
+  }
+
+  if (typeof value !== "boolean") {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: expected a boolean.`);
+  }
+
+  return value;
+}
+
+function normalizeShortcut(value: unknown, property: string, path: string): KeyId {
+  if (typeof value !== "string") {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: expected a string shortcut.`);
+  }
+
+  const shortcut = value.trim();
+  if (shortcut.length === 0) {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: shortcut cannot be empty.`);
+  }
+
+  return shortcut as KeyId;
+}
+
+function parseShortcutList(value: unknown, property: string, path: string): KeyId[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const rawShortcuts = Array.isArray(value) ? value : [value];
+  const shortcuts: KeyId[] = [];
+  const seen = new Set<string>();
+
+  for (const [index, rawShortcut] of rawShortcuts.entries()) {
+    const shortcut = normalizeShortcut(rawShortcut, `${property}[${index}]`, path);
+    const normalized = shortcut.toLowerCase();
+    if (seen.has(normalized)) {
+      continue;
+    }
+
+    seen.add(normalized);
+    shortcuts.push(shortcut);
+  }
+
+  return shortcuts;
+}
+
+function parseShortcutConfig(value: unknown, path: string): ImageToolsShortcutConfig {
+  if (value === undefined) {
+    return {
+      avoidBuiltinConflicts: false,
+      suppressBuiltinConflictWarnings: false,
+    };
+  }
+
+  if (!isRecord(value)) {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, "shortcuts")}: expected an object.`);
+  }
+
+  const avoidBuiltinConflicts = parseBoolean(
+    value.avoidBuiltinConflicts,
+    "shortcuts.avoidBuiltinConflicts",
+    path,
+  );
+  const suppressBuiltinConflictWarnings = parseBoolean(
+    value.suppressBuiltinConflictWarnings,
+    "shortcuts.suppressBuiltinConflictWarnings",
+    path,
+  );
+  const pasteImage = parseShortcutList(value.pasteImage, "shortcuts.pasteImage", path);
+
+  return pasteImage === undefined
+    ? { avoidBuiltinConflicts, suppressBuiltinConflictWarnings }
+    : { avoidBuiltinConflicts, suppressBuiltinConflictWarnings, pasteImage };
+}
+
+function parseConfig(rawConfig: unknown, path: string): ImageToolsConfig {
+  if (!isRecord(rawConfig)) {
+    throw new Error(`Invalid pi-image-tools config at ${path}: expected a JSON object.`);
+  }
+
+  return {
+    debug: parseBoolean(rawConfig.debug, "debug", path),
+    shortcuts: parseShortcutConfig(rawConfig.shortcuts, path),
+  };
+}
+
+export function loadImageToolsConfig(path = getConfigPath()): ImageToolsConfig {
+  if (!existsSync(path)) {
+    return {
+      debug: false,
+      shortcuts: {
+        avoidBuiltinConflicts: false,
+        suppressBuiltinConflictWarnings: false,
+      },
+    };
+  }
+
+  try {
+    const rawConfig = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+    return parseConfig(rawConfig, path);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid pi-image-tools config at ${path}: ${error.message}`);
+    }
+
+    throw error;
+  }
+}

package/src/debug-logger.ts

@@ -0,0 +1,48 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { getExtensionRoot, type ImageToolsConfig } from "./config.js";
+
+const DEBUG_DIRECTORY_NAME = "debug";
+const DEBUG_LOG_FILE_NAME = "debug.log";
+
+type DebugFields = Record<string, unknown>;
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  return "Unknown error";
+}
+
+export class DebugLogger {
+  private readonly logPath: string | undefined;
+
+  private constructor(private readonly enabled: boolean) {
+    this.logPath = enabled ? join(getExtensionRoot(), DEBUG_DIRECTORY_NAME, DEBUG_LOG_FILE_NAME) : undefined;
+  }
+
+  static create(config: ImageToolsConfig): DebugLogger {
+    return new DebugLogger(config.debug);
+  }
+
+  log(event: string, fields: DebugFields = {}): void {
+    if (!this.enabled || !this.logPath) {
+      return;
+    }
+
+    const debugDirectory = join(getExtensionRoot(), DEBUG_DIRECTORY_NAME);
+
+    try {
+      mkdirSync(debugDirectory, { recursive: true });
+      appendFileSync(
+        this.logPath,
+        `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...fields })}\n`,
+        "utf-8",
+      );
+    } catch (error) {
+      throw new Error(`pi-image-tools debug logging failed at ${this.logPath}: ${getErrorMessage(error)}`);
+    }
+  }
+}