opencode-snippets 1.2.0 → 1.4.0

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,11 +131,15 @@ 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();
 
-      const content = registry.get(key);
-      if (content === undefined) {
+      const snippet = registry.get(key);
+      if (snippet === undefined) {
         // Unknown snippet - leave as-is
         return match;
       }
@@ -53,15 +157,69 @@ export function expandHashtags(
 
       expansionCounts.set(key, count);
 
-      // Recursively expand any hashtags in the snippet content
-      const result = expandHashtags(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/loader.test.ts

@@ -35,8 +35,8 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(undefined, globalSnippetDir);
 
       expect(snippets.size).toBe(2);
-      expect(snippets.get("careful")).toBe("Think step by step. Double-check your work.");
-      expect(snippets.get("safe")).toBe("Think step by step. Double-check your work.");
+      expect(snippets.get("careful")?.content).toBe("Think step by step. Double-check your work.");
+      expect(snippets.get("safe")?.content).toBe("Think step by step. Double-check your work.");
     });
 
     it("should load multiple snippets from global directory", async () => {
@@ -46,8 +46,8 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(undefined, globalSnippetDir);
 
       expect(snippets.size).toBe(2);
-      expect(snippets.get("snippet1")).toBe("Content of snippet 1");
-      expect(snippets.get("snippet2")).toBe("Content of snippet 2");
+      expect(snippets.get("snippet1")?.content).toBe("Content of snippet 1");
+      expect(snippets.get("snippet2")?.content).toBe("Content of snippet 2");
     });
   });
 
@@ -63,7 +63,7 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       expect(snippets.size).toBe(1);
-      expect(snippets.get("project-specific")).toBe("This is a project-specific snippet");
+      expect(snippets.get("project-specific")?.content).toBe("This is a project-specific snippet");
     });
 
     it("should handle missing global directory when project exists", async () => {
@@ -74,8 +74,8 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       expect(snippets.size).toBe(2);
-      expect(snippets.get("team-rule")).toBe("Team rule 1");
-      expect(snippets.get("domain-knowledge")).toBe("Domain knowledge");
+      expect(snippets.get("team-rule")?.content).toBe("Team rule 1");
+      expect(snippets.get("domain-knowledge")?.content).toBe("Domain knowledge");
     });
   });
 
