opencode-gitlab-plugin 2.8.2 → 3.0.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 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)
+
+
+### ⚠ BREAKING CHANGES
+
+* the default export is a plugin definition object rather than a
+plugin function. Anything importing the default export and calling it must use
+the named `gitlabPlugin` export instead. OpenCode v1 hosts older than 1.18.29
+do not understand object entrypoints and must stay on 2.x. On OpenCode v2 the
+configuration key is `plugins`, and options move from a tuple to
+`{ "package": "...", "options": { ... } }`; v1's `plugin` key is normalised
+automatically.
+
+### ✨ Features
+
+* support the v2 plugin SDK ([0b0fe45](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/0b0fe4521210820fe4a424499fecaee4d9f55ae6))
+
+
+### 🐛 Bug Fixes
+
+* **ci:** sync lockfile with npm 11.6.2 ([ceb68d7](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/ceb68d7229d847070233566661472e43f4cdcc3a))
+
 ## [2.8.2](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v2.8.1...v2.8.2) (2026-09-18)
 
 

package/README.md

@@ -266,6 +266,14 @@ Full example with lazy-mcp configured in opencode (`~/.config/opencode/opencode.
       "command": ["npx", "-y", "lazy-mcp@latest", "--config", "~/.config/lazy-mcp/servers.json"]
     }
   },
+  "plugins": [{ "package": "opencode-gitlab-plugin", "options": { "tools": false } }]
+}
+```
+
+On OpenCode v1, use the legacy tuple form instead:
+
+```json
+{
   "plugin": [["opencode-gitlab-plugin", { "tools": false }]]
 }
 ```
@@ -298,6 +306,16 @@ export GITLAB_INSTANCE_URL=https://gitlab.example.com
 
 Add the following plugin to your opencode configuration `~/.config/opencode/opencode.json`:
 
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-gitlab-plugin"]
+}
+```
+
+The package ships both plugin SDK entrypoints, so it also works on OpenCode v1 with the
+legacy `plugin` key:
+
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
@@ -490,9 +508,9 @@ The plugin provides **64 tools** organized into the following categories:
 ### Example 1: Create and Manage Issues
 
 ```javascript
-import gitlabPlugin from 'opencode-gitlab-plugin';
+import { allTools } from 'opencode-gitlab-plugin';
 
