opencode-gitlab-plugin 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.5.0](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v2.4.0...v2.5.0) (2026-05-20)
+
+
+### ✨ Features
+
+* **notes:** add gitlab_update_note tool for editing comments ([54a87e7](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/54a87e70d4d276c077ab25619e1d910d6d709575))
+
+
+### 🐛 Bug Fixes
+
+* handle ToolResult union type in mcp-adapter and tests ([a91d5dd](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/a91d5ddc5574d1cf9b7dab2d9624cdddeefd158f))
+* **tests:** update orbit.test.ts for ToolResult type ([29fecec](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/29fecec6a8ba436b3d95b720cf67f162c8c62104))
+
+
+### ♻️ Code Refactoring
+
+* **notes:** address review feedback on !28 ([11e13ba](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/11e13ba5a6dafeb77dfb256bde3e9b7b1f5ddd32))
+
+## [2.4.0](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v2.3.0...v2.4.0) (2026-05-19)
+
+
+### ✨ Features
+
+* **orbit:** add GitLab Orbit Knowledge Graph API tools ([17fd452](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/17fd4521ec32f760b26a6596c5d023d7b55eed47))
+
 ## [2.3.0](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v2.2.0...v2.3.0) (2026-05-18)
 
 

package/dist/index.d.ts

@@ -20,6 +20,7 @@ import { Plugin } from '@opencode-ai/plugin';
  * - Discussions: unified tools for all resource types (list, get, create/reply, resolve)
  * - Notes: list/get notes (flat view) for MR, issue, epic, snippet
  * - Git: execute safe, read-only git commands in repository
+ * - Orbit: Knowledge Graph API (status, schema, query, neighbors)
  */
 declare const gitlabPlugin: Plugin;
 

package/dist/index.js

@@ -438,6 +438,14 @@ var MergeRequestsClient = class extends GitLabApiClient {
       { body }
     );
   }
+  async updateMrNote(projectId, mrIid, noteId, body) {
+    const encodedProject = this.encodeProjectId(projectId);
+    return this.fetch(
+      "PUT",
+      `/projects/${encodedProject}/merge_requests/${mrIid}/notes/${noteId}`,
+      { body }
+    );
+  }
   async createMergeRequest(projectId, options) {
     const encodedProject = this.encodeProjectId(projectId);
     return this.fetch(
@@ -816,6 +824,14 @@ var IssuesClient = class extends GitLabApiClient {
       `/projects/${encodedProject}/issues/${issueIid}/notes/${noteId}`
     );
   }
+  async updateIssueNote(projectId, issueIid, noteId, body) {
+    const encodedProject = this.encodeProjectId(projectId);
+    return this.fetch(
+      "PUT",
+      `/projects/${encodedProject}/issues/${issueIid}/notes/${noteId}`,
+      { body }
+    );
+  }
 };
 
 // src/client/work-items.ts
@@ -2150,6 +2166,14 @@ var EpicsClient = class extends GitLabApiClient {
       `/groups/${encodedGroup}/epics/${epicIid}/notes/${noteId}`
     );
   }
+  async updateEpicNote(groupId, epicIid, noteId, body) {
+    const encodedGroup = encodeURIComponent(groupId);
+    return this.fetch(
+      "PUT",
+      `/groups/${encodedGroup}/epics/${epicIid}/notes/${noteId}`,
+      { body }
+    );
+  }
 };
 
 // src/client/snippets.ts
@@ -2278,6 +2302,14 @@ var SnippetsClient = class extends GitLabApiClient {
       { body }
     );
   }
+  async updateSnippetNote(projectId, snippetId, noteId, body) {
+    const encodedProject = this.encodeProjectId(projectId);
+    return this.fetch(
+      "PUT",
+      `/projects/${encodedProject}/snippets/${snippetId}/notes/${noteId}`,
+      { body }
+    );
+  }
 };
 
 // src/client/discussions.ts
@@ -4489,19 +4521,22 @@ function filterNotesByResolved(result, resolved) {
     }
   };
 }
