@gaodes/pi-gitlab 0.3.0 → 0.4.2

package/.primecodex.json

@@ -1,6 +1,6 @@
 {
 	"version": 1,
-	"updatedAt": "2026-06-01T08:10:00+0300",
+	"updatedAt": "2026-06-01T08:15:00+0300",
 	"kind": "package",
 	"name": "pi-gitlab",
 	"source": "ssh://git@gitlab-ssh.elches.dev:2222/agents/primecodex/packages/pi-gitlab.git",
@@ -13,7 +13,7 @@
 	"npm": {
 		"name": "@gaodes/pi-gitlab",
 		"scope": "@gaodes",
-		"published": false,
-		"publishedUnderGaodes": false
+		"published": true,
+		"publishedUnderGaodes": true
 	}
 }

package/CHANGELOG.md

@@ -7,8 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-06-01
+
+### Fixed
+- Auto-derive apiBase from hostname in loadConfig and writeConfig when apiBase is not explicitly set
+
+## [0.4.1] - 2026-06-01
+
 ### Changed
-- Default token environment variable renamed from `GITLAB_TOKEN` to `PI_GITLAB_TOKEN` to avoid collisions with other tools. The `tokenEnv` setting still allows overriding to any custom env var.
+- Removed hardcoded personal GitLab instance hostname from `DEFAULT_CONFIG` — defaults are now empty strings, forcing users through setup wizard on first use
+- Replaced personal instance references in skills and README with generic placeholder text
+- Fixed lint warnings across codebase (unused imports, formatting)
+
+## [0.4.0] - 2026-06-01
+
+### Added (Phase 4 — 15 new skills + 3 new tools)
+
+**New skills:**
+- `gitlab-badge` — project badge management (list, create, update, delete, preview)
+- `gitlab-ci` — CI/CD pipeline and job operations (status, run, retry, trace, lint, artifacts)
+- `gitlab-container` — container registry management (repositories, tags, cleanup)
+- `gitlab-discussion` — threaded discussion management on MRs and issues
+- `gitlab-file` — repository file operations via API (read, blame, create, update, delete)
+- `gitlab-group` — group management (list, create, members, subgroups, projects)
+- `gitlab-label` — label management via CLI and API
+- `gitlab-milestone` — milestone and sprint management via CLI and API
+- `gitlab-protected-branch` — branch protection rule management
+- `gitlab-repo` — repository/project operations (clone, fork, view, create, archive)
+- `gitlab-search` — search across GitLab (projects, issues, MRs, code, commits, users, wiki)
+- `gitlab-variable` — CI/CD variable management via CLI and API
+- `gitlab-vulnerability` — security vulnerability management (list, confirm, dismiss, resolve)
+- `gitlab-webhook` — webhook management (list, create, update, delete, test)
+- `gitlab-wiki` — wiki page management (list, read, create, update, delete, attachments)
+
+**New tools:**
+- `gitlab_search_query` — structured search across GitLab globally, within a group, or project
+- `gitlab_ci_lint` — validate `.gitlab-ci.yml` configuration via CI lint API
+- `gitlab_repo_view` — view detailed project/repository info with stats
+
+### Changed
+- Updated `index.ts` header docstring to include Phase 4 tools and skills
 
 ## [0.3.0] - 2026-06-01
 
@@ -21,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - All Phase 3 tools are confirm-gated following the same `requireConfirm` pattern as Phase 2
+- Default token environment variable renamed from `GITLAB_TOKEN` to `PI_GITLAB_TOKEN` to avoid collisions with other tools. The `tokenEnv` setting still allows overriding to any custom env var.
 
 ## [0.2.0] - 2026-06-01
 

package/README.md

@@ -1,6 +1,6 @@
 # @gaodes/pi-gitlab
 
-Pi extension package for GitLab workflows on `gitlab.elches.dev` using `glab` + in-package skills.
+Pi extension package for GitLab workflows using `glab` + in-package skills.
 
 ## Install
 
