opencode-gitlab-plugin 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.0.1](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v3.0.0...v3.0.1) (2026-10-06)
+
+
+### 🐛 Bug Fixes
+
+* **orbit:** update tools to current Knowledge Graph query DSL ([a62c60b](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/a62c60bc195b63928868424cb5412bf579f23597))
+
 ## [3.0.0](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v2.8.2...v3.0.0) (2026-09-21)
 
 

package/dist/index.js

@@ -5450,6 +5450,50 @@ Examples:
 // src/tools/orbit.ts
 import { tool as tool18 } from "@opencode-ai/plugin";
 var z18 = tool18.schema;
+function orbitRelTypes(entityType) {
+  switch (entityType) {
+    case "MergeRequest":
+      return [
+        "AUTHORED",
+        "REVIEWER",
+        "ASSIGNED",
+        "CLOSES",
+        "MENTIONS",
+        "IN_PROJECT",
+        "HAS_HEAD_PIPELINE",
+        "TRIGGERED",
+        "IN_MILESTONE",
+        "HAS_LABEL"
+      ];
+    case "WorkItem":
+      return [
+        "AUTHORED",
+        "ASSIGNED",
+        "CLOSES",
+        "MENTIONS",
+        "RELATED_TO",
+        "CONTAINS",
+        "IN_PROJECT",
+        "IN_GROUP",
+        "IN_MILESTONE",
+        "HAS_LABEL"
+      ];
+    case "User":
+      return ["AUTHORED", "ASSIGNED", "REVIEWER", "MEMBER_OF", "OWNER", "CREATOR"];
+    case "Project":
+      return ["CONTAINS", "IN_PROJECT", "MEMBER_OF", "CREATOR"];
+    case "Pipeline":
+      return ["HAS_HEAD_PIPELINE", "TRIGGERED", "IN_PROJECT", "HAS_JOB", "HAS_STAGE"];
+    case "File":
+      return ["CONTAINS", "IMPORTS", "DEFINES", "CALLS", "ON_BRANCH"];
+    case "Group":
+      return ["CONTAINS", "MEMBER_OF", "OWNER", "IN_GROUP"];
+    case "Commit":
+      return ["MERGED_AT_COMMIT"];
+    default:
+      return ["AUTHORED", "ASSIGNED", "REVIEWER", "CLOSES", "MENTIONS", "RELATED_TO", "IN_PROJECT"];
+  }
+}
 var orbitTools = {
   gitlab_orbit_status: tool18({
     description: `Check GitLab Orbit Knowledge Graph API availability and health.
@@ -5583,47 +5627,64 @@ Note: Requires Orbit API to be available (Premium/Ultimate tier).`,
     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
+- traversal: Fetch matching nodes or follow relationships between nodes
+- neighbors: Return nodes connected to one bounded node
+- aggregation: Count/sum/avg/group graph results
+- path_finding: Find a bounded path between two nodes
+
+QUERY SHAPE (current DSL, format_version 5.x):
+Every query has a "query_type" and a "nodes" array of node selectors (max 5).
+A node selector names an entity and is made SELECTIVE via "node_ids" (exact
+internal ids) or "filters" (natural properties). Relationships between selectors
+go in a "relationships" array referencing selector "id" aliases.
 
-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
+IMPORTANT changes from older docs:
+- Use a top-level "nodes" ARRAY, not a single "node" object.
+- Pin ids with "node_ids": [123], NOT filters:{id:{op:"eq",value:123}}.
+- Filters use {op: value}, e.g. {"state": "merged"} or {"created_at": {"gte": "2026-01-01"}}.
+- A "neighbors" query uses a 1-element "nodes" array plus a top-level
+  "neighbors": {direction, rel_types:[...]} object. rel_types is REQUIRED to
+  bound the lookup and is capped at 10 entries.
 
-Example neighbors query to get a project's connections:
+Example neighbors query (an MR's graph neighbours):
 {
   "query_type": "neighbors",
-  "node": {
-    "entity": "Project",
-    "id": "p",
-    "filters": {"id": {"op": "eq", "value": 278964}}
+  "nodes": [{ "id": "mr", "entity": "MergeRequest", "node_ids": [507483917] }],
+  "neighbors": {
+    "direction": "both",
+    "rel_types": ["AUTHORED", "REVIEWER", "IN_PROJECT", "CLOSES", "HAS_HEAD_PIPELINE"]
   },
-  "neighbors": {"node": "p", "direction": "incoming"},
-  "aggregations": [],
-  "path": {"type": "shortest", "from": "p", "to": "p", "max_depth": 1}
+  "limit": 30
 }
 
-Example traversal query:
+Example traversal (merged MRs in a project):
 {
   "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}
+  "nodes": [
+    { "id": "project", "entity": "Project", "filters": {"full_path": "gitlab-org/gitlab"} },
+    { "id": "mr", "entity": "MergeRequest", "filters": {"state": "merged"},
+      "columns": ["iid", "title", "merged_at"] }
+  ],
+  "relationships": [{ "type": "IN_PROJECT", "from": "mr", "to": "project" }],
+  "limit": 25
 }
 
-Note: Use gitlab_get_merge_request to get the internal ID from an IID.
-Returns nodes array and edges array with relationship types.`,
+Notes:
+- node_ids are GitLab *internal* numeric ids (not IIDs). For an MR, get it via
+  gitlab_get_merge_request (the "id" field). For epics, use work_item_id.
+- Traversal/aggregation queries must include at least one selective node.
+- aggregation adds an "aggregations" array (e.g. [{"count":"mr"}]) with optional
+  "group_by"; path_finding adds a "path":{from,to,max_depth} object between two
+  node selectors. Both use the same envelope; see gitlab_orbit_schema and the
+  Orbit query-language docs for the full grammar.
+- Use gitlab_orbit_schema to discover entities and relationship types.
+Returns nodes and edges arrays.`,
     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."
+        'JSON string containing the full query object. Must include "query_type" and a top-level "nodes" array of selectors (each pinned by "node_ids" or "filters"); add "relationships"/"neighbors"/"aggregations"/"path" per the query_type. See the tool description for the current DSL and worked examples.'
       ),
       limit: z18.number().optional().describe("Maximum number of results (default: 30)")
     },
@@ -5642,12 +5703,23 @@ Returns nodes array and edges array with relationship types.`,
           2
         );
       }
+      if (typeof queryObj !== "object" || queryObj === null || Array.isArray(queryObj)) {
+        return JSON.stringify(
+          {
+            error: "Invalid query parameter",
+            suggestion: 'The query must be a JSON object with a "query_type" and a "nodes" array.'
+          },
+          null,
+          2
+        );
+      }
+      if (args.limit !== void 0) {
+        queryObj.limit = args.limit;
+      }
       const requestBody = {
-        query: queryObj
+        query: queryObj,
+        response_format: "raw"
       };
-      if (args.limit) {
-        requestBody.limit = args.limit;
-      }
       try {
         const result = await client.fetch("POST", "/orbit/query", requestBody);
         if (result.code) {
@@ -5656,7 +5728,7 @@ Returns nodes array and edges array with relationship types.`,
               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.'
+              suggestion: 'Check query structure against the current DSL: top-level "nodes" array, pin ids with "node_ids", filters use {op: value}, and a "neighbors" query needs neighbors:{direction, rel_types} (max 10 rel_types).'
             },
             null,
             2
@@ -5704,7 +5776,7 @@ Common use cases:
 
 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).`,
+then use that ID (e.g., 377844873). For epics, use the work_item_id.`,
     args: {
       entity_type: z18.string().describe(
         "Type of the entity (e.g., Project, MergeRequest, User, Pipeline, Commit, WorkItem, Group)"
@@ -5713,33 +5785,38 @@ then use that ID (e.g., 377844873).`,
         "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)"),
+      rel_types: z18.array(z18.string()).optional().describe(
+        'Relationship types to follow. Required by the API to bound the lookup; if omitted, a sensible default set for the entity type is used. The API caps this at 10 per selector, so more than 10 entries are truncated to the first 10 and the response includes a "warnings" field. See gitlab_orbit_schema for valid edge types.'
+      ),
       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 requestedRelTypes = args.rel_types?.length ? args.rel_types : orbitRelTypes(args.entity_type);
+      const relTypes = requestedRelTypes.slice(0, 10);
+      const warnings = requestedRelTypes.length > relTypes.length ? [`rel_types truncated to 10 (got ${requestedRelTypes.length})`] : [];
       const queryObj = {
         query_type: "neighbors",
-        node: {
-          entity: args.entity_type,
-          id: "n",
-          filters: {
-            id: { op: "eq", value: args.entity_id }
+        nodes: [
+          {
+            id: "n",
+            entity: args.entity_type,
+            node_ids: [args.entity_id]
           }
-        },
+        ],
         neighbors: {
-          node: "n",
-          direction
-        },
-        aggregations: [],
-        path: { type: "shortest", from: "n", to: "n", max_depth: 1 }
+          direction,
+          rel_types: relTypes
+        }
       };
+      if (args.limit !== void 0) {
+        queryObj.limit = args.limit;
+      }
       const requestBody = {
-        query: queryObj
+        query: queryObj,
+        response_format: "raw"
       };
-      if (args.limit) {
-        requestBody.limit = args.limit;
-      }
       try {
         const result = await client.fetch("POST", "/orbit/query", requestBody);
         if (result.code) {
@@ -5749,13 +5826,14 @@ then use that ID (e.g., 377844873).`,
               code: result.code,
               message: result.message,
               entity_type: args.entity_type,
-              entity_id: args.entity_id
+              entity_id: args.entity_id,
+              ...warnings.length > 0 && { warnings }
             },
             null,
             2
           );
         }
-        return JSON.stringify(result, null, 2);
+        return JSON.stringify(warnings.length > 0 ? { ...result, warnings } : result, null, 2);
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         if (errorMessage.includes("404") || errorMessage.includes("not found")) {