feat: add GitLab API support and fix pin filtering

Add comprehensive GitLab API support for tools hosted on GitLab:
- New latest_gitlab() function with releases and tags API support
- Update glab tool to use official GitLab repo (gitlab-org/cli)
- Add GitLab project support in github_release_binary installer
- Update helper functions for GitLab URLs and methods

Fix pin filtering in upgrade guide:
- Add explicit check for pinned_version="never" to skip tools permanently
- Add semantic version comparison to skip when latest <= pinned
- Remove confusing status override in cli_audit.py that showed ✅ for uninstalled tools

Add snapshot refresh delay:
- 500ms delay before snapshot refresh to allow binary updates to propagate
- Fixes race condition where upgrade succeeds but snapshot shows old version

Update catalog entries:
- glab: Switch from GitHub (profclems/glab v1.22.0) to GitLab (gitlab-org/cli v1.74.0)
- pip, pipx, poetry, yarn: Add pinned_version="never" to suppress install prompts

Author: CybotTM

catalog/glab.json

@@ -2,12 +2,12 @@
   "name": "glab",
   "install_method": "github_release_binary",
   "description": "GitLab CLI tool bringing GitLab to your command line",
-  "homepage": "https://github.com/profclems/glab",
-  "github_repo": "profclems/glab",
+  "homepage": "https://gitlab.com/gitlab-org/cli",
+  "gitlab_project": "gitlab-org/cli",
   "binary_name": "glab",
-  "download_url_template": "https://github.com/profclems/glab/releases/download/{version}/glab_{version_nov}_Linux_{arch}.tar.gz",
+  "download_url_template": "https://gitlab.com/api/v4/projects/gitlab-org%2Fcli/packages/generic/glab/{version_nov}/glab_{version_nov}_linux_{arch}.tar.gz",
   "arch_map": {
-    "x86_64": "x86_64",
+    "x86_64": "amd64",
     "aarch64": "arm64",
     "armv7l": "armv6"
   }

catalog/pip.json

@@ -10,5 +10,6 @@
     "dnf": "python3-pip",
     "pacman": "python-pip"
   },
-  "notes": "pip typically comes with Python 3. Use python3 -m pip if pip command is not available."
+  "notes": "pip typically comes with Python 3. Use python3 -m pip if pip command is not available.",
+  "pinned_version": "never"
 }

catalog/pipx.json

@@ -9,5 +9,6 @@
     "brew": "pipx",
     "dnf": "pipx",
     "pacman": "python-pipx"
-  }
+  },
+  "pinned_version": "never"
 }

catalog/poetry.json

@@ -10,5 +10,6 @@
     "dnf": "poetry",
     "pacman": "python-poetry"
   },
-  "notes": "Some distributions may require installing via pipx or the official installer: curl -sSL https://install.python-poetry.org | python3 -"
+  "notes": "Some distributions may require installing via pipx or the official installer: curl -sSL https://install.python-poetry.org | python3 -",
+  "pinned_version": "never"
 }

catalog/yarn.json

@@ -5,10 +5,11 @@
   "homepage": "https://yarnpkg.com/",
   "binary_name": "yarn",
   "script": "install_yarn.sh",
-  "notes": "Installed via Node.js corepack or npm. Requires Node.js to be installed via nvm. Do NOT install via apt (conflicts with cmdtest package)."
-  ,"guide": {
+  "notes": "Installed via Node.js corepack or npm. Requires Node.js to be installed via nvm. Do NOT install via apt (conflicts with cmdtest package).",
+  "guide": {
     "display_name": "Yarn",
     "install_action": "update",
     "order": 151
-  }
+  },
+  "pinned_version": "never"
 }

cli_audit.py

@@ -827,7 +827,7 @@ def _wcswidth(s: str) -> int:
 class Tool:
     name: str
     candidates: tuple[str, ...]
-    source_kind: str  # "gh" | "pypi" | "crates" | "npm" | "gnu" | "skip"
+    source_kind: str  # "gh" | "gitlab" | "pypi" | "crates" | "npm" | "gnu" | "skip"
     source_args: tuple[str, ...]  # e.g., (owner, repo) or (package,) or (crate,) or (npm_pkg,) or (gnu_project,)
 
 
@@ -902,7 +902,7 @@ class Tool:
     # 5) VCS & platforms
     Tool("git", ("git",), "gh", ("git", "git")),
     Tool("gh", ("gh",), "gh", ("cli", "cli")),
