opencode-snippets 1.1.2 → 1.3.0

package/README.md

@@ -2,11 +2,16 @@
 
 ✨ **Instant inline text expansion for OpenCode** - Type `#snippet` anywhere in your message and watch it transform.
 
+> [!TIP]
+> **Share Your Snippets!**  
+> Got a snippet that saves you time? Share yours or steal ideas from the community!
+> Browse and contribute in [GitHub Discussions](https://github.com/JosXa/opencode-snippets/discussions/categories/snippets).
+
 ## Why Snippets?
 
 As developers, we DRY (Don't Repeat Yourself) our code. We extract functions, create libraries, compose modules. Why should our prompts be any different?
 
-Stop copy-pasting the same instructions into every message. Snippets bring software engineering principles to prompt engineering:
+Stop copy-pasting (or worse, *typing* 🤢) the same instructions into every message. Snippets bring software engineering principles to prompt engineering:
 
 - 🔄 **DRY** - Write once, reuse everywhere
 - 🧩 **Composability** - Build complex prompts from simple pieces  
@@ -29,36 +34,15 @@ Snippets work like `@file` mentions - natural, inline, composable.
 
 Snippets compose with each other and with slash commands. Reference `#snippets` anywhere - in your messages, in slash commands, even inside other snippets:
 
-**Example: Slash commands as snippet proxies**
-
-`~/.config/opencode/snippet/ralph.md`:
-```markdown
-Start a ralph loop for this. Automatically guess how many iterations it will require if not specified.
-#todofile
-Give the path of the status/todo file to the ralph task and tell to continuously update it.
-```
-
-`~/.config/opencode/command/ralph.md`:
-```markdown
----
-description: "Initiates a Ralph loop"
----
-#ralph
-
-$ARGUMENTS
-```
-
-The `/ralph` slash command simply expands the `#ralph` snippet and passes through arguments. Minimal boilerplate, maximum reuse.
-
-**Example: Extending snippets with logic**
+**Example: Extending commands with snippets**
 
 `~/.config/opencode/command/commit-and-push.md`:
 ```markdown
 ---
 description: Create a git commit and push to remote
-agent: fast
 ---
 Please create a git commit with the current changes and push to the remote repository.
+#use-conventional-commits
 
 Here is the current git status:
 !`git status`
@@ -66,11 +50,10 @@ Here is the current git status:
 Here are the staged changes:
 !`git diff --cached`
 
-#conventional-commits
 #project-context
 ```
 
-The slash command provides workflow logic (git status, diffs, push) while reusing shared snippets for commit conventions and project context.
+You could also make "current git status and staged changes" a shell-enabled snippet of its own.
 
 **Example: Snippets composing snippets**
 
@@ -106,7 +89,7 @@ Add to your `opencode.json` plugins array:
 
 ## Quick Start
 
-**1. Create a snippet file:**
+**1. Create your global snippets directory:**
 
 ```bash
 mkdir -p ~/.config/opencode/snippet
@@ -125,25 +108,13 @@ Ask clarifying questions if anything is ambiguous.
 
 **3. Use it anywhere:**
 
-```
-Refactor this function #careful
-```
-
-The LLM receives:
-```
-Refactor this function Think step by step. Double-check your work before making changes.
-Ask clarifying questions if anything is ambiguous.
-```
-
-## Features
+https://github.com/user-attachments/assets/d31b69b5-cc7a-4208-9f6e-71c1a278536a
 
-### Hashtag Expansion
+## Where to Store Snippets
 
-Any `#snippet-name` is replaced with the contents of `~/.config/opencode/snippet/snippet-name.md`:
+Snippets can be global (`~/.config/opencode/snippet/*.md`) or project-specific (`.opencode/snippet/*.md`). Both directories are loaded automatically. Project snippets override global ones with the same name, just like OpenCode's slash commands.
 
-```
-#review-checklist Please check my PR
-```
+## Features
 
 ### Aliases
 
@@ -172,7 +143,7 @@ You can also use JSON array style: `aliases: ["cp", "pick"]`
 
 ### Shell Command Substitution
 
-Snippets support the same `!`backtick\`` syntax as [OpenCode slash commands](https://opencode.ai/docs/commands/#shell-output) for injecting live command output:
+Snippets support the same ``!`command` `` syntax as [OpenCode slash commands](https://opencode.ai/docs/commands/#shell-output) for injecting live command output:
 
 ```markdown
 Current branch: !`git branch --show-current`
@@ -180,18 +151,44 @@ Last commit: !`git log -1 --oneline`
 Working directory: !`pwd`
 ```
 
+> **Note:** Snippets deviate slightly from the regular slash command behavior. Instead of just passing the command output to the LLM, snippets prepend the command itself:
+> ``!`ls` `` → 
+> ```
+> $ ls
+> --> <output>
+> ```
+> This tells the LLM which command was actually run and makes failures visible (empty output would otherwise be indistinguishable from success).
+>
+> **TODO:** This behavior should either be PR'd upstream to OpenCode or made configurable in opencode-snippets.
+
 ### Recursive Includes
 
-Snippets can include other snippets:
+Snippets can include other snippets using `#snippet-name` syntax. This allows building complex, composable snippets from smaller pieces:
 
 ```markdown
-# In base-context.md:
-#project-info
-#coding-standards
-#git-conventions
+# In base-style.md:
+Use TypeScript strict mode. Always add JSDoc comments.
+
+# In python-style.md:
+Use type hints. Follow PEP 8.
+
+# In review.md:
+Review this code carefully:
+#base-style
+#python-style
+#security-checklist
 ```
 
-Loop detection prevents infinite recursion.
+**Loop Protection:** Snippets are expanded up to 15 times per message to support deep nesting. If a circular reference is detected (e.g., `#a` includes `#b` which includes `#a`), expansion stops after 15 iterations and the remaining hashtag is left as-is. A warning is logged to help debug the issue.
+
+**Example of loop protection:**
+```markdown
+# self.md contains: "I reference #self"
+# Expanding #self produces:
+I reference I reference I reference ... (15 times) ... I reference #self
+```
+
+This generous limit supports complex snippet hierarchies while preventing infinite loops.
 
 ## Example Snippets
 
@@ -205,21 +202,6 @@ Branch: !`git branch --show-current`
 Recent changes: !`git diff --stat HEAD~3 | tail -5`
 ```
 
-### `~/.config/opencode/snippet/review.md`
-```markdown
----
-aliases:
-  - pr
-  - check
----
-Review this code for:
-- Security vulnerabilities
-- Performance issues  
-- Code style consistency
-- Missing error handling
-- Test coverage gaps
-```
-
 ### `~/.config/opencode/snippet/minimal.md`
 ```markdown
 ---
@@ -234,22 +216,29 @@ Be extremely concise. No explanations unless asked.
 
 | Feature | `/commands` | `#snippets` |
 |---------|-------------|-------------|
-| Position | Must come first | Anywhere |
-| Multiple per message | No | Yes |
-| Live shell data | Yes | Yes |
-| Best for | Triggering actions & workflows | Context injection |
-
-**Use both together:**
-```
-/commit #conventional-commits #project-context
-```
+| Position | Must come first 🏁 | Anywhere 📍 |
+| Multiple per message | No ❌ | Yes ✅ |
+| Live shell data | Yes 💻 | Yes 💻 |
+| Best for | Triggering actions & workflows ⚡ | Context injection 📝 |
+
+> [!TIP]
+> #### My recommendation:
+> 
+> Use /slash commands for **triggering actions and workflows** imperatively - anything that needs to happen _right now_: `/commit-and-push`, `/add-worktree`, or `/pull-rebase`.  
+> Use #snippets for **all other context engineering**.
+>
+> If you can't decide, get the best of both worlds and just have your command proxy through to the snippet:
+>
+> `~/.config/opencode/command/pull.md`:
+> ```markdown
+> ---
+> description: Proxy through to the snippet at snippet/pull.md
+> ---
+> #pull
+> ```
 
 ## Configuration
 
-### Snippet Directory
-
-All snippets live in `~/.config/opencode/snippet/` as `.md` files.
-
 ### Debug Logging
 
 Enable debug logs by setting an environment variable:
@@ -271,7 +260,8 @@ Logs are written to `~/.config/opencode/logs/snippets/daily/`.
 
 ## Contributing
 
-Contributions welcome! Please open an issue or PR on GitHub.
+Contributions welcome! Please open an issue or PR on GitHub. 
+👥 [Discord Forum](https://discord.com/channels/1391832426048651334/1463378026833379409)
 
 ## License
 

package/index.ts

@@ -1,33 +1,80 @@
-import type { Plugin } from "@opencode-ai/plugin"
-import { loadSnippets } from "./src/loader.js"
-import { expandHashtags } from "./src/expander.js"
-import { executeShellCommands } from "./src/shell.js"
+import type { Plugin } from "@opencode-ai/plugin";
+import { createCommandExecuteHandler } from "./src/commands.js";
+import { expandHashtags } from "./src/expander.js";
+import { loadSnippets } from "./src/loader.js";
+import { logger } from "./src/logger.js";
+import { executeShellCommands, type ShellContext } from "./src/shell.js";
 
 /**
  * Snippets Plugin for OpenCode
- * 
+ *
  * Expands hashtag-based shortcuts in user messages into predefined text snippets.
- * 
+ * Also provides /snippet command for managing snippets.
+ *
  * @see https://github.com/JosXa/opencode-snippets for full documentation
  */
 export const SnippetsPlugin: Plugin = async (ctx) => {
-  // Load all snippets at startup
-  const snippets = await loadSnippets()
+  // Load all snippets at startup (global + project directory)
+  const startupStart = performance.now();
+  const snippets = await loadSnippets(ctx.directory);
+  const startupTime = performance.now() - startupStart;
+
+  logger.debug("Plugin startup complete", {
+    startupTimeMs: startupTime.toFixed(2),
+    snippetCount: snippets.size,
+  });
+
+  // Create command handler
+  const commandHandler = createCommandExecuteHandler(ctx.client, snippets, ctx.directory);
 
   return {
-    "chat.message": async (input, output) => {
+    // Register /snippet command
+    config: async (opencodeConfig) => {
+      opencodeConfig.command ??= {};
+      opencodeConfig.command.snippet = {
+        template: "",
+        description: "Manage text snippets (create, delete, list, help)",
+      };
+    },
+
+    // Handle /snippet command execution
+    "command.execute.before": commandHandler,
+
+    "chat.message": async (_input, output) => {
       // Only process user messages, never assistant messages
-      if (output.message.role !== "user") return
-      
+      if (output.message.role !== "user") return;
+
+      const messageStart = performance.now();
+      let expandTimeTotal = 0;
+      let shellTimeTotal = 0;
+      let processedParts = 0;
+
       for (const part of output.parts) {
         if (part.type === "text" && part.text) {
           // 1. Expand hashtags recursively with loop detection
-          part.text = expandHashtags(part.text, snippets)
-          
+          const expandStart = performance.now();
+          part.text = expandHashtags(part.text, snippets);
+          const expandTime = performance.now() - expandStart;
+          expandTimeTotal += expandTime;
+
           // 2. Execute shell commands: !`command`
-          part.text = await executeShellCommands(part.text, ctx)
+          const shellStart = performance.now();
+          part.text = await executeShellCommands(part.text, ctx as unknown as ShellContext);
+          const shellTime = performance.now() - shellStart;
+          shellTimeTotal += shellTime;
+          processedParts += 1;
         }
       }
-    }
-  }
-}
+
+      const totalTime = performance.now() - messageStart;
+      if (processedParts > 0) {
+        logger.debug("Message processing complete", {
+          totalTimeMs: totalTime.toFixed(2),
+          snippetExpandTimeMs: expandTimeTotal.toFixed(2),
+          shellTimeMs: shellTimeTotal.toFixed(2),
+          processedParts,
+        });
+      }
+    },
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-snippets",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts",
   "main": "index.ts",
   "type": "module",
@@ -34,12 +34,19 @@
     "@opencode-ai/plugin": ">=1.0.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
     "@types/bun": "latest",
     "@types/node": "^22",
+    "@typescript/native-preview": "^7.0.0-dev.20260120.1",
+    "husky": "^9.1.7",
     "typescript": "^5"
   },
-  "files": [
-    "index.ts",
-    "src/**/*.ts"
-  ]
+  "scripts": {
+    "build": "tsgo --noEmit",
+    "format:check": "biome check .",
+    "format:fix": "biome check --write .",
+    "ai:check": "bun run format:fix",
+    "prepare": "husky"
+  },
+  "files": ["index.ts", "src/**/*.ts"]
 }