@involvex/fresh-editor 0.1.76 → 0.1.78

package/bin/plugins/examples/README.md

@@ -0,0 +1,85 @@
+# Example Plugins
+
+This directory contains example plugins demonstrating the editor's plugin system. These are educational examples showing specific API features.
+
+For the complete API reference, see **[docs/plugin-api.md](../../docs/plugin-api.md)**.
+
+## Available Examples
+
+### hello_world.ts
+
+A simple "Hello World" plugin that demonstrates:
+- Registering a custom command
+- Setting status messages
+- Basic plugin structure
+
+### async_demo.ts
+
+Demonstrates async process spawning:
+- Running external commands with `spawnProcess`
+- Processing stdout/stderr
+- Handling exit codes
+
+### buffer_query_demo.ts
+
+Demonstrates buffer queries:
+- Getting buffer metadata with `getBufferInfo`
+- Listing all open buffers
+- Querying cursor and viewport information
+
+### virtual_buffer_demo.ts
+
+Demonstrates virtual buffer creation:
+- Creating virtual buffers with `createVirtualBufferInSplit`
+- Using text properties for embedded metadata
+- Defining custom modes with keybindings
+- Handling "go to" navigation from results
+
+### bookmarks.ts
+
+A complete bookmark management example:
+- Managing persistent state across sessions
+- Creating navigation commands
+- Using overlays for visual markers
+
+### git_grep.ts
+
+Git grep implementation demonstrating:
+- Spawning async git processes
+- Parsing structured output
+- Opening files at specific line:column positions
+- Interactive search with prompt API
+
+## Writing Your Own Plugin
+
+1. Create a `.ts` file in the plugins directory
+2. Use the `editor` global object to access the API
+3. Register commands with `editor.registerCommand()`
+4. The plugin will be automatically loaded when the editor starts
+
+Example template:
+
+```typescript
+/// <reference path="../types/fresh.d.ts" />
+
+// Define the command handler
+globalThis.my_command = function(): void {
+  editor.setStatus("My command executed!");
+};
+
+// Register the command
+editor.registerCommand(
+  "My Custom Command",
+  "Does something cool",
+  "my_command",
+  "normal"
+);
+
+// Initialization message
+editor.debug("My custom plugin loaded");
+```
+
+## Further Reading
+
+- **Getting Started:** [docs/PLUGIN_DEVELOPMENT.md](../../docs/PLUGIN_DEVELOPMENT.md)
+- **API Reference:** [docs/plugin-api.md](../../docs/plugin-api.md)

package/bin/plugins/examples/async_demo.ts

