opencode-snippets 1.3.0 → 1.4.0

package/README.md

@@ -190,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`

package/index.ts

@@ -1,6 +1,6 @@
 import type { Plugin } from "@opencode-ai/plugin";
 import { createCommandExecuteHandler } from "./src/commands.js";
-import { expandHashtags } from "./src/expander.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";
@@ -53,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.3.0",
+  "version": "1.4.0",
   "description": "Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts",
   "main": "index.ts",
   "type": "module",

package/src/commands.ts

@@ -55,7 +55,6 @@ export function createCommandExecuteHandler(
         case "ls":
           await handleListCommand(ctx);
           break;
-        case "help":
         default:
           await handleHelpCommand(ctx);
           break;

package/src/expander.test.ts

@@ -1,4 +1,4 @@
-import { expandHashtags } from "../src/expander.js";
+import { assembleMessage, expandHashtags, parseSnippetBlocks } from "../src/expander.js";
 import type { SnippetInfo, SnippetRegistry } from "../src/types.js";
 
 /** Helper to create a SnippetInfo from just content */
@@ -18,7 +18,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("Say #greeting", registry);
 
-      expect(result).toBe("Say Hello, World!");
+      expect(result.text).toBe("Say Hello, World!");
     });
 
     it("should expand multiple hashtags in one text", () => {
@@ -29,7 +29,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#greeting, #name!", registry);
 
-      expect(result).toBe("Hello, Alice!");
+      expect(result.text).toBe("Hello, Alice!");
     });
 
     it("should leave unknown hashtags unchanged", () => {
@@ -37,7 +37,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("This is #known and #unknown", registry);
 
-      expect(result).toBe("This is content and #unknown");
+      expect(result.text).toBe("This is content and #unknown");
     });
 
     it("should handle empty text", () => {
@@ -45,7 +45,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("", registry);
 
-      expect(result).toBe("");
+      expect(result.text).toBe("");
     });
 
     it("should handle text with no hashtags", () => {
@@ -53,7 +53,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("No hashtags here", registry);
 
-      expect(result).toBe("No hashtags here");
+      expect(result.text).toBe("No hashtags here");
     });
 
     it("should handle case-insensitive hashtags", () => {
@@ -61,7 +61,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#Greeting #GREETING #greeting", registry);
 
-      expect(result).toBe("Hello Hello Hello");
+      expect(result.text).toBe("Hello Hello Hello");
     });
   });
 
@@ -74,7 +74,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#outer", registry);
 
-      expect(result).toBe("Start Middle End");
+      expect(result.text).toBe("Start Middle End");
     });
 
     it("should expand nested hashtags multiple levels deep", () => {
@@ -87,7 +87,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#level1", registry);
 
-      expect(result).toBe("L1 L2 L3 L4");
+      expect(result.text).toBe("L1 L2 L3 L4");
     });
 
     it("should expand multiple nested hashtags in one snippet", () => {
@@ -99,7 +99,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#main", registry);
 
-      expect(result).toBe("Start Content A and Content B End");
+      expect(result.text).toBe("Start Content A and Content B End");
     });
 
     it("should expand complex nested structure", () => {
@@ -113,7 +113,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#greeting", registry);
 
-      expect(result).toBe("Hello John Doe");
+      expect(result.text).toBe("Hello John Doe");
     });
   });
 
@@ -125,7 +125,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       // Loop detected after 15 expansions, #self left as-is
       const expected = `${"I reference ".repeat(15)}#self`;
-      expect(result).toBe(expected);
+      expect(result.text).toBe(expected);
     });
 
     it("should detect and prevent two-way circular reference", () => {
@@ -138,7 +138,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       // Should expand alternating A and B 15 times then stop
       const expected = `${"A references B references ".repeat(15)}#a`;
-      expect(result).toBe(expected);
+      expect(result.text).toBe(expected);
     });
 
     it("should detect and prevent three-way circular reference", () => {
@@ -152,7 +152,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       // Should expand cycling through A, B, C 15 times then stop
       const expected = `${"A -> B -> C -> ".repeat(15)}#a`;
-      expect(result).toBe(expected);
+      expect(result.text).toBe(expected);
     });
 
     it("should detect loops in longer chains", () => {
@@ -167,7 +167,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       const result = expandHashtags("#a", registry);
 
       // Should expand until loop detected
-      expect(result).toBe("#b");
+      expect(result.text).toBe("#b");
     });
   });
 
