@fresh-editor/fresh-editor 0.1.6 → 0.1.7

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "GPL-2.0",
       "name": "@fresh-editor/fresh-editor",
-      "version": "0.1.6"
+      "version": "0.1.7"
     },
     "node_modules/@isaacs/balanced-match": {
       "engines": {
@@ -896,5 +896,5 @@
     }
   },
   "requires": true,
-  "version": "0.1.6"
+  "version": "0.1.7"
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "artifactDownloadUrl": "https://github.com/sinelaw/fresh/releases/download/v0.1.6",
+  "artifactDownloadUrl": "https://github.com/sinelaw/fresh/releases/download/v0.1.7",
   "author": "Noam Lewis",
   "bin": {
     "fresh": "run-fresh.js"
@@ -92,7 +92,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.1.6",
+  "version": "0.1.7",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"

package/plugins/README.md

@@ -1,121 +1,71 @@
 # Plugins
 
-This directory contains production-ready plugins for the editor. Plugins are automatically loaded when the editor starts.
+This directory contains production-ready plugins for the editor. Plugins are written in **TypeScript** and run in a sandboxed Deno environment. They are automatically loaded when the editor starts.
 
 ## Available Plugins
 
-### TODO Highlighter (`todo_highlighter.lua`)
-
-**A complete, useful plugin demonstrating Phase 2 API capabilities.**
-
-Highlights TODO/FIXME/HACK/NOTE/XXX/BUG keywords in comments with color-coded overlays.
-
-**Features:**
-- Multi-language comment support (C/C++, Python, Lua, JavaScript, HTML, etc.)
-- Color-coded highlighting:
-  - 🟠 **TODO** - Orange (tasks to do)
-  - 🔴 **FIXME** - Red (things to fix)
-  - 🟡 **HACK** - Yellow (temporary workarounds)
-  - 🟢 **NOTE** - Green (important notes)
-  - 🟣 **XXX** - Magenta (items needing review)
-  - 🔺 **BUG** - Dark Red (known bugs)
-- Smart comment detection (only highlights keywords in comments, not in regular text)
-
-**Commands:**
-- `TODO Highlighter: Toggle` - Enable/disable highlighting
-- `TODO Highlighter: Enable` - Turn on highlighting
-- `TODO Highlighter: Disable` - Turn off and clear highlights
-- `TODO Highlighter: Refresh` - Re-scan current buffer
-- `TODO Highlighter: Show Keywords` - Display tracked keywords
-
-**Usage:**
-1. Open any file with TODO comments
-2. Press `Ctrl+P` to open command palette
-3. Type "TODO" and select `TODO Highlighter: Toggle`
-4. Keywords in comments will be highlighted!
-
-**APIs Used:**
-- Buffer Query API: `get_active_buffer_id()`, `get_buffer_content()`
-- Overlay API: `add_overlay()`, `remove_overlay()`
-- Command Registration: `register_command()`
+### Core Plugins
 
----
-
-### Git Grep (`git-grep.lua`)
-
-**Full-featured git grep with hook-based prompt API (Phase 2 - Jan 2025)**
-
-Interactive search through all git-tracked files with real-time results.
+| Plugin | Description |
+|--------|-------------|
+| `welcome.ts` | Displays welcome message on startup |
+| `manual_help.ts` | Manual page and keyboard shortcuts display |
+| `diagnostics_panel.ts` | LSP diagnostics panel with navigation |
+| `search_replace.ts` | Search and replace functionality |
+| `path_complete.ts` | Path completion in prompts |
 
-**Features:**
-- Search as you type with async git grep
-- Shows file:line:column context for each match
-- Opens files at exact match location
-- Graceful handling of empty results and errors
-- ~150 lines of Lua demonstrating prompt API
+### Git Integration
 
-**Usage:**
-```lua
-start_git_grep()  -- From Lua or keybinding
-```
-Or use command palette: "Git Grep"
-
-**APIs Used:**
-- Hook-based Prompt API: `start_prompt()`, `set_prompt_suggestions()`
-- Prompt Hooks: `prompt-changed`, `prompt-confirmed`, `prompt-cancelled`
-- Async Process: `editor.spawn()`
-- File Navigation: `editor.open_file({path, line, column})`
-
----
+| Plugin | Description |
+|--------|-------------|
+| `git_grep.ts` | Interactive search through git-tracked files |
+| `git_find_file.ts` | Fuzzy file finder for git repositories |
+| `git_blame.ts` | Git blame view with commit navigation |
+| `git_log.ts` | Git log viewer with history browsing |
 
-### Git Find File (`git-find-file.lua`)
+### Code Enhancement
 
-**Fast fuzzy file finder for git repos (Phase 2 - Jan 2025)**
+| Plugin | Description |
+|--------|-------------|
+| `todo_highlighter.ts` | Highlights TODO/FIXME/HACK keywords in comments |
+| `color_highlighter.ts` | Highlights color codes with their actual colors |
+| `find_references.ts` | Find references across the codebase |
+| `clangd_support.ts` | Clangd-specific LSP features (switch header/source) |
 
-Find and open git-tracked files with fuzzy matching, similar to Ctrl+P in VSCode.
+### Editing Modes
 
-**Features:**
-- Fuzzy file name filtering (all chars match in order)
-- Caches git ls-files for instant filtering
-- Shows up to 100 matches in real-time
-- Opens selected file or manual path
-- ~150 lines of pure Lua implementation
+| Plugin | Description |
+|--------|-------------|
+| `markdown_compose.ts` | Semi-WYSIWYG markdown editing with soft breaks |
+| `merge_conflict.ts` | 3-way merge conflict resolution |
 
-**Usage:**
-```lua
-start_git_find_file()  -- From Lua or keybinding
-```
-Or use command palette: "Git Find File"
+### Development/Testing
 
-**APIs Used:**
-- Same hook-based prompt API as git grep
-- Demonstrates reusability of prompt system
-- Pure Lua fuzzy matching algorithm
-
----
-
-### Welcome (`welcome.lua`)
-
-Simple welcome message plugin that demonstrates basic plugin loading and status messages.
-
-**Commands:**
-- Various demo commands showing basic plugin capabilities
+| Plugin | Description |
+|--------|-------------|
+| `test_view_marker.ts` | Testing utilities for view markers |
 
 ---
 
 ## Example Plugins
 
-See `examples/` directory for educational examples demonstrating specific API features:
-- `hello.lua` - Minimal plugin example
-- `highlight_demo.lua` - Overlay API demonstrations
-- `buffer_query_demo.lua` - Buffer state querying (Phase 2)
-- `async_demo.lua` - Async process spawning (Phase 2)
+The `examples/` directory contains educational examples demonstrating specific API features:
+
+| Example | Description |
+|---------|-------------|
+| `hello_world.ts` | Minimal plugin demonstrating command registration |
+| `async_demo.ts` | Async process spawning |
+| `buffer_query_demo.ts` | Buffer state querying |
+| `virtual_buffer_demo.ts` | Creating virtual buffers with text properties |
+| `bookmarks.ts` | Bookmark management example |
+| `git_grep.ts` | Git grep implementation example |
 
 ---
 
 ## Plugin Development
 
 For plugin development guides, see:
-- **Quick Start:** `../PLUGINS_QUICKSTART.md`
-- **API Reference:** `examples/README.md`
-- **Implementation:** `../docs/PLUGIN_SYSTEM_IMPLEMENTATION.md`
+- **Getting Started:** [`docs/PLUGIN_DEVELOPMENT.md`](../docs/PLUGIN_DEVELOPMENT.md)
+- **API Reference:** [`docs/plugin-api.md`](../docs/plugin-api.md)
+- **Examples:** [`examples/README.md`](examples/README.md)
+- **Clangd Plugin:** [`clangd_support.md`](clangd_support.md)

package/plugins/examples/README.md

@@ -1,245 +1,85 @@
 # Example Plugins
 
-This directory contains example plugins demonstrating the editor's plugin system.
+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.lua
+### hello_world.ts
+
 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.ts
 
-### async_demo.lua
 Demonstrates async process spawning:
-- Running external commands
+- Running external commands with `spawnProcess`
 - Processing stdout/stderr
 - Handling exit codes
 
-### buffer_query_demo.lua
+### buffer_query_demo.ts
+
 Demonstrates buffer queries:
-- Getting buffer metadata
+- Getting buffer metadata with `getBufferInfo`
 - 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.
+### virtual_buffer_demo.ts
 
-```lua
-editor.insert_text(0, 0, "Hello, World!")
-```
+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
 
-#### 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)
-```
+### bookmarks.ts
 
-#### editor.spawn(command, args, callback) or editor.spawn(command, args, options, callback)
-Spawn an async process and get its output.
+A complete bookmark management example:
+- Managing persistent state across sessions
+- Creating navigation commands
+- Using overlays for visual markers
 
-```lua
--- Simple form
-editor.spawn("git", {"status", "--porcelain"}, function(stdout, stderr, exit_code)
-    editor.set_status("Git status: " .. stdout)
-end)
+### git_grep.ts
 
--- 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.
+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 `.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
+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:
 
-```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")
-```
+```typescript
+/// <reference path="../types/fresh.d.ts" />
 
-## Testing Plugins
+// Define the command handler
+globalThis.my_command = function(): void {
+  editor.setStatus("My command executed!");
+};
 
-Currently, plugins are unit tested through the plugin_manager tests. Integration tests will be added in a future update.
+// Register the command
+editor.registerCommand(
+  "My Custom Command",
+  "Does something cool",
+  "my_command",
+  "normal"
+);
+
+// Initialization message
+editor.debug("My custom plugin loaded");
+```
 
-## Future Enhancements
+## Further Reading
 
-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
+- **Getting Started:** [docs/PLUGIN_DEVELOPMENT.md](../../docs/PLUGIN_DEVELOPMENT.md)
+- **API Reference:** [docs/plugin-api.md](../../docs/plugin-api.md)

package/plugins/lib/fresh.d.ts

@@ -91,6 +91,12 @@ interface SpawnResult {
   exit_code: number;
 }
 
+/** Result from spawnBackgroundProcess - just the process ID */
+interface BackgroundProcessResult {
+  /** Unique process ID for later reference (kill, status check) */
+  process_id: number;
+}
+
 /** File stat information */
 interface FileStat {
   /** Whether the path exists */
@@ -322,6 +328,13 @@ interface EditorAPI {
    * is typically first. For selection info use getAllCursors instead.
    */
   getAllCursorPositions(): number[];
+  /**
+   * Check if a background process is still running
+   *
+   * @param process_id - ID returned from spawnBackgroundProcess
+   * @returns true if process is running, false if not found or exited
+   */
+  isProcessRunning(#[bigint] process_id: number): boolean;
 
   // === Buffer Info Queries ===
   /**
@@ -419,7 +432,7 @@ interface EditorAPI {
    * @param priority - Priority for ordering multiple lines at same position
    * @returns true if virtual line was added
    */
-  addVirtualLine(buffer_id: number, position: number, text: string, fg_r: number, fg_g: number, fg_b: number, bg_r: number, bg_g: number, bg_b: number, above: boolean, namespace: string, priority: number): boolean;
+  addVirtualLine(buffer_id: number, position: number, text: string, fg_r: number, fg_g: number, fg_b: number, bg_r: i16, bg_g: i16, bg_b: i16, above: boolean, namespace: string, priority: number): boolean;
   /**
    * Submit a transformed view stream for a viewport
    * @param buffer_id - Buffer to apply the transform to
@@ -475,6 +488,34 @@ interface EditorAPI {
    * @returns true if file was opened
    */
   openFileInSplit(split_id: number, path: string, line: number, column: number): boolean;
+  /**
+   * Spawn a long-running background process
+   *
+   * Unlike spawnProcess which waits for completion, this starts a process
+   * in the background and returns immediately with a process ID.
+   * Use killProcess(id) to terminate the process later.
+   * Use isProcessRunning(id) to check if it's still running.
+   *
+   * @param command - Program name (searched in PATH) or absolute path
+   * @param args - Command arguments (each array element is one argument)
+   * @param cwd - Working directory; null uses editor's cwd
+   * @returns Object with process_id for later reference
+   * @example
+   * const proc = await editor.spawnBackgroundProcess("asciinema", ["rec", "output.cast"]);
+   * // Later...
+   * await editor.killProcess(proc.process_id);
+   */
+  spawnBackgroundProcess(command: string, args: string[], cwd?: string | null): Promise<BackgroundProcessResult>;
+  /**
+   * Kill a background process by ID
+   *
+   * Sends SIGTERM to gracefully terminate the process.
+   * Returns true if the process was found and killed, false if not found.
+   *
+   * @param process_id - ID returned from spawnBackgroundProcess
+   * @returns true if process was killed, false if not found
+   */
+  killProcess(#[bigint] process_id: number): Promise<boolean>;
   /**
    * Send an arbitrary LSP request and receive the raw JSON response
    * @param language - Language ID (e.g., "cpp")