opencode-snippets 1.0.0 → 1.2.0

package/README.md

@@ -1,34 +1,88 @@
 # opencode-snippets
 
-**Instant inline text expansion for OpenCode** - Type `#snippet` anywhere in your message and watch it transform.
+✨ **Instant inline text expansion for OpenCode** - Type `#snippet` anywhere in your message and watch it transform.
 
 ## Why Snippets?
 
-OpenCode has powerful `/slash` commands, but they must come first in your message. What if you want to inject context *mid-thought*?
+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:
+
+- 🔄 **DRY** - Write once, reuse everywhere
+- 🧩 **Composability** - Build complex prompts from simple pieces  
+- 🔧 **Maintainability** - Update once, apply everywhere
+- 🔍 **Discoverability** - Your team's best practices, always a `#hashtag` away
+
+OpenCode's `/slash` commands must come first. Snippets work anywhere:
 
 ```
-# With slash commands (must be first):
+# Slash commands (must be first):
 /git-status Please review my changes
 
-# With snippets (anywhere!):
+# Snippets (anywhere!):
 Please review my changes #git-status and suggest improvements #code-style
 ```
 
-**Snippets work like `@file` mentions** - natural, inline, composable. Build complex prompts from reusable pieces without breaking your flow.
+Snippets work like `@file` mentions - natural, inline, composable.
+
+### 🎯 Composable by Design
+
+Snippets compose with each other and with slash commands. Reference `#snippets` anywhere - in your messages, in slash commands, even inside other snippets:
+
+**Example: Extending snippets with logic**
+
+`~/.config/opencode/command/commit-and-push.md`:
+```markdown
+---
+description: Create a git commit and push to remote
+---
+Please create a git commit with the current changes and push to the remote repository.
+
+Here is the current git status:
+!`git status`
+
+Here are the staged changes:
+!`git diff --cached`
+
+#conventional-commits
+#project-context
+```
+
+**Example: Snippets composing snippets**
+
+`~/.config/opencode/snippet/code-standards.md`:
+```markdown
+#style-guide
+#error-handling
+#testing-requirements
+```
+
+`~/.config/opencode/snippet/full-review.md`:
+```markdown
+#code-standards
+#security-checklist
+#performance-tips
+```
+
+Compose base snippets into higher-level ones. Type `#full-review` to inject all standards at once, keeping each concern in its own maintainable file.
+
+**The power:** Mix and match. Type `#tdd #careful` for test-driven development with extra caution. Build `/commit #conventional-commits #project-context` for context-aware commits. Create layered prompts from small, reusable pieces.
 
 ## Installation
 
-```bash
-# Add to your opencode.json plugins array:
-"plugins": ["opencode-snippets"]
+Add to your `opencode.json` plugins array:
 
-# Then install:
-bun install
+```json
+{
+  "plugins": [
+    "opencode-snippets"
+  ]
+}
 ```
 
 ## Quick Start
 
-**1. Create a snippet file:**
+**1. Create your global snippets directory:**
 
 ```bash
 mkdir -p ~/.config/opencode/snippet
@@ -39,7 +93,7 @@ mkdir -p ~/.config/opencode/snippet
 `~/.config/opencode/snippet/careful.md`:
 ```markdown
 ---
-aliases: ["safe", "cautious"]
+aliases: safe
 ---
 Think step by step. Double-check your work before making changes.
 Ask clarifying questions if anything is ambiguous.
@@ -48,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
 
@@ -73,7 +118,9 @@ Define multiple triggers for the same snippet:
 
 ```markdown
 ---
-aliases: ["cp", "pick"]
+aliases:
+  - cp
+  - pick
 description: "Git cherry-pick helper"
 ---
 Always pick parent 1 for merge commits.
@@ -81,9 +128,18 @@ Always pick parent 1 for merge commits.
 
 Now `#cherry-pick`, `#cp`, and `#pick` all expand to the same content.
 
+Single alias doesn't need array syntax:
+```markdown
+---
+aliases: safe
+---
+```
+
+You can also use JSON array style: `aliases: ["cp", "pick"]`
+
 ### Shell Command Substitution
 
-Inject live system data with `!`backtick\`` syntax:
+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`
@@ -91,58 +147,63 @@ Last commit: !`git log -1 --oneline`
 Working directory: !`pwd`
 ```
 
-Output:
-```
-Current branch: $ git branch --show-current
---> main
-Last commit: $ git log -1 --oneline  
---> abc123f feat: add new feature
-Working directory: $ pwd
---> /home/user/project
-```
+> **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
 
 ### `~/.config/opencode/snippet/context.md`
 ```markdown
 ---
-aliases: ["ctx"]
+aliases: ctx
 ---
 Project: !`basename $(pwd)`
 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
 ---
-aliases: ["min", "terse"]
+aliases:
+  - min
+  - terse
 ---
 Be extremely concise. No explanations unless asked.
 ```
@@ -151,23 +212,17 @@ Be extremely concise. No explanations unless asked.
 
 | Feature | `/commands` | `#snippets` |
 |---------|-------------|-------------|
-| Position | Must be first | Anywhere |
-| Multiple per message | No | Yes |
-| Live shell data | Via implementation | Built-in `!\`cmd\`` |
-| Best for | 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:
 
@@ -182,7 +237,7 @@ Logs are written to `~/.config/opencode/logs/snippets/daily/`.
 - Snippets are loaded once at plugin startup
 - Hashtag matching is **case-insensitive** (`#Hello` = `#hello`)
 - Unknown hashtags are left unchanged
-- Failed shell commands preserve the `!\`cmd\`` syntax
+- Failed shell commands preserve the original syntax in output
 - Frontmatter is stripped from expanded content
 - Only user messages are processed (not assistant responses)
 

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.0.0",
+  "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;