@@ -183,7 +183,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       const result = expandHashtags("#main", registry);
 
       // #shared should be expanded in both branches
-      expect(result).toBe("B1 uses Shared content and B2 uses Shared content");
+      expect(result.text).toBe("B1 uses Shared content and B2 uses Shared content");
     });
 
     it("should handle partial loops with valid branches", () => {
@@ -197,7 +197,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       // Valid expands once, loop expands 15 times
       const expected = `Valid content and ${"Loop ".repeat(15)}#loop`;
-      expect(result).toBe(expected);
+      expect(result.text).toBe(expected);
     });
 
     it("should handle multiple independent loops", () => {
@@ -211,7 +211,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       // Each loop expands 15 times independently
       const expected = `${"L1 ".repeat(15)}#loop1 and ${"L2 ".repeat(15)}#loop2`;
-      expect(result).toBe(expected);
+      expect(result.text).toBe(expected);
     });
 
     it("should handle nested loops", () => {
@@ -225,10 +225,10 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       // Complex nested loop - outer/inner cycle 15 times, plus self cycles
       // This is complex expansion behavior, just verify it doesn't hang
-      expect(result).toContain("Outer");
-      expect(result).toContain("Inner");
-      expect(result).toContain("#outer");
-      expect(result).toContain("#self");
+      expect(result.text).toContain("Outer");
+      expect(result.text).toContain("Inner");
+      expect(result.text).toContain("#outer");
+      expect(result.text).toContain("#self");
     });
 
     it("should handle diamond pattern (same snippet reached via multiple paths)", () => {
@@ -242,7 +242,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       const result = expandHashtags("#top", registry);
 
       // Diamond: top -> left -> bottom, top -> right -> bottom
-      expect(result).toBe("Left Bottom Right Bottom");
+      expect(result.text).toBe("Left Bottom Right Bottom");
     });
 
     it("should handle loop after valid expansion", () => {
@@ -255,7 +255,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#a", registry);
 
-      expect(result).toBe("Valid B #c");
+      expect(result.text).toBe("Valid B #c");
     });
   });
 
@@ -265,7 +265,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#anything", registry);
 
-      expect(result).toBe("#anything");
+      expect(result.text).toBe("#anything");
     });
 
     it("should handle snippet with empty content", () => {
@@ -273,7 +273,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("Before #empty After", registry);
 
-      expect(result).toBe("Before  After");
+      expect(result.text).toBe("Before  After");
     });
 
     it("should handle snippet containing only hashtags", () => {
@@ -285,7 +285,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#only-refs", registry);
 
-      expect(result).toBe("A B");
+      expect(result.text).toBe("A B");
     });
 
     it("should handle hashtags at start, middle, and end", () => {
@@ -297,7 +297,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#start text #middle text #end", registry);
 
-      expect(result).toBe("Start text Middle text End");
+      expect(result.text).toBe("Start text Middle text End");
     });
 
     it("should handle consecutive hashtags", () => {
@@ -309,7 +309,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#a#b#c", registry);
 
-      expect(result).toBe("ABC");
+      expect(result.text).toBe("ABC");
     });
 
     it("should handle hashtags with hyphens and underscores", () => {
@@ -321,7 +321,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#my-snippet #my_snippet #my-complex_name", registry);
 
-      expect(result).toBe("Hyphenated Underscored Mixed");
+      expect(result.text).toBe("Hyphenated Underscored Mixed");
     });
 
     it("should handle hashtags with numbers", () => {
@@ -332,7 +332,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#test123 #123test", registry);
 
-      expect(result).toBe("Test with numbers Numbers first");
+      expect(result.text).toBe("Test with numbers Numbers first");
     });
 
     it("should not expand hashtags in URLs", () => {
@@ -342,7 +342,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       // This test documents current behavior
       const result = expandHashtags("See https://github.com/user/repo/issues/#issue", registry);
 
-      expect(result).toBe("See https://github.com/user/repo/issues/ISSUE");
+      expect(result.text).toBe("See https://github.com/user/repo/issues/ISSUE");
     });
 
     it("should handle multiline content", () => {
@@ -350,7 +350,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("Start\n#multiline\nEnd", registry);
 
-      expect(result).toBe("Start\nLine 1\nLine 2\nLine 3\nEnd");
+      expect(result.text).toBe("Start\nLine 1\nLine 2\nLine 3\nEnd");
     });
 
     it("should handle nested multiline content", () => {
@@ -361,7 +361,7 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#outer", registry);
 
-      expect(result).toBe("Outer start\nInner line 1\nInner line 2\nOuter end");
+      expect(result.text).toBe("Outer start\nInner line 1\nInner line 2\nOuter end");
     });
   });
 