-var VALID_LIST_CREATE_TYPES = ["merge_request", "issue", "epic", "snippet"];
-var VALID_GET_NOTE_TYPES = ["issue", "epic"];
+var NOTE_RESOURCE_TYPES = ["merge_request", "issue", "epic", "snippet"];
+var GET_NOTE_RESOURCE_TYPES = ["issue", "epic"];
 function validationError3(param, resourceType) {
   return new Error(
     `Missing required parameter: '${param}' is required for resource_type '${resourceType}'`
   );
 }
-function validateListCreateParams(resourceType, args) {
-  if (!VALID_LIST_CREATE_TYPES.includes(resourceType)) {
+function validateNoteParams(resourceType, args, opts) {
+  if (!opts.allowedTypes.includes(resourceType)) {
     throw new Error(
-      `Invalid resource_type '${resourceType}'. Must be one of: ${VALID_LIST_CREATE_TYPES.join(", ")}`
+      `Invalid resource_type '${resourceType}'. Must be one of: ${opts.allowedTypes.join(", ")}`
     );
   }
+  if (opts.requireNoteId && args.note_id == null) {
+    throw validationError3("note_id", resourceType);
+  }
   switch (resourceType) {
     case "merge_request":
     case "issue":
@@ -4518,24 +4553,6 @@ function validateListCreateParams(resourceType, args) {
       break;
   }
 }
-function validateGetNoteParams(resourceType, args) {
-  if (!VALID_GET_NOTE_TYPES.includes(resourceType)) {
-    throw new Error(
-      `Invalid resource_type '${resourceType}'. Must be one of: ${VALID_GET_NOTE_TYPES.join(", ")}`
-    );
-  }
-  if (args.note_id == null) throw validationError3("note_id", resourceType);
-  switch (resourceType) {
-    case "issue":
-      if (!args.project_id) throw validationError3("project_id", resourceType);
-      if (args.iid == null) throw validationError3("iid", resourceType);
-      break;
-    case "epic":
-      if (!args.group_id) throw validationError3("group_id", resourceType);
-      if (args.iid == null) throw validationError3("iid", resourceType);
-      break;
-  }
-}
 var notesUnifiedTools = {
   /**
    * List notes/comments for any GitLab resource type
@@ -4571,7 +4588,7 @@ Examples:
       before: z14.string().optional().describe("Cursor for backward pagination - use startCursor from previous response")
     },
     execute: async (args, _ctx) => {
-      validateListCreateParams(args.resource_type, args);
+      validateNoteParams(args.resource_type, args, { allowedTypes: NOTE_RESOURCE_TYPES });
       const client = getGitLabClient();
       const paginationOptions = {
         first: args.first,
@@ -4625,7 +4642,10 @@ Examples:
       iid: z14.number().describe("Internal ID of the issue or epic")
     },
     execute: async (args, _ctx) => {
-      validateGetNoteParams(args.resource_type, args);
+      validateNoteParams(args.resource_type, args, {
+        allowedTypes: GET_NOTE_RESOURCE_TYPES,
+        requireNoteId: true
+      });
       const client = getGitLabClient();
       switch (args.resource_type) {
         case "issue":
@@ -4669,7 +4689,7 @@ Examples:
       snippet_id: z14.number().optional().describe("Snippet ID (required for snippet)")
     },
     execute: async (args, _ctx) => {
-      validateListCreateParams(args.resource_type, args);
+      validateNoteParams(args.resource_type, args, { allowedTypes: NOTE_RESOURCE_TYPES });
       const client = getGitLabClient();
       switch (args.resource_type) {
         case "merge_request":
@@ -4700,6 +4720,68 @@ Examples:
           throw new Error(`Unsupported resource type: ${args.resource_type}`);
       }
     }
+  }),
+  /**
+   * Update an existing note/comment on any GitLab resource
+   */
+  gitlab_update_note: tool14({
+    description: `Update an existing note/comment on any GitLab resource.
+Modifies the body content of an existing note. You can only update notes you authored.
+
+Examples:
+- MR note: resource_type="merge_request", project_id="group/project", iid=123, note_id=456, body="Updated comment"
+- Issue note: resource_type="issue", project_id="group/project", iid=456, note_id=789, body="Updated comment"
+- Epic note: resource_type="epic", group_id="my-group", iid=1, note_id=456, body="Updated comment"
+- Snippet note: resource_type="snippet", project_id="group/project", snippet_id=789, note_id=123, body="Updated comment"`,
+    args: {
+      resource_type: z14.enum(["merge_request", "issue", "epic", "snippet"]).describe("Type of GitLab resource"),
+      note_id: z14.number().describe("The ID of the note to update"),
+      body: z14.string().describe("The new content for the note (supports Markdown)"),
+      project_id: z14.string().optional().describe("Project ID or path. Required for merge_request, issue, snippet"),
+      group_id: z14.string().optional().describe("Group ID or path. Required for epic"),
+      iid: z14.number().optional().describe("Internal ID of the resource (for merge_request, issue, epic)"),
+      snippet_id: z14.number().optional().describe("Snippet ID (required for snippet)")
+    },
+    execute: async (args, _ctx) => {
+      validateNoteParams(args.resource_type, args, {
+        allowedTypes: NOTE_RESOURCE_TYPES,
+        requireNoteId: true
+      });
+      const client = getGitLabClient();
+      switch (args.resource_type) {
+        case "merge_request":
+          return JSON.stringify(
+            await client.updateMrNote(args.project_id, args.iid, args.note_id, args.body),
+            null,
+            2
+          );
+        case "issue":
+          return JSON.stringify(
+            await client.updateIssueNote(args.project_id, args.iid, args.note_id, args.body),
+            null,
+            2
+          );
+        case "epic":
+          return JSON.stringify(
+            await client.updateEpicNote(args.group_id, args.iid, args.note_id, args.body),
+            null,
+            2
+          );
+        case "snippet":
+          return JSON.stringify(
+            await client.updateSnippetNote(
+              args.project_id,
+              args.snippet_id,
+              args.note_id,
+              args.body
+            ),
+            null,
+            2
+          );
+        default:
+          throw new Error(`Unsupported resource type: ${args.resource_type}`);
+      }
+    }
   })
 };
 
@@ -5138,6 +5220,348 @@ Examples:
   })
 };
 
