opencode-snippets 1.2.0 → 1.4.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,7 +34,7 @@ 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: Extending snippets with logic**
+**Example: Extending commands with snippets**
 
 `~/.config/opencode/command/commit-and-push.md`:
 ```markdown
@@ -37,6 +42,7 @@ Snippets compose with each other and with slash commands. Reference `#snippets`
 description: Create a git commit and push to remote
 ---
 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`
@@ -44,10 +50,11 @@ Here is the current git status:
 Here are the staged changes:
 !`git diff --cached`
 
-#conventional-commits
 #project-context
 ```
 
+You could also make "current git status and staged changes" a shell-enabled snippet of its own.
+
 **Example: Snippets composing snippets**
 
 `~/.config/opencode/snippet/code-standards.md`:
@@ -101,10 +108,7 @@ Ask clarifying questions if anything is ambiguous.
 
 **3. Use it anywhere:**
 
-```
-Refactor this function. Think step by step. Double-check your work before making changes.
-Ask clarifying questions if anything is ambiguous.
-```
+https://github.com/user-attachments/assets/d31b69b5-cc7a-4208-9f6e-71c1a278536a
 
 ## Where to Store Snippets
 
@@ -186,6 +190,48 @@ I reference I reference I reference ... (15 times) ... I reference #self
 
 This generous limit supports complex snippet hierarchies while preventing infinite loops.
 
+### Prepend and Append Blocks
+
+For long reference material that would break your writing flow, use `<append>` blocks to place content at the end of your message:
+
+```markdown
+---
+aliases: jira-mcp
+---
+Jira MCP server
+<append>
+## Jira MCP Usage
+
+Use these custom field mappings when creating issues:
+- customfield_16570 => Acceptance Criteria
+- customfield_11401 => Team
+</append>
+```
+
+**Input:** `Create a bug ticket in #jira-mcp about the memory leak`
+
+**Output:**
+```
+Create a bug ticket in Jira MCP server about the memory leak
+
+## Jira MCP Usage
+
+Use these custom field mappings when creating issues:
+- customfield_16570 => Acceptance Criteria
+- customfield_11401 => Team
+```
+
+Write naturally—reference what you need mid-sentence—and the context follows at the bottom.
+
+Use `<prepend>` for content that should appear at the top of your message. Multiple blocks of the same type are concatenated in order of appearance.
+
+**Block behavior:**
+- Content outside `<prepend>`/`<append>` blocks replaces the hashtag inline
+- If a snippet has only blocks (no inline content), the hashtag is simply removed
+- Blocks from nested snippets are collected and assembled in the final message
+- Unclosed tags are handled leniently (rest of content becomes the block)
+- Nested `<prepend>` inside `<append>` (or vice versa) is an error—the hashtag is left unchanged
+
 ## Example Snippets
 
 ### `~/.config/opencode/snippet/context.md`
@@ -217,12 +263,25 @@ Be extremely concise. No explanations unless asked.
 | Live shell data | Yes 💻 | Yes 💻 |
 | Best for | Triggering actions & workflows ⚡ | Context injection 📝 |
 