-const plugin = await gitlabPlugin({});
+const plugin = { tool: allTools };
 
 // Create a new issue
 const issue = await plugin.tool.gitlab_create_issue.execute({
@@ -782,6 +800,7 @@ await plugin.tool.gitlab_link_vulnerability_to_issue.execute({
 
 ```
 opencode-gitlab-plugin/
+├── index.ts                # Package-root entrypoint for local v2 plugin loading
 ├── src/
 │   ├── client/              # API client modules
 │   │   ├── base.ts         # Base client with HTTP & GraphQL methods
@@ -806,8 +825,12 @@ opencode-gitlab-plugin/
 │   │   ├── repository.ts   # Repository tool definitions
 │   │   ├── discussions-unified.ts # Unified discussion tools (4 tools)
 │   │   ├── notes-unified.ts # Unified notes tools (3 tools)
+│   │   ├── index.ts        # Aggregated tool registries
 │   │   └── ...             # Other tool definitions
-│   ├── index.ts            # Main plugin entry point
+│   ├── v2/                 # Plugin SDK v2 entry point
+│   │   ├── plugin.ts       # Plugin.define({ id, setup })
+│   │   └── tool-adapter.ts # v1 tool definitions -> v2 tool registrations
+│   ├── index.ts            # Main plugin entry point (v2 setup + v1 server)
 │   ├── utils.ts            # Utility functions
 │   └── validation.ts       # GID validation utilities
 ├── tests/                  # Test suite (225 tests)
@@ -863,6 +886,25 @@ npm run format
 npm run format:check
 ```
 
+### Loading a Local Checkout
+
+OpenCode v2 resolves a plugin configured by absolute path by probing
+`<directory>/server` and `<directory>/index` — it does **not** read the package's
+`main`/`exports`. The repository root ships an `index.ts` for exactly this, so point
+the config at the checkout root:
+
+```json
+{
+  "plugins": [{ "package": "/abs/path/to/opencode-gitlab-plugin" }]
+}
+```
+
+This loads `src/` directly, so OpenCode's watcher picks up edits without a rebuild.
+Confirm it loaded with `opencode plugin list` — the `gitlab` plugin should be listed.
+
+A path to a _file_ (for example `.../dist/index.js`) is rejected with
+`configured plugin path must be a directory`.
+
 ### Git Hooks
 
 The project uses Husky for Git hooks:

package/dist/index.d.ts

@@ -1,7 +1,19 @@
-import { Plugin } from '@opencode-ai/plugin';
+import * as _opencode_plugin_promise_plugin from '@opencode/plugin/promise/plugin';
+import { ToolDefinition, Plugin as Plugin$1 } from '@opencode-ai/plugin';
+import { Plugin } from '@opencode/plugin';
 
 /**
- * GitLab Tools Plugin for OpenCode
+ * Tools exposed over the standalone MCP server (`opencode-gitlab-plugin` binary).
+ */
+declare const mcpTools: Record<string, ToolDefinition>;
+/**
+ * Every tool registered by the OpenCode plugin.
+ */
+declare const allTools: Record<string, ToolDefinition>;
+
+declare const PLUGIN_ID = "gitlab";
+/**
+ * GitLab Tools Plugin for OpenCode (plugin SDK v2)
  *
  * Provides tools for interacting with GitLab:
  * - Merge requests: get, list, changes, create, update, commits, pipelines, diffs (paginated), auto-merge
@@ -22,6 +34,26 @@ import { Plugin } from '@opencode-ai/plugin';
  * - Git: execute safe, read-only git commands in repository
  * - Orbit: Knowledge Graph API (status, schema, query, neighbors)
  */
-declare const gitlabPlugin: Plugin;
+declare const gitlabPluginV2: Plugin.Plugin;
+
+/**
+ * GitLab Tools Plugin for OpenCode — legacy (v1) plugin SDK entrypoint.
+ *
+ * Kept so the package keeps working on OpenCode v1. New installs use the v2
+ * `setup()` implementation in `./v2/plugin.ts`.
+ *
+ * @deprecated Use the default export with the v2 plugin SDK.
+ */
+declare const gitlabPlugin: Plugin$1;
+/**
+ * Dual entrypoint: OpenCode v2 calls `setup()`, OpenCode v1 calls `server()`.
+ *
+ * See https://opencode.ai/v2/docs/build/plugins/migrate-v1
+ */
+declare const _default: {
+    server: Plugin$1;
+    id: string;
+    setup: (context: _opencode_plugin_promise_plugin.Context) => Promise<_opencode_plugin_promise_plugin.Cleanup | void> | _opencode_plugin_promise_plugin.Cleanup | void;
+};
 
-export { gitlabPlugin as default, gitlabPlugin };
+export { PLUGIN_ID, allTools, _default as default, gitlabPlugin, gitlabPluginV2, mcpTools };

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
 
-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
+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.
 
-Example neighbors query to get a project's connections:
+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 (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")) {
@@ -5789,45 +5867,139 @@ then use that ID (e.g., 377844873).`,
   })
 };
 
+// src/tools/index.ts
+var mcpTools = {
+  ...mergeRequestTools,
+  ...issueTools,
+  ...epicTools,
+  ...pipelineTools,
+  ...repositoryTools,
+  ...searchTools,
+  ...projectTools,
+  ...userTools,
+  ...securityTools,
+  ...todoTools,
+  ...wikiTools,
+  ...workItemTools,
+  ...discussionsUnifiedTools,
+  ...notesUnifiedTools,
+  ...gitTools,
+  ...auditTools,
+  ...awardEmojiTools
+};
+var allTools = {
+  ...mcpTools,
+  ...orbitTools
+};
+
+// src/v2/plugin.ts
+import { Plugin } from "@opencode/plugin";
+
+// src/v2/tool-adapter.ts
+import { tool as tool19 } from "@opencode-ai/plugin";
+var z19 = tool19.schema;
+function toInputSchema(args) {
+  const schema = z19.toJSONSchema(z19.object(args ?? {}), { io: "input" });
+  delete schema["$schema"];
+  return {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+    ...schema
+  };
+}
+function toToolResult(result) {
+  if (typeof result === "string") {
+    return { content: result };
+  }
+  const metadata = { ...result.metadata ?? {} };
+  if (result.title !== void 0) metadata["title"] = result.title;
+  if (result.attachments !== void 0) metadata["attachments"] = result.attachments;
+  return {
+    content: result.output,
+    ...Object.keys(metadata).length > 0 ? { metadata } : {}
+  };
+}
+function toLegacyContext(context, directory, worktree) {
+  return {
+    sessionID: context.sessionID,
+    messageID: context.messageID,
+    agent: context.agent,
+    directory,
+    worktree,
+    abort: context.signal,
+    metadata: (update) => void context.progress(update),
+    ask: async () => {
+    }
+  };
+}
+function adaptTool(name, definition, options) {
+  const validator = z19.object(definition.args ?? {});
+  return {
+    name,
+    description: definition.description,
+    input: toInputSchema(definition.args),
+    async execute(input, context) {
+      const parsed = validator.parse(input ?? {});
+      const legacyContext = toLegacyContext(context, options.directory, options.worktree);
+      const result = await definition.execute(
+        parsed,
+        legacyContext
+      );
+      return toToolResult(result);
+    }
+  };
+}
+function adaptTools(tools, options) {
+  return Object.entries(tools).map(([name, definition]) => adaptTool(name, definition, options));
+}
+
+// src/v2/plugin.ts
+var PLUGIN_ID = "gitlab";
+var LAZY_MCP_HINT = `## GitLab Tools via lazy-mcp
+GitLab API tools (MRs, issues, pipelines, security, search, repos, users, todos, work items, discussions, notes, audit, git, award emoji) are served via the "gitlab" MCP server through lazy-mcp. Use lazy-mcp_list_commands with server "gitlab" to discover and call them.
+DAP tools (agents, flows, memory, skills) are on the "gitlab-dap" server instead.`;
+var gitlabPluginV2 = Plugin.define({
+  id: PLUGIN_ID,
+  async setup(ctx) {
+    if (ctx.options["tools"] === false) {
+      await ctx.session.hook("context", (event) => {
+        event.system.push({ type: "text", text: LAZY_MCP_HINT });
+      });
+      return;
+    }
+    const directory = ctx.location.directory;
+    const worktree = ctx.location.project.directory ?? directory;
+    const tools = adaptTools(allTools, { directory, worktree });
+    await ctx.tool.transform((editor) => {
+      for (const definition of tools) {
+        editor.add(definition);
+      }
+    });
+  }
+});
+
 // src/index.ts
 var gitlabPlugin = async (_input, options) => {
-  if (options?.tools === false) {
+  if (options?.["tools"] === false) {
     return {
-      "experimental.chat.system.transform": async (_input2, output) => {
-        output.system.push(
-          `## GitLab Tools via lazy-mcp
-GitLab API tools (MRs, issues, pipelines, security, search, repos, users, todos, work items, discussions, notes, audit, git, award emoji) are served via the "gitlab" MCP server through lazy-mcp. Use lazy-mcp_list_commands with server "gitlab" to discover and call them.
-DAP tools (agents, flows, memory, skills) are on the "gitlab-dap" server instead.`
-        );
+      "experimental.chat.system.transform": async (_hookInput, output) => {
+        output.system.push(LAZY_MCP_HINT);
       }
     };
   }
-  return {
-    tool: {
-      ...mergeRequestTools,
-      ...issueTools,
-      ...epicTools,
-      ...pipelineTools,
-      ...repositoryTools,
-      ...searchTools,
-      ...projectTools,
-      ...userTools,
-      ...securityTools,
-      ...todoTools,
-      ...wikiTools,
-      ...workItemTools,
-      ...discussionsUnifiedTools,
-      ...notesUnifiedTools,
-      ...gitTools,
-      ...auditTools,
-      ...awardEmojiTools,
-      ...orbitTools
-    }
-  };
+  return { tool: allTools };
+};
+var index_default = {
+  ...gitlabPluginV2,
+  server: gitlabPlugin
 };
-var index_default = gitlabPlugin;
 export {
+  PLUGIN_ID,
+  allTools,
   index_default as default,
-  gitlabPlugin
+  gitlabPlugin,
+  gitlabPluginV2,
+  mcpTools
 };
 //# sourceMappingURL=index.js.map