@@ -95,9 +95,9 @@ Key: `pi-gitlab` in `~/.pi/agent/prime-settings.json`
 ```json
 {
   "pi-gitlab": {
-    "hostname": "gitlab.elches.dev",
-    "sshHostname": "gitlab-ssh.elches.dev",
-    "sshPort": 2222,
+    "hostname": "gitlab.example.com",
+    "sshHostname": "gitlab-ssh.example.com",
+    "sshPort": 22,
     "tokenEnv": "PI_GITLAB_TOKEN",
     "defaultProjectPath": null,
     "render": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gaodes/pi-gitlab",
-	"version": "0.3.0",
+	"version": "0.4.2",
 	"description": "Pi extension package for GitLab workflows via glab CLI with in-package skills.",
 	"keywords": [
 		"pi-package",

package/skills/gitlab-assistant/SKILL.md

@@ -8,7 +8,7 @@ description: >
 
 # GitLab Assistant
 
-You are the entry point for GitLab workflows on `gitlab.elches.dev`.
+You are the entry point for GitLab workflows on `the configured GitLab instance`.
 
 ## Routing
 

package/skills/gitlab-badge/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: gitlab-badge
+description: >
+  GitLab project badge management. Use for listing, creating, updating,
+  and deleting project badges, previewing badge rendering, and managing
+  group-level badges.
+---
+
+# GitLab Badge Skill
+
+## Patterns
+
+### List project badges
+```
+gitlab_api({ endpoint: "projects/:project/badges", project: "namespace/project" })
+```
+
+### Get a specific badge
+```
+gitlab_api({ endpoint: "projects/:project/badges/:badge_id", project: "namespace/project" })
+```
+
+### Create a badge
+```
+gitlab_api({
+  endpoint: "projects/:project/badges",
+  project: "namespace/project",
+  method: "POST",
+  body: {
+    link_url: "https://example.com",
+    image_url: "https://img.shields.io/badge/build-passing-brightgreen"
+  },
+  confirm: true
+})
+```
+
+### Update a badge
+```
+gitlab_api({
+  endpoint: "projects/:project/badges/:badge_id",
+  project: "namespace/project",
+  method: "PUT",
+  body: { image_url: "https://new-badge-url" },
+  confirm: true
+})
+```
+
+### Delete a badge
+```
+gitlab_api({
+  endpoint: "projects/:project/badges/:badge_id",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+### Preview badge rendering
+```
+gitlab_api({
+  endpoint: "projects/:project/badges/render",
+  project: "namespace/project",
+  query: { link_url: "https://example.com", image_url: "https://img.shields.io/..." }
+})
+```
+
+### List group badges
+```
+gitlab_api({ endpoint: "groups/:group_id/badges" })
+```
+
+## Rules
+
+- All mutating operations (create, update, delete) require `confirm: true`.
+- Badge IDs are numeric; use list first to find the ID.
+- `link_url` and `image_url` are required when creating badges.
+- For group badges, use the group numeric ID (not path).

package/skills/gitlab-ci/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gitlab-ci
+description: >
+  GitLab CI/CD pipeline and job operations. Use for viewing pipeline
+  status, running pipelines, retrying jobs, tracing logs, downloading
+  artifacts, and linting CI configuration.
+---
+
+# GitLab CI/CD Skill
+
+## Patterns
+
+### Check pipeline status
+```
+gitlab_pipeline_status({ project: "namespace/project", ref: "main" })
+```
+
+### View CI status (current branch)
+```bash
+glab ci status
+```
+
+### View pipeline details
+```bash
+glab ci view
+```
+
+### List pipelines
+```bash
+glab ci list
+```
+
+### Run a pipeline
+```
+gitlab_pipeline_run({ project: "namespace/project", ref: "main", confirm: true })
+```
+
+### Retry a failed job
+```bash
+glab ci retry <job-id>
+```
+
+### Trace job logs
+```
+gitlab_job_logs({ project: "namespace/project", jobId: 123, tail: 100 })
+```
+
+### Download artifacts
+```bash
+glab ci artifact -b <branch> -j <job-name>
+```
+
+### Lint CI configuration
+```
+gitlab_ci_lint({ project: "namespace/project" })
+```
+
+### Delete a pipeline
+```bash
+glab ci delete <pipeline-id>
+```
+
+## Rules
+
+- All mutating operations require `confirm: true`.
+- Use `gitlab_pipeline_status` for structured pipeline info; use `glab ci status` for quick terminal view.
+- Use `gitlab_job_logs` for structured log fetching with redaction.
+- CI lint validates `.gitlab-ci.yml` without running a pipeline.
+- For CI/CD variables, use the `gitlab-variable` skill instead.

package/skills/gitlab-container/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: gitlab-container
+description: >
+  GitLab container registry management. Use for listing repositories,
+  viewing and deleting image tags, and cleaning up old container images.
+---
+
+# GitLab Container Registry Skill
+
+## Patterns
+
+### List container repositories
+```
+gitlab_api({ endpoint: "projects/:project/registry/repositories", project: "namespace/project" })
+```
+
+### Get a specific repository
+```
+gitlab_api({ endpoint: "projects/:project/registry/repositories/:repo_id", project: "namespace/project" })
+```
+
+### List tags in a repository
+```
+gitlab_api({ endpoint: "projects/:project/registry/repositories/:repo_id/tags", project: "namespace/project" })
+```
+
+### Get tag details
+```
+gitlab_api({ endpoint: "projects/:project/registry/repositories/:repo_id/tags/:tag", project: "namespace/project" })
+```
+
+### Delete a tag
+```
+gitlab_api({
+  endpoint: "projects/:project/registry/repositories/:repo_id/tags/:tag",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+### Bulk delete tags by regex
+```
+gitlab_api({
+  endpoint: "projects/:project/registry/repositories/:repo_id/tags",
+  project: "namespace/project",
+  method: "DELETE",
+  body: { name_regex: ".*", keep_n: 5 },
+  confirm: true
+})
+```
+
+### Delete entire repository
+```
+gitlab_api({
+  endpoint: "projects/:project/registry/repositories/:repo_id",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+## Rules
+
+- Container deletion operations are **destructive and irreversible** — always confirm with the user before proceeding.
+- Use `keep_n` when bulk-deleting to preserve recent tags.
+- Repository and tag IDs are numeric; list first to find IDs.

package/skills/gitlab-discussion/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gitlab-discussion
+description: >
+  GitLab threaded discussion management on merge requests and issues.
+  Use for listing, creating, and replying to discussion threads, and
+  resolving or unresolving discussions.
+---
+
+# GitLab Discussion Skill
+
+## Patterns
+
+### List MR discussions
+```
+gitlab_api({ endpoint: "projects/:project/merge_requests/:iid/discussions", project: "namespace/project" })
+```
+
+### List issue discussions
+```
+gitlab_api({ endpoint: "projects/:project/issues/:iid/discussions", project: "namespace/project" })
+```
+
+### Get a specific discussion
+```
+gitlab_api({ endpoint: "projects/:project/merge_requests/:iid/discussions/:discussion_id", project: "namespace/project" })
+```
+
+### Create a new discussion thread on an MR
+```
+gitlab_api({
+  endpoint: "projects/:project/merge_requests/:iid/discussions",
+  project: "namespace/project",
+  method: "POST",
+  body: { body: "Review comment on this MR" },
+  confirm: true
+})
+```
+
+### Create a position-based (line-specific) discussion
+```
+gitlab_api({
+  endpoint: "projects/:project/merge_requests/:iid/discussions",
+  project: "namespace/project",
+  method: "POST",
+  body: {
+    body: "Nit: consider using const here",
+    position: {
+      base_sha: "abc123",
+      head_sha: "def456",
+      start_sha: "abc123",
+      position_type: "text",
+      new_path: "src/index.ts",
+      new_line: 42
+    }
+  },
+  confirm: true
+})
+```
+
+### Reply to a discussion
+```
+gitlab_api({
+  endpoint: "projects/:project/merge_requests/:iid/discussions/:discussion_id/notes",
+  project: "namespace/project",
+  method: "POST",
+  body: { body: "Agreed, will fix" },
+  confirm: true
+})
+```
+
+### Resolve a discussion
+```
+gitlab_api({
+  endpoint: "projects/:project/merge_requests/:iid/discussions/:discussion_id",
+  project: "namespace/project",
+  method: "PUT",
+  body: { resolved: true },
+  confirm: true
+})
+```
+
+### Delete a note
+```
+gitlab_api({
+  endpoint: "projects/:project/merge_requests/:iid/discussions/:discussion_id/notes/:note_id",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+## Rules
+
+- All mutating operations require `confirm: true`.
+- For line-specific code review comments, include the `position` object with SHA references.
+- Discussion IDs and note IDs are numeric; list discussions first.
+- Use `resolved: false` to unresolve a previously resolved discussion.

package/skills/gitlab-file/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: gitlab-file
+description: >
+  GitLab repository file operations via API. Use for reading file content,
+  blame info, and creating, updating, or deleting files through the
+  GitLab API (not local files).
+---
+
+# GitLab File Skill
+
+## Patterns
+
+### Get file metadata and content (base64)
+```
+gitlab_api({
+  endpoint: "projects/:project/repository/files/:encoded_path",
+  project: "namespace/project",
+  query: { ref: "main" }
+})
+```
+
+### Get raw file content
+```
+gitlab_api({
+  endpoint: "projects/:project/repository/files/:encoded_path/raw",
+  project: "namespace/project",
+  query: { ref: "main" }
+})
+```
+
+### Get file blame info
+```
+gitlab_api({
+  endpoint: "projects/:project/repository/files/:encoded_path/blame",
+  project: "namespace/project",
+  query: { ref: "main" }
+})
+```
+
+### Create a file
+```
+gitlab_api({
+  endpoint: "projects/:project/repository/files/:encoded_path",
+  project: "namespace/project",
+  method: "POST",
+  body: {
+    branch: "main",
+    content: "file content here",
+    commit_message: "Add new file"
+  },
+  confirm: true
+})
+```
+
+### Update a file
+```
+gitlab_api({
+  endpoint: "projects/:project/repository/files/:encoded_path",
+  project: "namespace/project",
+  method: "PUT",
+  body: {
+    branch: "main",
+    content: "updated content",
+    commit_message: "Update file"
+  },
+  confirm: true
+})
+```
+
+### Delete a file
+```
+gitlab_api({
+  endpoint: "projects/:project/repository/files/:encoded_path",
+  project: "namespace/project",
+  method: "DELETE",
+  body: { branch: "main", commit_message: "Remove file" },
+  confirm: true
+})
+```
+
+## Rules
+
+- File paths in endpoints must be URL-encoded (e.g. `src%2Findex.ts`).
+- All mutating operations require `confirm: true`.
+- `branch` and `commit_message` are required for create, update, and delete.
+- For editing local files, use file editing tools — this skill is for API-side file operations only.

package/skills/gitlab-group/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: gitlab-group
+description: >
+  GitLab group management. Use for listing and managing groups,
+  subgroups, group membership, and group-level projects.
+---
+
+# GitLab Group Skill
+
+## Patterns
+
+### List groups
+```
+gitlab_api({ endpoint: "groups" })
+```
+
+### Get group details
+```
+gitlab_api({ endpoint: "groups/:group_id" })
+```
+
+### List subgroups
+```
+gitlab_api({ endpoint: "groups/:group_id/subgroups" })
+```
+
+### List projects in a group
+```
+gitlab_api({ endpoint: "groups/:group_id/projects" })
+```
+
+### List group members
+```
+gitlab_api({ endpoint: "groups/:group_id/members" })
+```
+
+### Add a member to a group
+```
+gitlab_api({
+  endpoint: "groups/:group_id/members",
+  method: "POST",
+  body: { user_id: 42, access_level: 30 },
+  confirm: true
+})
+```
+
+### Update member access level
+```
+gitlab_api({
+  endpoint: "groups/:group_id/members/:user_id",
+  method: "PUT",
+  body: { access_level: 40 },
+  confirm: true
+})
+```
+
+### Remove a member
+```
+gitlab_api({
+  endpoint: "groups/:group_id/members/:user_id",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+### Create a group
+```
+gitlab_api({
+  endpoint: "groups",
+  method: "POST",
+  body: { name: "new-group", path: "new-group" },
+  confirm: true
+})
+```
+
+### Share a project with a group
+```
+gitlab_api({
+  endpoint: "projects/:project/share",
+  project: "namespace/project",
+  method: "POST",
+  body: { group_id: 42, group_access: 30 },
+  confirm: true
+})
+```
+
+## Rules
+
+- All mutating operations require `confirm: true`.
+- Use numeric group IDs (not paths) in API endpoints.
+- Access levels: 10 = Guest, 20 = Reporter, 30 = Developer, 40 = Maintainer, 50 = Owner.
+- For project-level members, use the repo settings API instead.

package/skills/gitlab-label/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gitlab-label
+description: >
+  GitLab label management using the glab CLI. Use for listing and
+  creating project labels to organize issues and merge requests.
+---
+
+# GitLab Label Skill
+
+## Patterns
+
+### List project labels
+```bash
+glab label list
+```
+
+### Create a label
+```bash
+glab label create "bug" -c "#FF0000" -d "Bug report"
+```
+
+### List labels via API (structured)
+```
+gitlab_api({ endpoint: "projects/:project/labels", project: "namespace/project" })
+```
+
+### Create label via API
+```
+gitlab_api({
+  endpoint: "projects/:project/labels",
+  project: "namespace/project",
+  method: "POST",
+  body: { name: "bug", color: "#FF0000", description: "Bug report" },
+  confirm: true
+})
+```
+
+### Update a label
+```
+gitlab_api({
+  endpoint: "projects/:project/labels/:label_name",
+  project: "namespace/project",
+  method: "PUT",
+  body: { color: "#00FF00", description: "Updated description" },
+  confirm: true
+})
+```
+
+### Delete a label
+```
+gitlab_api({
+  endpoint: "projects/:project/labels/:label_name",
+  project: "namespace/project",
+  method: "DELETE",
+  confirm: true
+})
+```
+
+## Rules
+
+- Color values must be in hex format (e.g. `#FF0000`).
+- All mutating operations require `confirm: true`.
+- For applying labels to issues or MRs, use `gitlab-issue` or `gitlab-mr` skills.
+- Labels are project-scoped; group labels use the group API endpoint.