opencode-snippets 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JosXa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# opencode-snippets
+
+**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*?
+
+```
+# With slash commands (must be first):
+/git-status Please review my changes
+
+# With 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.
+
+## Installation
+
+```bash
+# Add to your opencode.json plugins array:
+"plugins": ["opencode-snippets"]
+
+# Then install:
+bun install
+```
+
+## Quick Start
+
+**1. Create a snippet file:**
+
+```bash
+mkdir -p ~/.config/opencode/snippet
+```
+
+**2. Add your first snippet:**
+
+`~/.config/opencode/snippet/careful.md`:
+```markdown
+---
+aliases: ["safe", "cautious"]
+---
+Think step by step. Double-check your work before making changes.
+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
+
+### Hashtag Expansion
+
+Any `#snippet-name` is replaced with the contents of `~/.config/opencode/snippet/snippet-name.md`:
+
+```
+#review-checklist Please check my PR
+```
+
+### Aliases
+
+Define multiple triggers for the same snippet:
+
+```markdown
+---
+aliases: ["cp", "pick"]
+description: "Git cherry-pick helper"
+---
+Always pick parent 1 for merge commits.
+```
+
+Now `#cherry-pick`, `#cp`, and `#pick` all expand to the same content.
+
+### Shell Command Substitution
+
+Inject live system data with `!`backtick\`` syntax:
+
+```markdown
+Current branch: !`git branch --show-current`
+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
+```
+
+### Recursive Includes
+
+Snippets can include other snippets:
+
+```markdown
+# In base-context.md:
+#project-info
+#coding-standards
+#git-conventions
+```
+
+Loop detection prevents infinite recursion.
+
+## Example Snippets
+
+### `~/.config/opencode/snippet/context.md`
+```markdown
+---
+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"]
+---
+Be extremely concise. No explanations unless asked.
+```
+
+## Snippets vs Slash Commands
+
+| 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 |
+
+**Use both together:**
+```
+/commit #conventional-commits #project-context
+```
+
+## Configuration
+
+### Snippet Directory
+
+All snippets live in `~/.config/opencode/snippet/` as `.md` files.
+
+### Debug Logging
+
+Enable debug logs by setting an environment variable:
+
+```bash
+DEBUG_SNIPPETS=true opencode
+```
+
+Logs are written to `~/.config/opencode/logs/snippets/daily/`.
+
+## Behavior Notes
+
+- 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
+- Frontmatter is stripped from expanded content
+- Only user messages are processed (not assistant responses)
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on GitHub.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,33 @@
+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"
+
+/**
+ * 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()
+
+  return {
+    "chat.message": async (input, output) => {
+      // Only process user messages, never assistant messages
+      if (output.message.role !== "user") return
+      
+      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)
+          
+          // 2. Execute shell commands: !`command`
+          part.text = await executeShellCommands(part.text, ctx)
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "opencode-snippets",
+  "version": "1.0.0",
+  "description": "Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts",
+  "main": "index.ts",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "snippets",
+    "templates",
+    "shortcuts",
+    "ai",
+    "coding-assistant"
+  ],
+  "author": "JosXa <info@josxa.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JosXa/opencode-snippets.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JosXa/opencode-snippets/issues"
+  },
+  "homepage": "https://github.com/JosXa/opencode-snippets#readme",
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^22",
+    "typescript": "^5"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts"
+  ]
+}

package/src/constants.ts

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

package/src/expander.ts

@@ -0,0 +1,57 @@
+import type { SnippetRegistry } from "./types.js"
+import { PATTERNS } from "./constants.js"
+
+/**
+ * Expands hashtags in text recursively with loop detection
+ * 
+ * @param text - The text containing hashtags to expand
+ * @param registry - The snippet registry to look up hashtags
+ * @param visited - Set of already-visited snippet keys (for loop detection)
+ * @returns The text with all hashtags expanded
+ */
+export function expandHashtags(
+  text: string,
+  registry: SnippetRegistry,
+  visited = new Set<string>()
+): string {
+  let expanded = text
+  let hasChanges = true
+  
+  // Keep expanding until no more hashtags are found
+  while (hasChanges) {
+    hasChanges = false
+    
+    // Reset regex state (global flag requires this)
+    PATTERNS.HASHTAG.lastIndex = 0
+    
+    expanded = expanded.replace(PATTERNS.HASHTAG, (match, name) => {
+      const key = name.toLowerCase()
+      
+      // Check if we've already expanded this snippet in the current chain
+      if (visited.has(key)) {
+        // Loop detected! Leave the hashtag unchanged to prevent infinite recursion
+        return match
+      }
+      
+      const content = registry.get(key)
+      if (!content) {
+        // Unknown snippet - leave as-is
+        return match
+      }
+      
+      // Mark this snippet as visited and expand it
+      visited.add(key)
+      hasChanges = true
+      
+      // Recursively expand any hashtags in the snippet content
+      const result = expandHashtags(content, registry, new Set(visited))
+      
+      // Remove from visited set after expansion (allows reuse in different branches)
+      visited.delete(key)
+      
+      return result
+    })
+  }
+  
+  return expanded
+}