+// src/tools/orbit.ts
+import { tool as tool18 } from "@opencode-ai/plugin";
+var z18 = tool18.schema;
+var orbitTools = {
+  gitlab_orbit_status: tool18({
+    description: `Check GitLab Orbit Knowledge Graph API availability and health.
+
+Returns the status of the Orbit API for the connected GitLab instance.
+Orbit is GitLab's Knowledge Graph API that provides rich SDLC graph data.
+
+Note: Orbit is only available on Premium/Ultimate tiers and requires the feature flag to be enabled.
+If unavailable, returns an error with suggestions for REST API alternatives.`,
+    args: {},
+    execute: async (_args, _ctx) => {
+      const client = getGitLabClient();
+      try {
+        const status = await client.fetch("GET", "/orbit/status");
+        return JSON.stringify(
+          {
+            ...status,
+            available: true,
+            message: "Orbit Knowledge Graph API is available"
+          },
+          null,
+          2
+        );
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes("404") || errorMessage.includes("not found")) {
+          return JSON.stringify(
+            {
+              available: false,
+              error: "Orbit API not available",
+              reason: "The Orbit Knowledge Graph API is not enabled on this GitLab instance. Orbit requires GitLab Premium/Ultimate tier and the feature flag to be enabled.",
+              alternatives: [
+                "Use REST API endpoints for MRs, issues, pipelines",
+                "Use GraphQL API for complex queries",
+                "Use gitlab_search for finding related entities"
+              ]
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("403") || errorMessage.includes("forbidden")) {
+          return JSON.stringify(
+            {
+              available: false,
+              error: "Orbit API access forbidden",
+              reason: "Your access token does not have permission to use the Orbit API. This may require specific scopes or Premium/Ultimate tier.",
+              alternatives: [
+                "Check token scopes include api or read_api",
+                "Verify your GitLab tier supports Orbit",
+                "Use REST/GraphQL APIs as fallback"
+              ]
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("502")) {
+          return JSON.stringify(
+            {
+              available: false,
+              error: "Orbit API temporarily unavailable",
+              reason: "The Orbit API returned a 502 error. This may be temporary.",
+              suggestion: "Try again later or use REST/GraphQL APIs as fallback."
+            },
+            null,
+            2
+          );
+        }
+        return JSON.stringify(
+          {
+            available: false,
+            error: "Orbit API error",
+            message: errorMessage,
+            alternatives: ["Use REST/GraphQL APIs as fallback"]
+          },
+          null,
+          2
+        );
+      }
+    }
+  }),
+  gitlab_orbit_schema: tool18({
+    description: `Get the Orbit Knowledge Graph schema.
+
+Returns the available node types, relationship types, and their properties.
+Use this to understand what entities and relationships can be queried.
+
+Node type domains include:
+- Core: Project, Group, User
+- Source Code: File, Definition, Commit
+- Code Review: MergeRequest, Diff, Review
+- CI/CD: Pipeline, Job, Deployment
+- Planning: WorkItem (issues, epics, tasks)
+- Security: Vulnerability
+
+Note: Requires Orbit API to be available (Premium/Ultimate tier).`,
+    args: {},
+    execute: async (_args, _ctx) => {
+      const client = getGitLabClient();
+      try {
+        const schema = await client.fetch("GET", "/orbit/schema");
+        return JSON.stringify(schema, null, 2);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes("404") || errorMessage.includes("not found")) {
+          return JSON.stringify(
+            {
+              error: "Orbit API not available",
+              suggestion: "Use gitlab_orbit_status to check API availability"
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("502")) {
+          return JSON.stringify(
+            {
+              error: "Orbit API temporarily unavailable",
+              suggestion: "The Orbit API returned a 502 error. This may be temporary - try again later."
+            },
+            null,
+            2
+          );
+        }
+        throw error;
+      }
+    }
+  }),
+  gitlab_orbit_query: tool18({
+    description: `Execute a query against the Orbit Knowledge Graph.
+
+Query types:
+- traversal: Walk the graph from a starting node
+- neighbors: Get immediate neighbors of a node
+
+IMPORTANT: The query format uses variable names for node references.
+- "id" in node definition is a VARIABLE NAME (alias), not the actual entity ID
+- Actual IDs go in "filters" with {"field": {"op": "eq", "value": X}} format
+
+Example neighbors query to get a project's connections:
+{
+  "query_type": "neighbors",
+  "node": {
+    "entity": "Project",
+    "id": "p",
+    "filters": {"id": {"op": "eq", "value": 278964}}
+  },
+  "neighbors": {"node": "p", "direction": "incoming"},
+  "aggregations": [],
+  "path": {"type": "shortest", "from": "p", "to": "p", "max_depth": 1}
+}
+
+Example traversal query:
+{
+  "query_type": "traversal",
+  "node": {
+    "entity": "MergeRequest",
+    "id": "mr",
+    "filters": {"id": {"op": "eq", "value": 377844873}}
+  },
+  "neighbors": {"node": "mr", "direction": "both"},
+  "aggregations": [],
+  "path": {"type": "shortest", "from": "mr", "to": "mr", "max_depth": 1}
+}
+
+Note: Use gitlab_get_merge_request to get the internal ID from an IID.
+Returns nodes array and edges array with relationship types.`,
+    args: {
+      // Using a JSON string rather than a structured zod schema because the Orbit query
+      // format is still evolving. This allows flexibility as the API changes without
+      // requiring schema updates for each iteration.
+      query: z18.string().describe(
+        "JSON string containing the full query object. Must include query_type, node, neighbors, aggregations, and path fields. See description for format details."
+      ),
+      limit: z18.number().optional().describe("Maximum number of results (default: 30)")
+    },
+    execute: async (args, _ctx) => {
+      const client = getGitLabClient();
+      let queryObj;
+      try {
+        queryObj = JSON.parse(args.query);
+      } catch {
+        return JSON.stringify(
+          {
+            error: "Invalid JSON in query parameter",
+            suggestion: "Ensure the query parameter is valid JSON"
+          },
+          null,
+          2
+        );
+      }
+      const requestBody = {
+        query: queryObj
+      };
+      if (args.limit) {
+        requestBody.limit = args.limit;
+      }
+      try {
+        const result = await client.fetch("POST", "/orbit/query", requestBody);
+        if (result.code) {
+          return JSON.stringify(
+            {
+              error: "Query compilation error",
+              code: result.code,
+              message: result.message,
+              suggestion: 'Check query structure. Node "id" is a variable name, actual IDs go in filters.'
+            },
+            null,
+            2
+          );
+        }
+        return JSON.stringify(result, null, 2);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes("404") || errorMessage.includes("not found")) {
+          return JSON.stringify(
+            {
+              error: "Orbit API not available",
+              suggestion: "Use gitlab_orbit_status to check API availability"
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("502")) {
+          return JSON.stringify(
+            {
+              error: "Orbit query failed",
+              message: "The Orbit API returned a 502 error. This is a known issue with some entity types (e.g., source_code domain).",
+              suggestion: "Try a different entity type or use REST/GraphQL APIs as fallback."
+            },
+            null,
+            2
+          );
+        }
+        throw error;
+      }
+    }
+  }),
+  gitlab_orbit_neighbors: tool18({
+    description: `Get immediate neighbors of a node in the Orbit Knowledge Graph.
+
+This is a simplified wrapper that builds the query for you.
+Returns nodes directly connected to the specified node.
+
+Common use cases:
+- Get all connections to a project (users, groups, pipelines, MRs)
+- Get pipelines for an MR
+- Get files changed in a commit
+- Get deployments from a pipeline
+
+Note: Use GitLab internal numeric IDs (not IIDs).
+Example: For MR !123 in gitlab-org/gitlab, first get the internal ID via gitlab_get_merge_request,
+then use that ID (e.g., 377844873).`,
+    args: {
+      entity_type: z18.string().describe(
+        "Type of the entity (e.g., Project, MergeRequest, User, Pipeline, Commit, WorkItem, Group)"
+      ),
+      entity_id: z18.number().describe(
+        "GitLab internal numeric ID (not IID). Get this from REST/GraphQL API responses."
+      ),
+      direction: z18.enum(["incoming", "outgoing", "both"]).optional().describe("Direction of relationships to traverse (default: both)"),
+      limit: z18.number().optional().describe("Maximum number of neighbors to return (default: 30)")
+    },
+    execute: async (args, _ctx) => {
+      const client = getGitLabClient();
+      const direction = args.direction || "both";
+      const queryObj = {
+        query_type: "neighbors",
+        node: {
+          entity: args.entity_type,
+          id: "n",
+          filters: {
+            id: { op: "eq", value: args.entity_id }
+          }
+        },
+        neighbors: {
+          node: "n",
+          direction
+        },
+        aggregations: [],
+        path: { type: "shortest", from: "n", to: "n", max_depth: 1 }
+      };
+      const requestBody = {
+        query: queryObj
+      };
+      if (args.limit) {
+        requestBody.limit = args.limit;
+      }
+      try {
+        const result = await client.fetch("POST", "/orbit/query", requestBody);
+        if (result.code) {
+          return JSON.stringify(
+            {
+              error: "Query error",
+              code: result.code,
+              message: result.message,
+              entity_type: args.entity_type,
+              entity_id: args.entity_id
+            },
+            null,
+            2
+          );
+        }
+        return JSON.stringify(result, null, 2);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes("404") || errorMessage.includes("not found")) {
+          return JSON.stringify(
+            {
+              error: "Orbit API not available",
+              entity_type: args.entity_type,
+              entity_id: args.entity_id,
+              suggestion: "Use gitlab_orbit_status to check API availability"
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("502")) {
+          return JSON.stringify(
+            {
+              error: "Orbit query failed",
+              entity_type: args.entity_type,
+              entity_id: args.entity_id,
+              message: "The Orbit API returned a 502 error. This is a known issue with some entity types.",
+              suggestion: "Try a different entity type or use REST/GraphQL APIs as fallback."
+            },
+            null,
+            2
+          );
+        }
+        throw error;
+      }
+    }
+  })
+};
+
 // src/index.ts
 var gitlabPlugin = async (_input, options) => {
   if (options?.tools === false) {
@@ -5169,7 +5593,8 @@ DAP tools (agents, flows, memory, skills) are on the "gitlab-dap" server instead
       ...notesUnifiedTools,
       ...gitTools,
       ...auditTools,
-      ...awardEmojiTools
+      ...awardEmojiTools,
+      ...orbitTools
     }
   };
 };