@@ -376,10 +376,10 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#review", registry);
 
-      expect(result).toContain("Code Review Checklist:");
-      expect(result).toContain("Check for SQL injection");
-      expect(result).toContain("Check for N+1 queries");
-      expect(result).toContain("Unit tests present");
+      expect(result.text).toContain("Code Review Checklist:");
+      expect(result.text).toContain("Check for SQL injection");
+      expect(result.text).toContain("Check for N+1 queries");
+      expect(result.text).toContain("Unit tests present");
     });
 
     it("should expand documentation template with shared components", () => {
@@ -394,8 +394,8 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       const result = expandHashtags("#doc", registry);
 
       // #author should be expanded in both header and footer
-      expect(result).toContain("Author: John Doe");
-      expect(result).toContain("Contact: John Doe");
+      expect(result.text).toContain("Author: John Doe");
+      expect(result.text).toContain("Contact: John Doe");
     });
 
     it("should handle instruction composition", () => {
@@ -407,7 +407,9 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("Instructions: #complete", registry);
 
-      expect(result).toBe("Instructions: Be thorough. Think step by step. Double-check your work.");
+      expect(result.text).toBe(
+        "Instructions: Be thorough. Think step by step. Double-check your work.",
+      );
     });
   });
 
@@ -424,9 +426,9 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
 
       const result = expandHashtags("#level0", registry);
 
-      expect(result).toContain("L0");
-      expect(result).toContain("End");
-      expect(result.split(" ").length).toBe(depth);
+      expect(result.text).toContain("L0");
+      expect(result.text).toContain("End");
+      expect(result.text.split(" ").length).toBe(depth);
     });
 
     it("should handle many snippets in one text", () => {
@@ -440,9 +442,9 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       const hashtags = Array.from({ length: count }, (_, i) => `#snippet${i}`).join(" ");
       const result = expandHashtags(hashtags, registry);
 
-      expect(result.split(" ").length).toBe(count);
-      expect(result).toContain("Content0");
-      expect(result).toContain(`Content${count - 1}`);
+      expect(result.text.split(" ").length).toBe(count);
+      expect(result.text).toContain("Content0");
+      expect(result.text).toContain(`Content${count - 1}`);
     });
 
     it("should handle wide branching (many children)", () => {
@@ -459,8 +461,378 @@ describe("expandHashtags - Recursive Includes and Loop Detection", () => {
       const result = expandHashtags("#parent", registry);
 
       for (let i = 0; i < branches; i++) {
-        expect(result).toContain(`Child${i}`);
+        expect(result.text).toContain(`Child${i}`);
       }
     });
   });
 });
