feat: Plugin API Completeness — file mutations, prompt editor, and attachment APIs

- WorkspaceFiles: writeFile, deleteFile, moveFile with path safety - writeFile: text/binary, auto-create dirs, overwrite option - deleteFile: idempotent, uses lstat (removes symlinks not targets) - moveFile: unix mv semantics, overwrite defaults to false - All mutations auto-refreshFiles() in File Explorer - Symlink escape prevention via realpath(dirname) check - PluginPromptEditor: insertText, getText, getSelection, onPaste, onKeyDown, focus - Uses CM6 EditorView.domEventHandlers() via Compartment (not raw DOM) - Handlers registered before mount are preserved and applied on mount - First-to-consume-wins ordering for multi-plugin scenarios - insertText replaces selection (not inserts after) - PluginAttachments: insertFileReference, getAttachedFiles, removeFileReference - insertFileReference validates file exists before inserting @path - Does not auto-focus editor (unlike prompt.insertText) - @file regex requires file extension to avoid matching emails - Server endpoints: PUT /file, DELETE /file, POST /file/move - All work for local and federated machines - Tests: 31 unit tests, 9 integration tests, 5 client tests - Docs: 3 new sections in plugins.md
2026-06-14 15:03:23 +02:00
parent 227187c4ca
commit 27a3b2b5ed
22 changed files with 1314 additions and 32 deletions
@@ -439,6 +439,7 @@ interface PluginRuntimeContext {
    selectedSession?: unknown;
    piWebStatus?: PiWebStatusResponse;
  };
+  prompt: PluginPromptEditor;
  openActionPalette: () => void;
  focusPrompt: () => void;
  addProject: () => void | Promise<void>;
@@ -464,6 +465,74 @@ Notes:
 - `openTerminal()` switches to the built-in terminal panel. Pass `{ terminalId }` to deep-link to a specific terminal.
 - Only fields documented here and declared in `plugin-api.d.ts` are stable public plugin API. Anything else is experimental: it may become public API later, change shape, or disappear.

+### Prompt editor API
+
+The `prompt` helper on `PluginRuntimeContext` provides stable access to the chat prompt editor:
+
+| Method | Description |
+| --- | --- |
+| `insertText(text)` | Insert text at cursor position. When text is selected, replaces the selection. Focuses the editor first if not focused. |
+| `getText()` | Returns the full prompt text. |
+| `getSelection()` | Returns `{ start, end, text }` if text is selected, or `null`. |
+| `onPaste(handler)` | Register a paste handler scoped to the prompt editor. Returns an unsubscribe function. Handler returns `true` to consume the event. |
+| `onKeyDown(handler)` | Register a keydown handler scoped to the prompt editor. Returns an unsubscribe function. Handler returns `true` to consume the event. |
+| `focus()` | Focus the prompt editor. |
+
+Usage:
+
+```js
+// Insert text at cursor
+context.prompt.insertText("@file.txt");
+
+// Intercept paste events
+const unsub = context.prompt.onPaste((event) => {
+  const items = event.clipboardData?.items;
+  if (items?.[0]?.type.startsWith("image/")) {
+    // Handle image paste
+    return true; // consume the event
+  }
+  return false;
+});
+// Later, when the plugin no longer needs the handler:
+unsub();
+```
+
+Handlers registered via `onPaste` and `onKeyDown` are scoped to the prompt editor using CodeMirror's extension system. They run in registration order: if a handler returns `true` to consume the event, subsequent plugin handlers for the same event will not run (first-to-consume-wins). Register handlers early if your plugin needs to intercept events before others. Handlers are automatically cleaned up when the editor is destroyed. Call the returned unsubscribe function when your plugin no longer needs the handler. Do not use `document.addEventListener` for prompt interactions — raw DOM listeners are not scoped to the editor, can leak memory, and may break across PI WEB upgrades.
+
+`focusPrompt()` on `PluginRuntimeContext` is kept for backward compatibility. `prompt.focus()` is the preferred path.
+
+### Attachment API
+
+The `attachments` helper on `PluginRuntimeContext` manages file references in the chat prompt:
+
+| Method | Description |
+| --- | --- |
+| `insertFileReference(path)` | Validate a workspace file exists and insert `@path` at the cursor. Returns the reference string. Throws if no workspace is selected or the file does not exist. |
+| `getAttachedFiles()` | Returns an array of file paths currently referenced in the prompt (without the `@` prefix). |
+| `removeFileReference(path)` | Remove the first occurrence of `@path` from the prompt. |
+
+Usage:
+
+```js
+// Save a file, then attach it
+const result = await context.files.writeFile(".pi-paste/screenshot.png", imageBytes);
+const ref = await context.attachments.insertFileReference(result.path);
+// ref is "@.pi-paste/screenshot.png"
+
+// Check what's attached
+const files = context.attachments.getAttachedFiles();
+// files is [".pi-paste/screenshot.png"]
+
+// Remove it
+context.attachments.removeFileReference(".pi-paste/screenshot.png");
+```
+
+`insertFileReference` validates the file exists using `files.readFile()` before inserting the `@path` reference. Use `files.writeFile()` to create the file first, then `attachments.insertFileReference()` to attach it.
+
+`getAttachedFiles()` uses a pattern that matches `@path/to/file.ext` — it requires a file extension (`.something`) to avoid matching email addresses like `user@example.com`. Paths are returned without the `@` prefix.
+
+`removeFileReference(path)` removes the first occurrence of `@path` in the prompt text. If the path is not found, it does nothing.
+
 #### Keyboard shortcuts

 - App-level keyboard shortcuts must be attached to actions. PI WEB does not support standalone plugin keyboard commands; contribute an action first, then add a `shortcut` if it needs a keybinding.