@@ -91,8 +91,8 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       expect(snippets.size).toBe(2);
-      expect(snippets.get("global")).toBe("Global snippet content");
-      expect(snippets.get("project")).toBe("Project snippet content");
+      expect(snippets.get("global")?.content).toBe("Global snippet content");
+      expect(snippets.get("project")?.content).toBe("Project snippet content");
     });
 
     it("should allow project snippets to override global snippets", async () => {
@@ -106,7 +106,7 @@ Think step by step. Double-check your work.`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       // Project snippet should override global
-      expect(snippets.get("careful")).toBe("Project-specific careful content");
+      expect(snippets.get("careful")?.content).toBe("Project-specific careful content");
       expect(snippets.size).toBe(1);
     });
   });
@@ -139,12 +139,12 @@ Project test guidelines`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       expect(snippets.size).toBe(6); // review, pr, check, test, tdd, testing
-      expect(snippets.get("review")).toBe("Global review guidelines");
-      expect(snippets.get("pr")).toBe("Global review guidelines");
-      expect(snippets.get("check")).toBe("Global review guidelines");
-      expect(snippets.get("test")).toBe("Project test guidelines");
-      expect(snippets.get("tdd")).toBe("Project test guidelines");
-      expect(snippets.get("testing")).toBe("Project test guidelines");
+      expect(snippets.get("review")?.content).toBe("Global review guidelines");
+      expect(snippets.get("pr")?.content).toBe("Global review guidelines");
+      expect(snippets.get("check")?.content).toBe("Global review guidelines");
+      expect(snippets.get("test")?.content).toBe("Project test guidelines");
+      expect(snippets.get("tdd")?.content).toBe("Project test guidelines");
+      expect(snippets.get("testing")?.content).toBe("Project test guidelines");
     });
 
     it("should allow project to override global aliases", async () => {
@@ -172,9 +172,9 @@ Project careful`,
       const snippets = await loadSnippets(projectDir, globalSnippetDir);
 
       // Project should override with its aliases
-      expect(snippets.get("careful")).toBe("Project careful");
-      expect(snippets.get("safe")).toBe("Project careful");
-      expect(snippets.get("cautious")).toBeUndefined();
+      expect(snippets.get("careful")?.content).toBe("Project careful");
+      expect(snippets.get("safe")?.content).toBe("Project careful");
+      expect(snippets.get("cautious")?.content).toBeUndefined();
       expect(snippets.size).toBe(2);
     });
   });
@@ -185,7 +185,7 @@ Project careful`,
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
       expect(snippets.size).toBe(1);
-      expect(snippets.get("empty")).toBe("");
+      expect(snippets.get("empty")?.content).toBe("");
     });
 
     it("should handle snippet with only metadata", async () => {
@@ -199,8 +199,8 @@ aliases: meta
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
       expect(snippets.size).toBe(2);
-      expect(snippets.get("metadata-only")).toBe("");
-      expect(snippets.get("meta")).toBe("");
+      expect(snippets.get("metadata-only")?.content).toBe("");
+      expect(snippets.get("meta")?.content).toBe("");
     });
 
     it("should handle multiline content", async () => {
@@ -212,7 +212,7 @@ Line 3`,
       );
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
-      expect(snippets.get("multiline")).toBe("Line 1\nLine 2\nLine 3");
+      expect(snippets.get("multiline")?.content).toBe("Line 1\nLine 2\nLine 3");
     });
 
     it("should ignore non-.md files", async () => {
@@ -221,7 +221,7 @@ Line 3`,
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
       expect(snippets.size).toBe(1);
-      expect(snippets.get("valid")).toBe("This should be loaded");
+      expect(snippets.get("valid")?.content).toBe("This should be loaded");
       expect(snippets.has("not-a-snippet")).toBe(false);
     });
 
