opencode-gitlab-dap 1.12.1 → 1.13.0

package/README.md

@@ -110,7 +110,7 @@ The plugin provides a multi-round design workflow:
 
 The vendored `flow_v2.json` schema from GitLab Rails powers client-side validation using `ajv`, catching errors before hitting the API.
 
-### 31 Tools
+### 34 Tools
 
 #### DAP Tools (20)
 
@@ -157,13 +157,18 @@ Say **"bootstrap project memory"** to automatically inspect a project and build
 
 ##### Skill Tools
 
-| Tool                   | Description                                    |
-| ---------------------- | ---------------------------------------------- |
-| `gitlab_skill_list`    | List available skills (and optionally drafts)  |
-| `gitlab_skill_load`    | Load a skill (published first, then drafts)    |
-| `gitlab_skill_save`    | Create or update a skill (supports draft flag) |
-| `gitlab_skill_promote` | Promote a draft skill to published             |
-
+| Tool                    | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| `gitlab_skill_list`     | List skills with auto-rebuilding index                    |
+| `gitlab_skill_load`     | Load a skill (SKILL page + available references)          |
+| `gitlab_skill_save`     | Create/update a skill with required description for index |
+| `gitlab_skill_promote`  | Promote a draft skill to published (moves all pages)      |
+| `gitlab_skill_discover` | Search group wiki for team-shared skills                  |
+| `gitlab_skill_install`  | Copy a skill from group wiki to project wiki              |
+| `gitlab_skill_delete`   | Delete a skill and remove from index                      |
+
+Each skill is a directory: `agents/skills/<name>/SKILL` with optional `references/` subpages.
+Skills are indexed in `agents/skills/index` for fast discovery.
 All tools support project scope (default) and group scope (`scope="groups"`).
 
 ### Dynamic Refresh

package/dist/index.cjs

@@ -3951,6 +3951,9 @@ var z6 = import_plugin6.tool.schema;
 var PREFIX2 = "agents";
 var SKILLS_PREFIX = `${PREFIX2}/skills`;
 var DRAFTS_PREFIX = `${PREFIX2}/skills-drafts`;