@@ -0,0 +1,165 @@
+/// <reference path="../../types/fresh.d.ts" />
+
+/**
+ * Async Process Demo Plugin
+ * Demonstrates spawning external processes asynchronously with async/await
+ */
+
+// Git status
+globalThis.async_git_status = async function(): Promise<void> {
+  editor.setStatus("Running git status...");
+
+  try {
+    const result = await editor.spawnProcess("git", ["status", "--short"]);
+    if (result.exit_code === 0) {
+      if (result.stdout === "" || result.stdout === "\n") {
+        editor.setStatus("Git: Working tree clean");
+      } else {
+        const count = result.stdout.split("\n").filter(line => line.trim()).length;
+        editor.setStatus(`Git: ${count} files changed`);
+      }
+    } else {
+      editor.setStatus(`Git status failed: ${result.stderr}`);
+    }
+  } catch (e) {
+    editor.setStatus(`Git status error: ${e}`);
+  }
+};
+
+editor.registerCommand(
+  "Async Demo: Git Status",
+  "Run git status and show output",
+  "async_git_status",
+  "normal"
+);
+
+// Current directory
+globalThis.async_pwd = async function(): Promise<void> {
+  try {
+    const result = await editor.spawnProcess("pwd");
+    if (result.exit_code === 0) {
+      const dir = result.stdout.trim();
+      editor.setStatus(`Current directory: ${dir}`);
+    } else {
+      editor.setStatus("pwd failed");
+    }
+  } catch (e) {
+    editor.setStatus(`pwd error: ${e}`);
+  }
+};
+
+editor.registerCommand(
+  "Async Demo: Current Directory",
+  "Show current directory using pwd",
+  "async_pwd",
+  "normal"
+);
+
+// List files
+globalThis.async_ls = async function(): Promise<void> {
+  editor.setStatus("Listing files...");
+
+  try {
+    const result = await editor.spawnProcess("ls", ["-1"]);
+    if (result.exit_code === 0) {
+      const count = result.stdout.split("\n").filter(line => line.trim()).length;
+      editor.setStatus(`Found ${count} files/directories`);
+    } else {
+      editor.setStatus("ls failed");
+    }
+  } catch (e) {
+    editor.setStatus(`ls error: ${e}`);
+  }
+};
+
+editor.registerCommand(
+  "Async Demo: List Files",
+  "List files in current directory",
+  "async_ls",
+  "normal"
+);
+
+// Git branch
+globalThis.async_git_branch = async function(): Promise<void> {
+  try {
+    const result = await editor.spawnProcess("git", ["branch", "--show-current"]);
+    if (result.exit_code === 0) {
+      const branch = result.stdout.trim();
+      if (branch !== "") {
+        editor.setStatus(`Git branch: ${branch}`);
+      } else {
+        editor.setStatus("Not on any branch (detached HEAD)");
+      }
+    } else {
+      editor.setStatus("Not a git repository");
+    }
+  } catch (e) {
+    editor.setStatus(`Git branch error: ${e}`);
+  }
+};
+
+editor.registerCommand(
+  "Async Demo: Git Branch",
+  "Show current git branch",
+  "async_git_branch",
+  "normal"
+);
+
+// Echo test
+globalThis.async_echo = async function(): Promise<void> {
+  try {
+    const result = await editor.spawnProcess("echo", ["Hello from async process!"]);
+    editor.setStatus(`Echo output: ${result.stdout.trim()}`);
+  } catch (e) {
+    editor.setStatus(`Echo error: ${e}`);
+  }
+};
+
+editor.registerCommand(
+  "Async Demo: Echo Test",
+  "Test with simple echo command",
+  "async_echo",
+  "normal"
+);
+
+// With working directory
+globalThis.async_with_cwd = async function(): Promise<void> {
+  try {
+    const result = await editor.spawnProcess("pwd", [], "/tmp");
+    const dir = result.stdout.trim();
+    editor.setStatus(`Working dir was: ${dir}`);
+  } catch (e) {
+    editor.setStatus(`pwd error: ${e}`);
+  }
+};
+
+editor.registerCommand(
+  "Async Demo: With Working Dir",
+  "Run command in /tmp directory",
+  "async_with_cwd",
+  "normal"
+);
+
+// Error handling
+globalThis.async_error = async function(): Promise<void> {
+  try {
+    const result = await editor.spawnProcess("this_command_does_not_exist");
+    if (result.exit_code !== 0) {
+      editor.setStatus(`Command failed (as expected): exit ${result.exit_code}`);
+    } else {
+      editor.setStatus("Unexpected success");
+    }
+  } catch (e) {
+    editor.setStatus(`Command failed with error: ${e}`);
+  }
+};
+
+editor.registerCommand(
+  "Async Demo: Error Handling",
+  "Demonstrate error handling with non-existent command",
+  "async_error",
+  "normal"
+);
+
+editor.setStatus("Async Demo plugin loaded! Try the 'Async Demo' commands.");
+editor.debug("Async Demo plugin initialized with native async/await support");

package/bin/plugins/examples/bookmarks.ts

