opencode-snippets 1.4.0 → 1.4.1

package/README.md

@@ -230,7 +230,7 @@ Use `<prepend>` for content that should appear at the top of your message. Multi
 - 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
+- Nested blocks are not allowed—the hashtag is left unchanged
 
 ## Example Snippets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-snippets",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts",
   "main": "index.ts",
   "type": "module",

package/src/arg-parser.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from "bun:test";
+import { parseCommandArgs } from "./arg-parser.js";
+
+describe("parseCommandArgs", () => {
+  // Basic splitting
+  describe("basic argument splitting", () => {
+    it("splits simple space-separated args", () => {
+      expect(parseCommandArgs("add test")).toEqual(["add", "test"]);
+    });
+
+    it("handles empty input", () => {
+      expect(parseCommandArgs("")).toEqual([]);
+    });
+
+    it("handles whitespace-only input", () => {
+      expect(parseCommandArgs("   ")).toEqual([]);
+    });
+
+    it("handles multiple spaces between args", () => {
+      expect(parseCommandArgs("add   test")).toEqual(["add", "test"]);
+    });
+
+    it("handles leading and trailing spaces", () => {
+      expect(parseCommandArgs("  add test  ")).toEqual(["add", "test"]);
+    });
+
+    it("handles tabs and mixed whitespace", () => {
+      expect(parseCommandArgs("add\t\ttest")).toEqual(["add", "test"]);
+    });
+  });
+
+  // Double quote handling
+  describe("double quote handling", () => {
+    it("preserves double-quoted strings with spaces", () => {
+      expect(parseCommandArgs('add "hello world"')).toEqual(["add", "hello world"]);
+    });
+
+    it("handles single quote inside double quotes", () => {
+      // THE MAIN BUG - apostrophe in description
+      expect(parseCommandArgs('--desc="don\'t do this"')).toEqual(["--desc=don't do this"]);
+    });
+
+    it("handles empty double-quoted string", () => {
+      expect(parseCommandArgs('add ""')).toEqual(["add", ""]);
+    });
+
+    it("handles double-quoted string at start", () => {
+      expect(parseCommandArgs('"hello world" test')).toEqual(["hello world", "test"]);
+    });
+
+    it("handles multiple double-quoted strings", () => {
+      expect(parseCommandArgs('"first" "second"')).toEqual(["first", "second"]);
+    });
+  });
+
+  // Single quote handling
+  describe("single quote handling", () => {
+    it("preserves single-quoted strings with spaces", () => {
+      expect(parseCommandArgs("add 'hello world'")).toEqual(["add", "hello world"]);
+    });
+
+    it("handles double quote inside single quotes", () => {
+      expect(parseCommandArgs("--desc='say \"hello\"'")).toEqual(['--desc=say "hello"']);
+    });
+
+    it("handles empty single-quoted string", () => {
+      expect(parseCommandArgs("add ''")).toEqual(["add", ""]);
+    });
+  });
+
+  // --key=value syntax
+  describe("--key=value syntax", () => {
+    it("handles --key=value without quotes", () => {
+      expect(parseCommandArgs("--desc=hello")).toEqual(["--desc=hello"]);
+    });
+
+    it('handles --key="value" with quotes stripped from value', () => {
+      expect(parseCommandArgs('--desc="hello world"')).toEqual(["--desc=hello world"]);
+    });
+
+    it("handles --key='value' with quotes stripped from value", () => {
+      expect(parseCommandArgs("--key='hello world'")).toEqual(["--key=hello world"]);
+    });
+
+    it("handles --key=value with special characters", () => {
+      expect(parseCommandArgs("--desc=hello,world")).toEqual(["--desc=hello,world"]);
+    });
+
+    it("preserves = inside quoted value", () => {
+      expect(parseCommandArgs('--desc="a=b"')).toEqual(["--desc=a=b"]);
+    });
+  });
+
+  // Multiline content (critical for snippet bodies)
+  describe("multiline content", () => {
+    it("handles multiline content in double quotes", () => {
+      expect(parseCommandArgs('add test "line1\nline2\nline3"')).toEqual([
+        "add",
+        "test",
+        "line1\nline2\nline3",
+      ]);
+    });
+
+    it("handles multiline content in single quotes", () => {
+      expect(parseCommandArgs("add test 'line1\nline2'")).toEqual(["add", "test", "line1\nline2"]);
+    });
+
+    it("handles multiline content with --key=value syntax", () => {
+      expect(parseCommandArgs('--desc="line1\nline2"')).toEqual(["--desc=line1\nline2"]);
+    });
+
+    it("preserves indentation in multiline content", () => {
+      const input = 'add test "line1\n  indented\n    more indented"';
+      expect(parseCommandArgs(input)).toEqual([
+        "add",
+        "test",
+        "line1\n  indented\n    more indented",
+      ]);
+    });
+  });
+
+  // Mixed scenarios
+  describe("mixed scenarios", () => {
+    it("handles mixed quoted and unquoted args", () => {
+      expect(parseCommandArgs('add test "hello world" --project')).toEqual([
+        "add",
+        "test",
+        "hello world",
+        "--project",
+      ]);
+    });
+
+    it("handles complex command with all option types", () => {
+      const input = 'add mysnippet "content here" --aliases=a,b --desc="don\'t forget" --project';
+      expect(parseCommandArgs(input)).toEqual([
+        "add",
+        "mysnippet",
+        "content here",
+        "--aliases=a,b",
+        "--desc=don't forget",
+        "--project",
+      ]);
+    });
+
+    it("handles --key value syntax (space-separated)", () => {
+      expect(parseCommandArgs("--desc hello")).toEqual(["--desc", "hello"]);
+    });
+
+    it("handles --key followed by quoted value", () => {
+      expect(parseCommandArgs('--desc "hello world"')).toEqual(["--desc", "hello world"]);
+    });
+  });
+
+  // Edge cases
+  describe("edge cases", () => {
+    it("handles unclosed double quote by including rest of string", () => {
+      // Graceful handling: treat unclosed quote as extending to end
+      expect(parseCommandArgs('add "unclosed')).toEqual(["add", "unclosed"]);
+    });
+
+    it("handles unclosed single quote by including rest of string", () => {
+      expect(parseCommandArgs("add 'unclosed")).toEqual(["add", "unclosed"]);
+    });
+
+    it("handles backslash-escaped quotes inside double quotes", () => {
+      expect(parseCommandArgs('--desc="say \\"hello\\""')).toEqual(['--desc=say "hello"']);
+    });
+
+    it("handles backslash-escaped quotes inside single quotes", () => {
+      expect(parseCommandArgs("--desc='it\\'s fine'")).toEqual(["--desc=it's fine"]);
+    });
+
+    it("handles literal backslash", () => {
+      expect(parseCommandArgs('--path="C:\\\\Users"')).toEqual(["--path=C:\\Users"]);
+    });
+  });
+});

package/src/arg-parser.ts

@@ -0,0 +1,87 @@
+/**
+ * Shell-like argument parser that handles quoted strings correctly.
+ *
+ * Supports:
+ * - Space-separated arguments
+ * - Double-quoted strings (preserves spaces, allows single quotes inside)
+ * - Single-quoted strings (preserves spaces, allows double quotes inside)
+ * - --key=value syntax with quoted values
+ * - Multiline content inside quotes
+ * - Backslash escapes for quotes inside quoted strings
+ *
+ * @param input - The raw argument string to parse
+ * @returns Array of parsed arguments with quotes stripped
+ */
+export function parseCommandArgs(input: string): string[] {
+  const args: string[] = [];
+  let current = "";
+  let state: "normal" | "double" | "single" = "normal";
+  let hasQuotedContent = false; // Track if we've entered a quoted section
+  let i = 0;
+
+  while (i < input.length) {
+    const char = input[i];
+
+    if (state === "normal") {
+      if (char === " " || char === "\t") {
+        // Whitespace in normal mode: finish current token
+        if (current.length > 0 || hasQuotedContent) {
+          args.push(current);
+          current = "";
+          hasQuotedContent = false;
+        }
+      } else if (char === '"') {
+        // Enter double-quote mode
+        state = "double";
+        hasQuotedContent = true;
+      } else if (char === "'") {
+        // Enter single-quote mode
+        state = "single";
+        hasQuotedContent = true;
+      } else {
+        current += char;
+      }
+    } else if (state === "double") {
+      if (char === "\\") {
+        // Check for escape sequences
+        const next = input[i + 1];
+        if (next === '"' || next === "\\") {
+          current += next;
+          i++; // Skip the escaped character
+        } else {
+          current += char;
+        }
+      } else if (char === '"') {
+        // Exit double-quote mode
+        state = "normal";
+      } else {
+        current += char;
+      }
+    } else if (state === "single") {
+      if (char === "\\") {
+        // Check for escape sequences
+        const next = input[i + 1];
+        if (next === "'" || next === "\\") {
+          current += next;
+          i++; // Skip the escaped character
+        } else {
+          current += char;
+        }
+      } else if (char === "'") {
+        // Exit single-quote mode
+        state = "normal";
+      } else {
+        current += char;
+      }
+    }
+
+    i++;
+  }
+
+  // Handle any remaining content (including unclosed quotes or empty quoted strings)
+  if (current.length > 0 || hasQuotedContent) {
+    args.push(current);
+  }
+
+  return args;
+}

package/src/commands.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "bun:test";
+import { parseAddOptions } from "./commands.js";
+
+describe("parseAddOptions", () => {
+  // Alias variations - all 4 must work per PR #13 requirements
+  describe("alias parameter variations", () => {
+    it("parses --alias=a,b", () => {
+      expect(parseAddOptions(["--alias=a,b"])).toEqual({
+        aliases: ["a", "b"],
+        description: undefined,
+        isProject: false,
+      });
+    });
+
+    it("parses --alias a,b (space-separated)", () => {
+      expect(parseAddOptions(["--alias", "a,b"])).toEqual({
+        aliases: ["a", "b"],
+        description: undefined,
+        isProject: false,
+      });
+    });
+
+    it("parses --aliases=a,b", () => {
+      expect(parseAddOptions(["--aliases=a,b"])).toEqual({
+        aliases: ["a", "b"],
+        description: undefined,
+        isProject: false,
+      });
+    });
+
+    it("parses --aliases a,b (space-separated)", () => {
+      expect(parseAddOptions(["--aliases", "a,b"])).toEqual({
+        aliases: ["a", "b"],
+        description: undefined,
+        isProject: false,
+      });
+    });
+
+    it("parses single alias", () => {
+      expect(parseAddOptions(["--alias=foo"])).toEqual({
+        aliases: ["foo"],
+        description: undefined,
+        isProject: false,
+      });
+    });
+
+    it("handles multiple alias values with spaces", () => {
+      expect(parseAddOptions(["--aliases=hello, world, foo"])).toEqual({
+        aliases: ["hello", "world", "foo"],
+        description: undefined,
+        isProject: false,
+      });
+    });
+  });
+
+  // Description variations - all must work
+  describe("description parameter variations", () => {
+    it("parses --desc=value", () => {
+      expect(parseAddOptions(["--desc=hello"])).toEqual({
+        aliases: [],
+        description: "hello",
+        isProject: false,
+      });
+    });
+
+    it("parses --desc value (space-separated)", () => {
+      expect(parseAddOptions(["--desc", "hello"])).toEqual({
+        aliases: [],
+        description: "hello",
+        isProject: false,
+      });
+    });
+
+    it("parses --desc with apostrophe (main bug)", () => {
+      expect(parseAddOptions(["--desc=don't break"])).toEqual({
+        aliases: [],
+        description: "don't break",
+        isProject: false,
+      });
+    });
+
+    it("parses --description=value", () => {
+      expect(parseAddOptions(["--description=test"])).toEqual({
+        aliases: [],
+        description: "test",
+        isProject: false,
+      });
+    });
+
+    it("parses --description value (space-separated)", () => {
+      expect(parseAddOptions(["--description", "test"])).toEqual({
+        aliases: [],
+        description: "test",
+        isProject: false,
+      });
+    });
+
+    it("parses --desc with multiline content", () => {
+      expect(parseAddOptions(["--desc=line1\nline2"])).toEqual({
+        aliases: [],
+        description: "line1\nline2",
+        isProject: false,
+      });
+    });
+  });
+
+  // Project flag
+  describe("--project flag", () => {
+    it("parses --project flag", () => {
+      expect(parseAddOptions(["--project"])).toEqual({
+        aliases: [],
+        description: undefined,
+        isProject: true,
+      });
+    });
+
+    it("parses --project in any position", () => {
+      expect(parseAddOptions(["--desc=test", "--project"])).toEqual({
+        aliases: [],
+        description: "test",
+        isProject: true,
+      });
+    });
+  });
+
+  // Combined options
+  describe("combined options", () => {
+    it("parses multiple options together", () => {
+      expect(parseAddOptions(["--alias=a,b", "--desc=hello", "--project"])).toEqual({
+        aliases: ["a", "b"],
+        description: "hello",
+        isProject: true,
+      });
+    });
+
+    it("parses all space-separated options together", () => {
+      expect(parseAddOptions(["--alias", "a,b", "--desc", "hello", "--project"])).toEqual({
+        aliases: ["a", "b"],
+        description: "hello",
+        isProject: true,
+      });
+    });
+
+    it("handles mixed = and space syntax", () => {
+      expect(parseAddOptions(["--alias=a,b", "--desc", "hello"])).toEqual({
+        aliases: ["a", "b"],
+        description: "hello",
+        isProject: false,
+      });
+    });
+  });
+
+  // Edge cases
+  describe("edge cases", () => {
+    it("returns defaults for empty args", () => {
+      expect(parseAddOptions([])).toEqual({
+        aliases: [],
+        description: undefined,
+        isProject: false,
+      });
+    });
+
+    it("ignores unknown options", () => {
+      expect(parseAddOptions(["--unknown=value", "--desc=hello"])).toEqual({
+        aliases: [],
+        description: "hello",
+        isProject: false,
+      });
+    });
+
+    it("ignores positional args (non-option)", () => {
+      expect(parseAddOptions(["positional", "--desc=hello"])).toEqual({
+        aliases: [],
+        description: "hello",
+        isProject: false,
+      });
+    });
+
+    it("does not consume value after --project", () => {
+      // --project is a flag, should not consume next arg
+      expect(parseAddOptions(["--project", "--desc=hello"])).toEqual({
+        aliases: [],
+        description: "hello",
+        isProject: true,
+      });
+    });
+  });
+});

package/src/commands.ts

@@ -1,14 +1,15 @@
+import { parseCommandArgs } from "./arg-parser.js";
 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";
+import type { OpencodeClient, SnippetRegistry } from "./types.js";
 
 /** Marker error to indicate command was handled */
 const COMMAND_HANDLED_MARKER = "__SNIPPETS_COMMAND_HANDLED__";
 
 interface CommandContext {
-  client: any;
+  client: OpencodeClient;
   sessionId: string;
   args: string[];
   rawArguments: string;
@@ -16,18 +17,113 @@ interface CommandContext {
   projectDir?: string;
 }
 
+/**
+ * Parsed options from the add command arguments
+ */
+export interface AddOptions {
+  aliases: string[];
+  description: string | undefined;
+  isProject: boolean;
+}
+
+/**
+ * Parses option arguments for the add command.
+ *
+ * Supports all variations per PR #13 requirements:
+ * - --alias=a,b, --alias a,b, --aliases=a,b, --aliases a,b
+ * - --desc=x, --desc x, --description=x, --description x
+ * - --project flag
+ *
+ * @param args - Array of parsed arguments (after name and content extraction)
+ * @returns Parsed options object
+ */
+export function parseAddOptions(args: string[]): AddOptions {
+  const result: AddOptions = {
+    aliases: [],
+    description: undefined,
+    isProject: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    // Skip non-option arguments
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+
+    // Handle --project flag
+    if (arg === "--project") {
+      result.isProject = true;
+      continue;
+    }
+
+    // Check for --alias or --aliases
+    if (arg === "--alias" || arg === "--aliases") {
+      // Space-separated: --alias a,b
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith("--")) {
+        result.aliases = parseAliasValue(nextArg);
+        i++; // Skip the value arg
+      }
+      continue;
+    }
+
+    if (arg.startsWith("--alias=") || arg.startsWith("--aliases=")) {
+      // Equals syntax: --alias=a,b
+      const value = arg.includes("--aliases=")
+        ? arg.slice("--aliases=".length)
+        : arg.slice("--alias=".length);
+      result.aliases = parseAliasValue(value);
+      continue;
+    }
+
+    // Check for --desc or --description
+    if (arg === "--desc" || arg === "--description") {
+      // Space-separated: --desc value
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith("--")) {
+        result.description = nextArg;
+        i++; // Skip the value arg
+      }
+      continue;
+    }
+
+    if (arg.startsWith("--desc=") || arg.startsWith("--description=")) {
+      // Equals syntax: --desc=value
+      const value = arg.startsWith("--description=")
+        ? arg.slice("--description=".length)
+        : arg.slice("--desc=".length);
+      result.description = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse comma-separated alias values, trimming whitespace
+ */
+function parseAliasValue(value: string): string[] {
+  return value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
 /**
  * Creates the command execute handler for the snippets command
  */
 export function createCommandExecuteHandler(
-  client: any,
+  client: OpencodeClient,
   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);
+    // Use shell-like argument parsing to handle quoted strings correctly
+    const args = parseCommandArgs(input.arguments);
     const subcommand = args[0]?.toLowerCase() || "help";
 
     const ctx: CommandContext = {
@@ -83,7 +179,7 @@ export function createCommandExecuteHandler(
  * 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;
+  const { client, sessionId, args, snippets, projectDir } = ctx;
 
   if (args.length === 0) {
     await sendIgnoredMessage(
@@ -106,47 +202,30 @@ async function handleAddCommand(ctx: CommandContext): Promise<void> {
 
   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];
+  // Extract content: second argument if it doesn't start with --
+  // The arg-parser already handles quoted strings, so content is clean
+  let content = "";
+  let optionArgs = args.slice(1);
 
-    // 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
-      }
-    }
+  if (args[1] && !args[1].startsWith("--")) {
+    content = args[1];
+    optionArgs = args.slice(2);
   }
 
+  // Parse all options using the new parser
+  const options = parseAddOptions(optionArgs);
+
   // Default to global, --project puts it in project directory
-  const targetDir = isProject ? projectDir : undefined;
-  const location = isProject && projectDir ? "project" : "global";
+  const targetDir = options.isProject ? projectDir : undefined;
+  const location = options.isProject && projectDir ? "project" : "global";
 
   try {
-    const filePath = await createSnippet(name, content, { aliases, description }, targetDir);
+    const filePath = await createSnippet(
+      name,
+      content,
+      { aliases: options.aliases, description: options.description },
+      targetDir,
+    );
 
     // Reload snippets
     await reloadSnippets(snippets, projectDir);
@@ -157,8 +236,8 @@ async function handleAddCommand(ctx: CommandContext): Promise<void> {
     } else {
       message += "\n\nEdit the file to add your snippet content.";
     }
-    if (aliases.length > 0) {
-      message += `\nAliases: ${aliases.join(", ")}`;
+    if (options.aliases.length > 0) {
+      message += `\nAliases: ${options.aliases.join(", ")}`;
     }
 
     await sendIgnoredMessage(client, sessionId, message);

package/src/expander.test.ts

@@ -563,7 +563,7 @@ Only append content
       });
     });
 
-    it("should return null for nested tags", () => {
+    it("should return null for nested tags (different types)", () => {
       const content = "<append>\n<prepend>\nnested\n</prepend>\n</append>";
 
       const result = parseSnippetBlocks(content);
@@ -571,6 +571,14 @@ Only append content
       expect(result).toBeNull();
     });
 
+    it("should return null for nested tags (same type)", () => {
+      const content = "<prepend>\n<prepend>\nnested\n</prepend>\n</prepend>";
+
+      const result = parseSnippetBlocks(content);
+
+      expect(result).toBeNull();
+    });
+
     it("should trim content inside blocks", () => {
       const content = "<append>\n  \n  Content with whitespace  \n  \n</append>";
 

package/src/loader.test.ts

@@ -258,4 +258,95 @@ Content`,
       expect(Array.isArray(Array.from(snippets.keys()))).toBe(true);
     });
   });
+
+  // PR #13 requirement: accept both 'alias' and 'aliases' in frontmatter
+  describe("Frontmatter alias/aliases normalization", () => {
+    it("accepts 'alias' as string (singular form)", async () => {
+      await writeFile(
+        join(globalSnippetDir, "greeting.md"),
+        `---
+alias: hi
+---
+Hello there!`,
+      );
+
+      const snippets = await loadSnippets(undefined, globalSnippetDir);
+
+      expect(snippets.size).toBe(2);
+      expect(snippets.get("greeting")?.content).toBe("Hello there!");
+      expect(snippets.get("hi")?.content).toBe("Hello there!");
+    });
+
+    it("accepts 'alias' as array (singular form)", async () => {
+      await writeFile(
+        join(globalSnippetDir, "greeting.md"),
+        `---
+alias:
+  - hi
+  - hello
+---
+Hello there!`,
+      );
+
+      const snippets = await loadSnippets(undefined, globalSnippetDir);
+
+      expect(snippets.size).toBe(3);
+      expect(snippets.get("greeting")?.content).toBe("Hello there!");
+      expect(snippets.get("hi")?.content).toBe("Hello there!");
+      expect(snippets.get("hello")?.content).toBe("Hello there!");
+    });
+
+    it("accepts 'aliases' as string (existing behavior)", async () => {
+      await writeFile(
+        join(globalSnippetDir, "greeting.md"),
+        `---
+aliases: hi
+---
+Hello there!`,
+      );
+
+      const snippets = await loadSnippets(undefined, globalSnippetDir);
+
+      expect(snippets.size).toBe(2);
+      expect(snippets.get("greeting")?.content).toBe("Hello there!");
+      expect(snippets.get("hi")?.content).toBe("Hello there!");
+    });
+
+    it("accepts 'aliases' as array (existing behavior)", async () => {
+      await writeFile(
+        join(globalSnippetDir, "greeting.md"),
+        `---
+aliases:
+  - hi
+  - hello
+---
+Hello there!`,
+      );
+
+      const snippets = await loadSnippets(undefined, globalSnippetDir);
+
+      expect(snippets.size).toBe(3);
+      expect(snippets.get("greeting")?.content).toBe("Hello there!");
+      expect(snippets.get("hi")?.content).toBe("Hello there!");
+      expect(snippets.get("hello")?.content).toBe("Hello there!");
+    });
+
+    it("prefers 'aliases' over 'alias' if both present", async () => {
+      await writeFile(
+        join(globalSnippetDir, "greeting.md"),
+        `---
+alias: ignored
+aliases: used
+---
+Hello there!`,
+      );
+
+      const snippets = await loadSnippets(undefined, globalSnippetDir);
+
+      expect(snippets.size).toBe(2);
+      expect(snippets.get("greeting")?.content).toBe("Hello there!");
+      expect(snippets.get("used")?.content).toBe("Hello there!");
+      expect(snippets.has("ignored")).toBe(false);
+    });
+  });
 });

package/src/loader.ts

@@ -90,13 +90,15 @@ async function loadSnippetFile(
     const content = parsed.content.trim();
     const frontmatter = parsed.data as SnippetFrontmatter;
 
-    // Handle aliases as string or array
+    // Handle aliases: accept both 'aliases' (plural) and 'alias' (singular)
+    // Prefer 'aliases' if both are present
     let aliases: string[] = [];
-    if (frontmatter.aliases) {
-      if (Array.isArray(frontmatter.aliases)) {
-        aliases = frontmatter.aliases;
+    const aliasSource = frontmatter.aliases ?? frontmatter.alias;
+    if (aliasSource) {
+      if (Array.isArray(aliasSource)) {
+        aliases = aliasSource;
       } else {
-        aliases = [frontmatter.aliases];
+        aliases = [aliasSource];
       }
     }
 

package/src/notification.ts

@@ -1,4 +1,5 @@
 import { logger } from "./logger.js";
+import type { OpencodeClient } from "./types.js";
 
 /**
  * Sends a message that will be displayed but ignored by the AI
@@ -9,7 +10,7 @@ import { logger } from "./logger.js";
  * @param text - The text to display
  */
 export async function sendIgnoredMessage(
-  client: any,
+  client: OpencodeClient,
   sessionId: string,
   text: string,
 ): Promise<void> {

package/src/types.ts

@@ -1,3 +1,10 @@
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+
+/**
+ * OpenCode client type from the SDK
+ */
+export type OpencodeClient = ReturnType<typeof createOpencodeClient>;
+
 /**
  * A snippet with its content and metadata
  */
@@ -31,8 +38,10 @@ export type SnippetRegistry = Map<string, SnippetInfo>;
  * Frontmatter data from snippet files
  */
 export interface SnippetFrontmatter {
-  /** Alternative hashtags for this snippet */
-  aliases?: string[];
+  /** Alternative hashtags for this snippet (plural form, preferred) */
+  aliases?: string | string[];
+  /** Alternative hashtags for this snippet (singular form, also accepted) */
+  alias?: string | string[];
   /** Optional description of what this snippet does */
   description?: string;
 }