package/src/loader.ts

@@ -0,0 +1,88 @@
+import { readdir, readFile } from "node:fs/promises"
+import { join, basename } from "node:path"
+import matter from "gray-matter"
+import type { SnippetRegistry, SnippetFrontmatter } from "./types.js"
+import { PATHS, CONFIG } from "./constants.js"
+import { logger } from "./logger.js"
+
+/**
+ * Loads all snippets from the snippets directory
+ * 
+ * @returns A map of snippet keys (lowercase) to their content
+ */
+export async function loadSnippets(): Promise<SnippetRegistry> {
+  const snippets: SnippetRegistry = new Map()
+  
+  try {
+    const files = await readdir(PATHS.SNIPPETS_DIR)
+    
+    for (const file of files) {
+      if (!file.endsWith(CONFIG.SNIPPET_EXTENSION)) continue
+      
+      const snippet = await loadSnippetFile(file)
+      if (snippet) {
+        registerSnippet(snippets, snippet.name, snippet.content, snippet.aliases)
+      }
+    }
+  } catch (error) {
+    // Snippets directory doesn't exist or can't be read - that's fine
+    logger.info("Snippets directory not found or unreadable", { 
+      path: PATHS.SNIPPETS_DIR,
+      error: error instanceof Error ? error.message : String(error)
+    })
+    // Return empty registry
+  }
+  
+  return snippets
+}
+
+/**
+ * Loads and parses a single snippet file
+ * 
+ * @param filename - The filename to load (e.g., "my-snippet.md")
+ * @returns The parsed snippet data, or null if parsing failed
+ */
+async function loadSnippetFile(filename: string) {
+  try {
+    const name = basename(filename, CONFIG.SNIPPET_EXTENSION)
+    const filePath = join(PATHS.SNIPPETS_DIR, filename)
+    const fileContent = await readFile(filePath, "utf-8")
+    const parsed = matter(fileContent)
+    
+    const content = parsed.content.trim()
+    const frontmatter = parsed.data as SnippetFrontmatter
+    const aliases = Array.isArray(frontmatter.aliases) ? frontmatter.aliases : []
+    
+    return { name, content, aliases }
+  } catch (error) {
+    // Failed to read or parse this snippet - skip it
+    logger.warn("Failed to load snippet file", { 
+      filename,
+      error: error instanceof Error ? error.message : String(error)
+    })
+    return null
+  }
+}
+
+/**
+ * Registers a snippet and its aliases in the registry
+ * 
+ * @param registry - The snippet registry to update
+ * @param name - The primary name of the snippet
+ * @param content - The snippet content
+ * @param aliases - Alternative names for the snippet
+ */
+function registerSnippet(
+  registry: SnippetRegistry,
+  name: string,
+  content: string,
+  aliases: string[]
+) {
+  // Register with primary name (lowercase)
+  registry.set(name.toLowerCase(), content)
+  
+  // Register all aliases (lowercase)
+  for (const alias of aliases) {
+    registry.set(alias.toLowerCase(), content)
+  }
+}

package/src/logger.ts