-    Tool("glab", ("glab",), "gh", ("profclems", "glab")),
+    Tool("glab", ("glab",), "gitlab", ("gitlab-org", "cli")),
     Tool("gam", ("gam",), "gh", ("GAM-team", "GAM")),
     # 6) Task runners & build systems
     Tool("just", ("just",), "gh", ("casey", "just")),
@@ -1892,6 +1892,8 @@ def upstream_method_for(tool: Tool) -> str:
         return "npm (nvm)"
     if kind == "gh":
         return "github"
+    if kind == "gitlab":
+        return "gitlab"
     if kind == "gnu":
         return "gnu-ftp"
     return ""
@@ -1904,6 +1906,9 @@ def tool_homepage_url(tool: Tool) -> str:
         if kind == "gh":
             owner, repo = args  # type: ignore[misc]
             return f"https://github.com/{owner}/{repo}"
+        if kind == "gitlab":
+            group, project = args  # type: ignore[misc]
+            return f"https://gitlab.com/{group}/{project}"
         if kind == "pypi":
             (pkg,) = args  # type: ignore[misc]
             return f"https://pypi.org/project/{pkg}/"
@@ -1930,6 +1935,11 @@ def latest_target_url(tool: Tool, latest_tag: str, latest_num: str) -> str:
             if latest_tag:
                 return f"https://github.com/{owner}/{repo}/releases/tag/{latest_tag}"
             return f"https://github.com/{owner}/{repo}/releases/latest"
+        if kind == "gitlab":
+            group, project = args  # type: ignore[misc]
+            if latest_tag:
+                return f"https://gitlab.com/{group}/{project}/-/releases/{latest_tag}"
+            return f"https://gitlab.com/{group}/{project}/-/releases"
         if kind == "pypi":
             (pkg,) = args  # type: ignore[misc]
             return f"https://pypi.org/project/{pkg}/"
@@ -2162,6 +2172,92 @@ def latest_github(owner: str, repo: str) -> tuple[str, str]:
     return "", ""
 
 
+def latest_gitlab(group: str, project: str) -> tuple[str, str]:
+    """
+    Fetch the latest release from GitLab using the GitLab API.
+    Args:
+        group: GitLab group/namespace (e.g., "gitlab-org")
+        project: Project name (e.g., "cli")
+    Returns:
+        (tag_name, version_number) tuple or ("", "") if not found
+    """
+    if OFFLINE_MODE:
+        return "", ""
+
+    # GitLab API requires URL-encoded project path
+    project_path = f"{group}%2F{project}"
+
+    # Try releases API first (excludes pre-releases by default)
+    try:
+        url = f"https://gitlab.com/api/v4/projects/{project_path}/releases"
+        if AUDIT_DEBUG:
+            print(f"# DEBUG: GitLab API {url} (timeout={TIMEOUT_SECONDS}s)", file=sys.stderr, flush=True)
+
+        data = json.loads(http_get(url))
+
+        if isinstance(data, list) and data:
+            # GitLab releases API returns releases in descending order by default
+            # First release is the latest
+            release = data[0]
+            tag = normalize_version_tag((release.get("tag_name") or "").strip())
+
+            if tag:
+                result = (tag, extract_version_number(tag))
+                set_manual_latest(project, tag)
+                set_hint(f"gitlab:{group}/{project}", "releases_api")
+                if AUDIT_DEBUG:
+                    print(f"# DEBUG: GitLab found release: {tag}", file=sys.stderr, flush=True)
+                return result
+    except Exception as e:
+        if AUDIT_DEBUG:
+            print(f"# DEBUG: GitLab releases API failed: {e}", file=sys.stderr, flush=True)
+        pass
+
+    # Fallback to tags API
+    try:
+        url = f"https://gitlab.com/api/v4/projects/{project_path}/repository/tags?per_page=20"
+        if AUDIT_DEBUG:
+            print(f"# DEBUG: GitLab tags API {url}", file=sys.stderr, flush=True)
+
+        data = json.loads(http_get(url))
+
+        if isinstance(data, list):
+            # Filter stable releases and find highest version
+            best: tuple[tuple[int, ...], str, str] | None = None
+
+            for item in data:
+                tag_name = (item.get("name") or "").strip()
+                tag = normalize_version_tag(tag_name)
+
+                # Accept only stable final release tags (v1.2.3, 1.2.3)
+                # Exclude rc, alpha, beta, pre, dev suffixes
+                if tag and re.match(r"^v?\d+\.\d+(\.\d+)?$", tag):
+                    ver = extract_version_number(tag)
+                    if ver:
+                        try:
+                            nums = tuple(int(x) for x in ver.split("."))
+                            tup = (nums, tag, ver)
+                            if best is None or tup[0] > best[0]:
+                                best = tup
+                        except Exception:
+                            continue
+
+            if best is not None:
+                _, tag, ver = best
+                result = (tag, ver)
+                set_manual_latest(project, tag)
+                set_hint(f"gitlab:{group}/{project}", "tags_api")
+                if AUDIT_DEBUG:
+                    print(f"# DEBUG: GitLab found tag: {tag}", file=sys.stderr, flush=True)
+                return result
+    except Exception as e:
+        if AUDIT_DEBUG:
+            print(f"# DEBUG: GitLab tags API failed: {e}", file=sys.stderr, flush=True)
+        pass
+
+    return "", ""
+
+
 def latest_pypi(package: str) -> tuple[str, str]:
     if OFFLINE_MODE:
         return "", ""