+
+describe("parseSnippetBlocks", () => {
+  describe("Basic parsing", () => {
+    it("should return full content as inline when no blocks present", () => {
+      const result = parseSnippetBlocks("Just some content");
+
+      expect(result).toEqual({
+        inline: "Just some content",
+        prepend: [],
+        append: [],
+      });
+    });
+
+    it("should extract append block and inline content", () => {
+      const result = parseSnippetBlocks("Inline text\n<append>\nAppend content\n</append>");
+
+      expect(result).toEqual({
+        inline: "Inline text",
+        prepend: [],
+        append: ["Append content"],
+      });
+    });
+
+    it("should extract prepend block and inline content", () => {
+      const result = parseSnippetBlocks("<prepend>\nPrepend content\n</prepend>\nInline text");
+
+      expect(result).toEqual({
+        inline: "Inline text",
+        prepend: ["Prepend content"],
+        append: [],
+      });
+    });
+
+    it("should extract both prepend and append blocks", () => {
+      const content = `<prepend>
+Before content
+</prepend>
+Inline text
+<append>
+After content
+</append>`;
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result).toEqual({
+        inline: "Inline text",
+        prepend: ["Before content"],
+        append: ["After content"],
+      });
+    });
+
+    it("should handle multiple blocks of the same type", () => {
+      const content = `<append>
+First append
+</append>
+Inline
+<append>
+Second append
+</append>`;
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result).toEqual({
+        inline: "Inline",
+        prepend: [],
+        append: ["First append", "Second append"],
+      });
+    });
+  });
+
+  describe("Edge cases", () => {
+    it("should handle empty inline (only blocks)", () => {
+      const content = `<append>
+Only append content
+</append>`;
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result).toEqual({
+        inline: "",
+        prepend: [],
+        append: ["Only append content"],
+      });
+    });
+
+    it("should handle unclosed tag leniently (rest is block content)", () => {
+      const content = "Inline\n<append>\nUnclosed append content";
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result).toEqual({
+        inline: "Inline",
+        prepend: [],
+        append: ["Unclosed append content"],
+      });
+    });
+
+    it("should return null for nested tags", () => {
+      const content = "<append>\n<prepend>\nnested\n</prepend>\n</append>";
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result).toBeNull();
+    });
+
+    it("should trim content inside blocks", () => {
+      const content = "<append>\n  \n  Content with whitespace  \n  \n</append>";
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result?.append[0]).toBe("Content with whitespace");
+    });
+
+    it("should trim inline content", () => {
+      const content = "  \n  Inline with whitespace  \n  ";
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result?.inline).toBe("Inline with whitespace");
+    });
+
+    it("should be case-insensitive for tags", () => {
+      const content = "<APPEND>\nContent\n</APPEND>";
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result).toEqual({
+        inline: "",
+        prepend: [],
+        append: ["Content"],
+      });
+    });
+
+    it("should handle empty blocks", () => {
+      const content = "Inline<append></append>";
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result).toEqual({
+        inline: "Inline",
+        prepend: [],
+        append: [],
+      });
+    });
+  });
+
+  describe("Real-world content", () => {
+    it("should parse Jira MCP example", () => {
+      const content = `Jira MCP server
+<append>
+## Jira MCP Usage
+
+Use these custom field mappings when creating issues:
+- customfield_16570 => Acceptance Criteria
+- customfield_11401 => Team
+</append>`;
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result?.inline).toBe("Jira MCP server");
+      expect(result?.append).toHaveLength(1);
+      expect(result?.append[0]).toContain("Jira MCP Usage");
+      expect(result?.append[0]).toContain("customfield_16570");
+    });
+  });
+});
+
+describe("assembleMessage", () => {
+  it("should assemble text only", () => {
+    const result = assembleMessage({
+      text: "Main content",
+      prepend: [],
+      append: [],
+    });
+
+    expect(result).toBe("Main content");
+  });
+
+  it("should assemble with append blocks", () => {
+    const result = assembleMessage({
+      text: "Main content",
+      prepend: [],
+      append: ["Appended section"],
+    });
+
+    expect(result).toBe("Main content\n\nAppended section");
+  });
+
+  it("should assemble with prepend blocks", () => {
+    const result = assembleMessage({
+      text: "Main content",
+      prepend: ["Prepended section"],
+      append: [],
+    });
+
+    expect(result).toBe("Prepended section\n\nMain content");
+  });
+
+  it("should assemble with both prepend and append", () => {
+    const result = assembleMessage({
+      text: "Main content",
+      prepend: ["Before"],
+      append: ["After"],
+    });
+
+    expect(result).toBe("Before\n\nMain content\n\nAfter");
+  });
+
+  it("should join multiple prepend blocks", () => {
+    const result = assembleMessage({
+      text: "Main",
+      prepend: ["First", "Second"],
+      append: [],
+    });
+
+    expect(result).toBe("First\n\nSecond\n\nMain");
+  });
+
+  it("should join multiple append blocks", () => {
+    const result = assembleMessage({
+      text: "Main",
+      prepend: [],
+      append: ["First", "Second"],
+    });
+
+    expect(result).toBe("Main\n\nFirst\n\nSecond");
+  });
+
+  it("should handle empty text with blocks", () => {
+    const result = assembleMessage({
+      text: "",
+      prepend: ["Before"],
+      append: ["After"],
+    });
+
+    expect(result).toBe("Before\n\nAfter");
+  });
+
+  it("should handle whitespace-only text with blocks", () => {
+    const result = assembleMessage({
+      text: "   ",
+      prepend: ["Before"],
+      append: ["After"],
+    });
+
+    expect(result).toBe("Before\n\nAfter");
+  });
+});
+
+describe("Prepend/Append integration with expandHashtags", () => {
+  it("should collect append blocks during expansion", () => {
+    const registry = createRegistry([
+      ["jira", "Jira MCP server\n<append>\nJira reference docs\n</append>"],
+    ]);
+
+    const result = expandHashtags("Create a ticket in #jira", registry);
+
+    expect(result.text).toBe("Create a ticket in Jira MCP server");
+    expect(result.append).toEqual(["Jira reference docs"]);
+  });
+
+  it("should collect prepend blocks during expansion", () => {
+    const registry = createRegistry([
+      ["context", "<prepend>\nImportant context\n</prepend>\nUse the context"],
+    ]);
+
+    const result = expandHashtags("#context please", registry);
+
+    expect(result.text).toBe("Use the context please");
+    expect(result.prepend).toEqual(["Important context"]);
+  });
+
+  it("should collect blocks from nested snippets", () => {
+    const registry = createRegistry([
+      ["outer", "Outer #inner text"],
+      ["inner", "Inner\n<append>\nInner's append\n</append>"],
+    ]);
+
+    const result = expandHashtags("#outer", registry);
+
+    expect(result.text).toBe("Outer Inner text");
+    expect(result.append).toEqual(["Inner's append"]);
+  });
+
+  it("should collect blocks from multiple snippets", () => {
+    const registry = createRegistry([
+      ["a", "A text\n<append>\nA's append\n</append>"],
+      ["b", "B text\n<append>\nB's append\n</append>"],
+    ]);
+
+    const result = expandHashtags("#a and #b", registry);
+
+    expect(result.text).toBe("A text and B text");
+    expect(result.append).toEqual(["A's append", "B's append"]);
+  });
+
+  it("should handle empty inline with only blocks", () => {
+    const registry = createRegistry([["ref", "<append>\nReference material\n</append>"]]);
+
+    const result = expandHashtags("Use #ref here", registry);
+
+    expect(result.text).toBe("Use  here");
+    expect(result.append).toEqual(["Reference material"]);
+  });
+
+  it("should assemble full message correctly", () => {
+    const registry = createRegistry([
+      ["jira", "Jira MCP server\n<append>\n## Jira Usage\n- Field mappings here\n</append>"],
+    ]);
+
+    const result = expandHashtags("Create a bug ticket in #jira about the memory leak", registry);
+    const assembled = assembleMessage(result);
+
+    expect(assembled).toBe(
+      "Create a bug ticket in Jira MCP server about the memory leak\n\n## Jira Usage\n- Field mappings here",
+    );
+  });
+
+  it("should collect multiple append blocks from single snippet", () => {
+    const registry = createRegistry([
+      ["multi", "Inline\n<append>\nFirst append\n</append>\n<append>\nSecond append\n</append>"],
+    ]);
+
+    const result = expandHashtags("#multi", registry);
+
+    expect(result.text).toBe("Inline");
+    expect(result.append).toEqual(["First append", "Second append"]);
+  });
+
+  it("should collect multiple prepend blocks from single snippet", () => {
+    const registry = createRegistry([
+      [
+        "multi",
+        "<prepend>\nFirst prepend\n</prepend>\n<prepend>\nSecond prepend\n</prepend>\nInline",
+      ],
+    ]);
+
+    const result = expandHashtags("#multi", registry);
+
+    expect(result.text).toBe("Inline");
+    expect(result.prepend).toEqual(["First prepend", "Second prepend"]);
+  });
+
+  it("should assemble multiple prepends and appends in correct order", () => {
+    const registry = createRegistry([
+      ["a", "<prepend>\nA prepend\n</prepend>\nA inline\n<append>\nA append\n</append>"],
+      ["b", "<prepend>\nB prepend\n</prepend>\nB inline\n<append>\nB append\n</append>"],
+    ]);
+
+    const result = expandHashtags("#a then #b", registry);
+    const assembled = assembleMessage(result);
+
+    // Prepends first (in order), then inline, then appends (in order)
+    expect(assembled).toBe(
+      "A prepend\n\nB prepend\n\nA inline then B inline\n\nA append\n\nB append",
+    );
+  });
+
+  it("should handle mix of snippets with and without blocks", () => {
+    const registry = createRegistry([
+      ["plain", "Plain content"],
+      ["withblocks", "Block inline\n<append>\nBlock append\n</append>"],
+    ]);
+
+    const result = expandHashtags("#plain and #withblocks", registry);
+    const assembled = assembleMessage(result);
+
+    expect(assembled).toBe("Plain content and Block inline\n\nBlock append");
+  });
+});