-**Use both together:**
-```
-/commit #conventional-commits #project-context
-```
+> [!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
 
-## Configuration### Debug Logging
+### Debug Logging
 
 Enable debug logs by setting an environment variable:
 
@@ -243,7 +302,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,5 +1,6 @@
 import type { Plugin } from "@opencode-ai/plugin";
-import { expandHashtags } from "./src/expander.js";
+import { createCommandExecuteHandler } from "./src/commands.js";
+import { assembleMessage, 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";
@@ -8,6 +9,7 @@ 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
  */
@@ -22,7 +24,22 @@ export const SnippetsPlugin: Plugin = async (ctx) => {
     snippetCount: snippets.size,
   });
 
+  // Create command handler
+  const commandHandler = createCommandExecuteHandler(ctx.client, snippets, ctx.directory);
+
   return {
+    // 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;
@@ -36,7 +53,8 @@ export const SnippetsPlugin: Plugin = async (ctx) => {
         if (part.type === "text" && part.text) {
           // 1. Expand hashtags recursively with loop detection
           const expandStart = performance.now();
-          part.text = expandHashtags(part.text, snippets);
+          const expansionResult = expandHashtags(part.text, snippets);
+          part.text = assembleMessage(expansionResult);
           const expandTime = performance.now() - expandStart;
           expandTimeTotal += expandTime;
 

package/package.json

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

package/src/commands.ts

@@ -0,0 +1,335 @@
+import { PATHS } from "./constants.js";
+import { createSnippet, deleteSnippet, listSnippets, reloadSnippets } from "./loader.js";
+import { logger } from "./logger.js";
+import { sendIgnoredMessage } from "./notification.js";
+import type { SnippetRegistry } from "./types.js";
+
+/** Marker error to indicate command was handled */
+const COMMAND_HANDLED_MARKER = "__SNIPPETS_COMMAND_HANDLED__";
+
+interface CommandContext {
+  client: any;
+  sessionId: string;
+  args: string[];
+  rawArguments: string;
+  snippets: SnippetRegistry;
+  projectDir?: string;
+}
+
+/**
+ * Creates the command execute handler for the snippets command
+ */
+export function createCommandExecuteHandler(
+  client: any,
+  snippets: SnippetRegistry,
+  projectDir?: string,
+) {
+  return async (input: { command: string; sessionID: string; arguments: string }) => {
+    if (input.command !== "snippet") return;
+
+    const args = input.arguments.split(/\s+/).filter(Boolean);
+    const subcommand = args[0]?.toLowerCase() || "help";
+
+    const ctx: CommandContext = {
+      client,
+      sessionId: input.sessionID,
+      args: args.slice(1),
+      rawArguments: input.arguments,
+      snippets,
+      projectDir,
+    };
+
+    try {
+      switch (subcommand) {
+        case "add":
+        case "create":
+        case "new":
+          await handleAddCommand(ctx);
+          break;
+        case "delete":
+        case "remove":
+        case "rm":
+          await handleDeleteCommand(ctx);
+          break;
+        case "list":
+        case "ls":
+          await handleListCommand(ctx);
+          break;
+        default:
+          await handleHelpCommand(ctx);
+          break;
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message === COMMAND_HANDLED_MARKER) {
+        throw error;
+      }
+      logger.error("Command execution failed", {
+        subcommand,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      await sendIgnoredMessage(
+        ctx.client,
+        ctx.sessionId,
+        `Error: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    // Signal that command was handled
+    throw new Error(COMMAND_HANDLED_MARKER);
+  };
+}
+
+/**
+ * Handle /snippet add <name> ["content"] [--project] [--alias=<alias>] [--desc=<description>]
+ */
+async function handleAddCommand(ctx: CommandContext): Promise<void> {
+  const { client, sessionId, args, rawArguments, snippets, projectDir } = ctx;
+
+  if (args.length === 0) {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      'Usage: /snippet add <name> ["content"] [options]\n\n' +
+        "Adds a new snippet. Defaults to global directory.\n\n" +
+        "Examples:\n" +
+        "  /snippet add greeting\n" +
+        '  /snippet add bye "see you later"\n' +
+        '  /snippet add hi "hello there" --aliases hello,hey\n' +
+        '  /snippet add fix "fix imports" --project\n\n' +
+        "Options:\n" +
+        "  --project             Add to project directory (.opencode/snippet/)\n" +
+        "  --aliases X,Y,Z       Add aliases (comma-separated)\n" +
+        '  --desc "..."          Add a description',
+    );
+    return;
+  }
+
+  const name = args[0];
+
+  // Extract quoted content from raw arguments
+  // Match content between quotes after the subcommand and name
+  const quotedMatch = rawArguments.match(/(?:add|create|new)\s+\S+\s+"([^"]+)"/i);
+  const content = quotedMatch ? quotedMatch[1] : "";
+
+  const isProject = args.includes("--project");
+  const aliases: string[] = [];
+  let description: string | undefined;
+
+  // Parse arguments with --param value syntax
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+
+    // Handle --aliases
+    if (arg === "--aliases") {
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith("--")) {
+        const values = nextArg
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean);
+        aliases.push(...values);
+        i++; // Skip the value arg
+      }
+    }
+    // Handle --desc or --description
+    else if (arg === "--desc" || arg === "--description") {
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith("--")) {
+        description = nextArg;
+        i++; // Skip the value arg
+      }
+    }
+  }
+
+  // Default to global, --project puts it in project directory
+  const targetDir = isProject ? projectDir : undefined;
+  const location = isProject && projectDir ? "project" : "global";
+
+  try {
+    const filePath = await createSnippet(name, content, { aliases, description }, targetDir);
+
+    // Reload snippets
+    await reloadSnippets(snippets, projectDir);
+
+    let message = `Added ${location} snippet: ${name}\nFile: ${filePath}`;
+    if (content) {
+      message += `\nContent: "${truncate(content, 50)}"`;
+    } else {
+      message += "\n\nEdit the file to add your snippet content.";
+    }
+    if (aliases.length > 0) {
+      message += `\nAliases: ${aliases.join(", ")}`;
+    }
+
+    await sendIgnoredMessage(client, sessionId, message);
+  } catch (error) {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      `Failed to add snippet: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/**
+ * Handle /snippet delete <name>
+ */
+async function handleDeleteCommand(ctx: CommandContext): Promise<void> {
+  const { client, sessionId, args, snippets, projectDir } = ctx;
+
+  if (args.length === 0) {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      "Usage: /snippet delete <name>\n\nDeletes a snippet by name. " +
+        "Project snippets are checked first, then global.",
+    );
+    return;
+  }
+
+  const name = args[0];
+
+  const deletedPath = await deleteSnippet(name, projectDir);
+
+  if (deletedPath) {
+    // Reload snippets
+    await reloadSnippets(snippets, projectDir);
+
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      `Deleted snippet: #${name}\nRemoved: ${deletedPath}`,
+    );
+  } else {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      `Snippet not found: #${name}\n\nUse /snippet list to see available snippets.`,
+    );
+  }
+}
+
+/** Maximum characters for snippet content preview */
+const MAX_CONTENT_PREVIEW_LENGTH = 200;
+/** Maximum characters for aliases display */
+const MAX_ALIASES_LENGTH = 50;
+/** Divider line */
+const DIVIDER = "────────────────────────────────────────────────";
+
+/**
+ * Truncate text with ellipsis if it exceeds maxLength
+ */
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Format aliases for display, truncating if needed
+ */
+function formatAliases(aliases: string[]): string {
+  if (aliases.length === 0) return "";
+
+  const joined = aliases.join(", ");
+  if (joined.length <= MAX_ALIASES_LENGTH) {
+    return ` (aliases: ${joined})`;
+  }
+
+  // Truncate and show count
+  const truncated = truncate(joined, MAX_ALIASES_LENGTH - 10);
+  return ` (aliases: ${truncated} +${aliases.length})`;
+}
+
+/**
+ * Format a single snippet for display
+ */
+function formatSnippetEntry(s: { name: string; content: string; aliases: string[] }): string {
+  const header = `${s.name}${formatAliases(s.aliases)}`;
+  const content = truncate(s.content.trim(), MAX_CONTENT_PREVIEW_LENGTH);
+
+  return `${header}\n${DIVIDER}\n${content || "(empty)"}`;
+}
+
+/**
+ * Handle /snippet list
+ */
+async function handleListCommand(ctx: CommandContext): Promise<void> {
+  const { client, sessionId, snippets, projectDir } = ctx;
+
+  const snippetList = listSnippets(snippets);
+
+  if (snippetList.length === 0) {
+    await sendIgnoredMessage(
+      client,
+      sessionId,
+      "No snippets found.\n\n" +
+        `Global snippets: ${PATHS.SNIPPETS_DIR}\n` +
+        (projectDir
+          ? `Project snippets: ${projectDir}/.opencode/snippet/`
+          : "No project directory detected.") +
+        "\n\nUse /snippet add <name> to add a new snippet.",
+    );
+    return;
+  }
+
+  const lines: string[] = [];
+
+  // Group by source
+  const globalSnippets = snippetList.filter((s) => s.source === "global");
+  const projectSnippets = snippetList.filter((s) => s.source === "project");
+
+  if (globalSnippets.length > 0) {
+    lines.push(`── Global (${PATHS.SNIPPETS_DIR}) ──`, "");
+    for (const s of globalSnippets) {
+      lines.push(formatSnippetEntry(s), "");
+    }
+  }
+
+  if (projectSnippets.length > 0) {
+    lines.push(`── Project (${projectDir}/.opencode/snippet/) ──`, "");
+    for (const s of projectSnippets) {
+      lines.push(formatSnippetEntry(s), "");
+    }
+  }
+
+  await sendIgnoredMessage(client, sessionId, lines.join("\n").trimEnd());
+}
+
+/**
+ * Handle /snippet help
+ */
+async function handleHelpCommand(ctx: CommandContext): Promise<void> {
+  const { client, sessionId } = ctx;
+
+  const helpText = `Snippets Command - Manage text snippets
+
+Usage: /snippet <command> [options]
+
+Commands:
+  add <name> ["content"] [options]
+    --project               Add to project directory (default: global)
+    --aliases X,Y,Z         Add aliases (comma-separated)
+    --desc "..."            Add a description
+
+  delete <name>             Delete a snippet
+  list                      List all available snippets
+  help                      Show this help message
+
+Snippet Locations:
+  Global:  ~/.config/opencode/snippet/
+  Project: <project>/.opencode/snippet/
+
+Usage in messages:
+  Type #snippet-name to expand a snippet inline.
+  Snippets can reference other snippets recursively.
+
+Examples:
+  /snippet add greeting
+  /snippet add bye "see you later"
+  /snippet add hi "hello there" --aliases hello,hey
+  /snippet add fix "fix imports" --project
+  /snippet delete old-snippet
+  /snippet list`;
+
+  await sendIgnoredMessage(client, sessionId, helpText);
+}

package/src/constants.ts

@@ -12,20 +12,15 @@ export const PATTERNS = {
   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,
+  CONFIG_DIR: join(homedir(), ".config", "opencode"),
 
   /** Snippets directory */
-  SNIPPETS_DIR: join(OPENCODE_CONFIG_DIR, "snippet"),
+  SNIPPETS_DIR: join(join(homedir(), ".config", "opencode"), "snippet"),
 } as const;
 
 /**