@@ -0,0 +1,329 @@
+/// <reference path="../../types/fresh.d.ts" />
+
+/**
+ * Bookmarks Plugin for Fresh Editor (TypeScript)
+ *
+ * Demonstrates the new TypeScript plugin ops:
+ * - editor.registerCommand() - Register plugin commands
+ * - editor.openFile() - Open file at specific location
+ * - editor.getActiveSplitId() - Get current split ID
+ * - editor.openFileInSplit() - Open file in specific split
+ *
+ * Features:
+ * - Add bookmarks at current cursor position
+ * - List all bookmarks
+ * - Jump to bookmarks
+ * - Remove bookmarks
+ * - Split-aware navigation
+ */
+
+// Bookmark storage
+interface Bookmark {
+  id: number;
+  name: string;
+  path: string;
+  line: number;
+  column: number;
+  splitId: number;
+}
+
+const bookmarks: Map<number, Bookmark> = new Map();
+let nextBookmarkId = 1;
+
+// Helper: Get current location info
+function getCurrentLocation(): {
+  path: string;
+  position: number;
+  splitId: number;
+} {
+  const bufferId = editor.getActiveBufferId();
+  const path = editor.getBufferPath(bufferId);
+  const position = editor.getCursorPosition();
+  const splitId = editor.getActiveSplitId();
+
+  return { path, position, splitId };
+}
+
+// Helper: Get actual line number using the API
+function getCurrentLineCol(): { line: number; column: number } {
+  // Use the actual getCursorLine API for accurate line number
+  const lineNumber = editor.getCursorLine();
+
+  // Get cursor position within the line by reading buffer content
+  const bufferId = editor.getActiveBufferId();
+  const cursorPos = editor.getCursorPosition();
+  const bufferInfo = editor.getBufferInfo(bufferId);
+
+  // Calculate column by finding start of current line
+  let column = 1;
+  if (bufferInfo && cursorPos > 0) {
+    // Read a small chunk before cursor to find line start
+    const readStart = Math.max(0, cursorPos - 1000);
+    const textBefore = editor.getBufferText(bufferId, readStart, cursorPos);
+    const lastNewline = textBefore.lastIndexOf("\n");
+    if (lastNewline !== -1) {
+      column = cursorPos - (readStart + lastNewline);
+    } else {
+      // No newline found, column is position from readStart
+      column = cursorPos - readStart + 1;
+    }
+  }
+
+  return { line: lineNumber, column };
+}
+
+// Action: Add bookmark at current position
+globalThis.bookmark_add = function (): void {
+  const { path, position, splitId } = getCurrentLocation();
+  const { line, column } = getCurrentLineCol();
+
+  if (!path) {
+    editor.setStatus("Cannot bookmark: buffer has no file path");
+    return;
+  }
+
+  const id = nextBookmarkId++;
+  const name = `Bookmark ${id}`;
+
+  const bookmark: Bookmark = {
+    id,
+    name,
+    path,
+    line,
+    column,
+    splitId,
+  };
+
+  bookmarks.set(id, bookmark);
+
+  // Add visual indicator with bookmark namespace
+  const bufferId = editor.getActiveBufferId();
+  editor.addOverlay(
+    bufferId,
+    "bookmark",  // namespace for all bookmarks
+    position,
+    position + 1,
+    0, // Red
+    128, // Green (teal color)
+    255, // Blue
+    true // Underline
+  );
+
+  editor.setStatus(`Added ${name} at ${path}:${line}:${column}`);
+  editor.debug(`Bookmark ${id} created: ${JSON.stringify(bookmark)}`);
+};
+
+// Action: List all bookmarks
+globalThis.bookmark_list = function (): void {
+  if (bookmarks.size === 0) {
+    editor.setStatus("No bookmarks");
+    return;
+  }
+
+  const list: string[] = [];
+  bookmarks.forEach((bm, id) => {
+    list.push(`[${id}] ${bm.path}:${bm.line}:${bm.column}`);
+  });
+
+  editor.setStatus(`Bookmarks: ${list.join(" | ")}`);
+  editor.debug(`All bookmarks: ${JSON.stringify([...bookmarks.values()])}`);
+};
+
+// Action: Jump to bookmark by ID
+globalThis.bookmark_goto = function (): void {
+  if (bookmarks.size === 0) {
+    editor.setStatus("No bookmarks to jump to");
+    return;
+  }
+
+  // Jump to the first bookmark (simplified)
+  const firstBookmark = bookmarks.values().next().value;
+  if (firstBookmark) {
+    const success = editor.openFile(
+      firstBookmark.path,
+      firstBookmark.line,
+      firstBookmark.column
+    );
+
+    if (success) {
+      editor.setStatus(
+        `Jumped to ${firstBookmark.name}: ${firstBookmark.path}:${firstBookmark.line}`
+      );
+    } else {
+      editor.setStatus(`Failed to open ${firstBookmark.path}`);
+    }
+  }
+};
+
+// Action: Jump to bookmark in same split (split-aware)
+globalThis.bookmark_goto_split = function (): void {
+  if (bookmarks.size === 0) {
+    editor.setStatus("No bookmarks");
+    return;
+  }
+
+  const currentSplit = editor.getActiveSplitId();
+  const firstBookmark = bookmarks.values().next().value;
+
+  if (firstBookmark) {
+    // Open in the current split, not the bookmark's original split
+    const success = editor.openFileInSplit(
+      currentSplit,
+      firstBookmark.path,
+      firstBookmark.line,
+      firstBookmark.column
+    );
+
+    if (success) {
+      editor.setStatus(
+        `Opened ${firstBookmark.name} in split ${currentSplit}`
+      );
+    } else {
+      editor.setStatus(`Failed to open in split ${currentSplit}`);
+    }
+  }
+};
+
+// Action: Remove all bookmarks
+globalThis.bookmark_clear = function (): void {
+  const bufferId = editor.getActiveBufferId();
+
+  // Remove all bookmark overlays using namespace
+  editor.clearNamespace(bufferId, "bookmark");
+
+  const count = bookmarks.size;
+  bookmarks.clear();
+
+  editor.setStatus(`Cleared ${count} bookmark(s)`);
+};
+
+// Action: Show current split info
+globalThis.show_split_info = function (): void {
+  const splitId = editor.getActiveSplitId();
+  const bufferId = editor.getActiveBufferId();
+  const path = editor.getBufferPath(bufferId);
+
+  editor.setStatus(`Split ${splitId} | Buffer ${bufferId} | ${path || "[untitled]"}`);
+};
+
+// Interactive bookmark selection using prompt API
+let bookmarkSuggestionIds: number[] = [];
+
+globalThis.bookmark_select = function (): void {
+  if (bookmarks.size === 0) {
+    editor.setStatus("No bookmarks to select");
+    return;
+  }
+
+  // Create suggestions from bookmarks
+  const suggestions: PromptSuggestion[] = [];
+  bookmarkSuggestionIds = [];
+
+  bookmarks.forEach((bm) => {
+    const filename = bm.path.split("/").pop() || bm.path;
+    suggestions.push({
+      text: `${bm.name}: ${bm.path}:${bm.line}:${bm.column}`,
+      description: `${filename} at line ${bm.line}`,
+      value: String(bm.id),
+      disabled: false,
+    });
+    bookmarkSuggestionIds.push(bm.id);
+  });
+
+  editor.startPrompt("Select bookmark: ", "bookmark-select");
+  editor.setPromptSuggestions(suggestions);
+  editor.setStatus(`${bookmarks.size} bookmark(s) available`);
+};
+
+// Handle bookmark selection confirmation
+globalThis.onBookmarkSelectConfirmed = function (args: {
+  prompt_type: string;
+  selected_index: number | null;
+  input: string;
+}): boolean {
+  if (args.prompt_type !== "bookmark-select") {
+    return true;
+  }
+
+  if (args.selected_index !== null && bookmarkSuggestionIds[args.selected_index] !== undefined) {
+    const bookmarkId = bookmarkSuggestionIds[args.selected_index];
+    const bookmark = bookmarks.get(bookmarkId);
+
+    if (bookmark) {
+      editor.openFile(bookmark.path, bookmark.line, bookmark.column);
+      editor.setStatus(`Jumped to ${bookmark.name}: ${bookmark.path}:${bookmark.line}`);
+    }
+  } else {
+    editor.setStatus("No bookmark selected");
+  }
+
+  return true;
+};
+
+// Handle bookmark selection cancellation
+globalThis.onBookmarkSelectCancelled = function (args: { prompt_type: string }): boolean {
+  if (args.prompt_type !== "bookmark-select") {
+    return true;
+  }
+
+  editor.setStatus("Bookmark selection cancelled");
+  return true;
+};
+
+// Register bookmark event handlers
+editor.on("prompt_confirmed", "onBookmarkSelectConfirmed");
+editor.on("prompt_cancelled", "onBookmarkSelectCancelled");
+
+// Register commands on plugin load
+editor.registerCommand(
+  "Add Bookmark",
+  "Add a bookmark at the current cursor position",
+  "bookmark_add",
+  "normal"
+);
+
+editor.registerCommand(
+  "List Bookmarks",
+  "Show all bookmarks",
+  "bookmark_list",
+  "normal"
+);
+
+editor.registerCommand(
+  "Go to Bookmark",
+  "Jump to the first bookmark",
+  "bookmark_goto",
+  "normal"
+);
+
+editor.registerCommand(
+  "Go to Bookmark (Current Split)",
+  "Jump to bookmark in current split",
+  "bookmark_goto_split",
+  "normal"
+);
+
+editor.registerCommand(
+  "Clear Bookmarks",
+  "Remove all bookmarks",
+  "bookmark_clear",
+  "normal"
+);
+
+editor.registerCommand(
+  "Show Split Info",
+  "Display current split and buffer information",
+  "show_split_info",
+  "" // Available in all contexts
+);
+
+editor.registerCommand(
+  "Select Bookmark",
+  "Interactively select and jump to a bookmark",
+  "bookmark_select",
+  "normal"
+);
+
+// Plugin initialized
+editor.setStatus("Bookmarks plugin loaded - 7 commands registered");
+editor.debug("Bookmarks plugin initialized with command registration and prompt API support");