@@ -2365,6 +2461,18 @@ def get_latest(tool: Tool) -> tuple[str, str]:
             return man_tag, man_num
         MANUAL_USED[tool.name] = False
         return tag, num
+    if kind == "gitlab":
+        group, project = args  # type: ignore[misc]
+        tag, num = latest_gitlab(group, project)
+        if tag or num:
+            MANUAL_USED[tool.name] = False
+            set_manual_method(tool.name, "gitlab")
+            return tag, num
+        if manual_available:
+            MANUAL_USED[tool.name] = True
+            return man_tag, man_num
+        MANUAL_USED[tool.name] = False
+        return tag, num
     if kind == "pypi":
         (pkg,) = args  # type: ignore[misc]
         tag, num = latest_pypi(pkg)
@@ -2530,20 +2638,9 @@ def audit_tool(tool: Tool) -> tuple[str, str, str, str, str, str, str, str]:
                 except Exception:
                     pass  # Catalog read failed, continue with original status
 
-    # Check if tool is marked as "never install"
-    if status == "NOT INSTALLED":
-        script_dir = os.path.dirname(os.path.abspath(__file__))
-        catalog_file = os.path.join(script_dir, "catalog", f"{tool.name}.json")
-        if os.path.exists(catalog_file):
-            try:
-                with open(catalog_file, "r", encoding="utf-8") as f:
-                    catalog_data = json.load(f)
-                    pinned_version = catalog_data.get("pinned_version", "")
-                    if pinned_version == "never":
-                        # Tool is marked as never install - treat as up-to-date to suppress prompts
-                        status = "UP-TO-DATE"
-            except Exception:
-                pass  # Catalog read failed, continue with original status
+    # Note: Tools with pinned_version="never" are filtered out in guide.sh,
+    # so we don't need to change their status here. Keep them as NOT INSTALLED
+    # to avoid confusion (showing ✅ icon when tool isn't actually installed).
 
     # Sanitize latest display to numeric (like installed)
     if latest_num:

latest_versions.json

@@ -9,20 +9,20 @@
     "gh:arxanas/git-branchless": "latest_redirect",
     "gh:ast-grep/ast-grep": "latest_redirect",
     "gh:astral-sh/uv": "latest_redirect",
-    "gh:aws/aws-cli": "atom_filtered",
+    "gh:aws/aws-cli": "tags_api",
     "gh:casey/just": "latest_redirect",
     "gh:cli/cli": "latest_redirect",
     "gh:composer/composer": "latest_redirect",
     "gh:dandavison/delta": "latest_redirect",
     "gh:direnv/direnv": "latest_redirect",
-    "gh:docker/cli": "atom_filtered",
+    "gh:docker/cli": "tags_api",
     "gh:docker/compose": "latest_redirect",
-    "gh:eradman/entr": "atom_filtered",
+    "gh:eradman/entr": "tags_api",
     "gh:eslint/eslint": "latest_redirect",
     "gh:git-lfs/git-lfs": "latest_redirect",
-    "gh:git/git": "atom_filtered",
+    "gh:git/git": "tags_api",
     "gh:gitleaks/gitleaks": "latest_redirect",
-    "gh:golang/go": "atom",
+    "gh:golang/go": "tags_api",
     "gh:golangci/golangci-lint": "latest_redirect",
     "gh:hashicorp/terraform": "latest_redirect",
     "gh:jqlang/jq": "latest_redirect",
@@ -36,7 +36,7 @@
     "gh:phiresky/ripgrep-all": "latest_redirect",
     "gh:prettier/prettier": "latest_redirect",
     "gh:profclems/glab": "latest_redirect",
