opencode-snippets 1.1.2 → 1.2.0

package/README.md

@@ -29,34 +29,12 @@ 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**
 
 `~/.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.
 
@@ -70,8 +48,6 @@ Here are the staged changes:
 #project-context
 ```
 
-The slash command provides workflow logic (git status, diffs, push) while reusing shared snippets for commit conventions and project context.
-
 **Example: Snippets composing snippets**
 
 `~/.config/opencode/snippet/code-standards.md`:
@@ -106,7 +82,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
@@ -126,24 +102,15 @@ 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.
+Refactor this function. Think step by step. Double-check your work before making changes.
 Ask clarifying questions if anything is ambiguous.
 ```
 
-## Features
-
-### 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 +139,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 +147,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-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 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
-# In base-context.md:
-#project-info
-#coding-standards
-#git-conventions
+# self.md contains: "I reference #self"
+# Expanding #self produces:
+I reference I reference I reference ... (15 times) ... I reference #self
 ```
 
-Loop detection prevents infinite recursion.
+This generous limit supports complex snippet hierarchies while preventing infinite loops.
 
 ## Example Snippets
 
@@ -205,21 +198,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,23 +212,17 @@ 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 |
+| 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
 ```
 
-## Configuration
-
-### Snippet Directory
-
-All snippets live in `~/.config/opencode/snippet/` as `.md` files.
-
-### Debug Logging
+## Configuration### Debug Logging
 
 Enable debug logs by setting an environment variable:
 

package/index.ts

@@ -1,33 +1,63 @@
-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 { 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.
- * 
+ *
  * @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,
+  });
 
   return {
-    "chat.message": async (input, output) => {
+    "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.2.0",
   "description": "Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts",
   "main": "index.ts",
   "type": "module",
@@ -34,12 +34,17 @@
     "@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",
     "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"
+  },
+  "files": ["index.ts", "src/**/*.ts"]
 }

package/src/constants.ts

@@ -1,5 +1,5 @@
-import { join } from "node:path"
-import { homedir } from "node:os"
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 /**
  * Regular expression patterns used throughout the plugin
@@ -7,15 +7,15 @@ import { homedir } from "node:os"
 export const PATTERNS = {
   /** Matches hashtags like #snippet-name */
   HASHTAG: /#([a-z0-9\-_]+)/gi,
-  
+
   /** Matches shell commands like !`command` */
   SHELL_COMMAND: /!`([^`]+)`/g,
-} as const
+} as const;
 
 /**
  * OpenCode configuration directory
  */
-export const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
+export const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode");
 
 /**
  * File system paths
@@ -23,10 +23,10 @@ export const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
 export const PATHS = {
   /** OpenCode configuration directory */
   CONFIG_DIR: OPENCODE_CONFIG_DIR,
-  
+
   /** Snippets directory */
   SNIPPETS_DIR: join(OPENCODE_CONFIG_DIR, "snippet"),
-} as const
+} as const;
 
 /**
  * Plugin configuration
@@ -34,4 +34,4 @@ export const PATHS = {
 export const CONFIG = {
   /** File extension for snippet files */
   SNIPPET_EXTENSION: ".md",
-} as const
+} as const;