package/bin/plugins/examples/buffer_query_demo.ts

@@ -0,0 +1,110 @@
+/// <reference path="../../types/fresh.d.ts" />
+
+/**
+ * Buffer Query Demo Plugin
+ * Demonstrates the buffer query APIs in Phase 2
+ */
+
+// Show buffer info
+globalThis.show_buffer_info_demo = function(): void {
+  const bufferId = editor.getActiveBufferId();
+  const info = editor.getBufferInfo(bufferId);
+
+  if (info) {
+    const msg = `Buffer ${info.id}: ${info.path || "[No Name]"} (${
+      info.modified ? "modified" : "saved"
+    }, ${info.length} bytes)`;
+    editor.setStatus(msg);
+  } else {
+    editor.setStatus("No buffer info available");
+  }
+};
+
+editor.registerCommand(
+  "Query Demo: Show Buffer Info",
+  "Display information about the current buffer",
+  "show_buffer_info_demo",
+  "normal"
+);
+
+// Show cursor position with selection info
+globalThis.show_cursor_info_demo = function(): void {
+  const cursor = editor.getPrimaryCursor();
+
+  if (cursor) {
+    let msg: string;
+    if (cursor.selection) {
+      msg = `Cursor at ${cursor.position}, selection: ${cursor.selection.start}-${cursor.selection.end} (${
+        cursor.selection.end - cursor.selection.start
+      } chars)`;
+    } else {
+      msg = `Cursor at byte position ${cursor.position} (no selection)`;
+    }
+    editor.setStatus(msg);
+  } else {
+    editor.setStatus("No cursor info available");
+  }
+};
+
+editor.registerCommand(
+  "Query Demo: Show Cursor Position",
+  "Display cursor position and selection info",
+  "show_cursor_info_demo",
+  "normal"
+);
+
+// Count all cursors (multi-cursor support)
+globalThis.count_cursors_demo = function(): void {
+  const cursors = editor.getAllCursors();
+  editor.setStatus(`Active cursors: ${cursors.length}`);
+};
+
+editor.registerCommand(
+  "Query Demo: Count All Cursors",
+  "Display the number of active cursors",
+  "count_cursors_demo",
+  "normal"
+);
+
+// List all buffers
+globalThis.list_all_buffers_demo = function(): void {
+  const buffers = editor.listBuffers();
+  let modifiedCount = 0;
+
+  for (const buf of buffers) {
+    if (buf.modified) {
+      modifiedCount++;
+    }
+  }
+
+  editor.setStatus(`Open buffers: ${buffers.length} (${modifiedCount} modified)`);
+};
+
+editor.registerCommand(
+  "Query Demo: List All Buffers",
+  "Show count of open buffers",
+  "list_all_buffers_demo",
+  "normal"
+);
+
+// Show viewport info
+globalThis.show_viewport_demo = function(): void {
+  const vp = editor.getViewport();
+
+  if (vp) {
+    const msg = `Viewport: ${vp.width}x${vp.height}, top_byte=${vp.top_byte}, left_col=${vp.left_column}`;
+    editor.setStatus(msg);
+  } else {
+    editor.setStatus("No viewport info available");
+  }
+};
+
+editor.registerCommand(
+  "Query Demo: Show Viewport Info",
+  "Display viewport dimensions and scroll position",
+  "show_viewport_demo",
+  "normal"
+);
+
+editor.setStatus("Buffer Query Demo plugin loaded! Try the 'Query Demo' commands.");
+editor.debug("Buffer Query Demo plugin initialized (TypeScript version)");