-    "gh:python/cpython": "atom_filtered",
+    "gh:python/cpython": "tags_api",
     "gh:rs/curlie": "latest_redirect",
     "gh:ruby/ruby": "latest_redirect",
     "gh:rubygems/rubygems": "latest_redirect",
@@ -47,6 +47,7 @@
     "gh:universal-ctags/ctags": "latest_redirect",
     "gh:wagoodman/dive": "latest_redirect",
     "gh:watchexec/watchexec": "latest_redirect",
+    "gitlab:gitlab-org/cli": "releases_api",
     "local_dc:docker-compose": "plugin",
     "local_flag:ast-grep": "--version",
     "local_flag:aws": "--version",
@@ -170,7 +171,7 @@
     "git-branchless": "github",
     "git-lfs": "github",
     "gitleaks": "github",
-    "glab": "github",
+    "glab": "gitlab",
     "go": "github",
     "golangci-lint": "github",
     "httpie": "pypi",

scripts/guide.sh

@@ -221,6 +221,44 @@ while read -r line; do
 
   # Only process tools with catalog entries
   if catalog_has_tool "$tool_name"; then
+    # Check if tool is pinned to a version >= latest available or "never"
+    pinned_version="$(catalog_get_property "$tool_name" pinned_version)"
+
+    # Skip if pinned to "never" (permanently skip installation)
+    if [ "$pinned_version" = "never" ]; then
+      continue
+    fi
+
+    latest_version="$(json_field "$tool_name" latest_version)"
+
+    if [ -n "$pinned_version" ] && [ -n "$latest_version" ]; then
+      # Compare versions: skip if latest <= pinned
+      # Simple numeric comparison for semantic versions
+      if "$CLI" - "$pinned_version" "$latest_version" <<'PY'
+import sys
+try:
+    pinned, latest = sys.argv[1], sys.argv[2]
+    # Strip 'v' prefix if present
+    pinned = pinned.lstrip('v')
+    latest = latest.lstrip('v')
+    # Split into parts and compare
+    p_parts = [int(x) for x in pinned.split('.')[:3]]
+    l_parts = [int(x) for x in latest.split('.')[:3]]
+    # Pad with zeros if needed
+    while len(p_parts) < 3: p_parts.append(0)
+    while len(l_parts) < 3: l_parts.append(0)
+    # Exit 0 (success) if latest <= pinned (should skip)
+    sys.exit(0 if tuple(l_parts) <= tuple(p_parts) else 1)
+except Exception:
+    # On error, don't skip (exit 1)
+    sys.exit(1)
+PY
+      then
+        # Skip this tool - pinned version is >= latest available
+        continue
+      fi
+    fi
+
     TOOLS_TO_PROCESS+=("$tool_name")
   fi
 done <<< "$AUDIT_OUTPUT"

scripts/installers/github_release_binary.sh

@@ -56,6 +56,14 @@ if [ -n "$VERSION_URL" ]; then
   LATEST="$(curl -fsSL "$VERSION_URL" 2>/dev/null || true)"
 fi
 
+# Try GitLab project if available
+GITLAB_PROJECT="$(jq -r '.gitlab_project // empty' "$CATALOG_FILE")"
+if [ -z "$LATEST" ] && [ -n "$GITLAB_PROJECT" ]; then
+  ENCODED_PROJECT="${GITLAB_PROJECT//\//%2F}"
+  LATEST="$(curl -fsSL "https://gitlab.com/api/v4/projects/${ENCODED_PROJECT}/releases?per_page=1" 2>/dev/null | \
+    jq -r '.[0].tag_name // empty' 2>/dev/null || true)"
+fi
+
 # Fallback to GitHub releases if no version URL
 if [ -z "$LATEST" ] && [ -n "$GITHUB_REPO" ]; then
   LATEST="$(curl -fsSIL -H "User-Agent: cli-audit" -o /dev/null -w '%{url_effective}' \

scripts/lib/install_strategy.sh

@@ -82,6 +82,9 @@ refresh_snapshot() {
 
   echo "# Refreshing snapshot for $tool_name..." >&2
 
+  # Brief delay to ensure binary is fully updated and PATH is refreshed
+  sleep 0.5
+
   # Run audit in merge mode for this specific tool
   CLI_AUDIT_COLLECT=1 CLI_AUDIT_MERGE=1 python3 "$audit_script" --only "$tool_name" >/dev/null 2>&1 || {
     echo "# Warning: Failed to refresh snapshot for $tool_name" >&2