@@ -521,6 +590,9 @@ interface WorkspacePanelContext {
  state?: PluginRuntimeState;
  files: {
    readFile(path: string): Promise<FileContentResponse>;
+    writeFile(path: string, content: string | Uint8Array, options?: WriteWorkspaceFileOptions): Promise<WriteWorkspaceFileResponse>;
+    deleteFile(path: string): Promise<DeleteWorkspaceFileResponse>;
+    moveFile(fromPath: string, toPath: string, options?: MoveWorkspaceFileOptions): Promise<MoveWorkspaceFileResponse>;
  };
  terminal: {
    open(options?: { terminalId?: string }): void;
@@ -539,7 +611,7 @@ interface WorkspacePanelContext {

 `icon` is optional and is used in the compact mobile tab bar. Prefer an SVG rendered with the `svg` helper from `PluginActivationContext`; use `currentColor` so PI WEB themes can style it. If `icon` is omitted, mobile tabs fall back to initials from the panel title, or to the full title when initials collide.

-`machine`, `workspace`, `files`, `terminal`, and `host` are documented as stable for panel callbacks. Use `terminal.open()` to switch to the built-in terminal panel; pass `{ terminalId }` to deep-link to a specific terminal. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate panel callbacks such as `badge`, `visible`, or `render`.
+`machine`, `workspace`, `files`, `terminal`, and `host` are documented as stable for panel callbacks. The `files` helper supports `readFile`, `writeFile`, `deleteFile`, and `moveFile` — see [Reading workspace files](#reading-workspace-files) and [Writing workspace files](#writing-workspace-files). Use `terminal.open()` to switch to the built-in terminal panel; pass `{ terminalId }` to deep-link to a specific terminal. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate panel callbacks such as `badge`, `visible`, or `render`.

 For compatibility, PI WEB still provides the old `context.openTerminal()` workspace-panel helper at runtime. It is deprecated, intentionally omitted from the public TypeScript declarations, and planned for removal in v2. Existing JavaScript plugins keep working, while typed plugins should migrate to `context.terminal.open()`.

@@ -607,6 +679,9 @@ interface WorkspaceLabelContext {
  state?: PluginRuntimeState;
  files: {
    readFile(path: string): Promise<FileContentResponse>;
+    writeFile(path: string, content: string | Uint8Array, options?: WriteWorkspaceFileOptions): Promise<WriteWorkspaceFileResponse>;
+    deleteFile(path: string): Promise<DeleteWorkspaceFileResponse>;
+    moveFile(fromPath: string, toPath: string, options?: MoveWorkspaceFileOptions): Promise<MoveWorkspaceFileResponse>;
  };
  host: {
    requestRender(): void;
@@ -614,7 +689,7 @@ interface WorkspaceLabelContext {
 }
 ```

-`machine`, `workspace`, `files`, and `host` are documented as stable for label callbacks. Include `machine.id` in any label caches that depend on workspace data. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate label `visible` or `items` callbacks.
+`machine`, `workspace`, `files`, and `host` are documented as stable for label callbacks. The `files` helper supports `readFile`, `writeFile`, `deleteFile`, and `moveFile` — see [Reading workspace files](#reading-workspace-files) and [Writing workspace files](#writing-workspace-files). Include `machine.id` in any label caches that depend on workspace data. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate label `visible` or `items` callbacks.

 Items are sorted by `order` and then id. Return an empty array to render nothing. Keep callbacks synchronous and lightweight; start async work from the callback, return cached items, then call `host.requestRender()` when the cache changes.

@@ -753,6 +828,96 @@ workspaceLabels: [

 The file response includes fields such as `path`, `content`, `truncated`, and `binary`. Be careful with sensitive files such as `.env`: plugins are trusted browser code, and file contents are exposed to the plugin.

+## Writing, deleting, and moving workspace files
+
+Workspace panels and workspace labels can write, delete, and move files through the documented `files` helper. Like `readFile`, PI WEB binds these helpers to the callback's machine and workspace, so they work the same for local and federated machines.
+
+### Writing files
+
+```js
+workspacePanels: [
+  {
+    id: "workspace.generate",
+    title: "Generate",
+    render: ({ files }) => html`
+      <button @click=${async () => {
+        const result = await files.writeFile("output/result.txt", "Generated content\n");
+        console.log("Wrote", result.path, result.size, "bytes");
+      }}>Generate</button>
+    `,
+  },
+]
+```
+
+### Binary writes
+
+Pass a `Uint8Array` for binary content such as images:
+
+```js
+const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]);
+await files.writeFile("screenshots/thumb.png", png);
+```
+
+### Options
+
+`files.writeFile` accepts an optional third argument:
+
+- `createDirs` (default `true`): create intermediate directories, like `mkdir -p`.
+- `overwrite` (default `true`): overwrite existing files. Set to `false` to throw if the file already exists.
+
+```js
+// Create only — throw if the file already exists
+await files.writeFile("config/new-config.json", jsonContent, { overwrite: false });
+```
+
+### Deleting files
+
+`files.deleteFile` removes a workspace file. It is idempotent: deleting a file that does not exist returns `{ existed: false }` instead of throwing.
+
+```js
+const result = await files.deleteFile("temp/cache.json");
+console.log(result.existed ? "File deleted" : "File did not exist");
+```
+
+### Moving files
+
+`files.moveFile` renames or moves a file within the workspace, like `mv`. The default is safe: it will not overwrite an existing target file.
+
+```js
+// Rename a file
+await files.moveFile("old-name.txt", "new-name.txt");
+
+// Move into a subdirectory (creates intermediate dirs by default)
+await files.moveFile("file.txt", "archive/file.txt");
+
+// Overwrite an existing target
+await files.moveFile("incoming.txt", "current.txt", { overwrite: true });
+
+// Move without creating intermediate directories
+await files.moveFile("file.txt", "deep/nested/file.txt", { createDirs: false }); // throws if dirs don't exist
+```
+
+`files.moveFile` accepts an optional third argument:
+
+- `createDirs` (default `true`): create intermediate directories for the target path.
+- `overwrite` (default `false`): overwrite the target file if it exists. The default is safer than `writeFile` because moving is a more destructive operation.
+
+### Error handling
+
+All file mutations share the same safety layer:
+
+- `overwrite: false` on `writeFile` or existing target on `moveFile` (default) throws if the file already exists.
+- Path traversal (e.g., `../../etc/passwd`) is blocked by the workspace safety layer.
+- Writing to or moving to a path that is a directory returns an error.
+- Deleting a directory returns an error.
+- Intermediate directory creation with `createDirs: false` fails if the parent directory does not exist.
+
+After any mutation (`writeFile`, `deleteFile`, or `moveFile`), the File Explorer updates automatically. No explicit `refreshFiles()` call is needed from plugin code. For label and badge updates, call `context.host.requestRender()` if the UI should reflect the change.
+
+### Security
+
+Plugins are trusted browser code. File writes go through the same path safety validation as reads — paths are resolved and checked to stay inside the workspace root.
+
 ## Running workspace terminal commands

 Workspace panels can start terminal commands through the documented `terminal` helper. Commands run in the current workspace on the panel's machine.
@@ -801,7 +966,7 @@ If you are an AI agent building or editing a PI WEB plugin, follow this checklis
 9. Add workspace panels for larger workspace UI.
 10. Add workspace labels for compact inline metadata.
 11. Return arrays from workspace label `items()`; return an empty array to render nothing.
-12. Use documented context helpers first: `files`, `terminal`, `host.requestRender`, `workspace`, `machine`, `state.selectedWorkspace`, `state.selectedSession`, and `state.piWebStatus`.
+12. Use documented context helpers first: `files`, `terminal`, `host.requestRender`, `workspace`, `machine`, `state.selectedWorkspace`, `state.selectedSession`, `state.piWebStatus`, `prompt`, and `attachments`.
 13. Do not fetch PI WEB `/api/...` endpoints directly unless you intentionally accept private API churn; prefer documented helpers.
 14. Treat plugins as trusted code and avoid reading or displaying secrets unless intentional.
 15. After local edits, tell the user to hard reload the browser and check the console for plugin errors.
@@ -811,13 +976,13 @@ If you are an AI agent building or editing a PI WEB plugin, follow this checklis
 Check discovery:

 ```bash
-curl http://127.0.0.1:8504/pi-web-plugins/manifest.json
+curl http://localhost:8504/pi-web-plugins/manifest.json
 ```

 Check a plugin module:

 ```bash
-curl http://127.0.0.1:8504/pi-web-plugins/my-plugin/pi-web-plugin.js
+curl http://localhost:8504/pi-web-plugins/my-plugin/pi-web-plugin.js
 ```

 Common issues: