refactor: align snippet file ref handling with repository/files pattern

getSnippetFileRawContent now takes an explicit ref string instead of a
raw_url to parse. The ref-extraction logic is factored into a standalone
extractSnippetRef helper, resolved once at the call site rather than
once per file inside the fetch function.

get_snippet also gains an optional ref parameter (matching get_file_contents)
so callers can override the ref directly without relying on raw_url parsing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: renanliberato

index.ts

@@ -8380,18 +8380,11 @@ async function getSnippetRawContent(
 }
 
 /**
- * Get the raw content of a specific file inside a multi-file snippet.
- * Extracts the ref from the file's raw_url (e.g. .../raw/main/file.md) so we
- * never have to guess it, then hits the proper REST API endpoint.
+ * Extract the ref (branch/tag/commit) from a snippet file's raw_url.
+ * Anchors on /snippets/{id}/raw/ so branch names or file paths containing
+ * the word "raw" don't produce a false match.
  */
-async function getSnippetFileRawContent(
-  projectId: string | undefined,
-  snippetId: number,
-  rawUrl: string,
-  filePath: string
-): Promise<string> {
-  // Anchor on the unambiguous /snippets/{id}/raw/ segment so branch names and
-  // file paths containing the word "raw" don't confuse the extraction.
+function extractSnippetRef(rawUrl: string, snippetId: number, filePath: string): string {
   const rawMarker = `/snippets/${snippetId}/raw/`;
   const decoded = decodeURIComponent(new URL(rawUrl).pathname);
   const markerIdx = decoded.indexOf(rawMarker);
@@ -8403,7 +8396,20 @@ async function getSnippetFileRawContent(
   if (fileStart === -1) {
     throw new Error(`Cannot locate file path "${filePath}" in snippet file raw_url: ${rawUrl}`);
   }
-  const ref = afterRaw.slice(0, fileStart);
+  return afterRaw.slice(0, fileStart);
+}
+
+/**
+ * Fetch the raw content of one file inside a multi-file snippet.
+ * Accepts an explicit ref (branch/tag/commit) — callers resolve it via
+ * extractSnippetRef or a user-supplied parameter before calling this.
+ */
+async function getSnippetFileRawContent(
+  projectId: string | undefined,
+  snippetId: number,
+  ref: string,
+  filePath: string
+): Promise<string> {
   const encodedRef = encodeURIComponent(ref);
   const encodedPath = filePath.split("/").map(encodeURIComponent).join("/");
   const url = `${getSnippetsEndpoint(projectId)}/${snippetId}/files/${encodedRef}/${encodedPath}/raw`;
@@ -10570,11 +10576,14 @@ async function handleToolCall(params: any) {
         if (args.include_content) {
           const files = snippet.files ?? [];
           if (files.length > 1) {
+            const firstFile = files[0];
+            if (!firstFile.raw_url) throw new Error(`Snippet file "${firstFile.path}" has no raw_url`);
+            const ref = args.ref ?? extractSnippetRef(firstFile.raw_url, args.snippet_id, firstFile.path);
             result.files = await Promise.all(
-              files.map(async f => {
-                if (!f.raw_url) throw new Error(`Snippet file "${f.path}" has no raw_url`);
-                return { ...f, content: await getSnippetFileRawContent(args.project_id, args.snippet_id, f.raw_url, f.path) };
-              })
+              files.map(async f => ({
+                ...f,
+                content: await getSnippetFileRawContent(args.project_id, args.snippet_id, ref, f.path),
+              }))
             );
           } else {
             result.content = await getSnippetRawContent(

schemas.ts

@@ -3353,6 +3353,10 @@ export const GetSnippetSchema = z.object({
     .optional()
     .default(false)
     .describe("Whether to fetch the raw file content (default: false)"),
+  ref: z
+    .string()
+    .optional()
+    .describe("Branch, tag, or commit to fetch content from. Inferred from the snippet's raw_url when omitted."),
 });
 
 export const SnippetFileSchema = z.object({

test/test-snippets.ts

@@ -10,6 +10,7 @@ const TEST_PERSONAL_SNIPPET_ID = 99;
 const TEST_MULTIFILE_SNIPPET_ID = 77;
 const TEST_MASTER_SNIPPET_ID = 88;
 const TEST_SLASH_REF_SNIPPET_ID = 101;
+const TEST_EXPLICIT_REF_SNIPPET_ID = 102;
 const RAW_CONTENT = "console.log('hello world');\n";
 const MULTIFILE_A_CONTENT = "# policy\nbody A\n";
 const MULTIFILE_B_CONTENT = "# instructions\nbody B\n";
@@ -296,6 +297,43 @@ describe("snippet tools", () => {
       (_req, res) => { res.type("text/plain").send(MULTIFILE_B_CONTENT); }
     );
 
+    // --- Explicit ref snippet: raw_url carries ref "wrong" but caller overrides with "v2" ---
+    mockGitLab.addMockHandler(
+      "get",
+      `/projects/${TEST_PROJECT_ID}/snippets/${TEST_EXPLICIT_REF_SNIPPET_ID}`,
+      (_req, res) => {
+        res.json(
+          buildSnippet({
+            id: TEST_EXPLICIT_REF_SNIPPET_ID,
+            title: "Explicit ref snippet",
+            file_name: null,
+            files: [
+              {
+                path: "a.md",
+                raw_url: `${mockGitLabUrl}/-/snippets/${TEST_EXPLICIT_REF_SNIPPET_ID}/raw/wrong/a.md`,
+              },
+              {
+                path: "b.md",
+                raw_url: `${mockGitLabUrl}/-/snippets/${TEST_EXPLICIT_REF_SNIPPET_ID}/raw/wrong/b.md`,
+              },
+            ],
+          })
+        );
+      }
+    );
+
+    mockGitLab.addMockHandler(
+      "get",
+      `/projects/${TEST_PROJECT_ID}/snippets/${TEST_EXPLICIT_REF_SNIPPET_ID}/files/v2/a.md/raw`,
+      (_req, res) => { res.type("text/plain").send(MULTIFILE_A_CONTENT); }
+    );
+
+    mockGitLab.addMockHandler(
+      "get",
+      `/projects/${TEST_PROJECT_ID}/snippets/${TEST_EXPLICIT_REF_SNIPPET_ID}/files/v2/b.md/raw`,
+      (_req, res) => { res.type("text/plain").send(MULTIFILE_B_CONTENT); }
+    );
+
     // --- Personal snippet handlers ---
     mockGitLab.addMockHandler("get", "/snippets", (_req, res) => {
       res.json([
@@ -550,6 +588,25 @@ describe("snippet tools", () => {
     assert.strictEqual(result.files[1].content, MULTIFILE_B_CONTENT);
   });
 
+  test("get_snippet with include_content uses explicit ref when provided, ignoring raw_url ref", async () => {
+    const result = await callTool(
+      "get_snippet",
+      {
+        project_id: TEST_PROJECT_ID,
+        snippet_id: TEST_EXPLICIT_REF_SNIPPET_ID,
+        include_content: true,
+        ref: "v2",
+      },
+      env()
+    );
+
+    assert.strictEqual(result.id, TEST_EXPLICIT_REF_SNIPPET_ID);
+    assert.ok(Array.isArray(result.files));
+    assert.strictEqual(result.files.length, 2);
+    assert.strictEqual(result.files[0].content, MULTIFILE_A_CONTENT);
+    assert.strictEqual(result.files[1].content, MULTIFILE_B_CONTENT);
+  });
+
   test("create_snippet supports multi-file snippets via files[]", async () => {
     const result = await callTool(
       "create_snippet",