@fresh-editor/fresh-editor 0.1.4

package/plugins/examples/README.md

@@ -0,0 +1,245 @@
+# Example Plugins
+
+This directory contains example plugins demonstrating the editor's plugin system.
+
+## Available Examples
+
+### hello.lua
+A simple "Hello World" plugin that demonstrates:
+- Registering a custom command
+- Setting status messages
+- Basic plugin structure
+
+### highlight_demo.lua
+Demonstrates visual overlays:
+- Multiple command registration
+- Adding colored overlays to buffers
+- Using the overlay API
+
+### git_grep_demo.lua
+Simple demo of git integration and file navigation:
+- Spawning async git processes
+- Parsing git grep output
+- Opening files at specific line:column positions
+- Basic prototype (see full plugins in parent directory)
+
+### async_demo.lua
+Demonstrates async process spawning:
+- Running external commands
+- Processing stdout/stderr
+- Handling exit codes
+
+### buffer_query_demo.lua
+Demonstrates buffer queries:
+- Getting buffer metadata
+- Listing all open buffers
+- Querying cursor and viewport information
+
+## Plugin API
+
+### Available Functions
+
+#### editor.register_command(command_table)
+Register a new command in the command palette.
+
+```lua
+editor.register_command({
+    name = "My Command",
+    description = "What this command does",
+    action = "my_command_function",  -- Name of global Lua function to call
+    contexts = {"normal"}  -- or {"help", "prompt", "popup", "file_explorer"}
+})
+
+-- Define the global function
+function my_command_function()
+    editor.set_status("My command executed!")
+end
+```
+
+The `action` field should be the name of a global Lua function that will be called when the command is executed from the command palette.
+
+#### editor.set_status(message)
+Set the status bar message.
+
+```lua
+editor.set_status("Plugin loaded successfully")
+```
+
+#### editor.insert_text(buffer_id, position, text)
+Insert text at a specific position in a buffer.
+
+```lua
+editor.insert_text(0, 0, "Hello, World!")
+```
+
+#### editor.add_overlay(buffer_id, overlay_id, start, end, r, g, b, underline)
+Add a visual overlay (highlight/underline) to a buffer.
+
+```lua
+-- Add red underline to positions 0-10 in buffer 0
+editor.add_overlay(0, "my-overlay", 0, 10, 255, 0, 0, true)
+```
+
+#### editor.on(hook_name, callback)
+Register a hook callback (currently simplified).
+
+```lua
+editor.on("after-file-save", function(args)
+    print("File saved!")
+    return true  -- return false to cancel operation
+end)
+```
+
+#### editor.spawn(command, args, callback) or editor.spawn(command, args, options, callback)
+Spawn an async process and get its output.
+
+```lua
+-- Simple form
+editor.spawn("git", {"status", "--porcelain"}, function(stdout, stderr, exit_code)
+    editor.set_status("Git status: " .. stdout)
+end)
+
+-- With options (e.g., working directory)
+editor.spawn("ls", {"-la"}, {cwd = "/tmp"}, function(stdout, stderr, exit_code)
+    print("Files: " .. stdout)
+end)
+```
+
+#### editor.open_file(path) or editor.open_file({path, line, column})
+Open a file, optionally jumping to a specific line and column.
+
+```lua
+-- Open file at start
+editor.open_file("src/main.rs")
+
+-- Open file and jump to line 42, column 10 (1-indexed)
+editor.open_file({
+    path = "src/main.rs",
+    line = 42,
+    column = 10
+})
+```
+
+This is particularly useful for implementing features like git grep, LSP go-to-definition, etc.
+
+#### editor.start_prompt(options) and editor.set_prompt_suggestions(suggestions)
+Create interactive prompts with hook-based event handling.
+
+```lua
+-- Start a prompt
+editor.start_prompt({
+    label = "Git grep: ",
+    prompt_type = "git-grep"  -- Custom identifier for hook filtering
+})
+
+-- React to input changes via hooks
+editor.on("prompt-changed", function(args)
+    if args.prompt_type == "git-grep" then
+        local query = args.input
+
+        -- Spawn async git grep
+        editor.spawn("git", {"grep", "-n", "--column", "-I", "--", query},
+            function(stdout, stderr, exit_code)
+                if exit_code == 0 then
+                    local results = parse_git_grep(stdout)
+
+                    -- Update suggestions
+                    editor.set_prompt_suggestions(results)
+                end
+            end)
+    end
+end)
+
+-- Handle selection
+editor.on("prompt-confirmed", function(args)
+    if args.prompt_type == "git-grep" and args.selected_index then
+        local selected = prompt_suggestions[args.selected_index + 1] -- Lua is 1-indexed
+        editor.open_file({
+            path = selected.file,
+            line = selected.line,
+            column = selected.column
+        })
+    end
+end)
+```
+
+Suggestions format:
+```lua
+editor.set_prompt_suggestions({
+    {
+        text = "src/main.rs:42:10: match found here",
+        value = "src/main.rs:42:10",  -- Optional: value to use when selected
+        description = "Path to file",  -- Optional
+        disabled = false,              -- Optional: grey out this suggestion
+        keybinding = nil               -- Optional: show keyboard shortcut
+    },
+    -- ... more suggestions
+})
+```
+
+This hook-based approach is simpler than callbacks and matches Emacs' extensibility model.
+
+## Available Hooks
+
+### File Hooks
+- `before-file-open` - Before a file is opened
+- `after-file-open` - After a file is successfully opened
+- `before-file-save` - Before a file is saved
+- `after-file-save` - After a file is saved
+
+### Edit Hooks
+- `after-insert` - After text is inserted
+- `after-delete` - After text is deleted
+
+### Command Hooks
+- `pre-command` - Before a command executes
+- `post-command` - After a command executes
+
+### Prompt Hooks (NEW - Jan 2025)
+- `prompt-changed` - User typed/edited prompt input (args: `prompt_type`, `input`)
+- `prompt-confirmed` - User pressed Enter (args: `prompt_type`, `input`, `selected_index`)
+- `prompt-cancelled` - User pressed Escape/Ctrl+G (args: `prompt_type`, `input`)
+
+These prompt hooks enable plugins to create interactive prompts like git grep, file finders, etc.
+
+## Writing Your Own Plugin
+
+1. Create a `.lua` file in the plugins directory
+2. Use the API functions above to add functionality
+3. The plugin will be automatically loaded when the editor starts
+
+Example template:
+
+```lua
+-- My Custom Plugin
+
+-- Register commands
+editor.register_command({
+    name = "My Custom Command",
+    description = "Does something cool",
+    action = "none",
+    contexts = {"normal"}
+})
+
+-- Add hooks if needed
+editor.on("after-file-save", function(args)
+    editor.set_status("File saved - plugin notified!")
+    return true
+end)
+
+-- Initialization message
+print("My custom plugin loaded")
+```
+
+## Testing Plugins
+
+Currently, plugins are unit tested through the plugin_manager tests. Integration tests will be added in a future update.
+
+## Future Enhancements
+
+Planned features:
+- Buffer query API (get content, cursor position, etc.)
+- Popup API (custom dialogs, menus)
+- Async task spawning (for git operations, external commands)
+- More comprehensive hook system
+- WASM plugin support for multi-language plugins

package/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");