package/src/expander.ts

@@ -1,25 +1,125 @@
 import { PATTERNS } from "./constants.js";
 import { logger } from "./logger.js";
-import type { SnippetRegistry } from "./types.js";
+import type { ExpansionResult, ParsedSnippetContent, SnippetRegistry } from "./types.js";
 
 /**
  * Maximum number of times a snippet can be expanded to prevent infinite loops
  */
 const MAX_EXPANSION_COUNT = 15;
 
+/**
+ * Tag types for parsing
+ */
+type BlockType = "prepend" | "append";
+
+/**
+ * Parses snippet content to extract inline text and prepend/append blocks
+ *
+ * Uses a lenient stack-based parser:
+ * - Unclosed tags → treat rest of content as block
+ * - Nesting → log error, return null (skip expansion)
+ * - Multiple blocks → collected in document order
+ *
+ * @param content - The raw snippet content to parse
+ * @returns Parsed content with inline, prepend, and append parts, or null on error
+ */
+export function parseSnippetBlocks(content: string): ParsedSnippetContent | null {
+  const prepend: string[] = [];
+  const append: string[] = [];
+  let inline = "";
+
+  // Regex to find opening and closing tags
+  const tagPattern = /<(\/?)(?<tagName>prepend|append)>/gi;
+  let lastIndex = 0;
+  let currentBlock: { type: BlockType; startIndex: number; contentStart: number } | null = null;
+
+  let match = tagPattern.exec(content);
+  while (match !== null) {
+    const isClosing = match[1] === "/";
+    const tagName = match.groups?.tagName?.toLowerCase() as BlockType;
+    const tagStart = match.index;
+    const tagEnd = tagStart + match[0].length;
+
+    if (isClosing) {
+      // Closing tag
+      if (currentBlock === null) {
+        // Closing tag without opening - ignore it, treat as inline content
+        continue;
+      }
+      if (currentBlock.type !== tagName) {
+        // Mismatched closing tag - this is a nesting error
+        logger.warn(
+          `Mismatched closing tag: expected </${currentBlock.type}>, found </${tagName}>`,
+        );
+        return null;
+      }
+      // Extract block content
+      const blockContent = content.slice(currentBlock.contentStart, tagStart).trim();
+      if (blockContent) {
+        if (currentBlock.type === "prepend") {
+          prepend.push(blockContent);
+        } else {
+          append.push(blockContent);
+        }
+      }
+      lastIndex = tagEnd;
+      currentBlock = null;
+    } else {
+      // Opening tag
+      if (currentBlock !== null) {
+        // Nested opening tag - error
+        logger.warn(`Nested tags not allowed: found <${tagName}> inside <${currentBlock.type}>`);
+        return null;
+      }
+      // Add any inline content before this tag
+      const inlinePart = content.slice(lastIndex, tagStart);
+      inline += inlinePart;
+      currentBlock = { type: tagName, startIndex: tagStart, contentStart: tagEnd };
+    }
+    match = tagPattern.exec(content);
+  }
+
+  // Handle unclosed tag (lenient: treat rest as block content)
+  if (currentBlock !== null) {
+    const blockContent = content.slice(currentBlock.contentStart).trim();
+    if (blockContent) {
+      if (currentBlock.type === "prepend") {
+        prepend.push(blockContent);
+      } else {
+        append.push(blockContent);
+      }
+    }
+  } else {
+    // Add any remaining inline content
+    inline += content.slice(lastIndex);
+  }
+
+  return {
+    inline: inline.trim(),
+    prepend,
+    append,
+  };
+}
+
 /**
  * Expands hashtags in text recursively with loop detection
  *
+ * Returns an ExpansionResult containing the inline-expanded text plus
+ * collected prepend/append blocks from all expanded snippets.
+ *
  * @param text - The text containing hashtags to expand
  * @param registry - The snippet registry to look up hashtags
  * @param expansionCounts - Map tracking how many times each snippet has been expanded
- * @returns The text with all hashtags expanded
+ * @returns ExpansionResult with text and collected blocks
  */
 export function expandHashtags(
   text: string,
   registry: SnippetRegistry,
   expansionCounts = new Map<string, number>(),
-): string {
+): ExpansionResult {
+  const collectedPrepend: string[] = [];
+  const collectedAppend: string[] = [];
+
   let expanded = text;
   let hasChanges = true;
 
@@ -31,6 +131,10 @@ export function expandHashtags(
     // Reset regex state (global flag requires this)
     PATTERNS.HASHTAG.lastIndex = 0;
 
+    // We need to collect blocks during replacement, so we track them here
+    const roundPrepend: string[] = [];
+    const roundAppend: string[] = [];
+
     expanded = expanded.replace(PATTERNS.HASHTAG, (match, name) => {
       const key = name.toLowerCase();
 
@@ -53,15 +157,69 @@ export function expandHashtags(
 
       expansionCounts.set(key, count);
 
-      // Recursively expand any hashtags in the snippet content
-      const result = expandHashtags(snippet.content, registry, expansionCounts);
+      // Parse the snippet content for blocks
+      const parsed = parseSnippetBlocks(snippet.content);
+      if (parsed === null) {
+        // Parse error - leave hashtag unchanged
+        logger.warn(`Failed to parse snippet '${key}', leaving hashtag unchanged`);
+        return match;
+      }
+
+      // Collect prepend/append blocks
+      roundPrepend.push(...parsed.prepend);
+      roundAppend.push(...parsed.append);
 
-      return result;
+      // Recursively expand any hashtags in the inline content
+      const nestedResult = expandHashtags(parsed.inline, registry, expansionCounts);
+
+      // Collect blocks from nested expansion
+      roundPrepend.push(...nestedResult.prepend);
+      roundAppend.push(...nestedResult.append);
+
+      return nestedResult.text;
     });
 
+    // Add this round's blocks to collected blocks
+    collectedPrepend.push(...roundPrepend);
+    collectedAppend.push(...roundAppend);
+
     // Only continue if the text actually changed AND no loop was detected
     hasChanges = expanded !== previous && !loopDetected;
   }
 
-  return expanded;
+  return {
+    text: expanded,
+    prepend: collectedPrepend,
+    append: collectedAppend,
+  };
+}
+
+/**
+ * Assembles the final message from an expansion result
+ *
+ * Joins: prepend blocks + inline text + append blocks
+ * with double newlines between non-empty sections.
+ *
+ * @param result - The expansion result to assemble
+ * @returns The final assembled message
+ */
+export function assembleMessage(result: ExpansionResult): string {
+  const parts: string[] = [];
+
+  // Add prepend blocks
+  if (result.prepend.length > 0) {
+    parts.push(result.prepend.join("\n\n"));
+  }
+
+  // Add main text
+  if (result.text.trim()) {
+    parts.push(result.text);
+  }
+
+  // Add append blocks
+  if (result.append.length > 0) {
+    parts.push(result.append.join("\n\n"));
+  }
+
+  return parts.join("\n\n");
 }

package/src/types.ts

@@ -36,3 +36,27 @@ export interface SnippetFrontmatter {
   /** Optional description of what this snippet does */
   description?: string;
 }
+
+/**
+ * Parsed snippet content with inline text and prepend/append blocks
+ */
+export interface ParsedSnippetContent {
+  /** Content outside blocks (replaces hashtag inline) */
+  inline: string;
+  /** <prepend> block contents in document order */
+  prepend: string[];
+  /** <append> block contents in document order */
+  append: string[];
+}
+
+/**
+ * Result of expanding hashtags, including collected prepend/append blocks
+ */
+export interface ExpansionResult {
+  /** The inline-expanded text */
+  text: string;
+  /** Collected prepend blocks from all expanded snippets */
+  prepend: string[];
+  /** Collected append blocks from all expanded snippets */
+  append: string[];
+}