apex-fast 0.0.2-next.1 → 0.0.3

package/Morph-Rules.md

@@ -0,0 +1,167 @@
+# Morph Fast Apply - AI Agent Instructions
+
+> **What is morph_edit / fastApply?** A tool that allows you to edit files using partial code snippets tagged with `// ... existing code ...` markers. Morph's AI merges your changes into the full file at 10,500+ tokens/sec with 98% accuracy.
+
+---
+
+## Choosing the Right Tool
+
+| Situation                           | Tool        | Reason                                                               |
+| ----------------------------------- | ----------- | -------------------------------------------------------------------- |
+| **Small, exact string replacement** | `edit`      | **FASTEST.** No API call, immediate execution.                       |
+| **Simple variable/function rename** | `edit`      | Precise, no AI needed.                                               |
+| **Large file (300+ lines)**         | `fastApply` | 10x faster, handles partial snippets without reading the whole file. |
+| **Multiple scattered changes**      | `fastApply` | Batch changes efficiently in one pass.                               |
+| **Complex refactoring**             | `fastApply` | AI understands context better than strict string matching.           |
+| **Whitespace-sensitive edits**      | `fastApply` | Forgiving with formatting differences.                               |
+
+### ❌ Anti-Patterns (When NOT to use fastApply)
+
+- **Do NOT** use for single-line changes (e.g., changing a port number). Use `edit`.
+- **Do NOT** use for simple typo fixes. Use `edit`.
+- **Do NOT** use for creating brand new files. Use `write`/`create`.
+
+---
+
+## Quick Reference
+
+**IMPORTANT:** Use `fastApply` over `str_replace_editor` or full file writes. It works with partial code snippets—no need for full file content.
+
+---
+
+## CRITICAL: Omitting Markers Causes Deletions
+
+**If you omit the `// ... existing code ...` markers, Morph will DELETE that code.**
+
+```javascript
+// BAD - will DELETE everything before and after the function
+function newFeature() {
+  return 'hello';
+}
+
+// GOOD - preserves existing code
+// ... existing code ...
+function newFeature() {
+  return 'hello';
+}
+// ... existing code ...
+```
+
+**Always wrap your changes with markers at the start AND end** unless you intend to replace the entire file.
+
+### 🛡️ Pre-flight Validation
+
+If you attempt a `fastApply` on a large file (>10 lines) and provide no `// ... existing code ...` markers, the plugin will **automatically reject the edit**. This failsafe prevents the AI from unintentionally wiping out entire files. Ensure your `codeEdit` param correctly utilizes markers.
+
+---
+
+## Instructions Parameter
+
+**This is critical for accuracy.** Write a first-person description of your changes.
+
+**Good:** "I am adding error handling for null users and removing the deprecated auth check"
+
+**Bad:** "Update code" / "Fix bug" / "Add stuff"
+
+---
+
+## Examples
+
+### Adding a new function
+
+```javascript
+// ... existing code ...
+import { newDep } from './newDep';
+// ... existing code ...
+
+function newFeature() {
+  return newDep.process();
+}
+// ... existing code ...
+```
+
+### Modifying existing code
+
+```javascript
+// ... existing code ...
+function existingFunc(param) {
+  // Updated implementation
+  const result = param * 2; // Changed from * 1
+  return result;
+}
+// ... existing code ...
+```
+
+### Adding a timeout to fetch (From Morph docs)
+
+```javascript
+// ... existing code ...
+export async function fetchData(endpoint: string) {
+  // ... existing code ...
+  const response = await fetch(endpoint, {
+    headers,
+    timeout: 5000  // added timeout
+  });
+  // ... existing code ...
+}
+// ... existing code ...
+```
+
+### Deleting code (Show what remains)
+
+```javascript
+// ... existing code ...
+function keepThis() {
+  return 'stays';
+}
+
+// The function between these two was removed
+
+function alsoKeepThis() {
+  return 'also stays';
+}
+// ... existing code ...
+```
+
+---
+
+## Providing Context for Disambiguation
+
+When a file has similar code patterns, include enough unique context:
+
+```javascript
+// BAD - "return result" could match many places
+// ... existing code ...
+  return result;
+}
+// ... existing code ...
+
+// GOOD - unique function signature anchors the location accurately
+// ... existing code ...
+function processUserData(userId) {
+  const result = await fetchUser(userId);
+  return result;
+}
+// ... existing code ...
+```
+
+---
+
+## Common Mistakes
+
+| Mistake                 | Result                    | Fix                                                          |
+| ----------------------- | ------------------------- | ------------------------------------------------------------ |
+| No markers at start/end | Deletes code before/after | Always start and end snippet with `// ... existing code ...` |
+| Too little context      | Wrong location chosen     | Add 1-2 unique lines around your change                      |
+| Vague instructions      | Ambiguous merge           | Be specific: what, where, why                                |
+| Using for tiny changes  | Slower than `edit`        | Use native `edit` for 1-2 line exact replacements            |
+
+---
+
+## Fallback Behavior
+
+If the Morph API fails (timeout, rate limit, etc.):
+
+1. An error message containing the specifics is returned
+2. Use the native `edit` tool as a fallback
+3. Note that the native `edit` tool requires exact string matching