@@ -238,7 +238,7 @@ Content`,
 
       const snippets = await loadSnippets(undefined, globalSnippetDir);
       // Should load valid snippet, skip invalid one
-      expect(snippets.get("special-chars")).toBe("Special content");
+      expect(snippets.get("special-chars")?.content).toBe("Special content");
     });
 
     it("should handle non-existent directories gracefully", async () => {

package/src/loader.ts

@@ -1,16 +1,16 @@
-import { readdir, readFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import matter from "gray-matter";
 import { CONFIG, PATHS } from "./constants.js";
 import { logger } from "./logger.js";
-import type { SnippetFrontmatter, SnippetRegistry } from "./types.js";
+import type { SnippetFrontmatter, SnippetInfo, SnippetRegistry } from "./types.js";
 
 /**
  * Loads all snippets from global and project directories
  *
  * @param projectDir - Optional project directory path (from ctx.directory)
  * @param globalDir - Optional global snippets directory (for testing)
- * @returns A map of snippet keys (lowercase) to their content
+ * @returns A map of snippet keys (lowercase) to their SnippetInfo
  */
 export async function loadSnippets(
   projectDir?: string,
@@ -41,7 +41,7 @@ export async function loadSnippets(
 async function loadFromDirectory(
   dir: string,
   registry: SnippetRegistry,
-  source: string,
+  source: "global" | "project",
 ): Promise<void> {
   try {
     const files = await readdir(dir);
@@ -49,9 +49,9 @@ async function loadFromDirectory(
     for (const file of files) {
       if (!file.endsWith(CONFIG.SNIPPET_EXTENSION)) continue;
 
-      const snippet = await loadSnippetFile(dir, file);
+      const snippet = await loadSnippetFile(dir, file, source);
       if (snippet) {
-        registerSnippet(registry, snippet.name, snippet.content, snippet.aliases);
+        registerSnippet(registry, snippet);
       }
     }
 
@@ -73,9 +73,14 @@ async function loadFromDirectory(
  *
  * @param dir - Directory containing the snippet file
  * @param filename - The filename to load (e.g., "my-snippet.md")
- * @returns The parsed snippet data, or null if parsing failed
+ * @param source - Whether this is a global or project snippet
+ * @returns The parsed snippet info, or null if parsing failed
  */
-async function loadSnippetFile(dir: string, filename: string) {
+async function loadSnippetFile(
+  dir: string,
+  filename: string,
+  source: "global" | "project",
+): Promise<SnippetInfo | null> {
   try {
     const name = basename(filename, CONFIG.SNIPPET_EXTENSION);
     const filePath = join(dir, filename);
@@ -95,7 +100,14 @@ async function loadSnippetFile(dir: string, filename: string) {
       }
     }
 
-    return { name, content, aliases };
+    return {
+      name,
+      content,
+      aliases,
+      description: frontmatter.description,
+      filePath,
+      source,
+    };
   } catch (error) {
     // Failed to read or parse this snippet - skip it
     logger.warn("Failed to load snippet file", {
@@ -109,34 +121,146 @@ async function loadSnippetFile(dir: string, filename: string) {
 /**
  * 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 registry - The registry to add the snippet to
+ * @param snippet - The snippet info to register
+ */
+function registerSnippet(registry: SnippetRegistry, snippet: SnippetInfo): void {
+  const key = snippet.name.toLowerCase();
+
+  // If snippet with same name exists, remove its old aliases first
+  const existing = registry.get(key);
+  if (existing) {
+    for (const alias of existing.aliases) {
+      registry.delete(alias.toLowerCase());
+    }
+  }
+
+  // Register the snippet under its name
+  registry.set(key, snippet);
+
+  // Register under all aliases (pointing to the same snippet info)
+  for (const alias of snippet.aliases) {
+    registry.set(alias.toLowerCase(), snippet);
+  }
+}
+
+/**
+ * Lists all unique snippets (by name) from the registry
+ *
+ * @param registry - The snippet registry
+ * @returns Array of unique snippet info objects
+ */
+export function listSnippets(registry: SnippetRegistry): SnippetInfo[] {
+  const seen = new Set<string>();
+  const snippets: SnippetInfo[] = [];
+
+  for (const snippet of registry.values()) {
+    if (!seen.has(snippet.name)) {
+      seen.add(snippet.name);
+      snippets.push(snippet);
+    }
+  }
+
+  return snippets;
+}
+
+/**
+ * Ensures the snippets directory exists
+ */
+export async function ensureSnippetsDir(projectDir?: string): Promise<string> {
+  const dir = projectDir ? join(projectDir, ".opencode", "snippet") : PATHS.SNIPPETS_DIR;
+  await mkdir(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Creates a new snippet file
+ *
+ * @param name - The snippet name (without extension)
  * @param content - The snippet content
- * @param aliases - Alternative names for the snippet
+ * @param options - Optional metadata (aliases, description)
+ * @param projectDir - If provided, creates in project directory; otherwise global
+ * @returns The path to the created snippet file
  */
-function registerSnippet(
-  registry: SnippetRegistry,
+export async function createSnippet(
   name: string,
   content: string,
-  aliases: string[],
-) {
-  const key = name.toLowerCase();
-
-  // If snippet already exists, remove all entries with the old content
-  const oldContent = registry.get(key);
-  if (oldContent !== undefined) {
-    for (const [k, v] of registry.entries()) {
-      if (v === oldContent) {
-        registry.delete(k);
-      }
+  options: { aliases?: string[]; description?: string } = {},
+  projectDir?: string,
+): Promise<string> {
+  const dir = await ensureSnippetsDir(projectDir);
+  const filePath = join(dir, `${name}${CONFIG.SNIPPET_EXTENSION}`);
+
+  // Build frontmatter if we have metadata
+  const frontmatter: SnippetFrontmatter = {};
+  if (options.aliases?.length) {
+    frontmatter.aliases = options.aliases;
+  }
+  if (options.description) {
+    frontmatter.description = options.description;
+  }
+
+  // Create file content with frontmatter if needed
+  let fileContent: string;
+  if (Object.keys(frontmatter).length > 0) {
+    fileContent = matter.stringify(content, frontmatter);
+  } else {
+    fileContent = content;
+  }
+
+  await writeFile(filePath, fileContent, "utf-8");
+  logger.info("Created snippet", { name, path: filePath });
+
+  return filePath;
+}
+
+/**
+ * Deletes a snippet file
+ *
+ * @param name - The snippet name (without extension)
+ * @param projectDir - If provided, looks in project directory first; otherwise global
+ * @returns The path of the deleted file, or null if not found
+ */
+export async function deleteSnippet(name: string, projectDir?: string): Promise<string | null> {
+  // Try project directory first if provided
+  if (projectDir) {
+    const projectPath = join(
+      projectDir,
+      ".opencode",
+      "snippet",
+      `${name}${CONFIG.SNIPPET_EXTENSION}`,
+    );
+    try {
+      await unlink(projectPath);
+      logger.info("Deleted project snippet", { name, path: projectPath });
+      return projectPath;
+    } catch {
+      // Not found in project, try global
     }
   }
 
-  // Register with primary name (lowercase)
-  registry.set(key, content);
+  // Try global directory
+  const globalPath = join(PATHS.SNIPPETS_DIR, `${name}${CONFIG.SNIPPET_EXTENSION}`);
+  try {
+    await unlink(globalPath);
+    logger.info("Deleted global snippet", { name, path: globalPath });
+    return globalPath;
+  } catch {
+    logger.warn("Snippet not found for deletion", { name });
+    return null;
+  }
+}
 
-  // Register all aliases (lowercase)
-  for (const alias of aliases) {
-    registry.set(alias.toLowerCase(), content);
+/**
+ * Reloads snippets into the registry from disk
+ */
+export async function reloadSnippets(
+  registry: SnippetRegistry,
+  projectDir?: string,
+): Promise<void> {
+  registry.clear();
+  const fresh = await loadSnippets(projectDir);
+  for (const [key, value] of fresh) {
+    registry.set(key, value);
   }
 }

package/src/logger.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { OPENCODE_CONFIG_DIR } from "./constants.js";
+import { PATHS } from "./constants.js";
 
 /**
  * Check if debug logging is enabled via environment variable
@@ -14,7 +14,7 @@ export class Logger {
   private logDir: string;
 
   constructor(logDirOverride?: string) {
-    this.logDir = logDirOverride ?? join(OPENCODE_CONFIG_DIR, "logs", "snippets");
+    this.logDir = logDirOverride ?? join(PATHS.CONFIG_DIR, "logs", "snippets");
   }
 
   get enabled(): boolean {

package/src/notification.ts

@@ -0,0 +1,29 @@
+import { logger } from "./logger.js";
+
+/**
+ * Sends a message that will be displayed but ignored by the AI
+ * Used for command output that shouldn't trigger AI responses
+ *
+ * @param client - The OpenCode client instance
+ * @param sessionId - The current session ID
+ * @param text - The text to display
+ */
+export async function sendIgnoredMessage(
+  client: any,
+  sessionId: string,
+  text: string,
+): Promise<void> {
+  try {
+    await client.session.prompt({
+      path: { id: sessionId },
+      body: {
+        noReply: true,
+        parts: [{ type: "text", text, ignored: true }],
+      },
+    });
+  } catch (error) {
+    logger.error("Failed to send ignored message", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}