@@ -0,0 +1,121 @@
+import { writeFileSync, mkdirSync, existsSync } from "fs"
+import { join } from "path"
+import { OPENCODE_CONFIG_DIR } from "./constants.js"
+
+/**
+ * Check if debug logging is enabled via environment variable
+ */
+function isDebugEnabled(): boolean {
+    const value = process.env.DEBUG_SNIPPETS
+    return value === "1" || value === "true"
+}
+
+export class Logger {
+    private logDir: string
+
+    constructor() {
+        this.logDir = join(OPENCODE_CONFIG_DIR, "logs", "snippets")
+    }
+
+    private get enabled(): boolean {
+        return isDebugEnabled()
+    }
+
+    private ensureLogDir() {
+        if (!existsSync(this.logDir)) {
+            mkdirSync(this.logDir, { recursive: true })
+        }
+    }
+
+    private formatData(data?: any): string {
+        if (!data) return ""
+
+        const parts: string[] = []
+        for (const [key, value] of Object.entries(data)) {
+            if (value === undefined || value === null) continue
+
+            // Format arrays compactly
+            if (Array.isArray(value)) {
+                if (value.length === 0) continue
+                parts.push(`${key}=[${value.slice(0, 3).join(",")}${value.length > 3 ? `...+${value.length - 3}` : ""}]`)
+            }
+            else if (typeof value === 'object') {
+                const str = JSON.stringify(value)
+                if (str.length < 50) {
+                    parts.push(`${key}=${str}`)
+                }
+            }
+            else {
+                parts.push(`${key}=${value}`)
+            }
+        }
+        return parts.join(" ")
+    }
+
+    private getCallerFile(): string {
+        const originalPrepareStackTrace = Error.prepareStackTrace
+        try {
+            const err = new Error()
+            Error.prepareStackTrace = (_, stack) => stack
+            const stack = err.stack as unknown as NodeJS.CallSite[]
+            Error.prepareStackTrace = originalPrepareStackTrace
+
+            for (let i = 3; i < stack.length; i++) {
+                const filename = stack[i]?.getFileName()
+                if (filename && !filename.includes('logger.')) {
+                    const match = filename.match(/([^/\\]+)\.[tj]s$/)
+                    return match ? match[1] : 'unknown'
+                }
+            }
+            return 'unknown'
+        } catch {
+            return 'unknown'
+        }
+    }
+
+    private write(level: string, component: string, message: string, data?: any) {
+        if (!this.enabled) return
+
+        try {
+            this.ensureLogDir()
+
+            const timestamp = new Date().toISOString()
+            const dataStr = this.formatData(data)
+
+            const dailyLogDir = join(this.logDir, "daily")
+            if (!existsSync(dailyLogDir)) {
+                mkdirSync(dailyLogDir, { recursive: true })
+            }
+
+            const logLine = `${timestamp} ${level.padEnd(5)} ${component}: ${message}${dataStr ? " | " + dataStr : ""}\n`
+
+            const logFile = join(dailyLogDir, `${new Date().toISOString().split('T')[0]}.log`)
+            writeFileSync(logFile, logLine, { flag: "a" })
+        } catch (error) {
+            // Silent fail
+        }
+    }
+
+    info(message: string, data?: any) {
+        const component = this.getCallerFile()
+        this.write("INFO", component, message, data)
+    }
+
+    debug(message: string, data?: any) {
+        const component = this.getCallerFile()
+        this.write("DEBUG", component, message, data)
+    }
+
+    warn(message: string, data?: any) {
+        const component = this.getCallerFile()
+        this.write("WARN", component, message, data)
+    }
+
+    error(message: string, data?: any) {
+        const component = this.getCallerFile()
+        this.write("ERROR", component, message, data)
+    }
+}
+
+// Export singleton logger instance
+export const logger = new Logger()

package/src/shell.ts

@@ -0,0 +1,44 @@
+import { PATTERNS } from "./constants.js"
+import { logger } from "./logger.js"
+
+/**
+ * Executes shell commands in text using !`command` syntax
+ * 
+ * @param text - The text containing shell commands to execute
+ * @param ctx - The plugin context (with Bun shell)
+ * @returns The text with shell commands replaced by their output
+ */
+export async function executeShellCommands(
+  text: string,
+  ctx: any
+): Promise<string> {
+  let result = text
+  
+  // Reset regex state (global flag requires this)
+  PATTERNS.SHELL_COMMAND.lastIndex = 0
+  
+  // Find all shell command matches
+  const matches = [...text.matchAll(PATTERNS.SHELL_COMMAND)]
+  
+  // Execute each command and replace in text
+  for (const match of matches) {
+    const cmd = match[1]
+    const placeholder = match[0]
+    
+    try {
+      const output = await ctx.$`${{ raw: cmd }}`.quiet().nothrow().text()
+      // Format like slash commands: print command first, then output
+      const replacement = `$ ${cmd}\n--> ${output.trim()}`
+      result = result.replace(placeholder, replacement)
+    } catch (error) {
+      // If shell command fails, leave it as-is
+      // This preserves the original syntax for debugging
+      logger.warn("Shell command execution failed", {
+        command: cmd,
+        error: error instanceof Error ? error.message : String(error)
+      })
+    }
+  }
+  
+  return result
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+/**
+ * A snippet with its content and metadata
+ */
+export interface Snippet {
+  /** The primary name/key of the snippet */
+  name: string
+  /** The content of the snippet (without frontmatter) */
+  content: string
+  /** Alternative names that also trigger this snippet */
+  aliases: string[]
+}
+
+/**
+ * Snippet registry that maps keys to content
+ */
+export type SnippetRegistry = Map<string, string>
+
+/**
+ * Frontmatter data from snippet files
+ */
+export interface SnippetFrontmatter {
+  /** Alternative hashtags for this snippet */
+  aliases?: string[]
+  /** Optional description of what this snippet does */
+  description?: string
+}