package/README.md

@@ -1,33 +1,208 @@
 # apex-fast
 
-Fast Apply is a tool that you give to your AI agent that allows it to edit code or files.
+**apex-fast** is a plugin for [OpenCode AI](https://opencode.ai) that integrates [Morph Fast Apply](https://morphllm.com) — an AI model specialized for code editing boasting 10,500+ tokens/second speeds and 98% accuracy. This plugin overrides the built-in edit tool with `morph_edit`, which is significantly faster for large files and complex changes.
 
-> A Bun module created from the [bun-module](https://github.com/zenobi-us/bun-module) template
+---
 
-## Usage
+## ✨ Features
 
-<!-- Example usage code goes here -->
+- ⚡ **10x Faster** — Uses partial snippets, no need to read the entire file
+- 🧠 **Smart Routing** — Automatically selects `morph-v3-fast` or `morph-v3-large` models based on instruction complexity
+- 🔒 **Overrides `edit` Tool** — Blocks the built-in `edit` tool and directs the AI to use `fastApply` instead
+- 🛡️ **Pre-flight Validation & Readonly Agents Protection** — Prevents catastrophic accidental deletions and disables edits in `plan` or `explore` modes.
+- 🛠️ **MCP Server** — Can be run as a standalone MCP server (local via stdio or remote via SSE)
 
-## Installation
+---
 
-<!-- Installation instructions go here -->
+## 🚀 Installation
 
-## Development
+### Step 1: Get Morph API Key
 
-- `mise run build` - Build the module
-- `mise run test` - Run tests
-- `mise run lint` - Lint code
-- `mise run lint:fix` - Fix linting issues
-- `mise run format` - Format code with Prettier
+Sign up and get your API key at **[morphllm.com](https://morphllm.com)**.
 
-## Release
+---
 
-See the [RELEASE.md](RELEASE.md) file for instructions on how to release a new version of the module.
+### Step 2: Configure Plugin in OpenCode
 
-## Contributing
+Edit your `~/.config/opencode/opencode.json` file and add the plugin:
 
-Contributions are welcome! Please file issues or submit pull requests on the GitHub repository.
+```json
+{
+  "plugin": ["apex-fast@latest"],
+  "instructions": ["Follow Instructions in `~/.config/opencode/Morph-Rules.md`"]
+}
+```
 
-## License
+> **Note:** The `"instructions"` field tells the AI to read `Morph-Rules.md` as its guide on when to use `fastApply` vs other tools.
+
+---
+
+### Step 3: Install `Morph-Rules.md` _(REQUIRED)_
+
+The `Morph-Rules.md` file acts as the primary behavioral guideline for the AI. You **must** copy it into your OpenCode config directory. Without it, the AI won't know how to use `morph_edit` properly.
+
+```bash
+# Download Morph-Rules.md into your OpenCode config directory
+curl -o ~/.config/opencode/Morph-Rules.md \
+  https://raw.githubusercontent.com/yunaamelia/apex-fast/main/Morph-Rules.md
+```
+
+Alternatively, manually copy it from this repository.
+
+---
+
+### Step 4: Set Environment Variable
+
+The plugin requires the `MORPH_API_KEY` to be available in your environment.
+
+**Permanent approach (recommended):**
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+echo 'export MORPH_API_KEY="sk-your-key-here"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Or** add it directly to a `.env` file in your working directory:
+
+```env
+MORPH_API_KEY=sk-your-key-here
+```
+
+---
+
+## 🛠️ Using the `fastApply` Tool
+
+Once the plugin is active, your AI will have access to the `fastApply` tool. Use the syntax `// ... existing code ...` as a marker for unchanged code.
+
+### Parameters
+
+| Parameter      | Type     | Required | Description                                                   |
+| -------------- | -------- | -------- | ------------------------------------------------------------- |
+| `filePath`     | `string` | ✅       | Relative path to the file you want to edit                    |
+| `instructions` | `string` | ✅       | Specific instructions detailing what to change                |
+| `codeEdit`     | `string` | ❌       | Partial code snippet using `// ... existing code ...` markers |
+
+### Usage Examples
+
+**Adding a new function:**
+
+```javascript
+// ... existing code ...
+import { newDep } from './newDep';
+// ... existing code ...
+
+function newFeature() {
+  return newDep.process();
+}
+// ... existing code ...
+```
+
+**Modifying existing code:**
+
+```javascript
+// ... existing code ...
+function existingFunc(param) {
+  // Updated implementation
+  const result = param * 2; // Changed from * 1
+  return result;
+}
+// ... existing code ...
+```
+
+> ⚠️ **IMPORTANT:** Always include `// ... existing code ...` at the beginning and end of your snippet. Otherwise, Morph will **delete** the code outside of the snippet.
+
+---
+
+## 📋 Tool Selection Guide
+
+| Situation                        | Tool        | Reason                                    |
+| -------------------------------- | ----------- | ----------------------------------------- |
+| Small & exact string replacement | `edit`      | Fastest, no API call                      |
+| Simple variable/function rename  | `edit`      | Precise, no AI needed                     |
+| **Large files (300+ lines)**     | `fastApply` | 10x faster, partial snippets              |
+| **Multiple scattered changes**   | `fastApply` | Batch changes in one pass                 |
+| **Complex refactoring**          | `fastApply` | AI parses context better                  |
+| **Whitespace-sensitive edits**   | `fastApply` | High tolerance for formatting differences |
+
+---
+
+## 🖥️ Running as an MCP Server (Optional)
+
+This plugin can also run as a **standalone MCP Server** for use with other MCP clients (like Claude Desktop).
+
+### Stdio Mode (Default)
+
+```bash
+MORPH_API_KEY=sk-your-key npx apex-fast-mcp
+```
+
+### SSE Mode (Remote/HTTP)
+
+```bash
+MORPH_API_KEY=sk-your-key npx apex-fast-mcp sse 3000
+```
+
+The server will run on:
+
+- **SSE Endpoint:** `http://localhost:3000/sse`
+- **Message Endpoint:** `http://localhost:3000/message`
+
+---
+
+## ⚠️ Troubleshooting
+
+### Error: `[ERROR] Missing MORPH_API_KEY`
+
+The plugin cannot find the API key. Ensure:
+
+- The `MORPH_API_KEY` environment variable is set
+- If using `.env`, the file exists in the current working directory
+
+### Error: `[ERROR] Failed to read file`
+
+The specific `filePath` cannot be read. Ensure:
+
+- The path provided is **relative** to the current working directory
+- The file actually exists
+
+### Pre-flight Validation Error
+
+If you attempt to edit a large file (>10 lines) and omit the `// ... existing code ...` markers, the plugin will block the tool call to prevent catastrophic code loss. The AI should simply rewrite the `codeEdit` parameter correctly wrapped inside markers.
+
+### Fallback Behavior for Morph API Failure
+
+If Morph API times out or rate limits:
+
+1. The plugin will return an error message containing the specifics
+2. The AI can fall back to using the built-in `edit` tool
+3. The built-in `edit` tool requires exact string matching
+
+---
+
+## 🔧 Development
+
+```bash
+mise run build     # Build the project
+mise run test      # Run the test suite
+mise run lint      # Lint the code
+mise run lint:fix  # Automatically fix linting issues
+```
+
+---
+
+## 📦 Release
+
+See the [RELEASE.md](RELEASE.md) file for instructions on how to release a new version.
+
+---
+
+## 🤝 Contributing
+
+Contributions are very welcome! Please open an issue or submit a pull request on the GitHub repository.
+
+---
+
+## 📄 License
 
 See the [LICENSE](LICENSE) file for details.

package/dist/index.js

@@ -94,7 +94,7 @@ function isTextualFile(filePath, maxBytes = 2000000) {
 var init_chunk_YPKNMYD4 = () => {};
 
 // node_modules/@vscode/ripgrep/lib/index.js
-var __dirname = "/home/runner/work/apex-fast/apex-fast/node_modules/@vscode/ripgrep/lib", path2, $rgPath;
+var __dirname = "/home/racoondev/my-module/node_modules/@vscode/ripgrep/lib", path2, $rgPath;
 var init_lib = __esm(() => {
   path2 = __require("path");
   $rgPath = path2.join(__dirname, `../bin/rg${process.platform === "win32" ? ".exe" : ""}`);
@@ -64705,6 +64705,11 @@ var FastApplyPlugin = async (ctx) => {
           codeEdit: tool.schema.string().optional().describe("The specific code snippet to edit (optional)")
         },
         execute: async (args, context) => {
+          console.log(`[DEBUG] fastApply called for file: ${args.filePath}`);
+          const READONLY_AGENTS = ["plan", "explore"];
+          if (context && context.agent && READONLY_AGENTS.includes(context.agent)) {
+            throw new Error(`[ERROR] fastApply is not available in ${context.agent} mode. Please switch to a build/code mode.`);
+          }
           const directory = ctx?.directory || context?.directory || process.cwd();
           const absolutePath = path6.join(directory, args.filePath);
           let originalCode;
@@ -64718,6 +64723,15 @@ var FastApplyPlugin = async (ctx) => {
           }
           let result;
           try {
+            if (args.codeEdit) {
+              const lines = originalCode.split(`
+`);
+              const isLargeFile = lines.length > 10;
+              const hasMarkers = args.codeEdit.includes("... existing code ...");
+              if (isLargeFile && !hasMarkers) {
+                throw new Error("[ERROR] codeEdit missing '// ... existing code ...' markers for file >10 lines. This prevents catastrophic deletion. Please wrap partial edits with markers.");
+              }
+            }
             const { difficulty } = await morph.routers.raw.classify({
               input: args.instructions
             });
@@ -64749,6 +64763,18 @@ var FastApplyPlugin = async (ctx) => {
           }
         }
       })
+    },
+    "tool.execute.after": async (input, output) => {
+      if (input.tool === "fastApply") {
+        const fileMatch = output.output.match(/Successfully applied changes to (.+)/);
+        if (fileMatch) {
+          output.title = `Morph: applied changes to ${fileMatch[1]}`;
+        }
+        output.metadata = {
+          ...output.metadata,
+          provider: "morph"
+        };
+      }
     }
   };
 };