+var SKILLS_INDEX = `${SKILLS_PREFIX}/index`;
+var DRAFTS_INDEX = `${DRAFTS_PREFIX}/index`;
+var PROJECT_ID_DESC2 = 'FULL project path with namespace (e.g., "gitlab-org/gitlab"). Must contain a slash. Never use just the project name.';
 function resolveScope2(args) {
   if (args.scope === "groups" && args.group_id) {
     return { scope: "groups", id: args.group_id };
@@ -3963,6 +3966,117 @@ function validateProjectId2(projectId) {
   }
   return null;
 }
+function parseIndex(content) {
+  const entries = [];
+  const blocks = content.split(/^## /m).filter(Boolean);
+  for (const block of blocks) {
+    const lines = block.trim().split("\n");
+    const name = lines[0].trim();
+    if (!name) continue;
+    const rest = lines.slice(1).join("\n").trim();
+    const descLines = [];
+    let source;
+    for (const line of rest.split("\n")) {
+      if (line.startsWith("Source:")) {
+        source = line.slice(7).trim();
+      } else if (line.trim()) {
+        descLines.push(line);
+      }
+    }
+    entries.push({ name, description: descLines.join("\n"), source, draft: false });
+  }
+  return entries;
+}
+function formatIndex(entries) {
+  return entries.map((e) => {
+    let block = `## ${e.name}
+${e.description}`;
+    if (e.source) block += `
+Source: ${e.source}`;
+    return block;
+  }).join("\n\n");
+}
+async function readIndex(instanceUrl, token, scope, id, indexSlug) {
+  try {
+    const page = await getWikiPage(instanceUrl, token, scope, id, indexSlug);
+    return parseIndex(page.content);
+  } catch {
+    return [];
+  }
+}
+async function writeIndex(instanceUrl, token, scope, id, indexSlug, entries) {
+  const content = formatIndex(entries);
+  try {
+    await updateWikiPage(instanceUrl, token, scope, id, indexSlug, content);
+  } catch {
+    await createWikiPage(instanceUrl, token, scope, id, indexSlug, content || "# Skills Index");
+  }
+}
+async function upsertIndexEntry(instanceUrl, token, scope, id, indexSlug, entry) {
+  const entries = await readIndex(instanceUrl, token, scope, id, indexSlug);
+  const idx = entries.findIndex((e) => e.name === entry.name);
+  if (idx >= 0) {
+    entries[idx] = entry;
+  } else {
+    entries.push(entry);
+  }
+  await writeIndex(instanceUrl, token, scope, id, indexSlug, entries);
+}
+async function removeIndexEntry(instanceUrl, token, scope, id, indexSlug, name) {
+  const entries = await readIndex(instanceUrl, token, scope, id, indexSlug);
+  const filtered = entries.filter((e) => e.name !== name);
+  if (filtered.length !== entries.length) {
+    await writeIndex(instanceUrl, token, scope, id, indexSlug, filtered);
+  }
+}
+function extractSkillNames(pages, prefix) {
+  const skillSuffix = "/SKILL";
+  const names = /* @__PURE__ */ new Set();
+  for (const p of pages) {
+    if (p.slug.startsWith(prefix + "/") && p.slug.endsWith(skillSuffix)) {
+      const middle = p.slug.slice(prefix.length + 1, -skillSuffix.length);
+      if (middle && !middle.includes("/")) {
+        names.add(middle);
+      }
+    }
+  }
+  return [...names];
+}
+async function rebuildIndex(instanceUrl, token, scope, id, prefix, indexSlug) {
+  const pages = await listWikiPages(instanceUrl, token, scope, id);
+  const actualNames = extractSkillNames(pages, prefix);
+  const currentEntries = await readIndex(instanceUrl, token, scope, id, indexSlug);
+  const indexed = new Set(currentEntries.map((e) => e.name));
+  const actual = new Set(actualNames);
+  let dirty = false;
+  const removed = currentEntries.filter((e) => !actual.has(e.name));
+  if (removed.length > 0) dirty = true;
+  const added = [];
+  for (const name of actualNames) {
+    if (!indexed.has(name)) {
+      added.push(name);
+      dirty = true;
+    }
+  }
+  if (!dirty && added.length === 0) return currentEntries;
+  const kept = currentEntries.filter((e) => actual.has(e.name));
+  for (const name of added) {
+    kept.push({
+      name,
+      description: "(auto-indexed \u2014 update description with gitlab_skill_save)",
+      draft: prefix === DRAFTS_PREFIX
+    });
+  }
+  await writeIndex(instanceUrl, token, scope, id, indexSlug, kept);
+  return kept;
+}
+async function upsertPage(instanceUrl, token, scope, id, slug, content) {
+  try {
+    await updateWikiPage(instanceUrl, token, scope, id, slug, content);
+  } catch {
+    await createWikiPage(instanceUrl, token, scope, id, slug, content);
+  }
+}
 function makeSkillTools(ctx) {
   function authAndValidate(projectId) {
     const auth = ctx.ensureAuth();
@@ -3973,11 +4087,9 @@ function makeSkillTools(ctx) {
   }
   return {
     gitlab_skill_list: (0, import_plugin6.tool)({
-      description: "List available project skills and optionally draft skills.\nSkills define step-by-step procedures for common tasks (e.g., incident retros, debugging, deployments).",
+      description: "List available project skills and optionally draft skills.\nSkills define step-by-step procedures for common tasks (e.g., incident retros, debugging, deployments).\nAuto-rebuilds the skill index if it is out of sync with actual skill pages.",
       args: {
-        project_id: z6.string().describe(
-          'FULL project path with namespace (e.g., "gitlab-org/gitlab"). Must contain a slash. Never use just the project name.'
-        ),
+        project_id: z6.string().describe(PROJECT_ID_DESC2),
         include_drafts: z6.boolean().optional().describe("Also list draft skills (default: false)"),
         scope: z6.enum(["projects", "groups"]).optional().describe("Scope (default: projects)"),
         group_id: z6.string().optional().describe("Group path (required when scope is groups)")
@@ -3986,23 +4098,27 @@ function makeSkillTools(ctx) {
         const auth = authAndValidate(args.project_id);
         const { scope, id } = resolveScope2(args);
         try {
-          const pages = await listWikiPages(auth.instanceUrl, auth.token, scope, id);
-          const indexSlug = `${SKILLS_PREFIX}/index`;
-          const skills = pages.filter((p) => p.slug.startsWith(`${SKILLS_PREFIX}/`) && p.slug !== indexSlug).map((p) => ({
-            name: p.slug.slice(SKILLS_PREFIX.length + 1),
-            title: p.title,
-            draft: false
-          }));
+          const published = await rebuildIndex(
+            auth.instanceUrl,
+            auth.token,
+            scope,
+            id,
+            SKILLS_PREFIX,
+            SKILLS_INDEX
+          );
           let drafts = [];
           if (args.include_drafts) {
-            const draftsIndexSlug = `${DRAFTS_PREFIX}/index`;
-            drafts = pages.filter((p) => p.slug.startsWith(`${DRAFTS_PREFIX}/`) && p.slug !== draftsIndexSlug).map((p) => ({
-              name: p.slug.slice(DRAFTS_PREFIX.length + 1),
-              title: p.title,
-              draft: true
-            }));
+            drafts = await rebuildIndex(
+              auth.instanceUrl,
+              auth.token,
+              scope,
+              id,
+              DRAFTS_PREFIX,
+              DRAFTS_INDEX
+            );
+            drafts = drafts.map((e) => ({ ...e, draft: true }));
           }
-          const all = [...skills, ...drafts];
+          const all = [...published, ...drafts];
           if (all.length === 0) return "No skills found. Use gitlab_skill_save to create one.";
           return JSON.stringify(all, null, 2);
         } catch (err) {
@@ -4011,11 +4127,9 @@ function makeSkillTools(ctx) {
       }
     }),
     gitlab_skill_load: (0, import_plugin6.tool)({
-      description: "Load a specific skill by name.\nSkills contain step-by-step instructions for common tasks.\nChecks published skills first, then falls back to draft skills.",
+      description: "Load a specific skill by name.\nSkills contain step-by-step instructions for common tasks.\nChecks published skills first, then falls back to draft skills.\nReturns the SKILL content and lists available reference pages.",
       args: {
-        project_id: z6.string().describe(
-          'FULL project path with namespace (e.g., "gitlab-org/gitlab"). Must contain a slash. Never use just the project name.'
-        ),
+        project_id: z6.string().describe(PROJECT_ID_DESC2),
         name: z6.string().describe('Skill name (e.g., "incident-retro", "helm-rollback")'),
         scope: z6.enum(["projects", "groups"]).optional().describe("Scope (default: projects)"),
         group_id: z6.string().optional().describe("Group path (required when scope is groups)")
@@ -4023,41 +4137,46 @@ function makeSkillTools(ctx) {
       execute: async (args) => {
         const auth = authAndValidate(args.project_id);
         const { scope, id } = resolveScope2(args);
-        try {
-          const page = await getWikiPage(
-            auth.instanceUrl,
-            auth.token,
-            scope,
-            id,
-            `${SKILLS_PREFIX}/${args.name}`
-          );
-          return page.content;
-        } catch {
+        const prefixes = [SKILLS_PREFIX, DRAFTS_PREFIX];
+        for (const prefix of prefixes) {
           try {
-            const draft = await getWikiPage(
+            const page = await getWikiPage(
               auth.instanceUrl,
               auth.token,
               scope,
               id,
-              `${DRAFTS_PREFIX}/${args.name}`
+              `${prefix}/${args.name}/SKILL`
             );
-            return `[DRAFT SKILL]
+            const pages = await listWikiPages(auth.instanceUrl, auth.token, scope, id);
+            const refPrefix = `${prefix}/${args.name}/references/`;
+            const refs = pages.filter((p) => p.slug.startsWith(refPrefix)).map((p) => p.slug.slice(refPrefix.length));
+            const isDraft = prefix === DRAFTS_PREFIX;
+            let result = isDraft ? `[DRAFT SKILL]
+
+${page.content}` : page.content;
+            if (refs.length > 0) {
+              result += `
 
-${draft.content}`;
+---
+Available references: ${refs.join(", ")}`;
+              result += `
+Load with: gitlab_skill_load_reference(name="${args.name}", reference="<name>")`;
+            }
+            return result;
           } catch {
-            return `Skill "${args.name}" not found. Use gitlab_skill_list to see available skills.`;
+            continue;
           }
         }
+        return `Skill "${args.name}" not found. Use gitlab_skill_list to see available skills.`;
       }
     }),
     gitlab_skill_save: (0, import_plugin6.tool)({
-      description: "Create or update a skill.\nSkills define step-by-step procedures for common tasks.\nUse draft=true for skills that haven't been proven yet.",
+      description: "Create or update a skill.\nSkills define step-by-step procedures for common tasks.\nUse draft=true for skills that haven't been proven yet.\nUpdates the skill index with the provided description.",
       args: {
-        project_id: z6.string().describe(
-          'FULL project path with namespace (e.g., "gitlab-org/gitlab"). Must contain a slash. Never use just the project name.'
-        ),
+        project_id: z6.string().describe(PROJECT_ID_DESC2),
         name: z6.string().describe('Skill name (e.g., "incident-retro")'),
         content: z6.string().describe("Skill content in markdown"),
+        description: z6.string().describe("Short description for the skill index (1-2 sentences)"),
         draft: z6.boolean().optional().describe("Save as draft skill (default: false)"),
         scope: z6.enum(["projects", "groups"]).optional().describe("Scope (default: projects)"),
         group_id: z6.string().optional().describe("Group path (required when scope is groups)")
@@ -4066,35 +4185,27 @@ ${draft.content}`;
         const auth = authAndValidate(args.project_id);
         const { scope, id } = resolveScope2(args);
         const prefix = args.draft ? DRAFTS_PREFIX : SKILLS_PREFIX;
-        const slug = `${prefix}/${args.name}`;
+        const indexSlug = args.draft ? DRAFTS_INDEX : SKILLS_INDEX;
+        const slug = `${prefix}/${args.name}/SKILL`;
         const label = args.draft ? "draft " : "";
-        for (let attempt = 0; attempt < 3; attempt++) {
-          try {
-            await updateWikiPage(auth.instanceUrl, auth.token, scope, id, slug, args.content);
-            return `Updated ${label}skill: ${args.name}`;
-          } catch {
-            try {
-              await createWikiPage(auth.instanceUrl, auth.token, scope, id, slug, args.content);
-              return `Created ${label}skill: ${args.name}`;
-            } catch (err) {
-              const msg = err.message ?? "";
-              if (msg.includes("Duplicate page") || msg.includes("reference update")) {
-                await new Promise((r) => setTimeout(r, 1e3 * (attempt + 1)));
-                continue;
-              }
-              return `Error saving skill: ${msg}`;
-            }
-          }
+        try {
+          await upsertPage(auth.instanceUrl, auth.token, scope, id, slug, args.content);
+          await upsertIndexEntry(auth.instanceUrl, auth.token, scope, id, indexSlug, {
+            name: args.name,
+            description: args.description,
+            source: "project",
+            draft: !!args.draft
+          });
+          return `Saved ${label}skill: ${args.name}`;
+        } catch (err) {
+          return `Error saving skill: ${err.message}`;
         }
-        return `Error saving skill: failed after 3 retries`;
       }
     }),
     gitlab_skill_promote: (0, import_plugin6.tool)({
-      description: "Promote a draft skill to published.\nMoves the skill from the drafts directory to the published skills directory.",
+      description: "Promote a draft skill to published.\nMoves all skill pages from drafts to published and updates both indexes.",
       args: {
-        project_id: z6.string().describe(
-          'FULL project path with namespace (e.g., "gitlab-org/gitlab"). Must contain a slash. Never use just the project name.'
-        ),
+        project_id: z6.string().describe(PROJECT_ID_DESC2),
         name: z6.string().describe("Skill name to promote"),
         scope: z6.enum(["projects", "groups"]).optional().describe("Scope (default: projects)"),
         group_id: z6.string().optional().describe("Group path (required when scope is groups)")
@@ -4102,36 +4213,170 @@ ${draft.content}`;
       execute: async (args) => {
         const auth = authAndValidate(args.project_id);
         const { scope, id } = resolveScope2(args);
-        const draftSlug = `${DRAFTS_PREFIX}/${args.name}`;
-        const publishedSlug = `${SKILLS_PREFIX}/${args.name}`;
         try {
-          const draft = await getWikiPage(auth.instanceUrl, auth.token, scope, id, draftSlug);
-          try {
-            await updateWikiPage(
-              auth.instanceUrl,
-              auth.token,
-              scope,
-              id,
-              publishedSlug,
-              draft.content
-            );
-          } catch {
-            await createWikiPage(
+          const pages = await listWikiPages(auth.instanceUrl, auth.token, scope, id, true);
+          const draftPrefix = `${DRAFTS_PREFIX}/${args.name}/`;
+          const draftPages = pages.filter(
+            (p) => p.slug.startsWith(draftPrefix) && p.content
+          );
+          if (draftPages.length === 0) {
+            return `Draft skill "${args.name}" not found. Use gitlab_skill_list(include_drafts=true) to see available drafts.`;
+          }
+          const draftIndex = await readIndex(auth.instanceUrl, auth.token, scope, id, DRAFTS_INDEX);
+          const entry = draftIndex.find((e) => e.name === args.name);
+          const description = entry?.description ?? "(promoted from draft)";
+          for (const page of draftPages) {
+            const newSlug = page.slug.replace(DRAFTS_PREFIX, SKILLS_PREFIX);
+            await upsertPage(auth.instanceUrl, auth.token, scope, id, newSlug, page.content);
+            await deleteWikiPage(auth.instanceUrl, auth.token, scope, id, page.slug);
+          }
+          await removeIndexEntry(auth.instanceUrl, auth.token, scope, id, DRAFTS_INDEX, args.name);
+          await upsertIndexEntry(auth.instanceUrl, auth.token, scope, id, SKILLS_INDEX, {
+            name: args.name,
+            description,
+            source: "project",
+            draft: false
+          });
+          return `Promoted skill "${args.name}" from draft to published.`;
+        } catch (err) {
+          return `Error promoting skill: ${err.message}`;
+        }
+      }
+    }),
+    gitlab_skill_discover: (0, import_plugin6.tool)({
+      description: "Search for skills available in the group wiki.\nReads the group-level skill index and filters by query.\nUse gitlab_skill_install to copy a discovered skill to your project.",
+      args: {
+        project_id: z6.string().describe(PROJECT_ID_DESC2),
+        query: z6.string().describe("Search query (matches skill name and description)"),
+        group_id: z6.string().describe("Group path to search for shared skills")
+      },
+      execute: async (args) => {
+        const auth = authAndValidate(args.project_id);
+        try {
+          const entries = await readIndex(
+            auth.instanceUrl,
+            auth.token,
+            "groups",
+            args.group_id,
+            SKILLS_INDEX
+          );
+          if (entries.length === 0) {
+            return `No skills found in group "${args.group_id}" wiki. The group skill index (${SKILLS_INDEX}) is empty or does not exist.`;
+          }
+          const q = args.query.toLowerCase();
+          const matches = entries.filter(
+            (e) => e.name.toLowerCase().includes(q) || e.description.toLowerCase().includes(q)
+          );
+          if (matches.length === 0) {
+            return `No skills matching "${args.query}" in group "${args.group_id}". Available skills:
+${entries.map((e) => `- ${e.name}: ${e.description}`).join("\n")}`;
+          }
+          return `Found ${matches.length} skill(s) in group "${args.group_id}":
+
+` + matches.map(
+            (e) => `**${e.name}**: ${e.description}
+Install: gitlab_skill_install(name="${e.name}", group_id="${args.group_id}")`
+          ).join("\n\n");
+        } catch (err) {
+          return `Error discovering skills: ${err.message}`;
+        }
+      }
+    }),
+    gitlab_skill_install: (0, import_plugin6.tool)({
+      description: "Install a skill from a group wiki into the project wiki.\nCopies all skill pages (SKILL + references) from the group to the project.\nUpdates the project skill index with the installed skill.",
+      args: {
+        project_id: z6.string().describe(PROJECT_ID_DESC2),
+        name: z6.string().describe('Skill name to install (e.g., "incident-retro")'),
+        group_id: z6.string().describe("Group path to install from"),
+        draft: z6.boolean().optional().describe("Install as draft (default: false)")
+      },
+      execute: async (args) => {
+        const auth = authAndValidate(args.project_id);
+        const projectScope = resolveScope2(args);
+        try {
+          const groupPages = await listWikiPages(
+            auth.instanceUrl,
+            auth.token,
+            "groups",
+            args.group_id,
+            true
+          );
+          const sourcePrefix = `${SKILLS_PREFIX}/${args.name}/`;
+          const skillPages = groupPages.filter(
+            (p) => p.slug.startsWith(sourcePrefix) && p.content
+          );
+          if (skillPages.length === 0) {
+            return `Skill "${args.name}" not found in group "${args.group_id}" wiki.`;
+          }
+          const targetPrefix = args.draft ? DRAFTS_PREFIX : SKILLS_PREFIX;
+          const targetIndex = args.draft ? DRAFTS_INDEX : SKILLS_INDEX;
+          for (const page of skillPages) {
+            const newSlug = page.slug.replace(SKILLS_PREFIX, targetPrefix);
+            await upsertPage(
               auth.instanceUrl,
               auth.token,
-              scope,
-              id,
-              publishedSlug,
-              draft.content
+              projectScope.scope,
+              projectScope.id,
+              newSlug,
+              page.content
             );
           }
-          await deleteWikiPage(auth.instanceUrl, auth.token, scope, id, draftSlug);
-          return `Promoted skill "${args.name}" from draft to published.`;
+          const groupIndex = await readIndex(
+            auth.instanceUrl,
+            auth.token,
+            "groups",
+            args.group_id,
+            SKILLS_INDEX
+          );
+          const entry = groupIndex.find((e) => e.name === args.name);
+          const description = entry?.description ?? "(installed from group)";
+          await upsertIndexEntry(
+            auth.instanceUrl,
+            auth.token,
+            projectScope.scope,
+            projectScope.id,
+            targetIndex,
+            {
+              name: args.name,
+              description,
+              source: `group:${args.group_id}`,
+              draft: !!args.draft
+            }
+          );
+          return `Installed skill "${args.name}" from group "${args.group_id}" into project. ${skillPages.length} page(s) copied.`;
         } catch (err) {
-          if (err.message?.includes("not found") || err.message?.includes("404")) {
-            return `Draft skill "${args.name}" not found. Use gitlab_skill_list(include_drafts=true) to see available drafts.`;
+          return `Error installing skill: ${err.message}`;
+        }
+      }
+    }),
+    gitlab_skill_delete: (0, import_plugin6.tool)({
+      description: "Delete a skill and remove it from the index.\nRemoves all pages under the skill directory (SKILL + references).\nWiki git history preserves deleted content.",
+      args: {
+        project_id: z6.string().describe(PROJECT_ID_DESC2),
+        name: z6.string().describe("Skill name to delete"),
+        draft: z6.boolean().optional().describe("Delete from drafts instead of published (default: false)"),
+        scope: z6.enum(["projects", "groups"]).optional().describe("Scope (default: projects)"),
+        group_id: z6.string().optional().describe("Group path (required when scope is groups)")
+      },
+      execute: async (args) => {
+        const auth = authAndValidate(args.project_id);
+        const { scope, id } = resolveScope2(args);
+        const prefix = args.draft ? DRAFTS_PREFIX : SKILLS_PREFIX;
+        const indexSlug = args.draft ? DRAFTS_INDEX : SKILLS_INDEX;
+        const skillPrefix = `${prefix}/${args.name}/`;
+        try {
+          const pages = await listWikiPages(auth.instanceUrl, auth.token, scope, id);
+          const skillPages = pages.filter((p) => p.slug.startsWith(skillPrefix));
+          if (skillPages.length === 0) {
+            return `Skill "${args.name}" not found. Use gitlab_skill_list to see available skills.`;
           }
-          return `Error promoting skill: ${err.message}`;
+          for (const page of skillPages) {
+            await deleteWikiPage(auth.instanceUrl, auth.token, scope, id, page.slug);
+          }
+          await removeIndexEntry(auth.instanceUrl, auth.token, scope, id, indexSlug, args.name);
+          return `Deleted skill "${args.name}" (${skillPages.length} page(s) removed).`;
+        } catch (err) {
+          return `Error deleting skill: ${err.message}`;
         }
       }
     })