opencode-gitlab-plugin 2.8.1 → 3.0.0

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.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)
+
+
+### 🐛 Bug Fixes
+
+* **tools:** validate generated GitLab arguments ([69fcfd5](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/69fcfd56c8086f600277da8176a9e5c09b0e8ac5))
+
 ## [2.8.1](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v2.8.0...v2.8.1) (2026-09-06)
 
 

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",
@@ -389,15 +407,15 @@ The plugin provides **64 tools** organized into the following categories:
 
 ### Repository Tools (7 tools)
 
-| Tool                          | Description                                            |
-| ----------------------------- | ------------------------------------------------------ |
-| `gitlab_get_file`             | Get file contents from any branch, tag, or commit      |
-| `gitlab_get_commit`           | Get commit details with metadata, author, and stats    |
-| `gitlab_list_commits`         | List commits with filtering by branch, path, and dates |
-| `gitlab_get_commit_diff`      | Get diff for a specific commit                         |
-| `gitlab_list_repository_tree` | List files and directories at a given path             |
-| `gitlab_list_branches`        | List all branches in a repository                      |
-| `gitlab_get_commit_comments`  | Get all commit comments in flat structure              |
+| Tool                          | Description                                                   |
+| ----------------------------- | ------------------------------------------------------------- |
+| `gitlab_get_file`             | Get file contents from an explicit branch, tag, or commit ref |
+| `gitlab_get_commit`           | Get commit details with metadata, author, and stats           |
+| `gitlab_list_commits`         | List commits with filtering by branch, path, and dates        |
+| `gitlab_get_commit_diff`      | Get diff for a specific commit                                |
+| `gitlab_list_repository_tree` | List files and directories at a given path                    |
+| `gitlab_list_branches`        | List all branches in a repository                             |
+| `gitlab_get_commit_comments`  | Get all commit comments in flat structure                     |
 
 ### Search Tools (2 tools)
 
@@ -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

@@ -129,19 +129,45 @@ var GitLabApiClient = class {
   }
 };
 
-// src/client/notes-types.ts
-function buildPaginationVariables(options) {
+// src/client/connection-pagination.ts
+var DEFAULT_PAGE_SIZE = 20;
+var MAX_PAGE_SIZE = 100;
+function normalizePageSize(value) {
+  if (value === void 0 || value === 0) return void 0;
+  if (!Number.isFinite(value)) return DEFAULT_PAGE_SIZE;
+  return Math.min(Math.max(Math.floor(value), 1), MAX_PAGE_SIZE);
+}
+function buildConnectionVariables(options) {
   const variables = {};
-  if (options?.first !== void 0) {
-    variables.first = options.first;
-  } else if (options?.last == null) {
-    variables.first = 20;
+  const first = normalizePageSize(options?.first);
+  const last = normalizePageSize(options?.last);
+  if (first !== void 0 && last !== void 0) {
+    throw new Error("Pagination accepts either 'first' or 'last', not both");
+  }
+  if (options?.after && last !== void 0) {
+    throw new Error("Pagination cursor 'after' cannot be combined with 'last'");
+  }
+  if (options?.before && first !== void 0) {
+    throw new Error("Pagination cursor 'before' cannot be combined with 'first'");
+  }
+  if (first !== void 0) {
+    variables.first = first;
+  } else if (last !== void 0) {
+    variables.last = last;
+  } else if (options?.before) {
+    variables.last = DEFAULT_PAGE_SIZE;
+  } else {
+    variables.first = DEFAULT_PAGE_SIZE;
   }
   if (options?.after) variables.after = options.after;
-  if (options?.last !== void 0) variables.last = options.last;
   if (options?.before) variables.before = options.before;
   return variables;
 }
+
+// src/client/notes-types.ts
+function buildPaginationVariables(options) {
+  return buildConnectionVariables(options);
+}
 var NOTES_FRAGMENT = `
   fragment NoteFields on Note {
     id
@@ -180,16 +206,7 @@ var NOTES_CONNECTION_FRAGMENT = `
 
 // src/client/discussions-types.ts
 function buildDiscussionsPaginationVariables(options) {
-  const variables = {};
-  if (options?.first !== void 0) {
-    variables.first = options.first;
-  } else if (options?.last == null) {
-    variables.first = 20;
-  }
-  if (options?.after) variables.after = options.after;
-  if (options?.last !== void 0) variables.last = options.last;
-  if (options?.before) variables.before = options.before;
-  return variables;
+  return buildConnectionVariables(options);
 }
 var DISCUSSION_NOTE_FRAGMENT = `
   fragment DiscussionNoteFields on Note {
@@ -1449,10 +1466,7 @@ var RepositoryClient = class extends GitLabApiClient {
   async getFile(projectId, filePath, ref) {
     const encodedProject = this.encodeProjectId(projectId);
     const encodedPath = encodeURIComponent(filePath);
-    let url = `/projects/${encodedProject}/repository/files/${encodedPath}`;
-    if (ref) {
-      url += `?ref=${encodeURIComponent(ref)}`;
-    }
+    const url = `/projects/${encodedProject}/repository/files/${encodedPath}?ref=${encodeURIComponent(ref)}`;
     const file = await this.fetch("GET", url);
     if (file.encoding === "base64") {
       return Buffer.from(file.content, "base64").toString("utf-8");
@@ -3546,13 +3560,13 @@ var repositoryTools = {
   gitlab_get_file: tool5({
     description: `Get the contents of a file from a repository.
 Supports fetching files from any branch, tag, or commit SHA.
-If ref is not specified, uses the project's default branch.
+An explicit ref is required by the GitLab repository files API.
 Note: Invalid refs will result in a 404 error from the GitLab API.`,
     args: {
       project_id: z5.string().describe("The project ID or URL-encoded path"),
       file_path: z5.string().describe("Path to the file in the repository"),
-      ref: z5.string().optional().describe(
-        `Branch name, tag, or commit SHA to fetch the file from. Supports full or short commit SHAs. If omitted, uses the project's default branch (e.g., "main" or "master").`
+      ref: z5.string().trim().min(1).describe(
+        "Branch name, tag, or commit SHA to fetch the file from. Supports full or short commit SHAs."
       )
     },
     execute: async (args, _ctx) => {
@@ -3730,6 +3744,8 @@ Scopes and their requirements:
 - wiki_blobs: Search wiki content (supports ref filter)
 - group_projects: Search projects within a group (requires group_id)
 
+For scopes other than milestones, state="all" is treated as omitted because it does not filter results.
+
 Examples:
 - Issues: scope="issues", search="bug", project_id="my-group/my-project"
 - Code: scope="blobs", search="function calculateTotal"
@@ -3764,6 +3780,9 @@ Examples:
       state: z6.enum(["active", "closed", "all"]).optional().describe("Filter by state (for milestones scope)")
     },
     execute: async (args, _ctx) => {
+      if (args.scope !== "milestones" && args.state === "all") {
+        args.state = void 0;
+      }
       validateSearchParams(args.scope, {
         project_id: args.project_id,
         group_id: args.group_id,
@@ -4472,10 +4491,10 @@ Examples:
         "Filter by resolved status: true for resolved, false for unresolved. Only returns resolvable discussions (excludes system notes). Client-side filtering."
       ),
       // Pagination
-      first: z13.number().optional().describe("Number of items to return (default: 20)"),
+      first: z13.number().int().min(0).max(100).optional().describe("Number of items to return (default: 20, max: 100; 0 uses the default)"),
       after: z13.string().optional().describe("Cursor for pagination - use endCursor from previous response"),
       before: z13.string().optional().describe("Cursor for backward pagination"),
-      last: z13.number().optional().describe("Number of items from the end")
+      last: z13.number().int().min(0).max(100).optional().describe("Number of items from the end (max: 100; 0 is omitted)")
     },
     execute: async (args, _ctx) => {
       validateResourceParams(args.resource_type, args);
@@ -4788,9 +4807,11 @@ Examples:
         "Filter by resolved status: true for resolved, false for unresolved. Only returns resolvable notes (excludes system notes). Client-side filtering."
       ),
       // Pagination
-      first: z14.number().optional().describe("Number of items to return from the beginning (default: 20, max: 100)"),
+      first: z14.number().int().min(0).max(100).optional().describe(
+        "Number of items to return from the beginning (default: 20, max: 100; 0 uses the default)"
+      ),
       after: z14.string().optional().describe("Cursor for forward pagination - use endCursor from previous response"),
-      last: z14.number().optional().describe("Number of items to return from the end (for backward pagination)"),
+      last: z14.number().int().min(0).max(100).optional().describe("Number of items to return from the end (max: 100; 0 is omitted)"),
       before: z14.string().optional().describe("Cursor for backward pagination - use startCursor from previous response")
     },
     execute: async (args, _ctx) => {
@@ -5768,45 +5789,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