@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/claude/packs/integrations/skills/github-actions-to-gitlab-ci/references/validator.md

@@ -0,0 +1,91 @@
+# Validator reference
+
+Detailed handling for `scripts/validate.sh`. Load when something other than the happy path occurs: script not found, permission denied, neither backend installed, no shell or network access, validation fails, or the `glab` backend needs a project.
+
+The happy path itself stays in `SKILL.md` step 4.5: `bash <skill-dir>/scripts/validate.sh /path/to/translated.gitlab-ci.yml`.
+
+## Finding the script
+
+The script is at `scripts/validate.sh` inside the skill bundle. The path depends on the host tool:
+
+- **Claude Code**: use `${CLAUDE_SKILL_DIR}/scripts/validate.sh`
+- **opencode and other tools**: the skill is at one of the discovery paths (`~/.claude/skills/github-actions-to-gitlab-ci/`, `~/.config/opencode/skills/github-actions-to-gitlab-ci/`, `~/.agents/skills/github-actions-to-gitlab-ci/`, or a project-local equivalent). Locate the directory you loaded this skill from and append `/scripts/validate.sh`.
+- **Fallback**: if you cannot locate the bundled script, run the underlying tool directly: `glci lint -f <path>` (preferred) or `glab ci lint <path>` (fallback). The bundled script is a thin wrapper around exactly those commands.
+
+## Backend selection
+
+Set `VALIDATE_BACKEND=glci|glab` to force a specific backend. The default is `auto`, which prefers `glci` when installed and falls back to `glab`.
+
+## `glab` backend project resolution
+
+The `glab` backend needs a GitLab project context (the lint API is per-project). The script resolves the project from, in order:
+
+1. A `--project <group/project>` flag passed to the script.
+2. The `VALIDATE_PROJECT` environment variable.
+3. The git remote of the current directory (when the user is inside a GitLab checkout).
+4. The user's `glab` default.
+
+The skill does not hardcode any project. If none of these resolves, the script exits 2 with a clear error explaining the three options the user has: install `glci` instead, set `VALIDATE_PROJECT`, or pass `--project`. For users migrating from GitHub Actions who do not have a GitLab project they can use, the simplest path is to install `glci`, which validates entirely offline and needs no project.
+
+## Migrating from a GitHub-hosted repo
+
+Users invoking this skill are almost always sitting in a repo whose origin is on GitHub. That has two consequences:
+
+- The git-remote step of the `glab` project resolver will never produce a GitLab path. The script's resolver rejects non-GitLab hosts.
+- Unless the user has set `VALIDATE_PROJECT` or `--project`, the `glab` path can only fail.
+
+When you detect (or anticipate) a non-GitLab origin, lead with `glci` from the start: recommend installing it before invoking the validator. This avoids the failed `glab` fallback entirely.
+
+## Permission denied / missing executable bit
+
+Two binaries can hit this: the bundled `scripts/validate.sh` itself, and the `glci` binary when installed manually.
+
+**`validate.sh`**: the executable bit is lost when the skill is copied via tarball or zip (not via `git clone`). Fix once with `chmod +x <skill-dir>/scripts/validate.sh`, or always invoke via `bash` as shown in SKILL.md.
+
+**`glci`**: manual installs via `sudo mv` often preserve whatever mode the downloaded file had and silently produce a binary without the `x` bit. `validate.sh` detects this in standard locations and exits 2 with a pointer. If the script reports glci as missing despite a prior install, check the standard paths:
+
+```bash
+ls -l /usr/local/bin/glci /opt/homebrew/bin/glci ~/bin/glci ~/.local/bin/glci 2>/dev/null
+```
+
+If a file is present without `x` in its mode, fix it with `sudo chmod +x <path>` (or without sudo if the file is under `$HOME`).
+
+## Neither backend installed (exit code 2)
+
+The script prints install commands for both tools. The agent should not run any install command itself without explicit user consent, and even with consent, prefer asking the user to run it themselves. This sidesteps environments where the agent is sandboxed (no shell access, `curl` blocked, or otherwise restricted) and keeps the user in control of what gets installed on their machine.
+
+Surface both options with their tradeoffs and let the user pick:
+
+- **glci** (recommended when the user does not yet have GitLab tooling). Runs offline, no GitLab account or token required, deeper parse, unlocks future structural validation. The bundled `scripts/validate.sh` prints the install one-liner in its error output, pointing at `main/install.sh` which always installs the latest tag. If `curl` is restricted in the user's environment or they prefer a manual install, point them to the releases page: https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/releases. They can download the binary matching their OS/arch (`glci-darwin-arm64`, `glci-linux-amd64`, etc.), mark it executable with `chmod +x`, and move it to a directory on PATH.
+- **glab** (recommended if the user already has a GitLab account). Calls the GitLab CI Lint API. Install via the user's preferred method (Homebrew, apt, dnf, winget, manual download). See https://gitlab.com/gitlab-org/cli#installation for the full list. After install, the user runs `glab auth login` once.
+
+When the user is migrating from GitHub Actions and does not yet have GitLab tooling, lead with `glci` because it does not assume an existing GitLab account. If the user already mentioned a GitLab account or `glab` set up, lead with `glab`. Hand the user the relevant install command (or the releases URL for a manual download), ask them to run it themselves, and once they confirm, re-run `validate.sh` and continue.
+
+If the user declines both, skip validation in this run and clearly note in the migration report that the translated `.gitlab-ci.yml` was not validated locally. Recommend they validate in the GitLab UI Pipeline editor (**Build > Pipeline editor > Validate**, or **CI/CD > Pipelines > CI/CD Lint** on older versions) after pushing.
+
+## No shell access
+
+Some hosts (web-only chat surfaces, read-only review agents, sandboxed environments without shell access) cannot invoke `bash` or run the bundled validator. In that case:
+
+- Skip the script invocation; do not pretend it ran.
+- Mark "local validation skipped (agent has no shell access)" in the migration report so the user knows they are receiving an unvalidated translation.
+- Tell the user to validate the YAML in the GitLab UI: open the project on GitLab and go to **Build > Pipeline editor > Validate** (or **CI/CD > Pipelines > CI/CD Lint** on older versions). Paste the YAML, click Validate. Zero local tooling required.
+- For future runs, recommend the user install `glci` (preferred) or `glab` locally so subsequent translations can be validated end-to-end. The bundled `scripts/validate.sh` will work on hosts that support bash.
+
+## No network access
+
+Two paths to be aware of:
+
+- `glci lint` is offline by design. If `glci` is installed locally, validation still works without any network.
+- `glab ci lint` calls the GitLab CI Lint API and will fail without network. If only `glab` is installed, validation will exit non-zero with a network error; document this in the migration report as "could not validate (no network)" and recommend the user retry when network is available, install `glci` for offline validation, or use the GitLab UI Pipeline editor.
+
+## Validation failures
+
+The output lists errors with line numbers. Two responses:
+
+- **Syntax error**: fix it and re-run the validator.
+- **Translation gap**: document the error as a "Needs review" item in the migration report rather than silently shipping a broken file.
+
+## What the validator does not catch
+
+The validator does not catch semantic errors (does the pipeline do what the user intended?) or runtime errors (will the scripts succeed?). Those remain the user's responsibility, surfaced via the migration report.

package/assets/claude/packs/integrations/skills/github-actions-to-gitlab-ci/scripts/validate.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# Validate a .gitlab-ci.yml file using glci (preferred) or glab (fallback).
+# Usage: ./validate.sh [--project <group/project>] [path-to-file]
+# Default file: .gitlab-ci.yml in the current directory.
+#
+# Backend selection (env var VALIDATE_BACKEND):
+#   auto (default) - prefer glci if installed, fall back to glab
+#   glci           - require glci, do not fall back
+#   glab           - require glab, do not fall back
+#
+# glci lint runs fully offline. It resolves include:, extends:, !reference,
+# default:, and workflow: without a GitLab token. No GitLab project context
+# required. Deeper than glab ci lint.
+#
+# glab ci lint calls the GitLab CI Lint API. Requires glab to be installed and
+# authenticated, AND a GitLab project context the user can read. The script
+# resolves the project from (in order):
+#   1. --project <group/project> flag
+#   2. VALIDATE_PROJECT environment variable
+#   3. git remote origin URL (when run inside a GitLab checkout)
+#   4. glab's default host project via `glab config get`
+# If none of those resolve, the script exits 2 with a clear error.
+#
+# Exit codes:
+#   0 - file is syntactically valid
+#   1 - file is invalid (errors printed)
+#   2 - file not found, no backend available, no project for glab backend,
+#       or unknown VALIDATE_BACKEND
+
+set -uo pipefail
+
+# Parse args: --project <path>, then positional FILE.
+PROJECT_FLAG=""
+FILE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --project)
+      shift
+      PROJECT_FLAG="${1:-}"
+      shift
+      ;;
+    --project=*)
+      PROJECT_FLAG="${1#--project=}"
+      shift
+      ;;
+    -h|--help)
+      sed -n '1,28p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *)
+      if [ -z "$FILE" ]; then
+        FILE="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+FILE="${FILE:-.gitlab-ci.yml}"
+BACKEND="${VALIDATE_BACKEND:-auto}"
+
+if [ ! -f "$FILE" ]; then
+  echo "ERROR: $FILE not found" >&2
+  exit 2
+fi
+
+have_glci=0
+have_glab=0
+command -v glci >/dev/null 2>&1 && have_glci=1
+command -v glab >/dev/null 2>&1 && have_glab=1
+
+# If glci is not on PATH, check common install paths for an existing file that
+# is not executable. Manual installs via `sudo mv` often preserve whatever mode
+# the downloaded file had and silently produce an inert binary.
+broken_glci_path=""
+if [ "$have_glci" = 0 ]; then
+  for candidate in /usr/local/bin/glci /opt/homebrew/bin/glci "$HOME/bin/glci" "$HOME/.local/bin/glci"; do
+    if [ -f "$candidate" ] && [ ! -x "$candidate" ]; then
+      broken_glci_path="$candidate"
+      break
+    fi
+  done
+fi
+
+print_install_pointers() {
+  # The install script at main/install.sh always pins to the latest tag.
+  echo "Install glci (preferred, offline, no token):" >&2
+  echo "  curl -fsSL https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/raw/main/install.sh | bash" >&2
+  echo "  (or browse releases: https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/releases)" >&2
+  echo "Install glab (fallback, requires authenticated GitLab account):" >&2
+  echo "  https://gitlab.com/gitlab-org/cli#installation" >&2
+}
+
+# Resolution chain for the glab backend's project context.
+# Echoes the resolved "group/project" path on stdout, empty if none found.
+resolve_glab_project() {
+  # 1. Explicit --project flag
+  if [ -n "$PROJECT_FLAG" ]; then
+    echo "$PROJECT_FLAG"
+    return 0
+  fi
+  # 2. VALIDATE_PROJECT env var
+  if [ -n "${VALIDATE_PROJECT:-}" ]; then
+    echo "$VALIDATE_PROJECT"
+    return 0
+  fi
+  # 3. git remote origin URL, parsed for gitlab host
+  local remote_url
+  remote_url="$(git config --get remote.origin.url 2>/dev/null || true)"
+  if [ -n "$remote_url" ]; then
+    # Strip protocol and host for both SSH and HTTPS remotes. Only matches
+    # gitlab.com or any *.gitlab.* host; non-GitLab hosts (github.com, etc.)
+    # are left intact and rejected by the equality check below. The .git
+    # suffix is stripped separately so a github.com URL with .git does not
+    # masquerade as a "stripped" GitLab path.
+    local stripped
+    stripped="$(echo "$remote_url" \
+      | sed -E 's#^(https?://|git@)[^/:]*gitlab[^/:]*[:/]##')"
+    if [ -n "$stripped" ] && [ "$stripped" != "$remote_url" ]; then
+      echo "${stripped%.git}"
+      return 0
+    fi
+  fi
+  # 4. glab's default host project, if glab is installed
+  if [ "$have_glab" = 1 ]; then
+    local glab_default
+    glab_default="$(glab config get -g host 2>/dev/null || true)"
+    # glab config does not expose a "default project" directly; users must
+    # set one explicitly. Skip this step rather than guessing.
+    : "${glab_default:=}"
+  fi
+  echo ""
+}
+
+print_no_project_error() {
+  echo "ERROR: glab backend requires a GitLab project context." >&2
+  echo "  No project found via --project flag, VALIDATE_PROJECT env var, git remote, or glab config." >&2
+  echo "" >&2
+  echo "You have three options:" >&2
+  echo "  1. Install glci (preferred; works offline, no GitLab project required):" >&2
+  echo "     curl -fsSL https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/raw/main/install.sh | bash" >&2
+  echo "     (or browse releases: https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/releases)" >&2
+  echo "  2. Set VALIDATE_PROJECT to a GitLab project you own (or can read):" >&2
+  echo "     VALIDATE_PROJECT=your-group/your-project bash scripts/validate.sh <file>" >&2
+  echo "  3. Pass --project explicitly per invocation:" >&2
+  echo "     bash scripts/validate.sh --project your-group/your-project <file>" >&2
+}
+
+case "$BACKEND" in
+  auto)
+    if [ "$have_glci" = 1 ]; then
+      BACKEND=glci
+    elif [ -n "$broken_glci_path" ]; then
+      echo "ERROR: found glci at $broken_glci_path but it is not executable." >&2
+      echo "  Fix it and re-run:" >&2
+      echo "    chmod +x $broken_glci_path" >&2
+      exit 2
+    elif [ "$have_glab" = 1 ]; then
+      BACKEND=glab
+      echo "Note: glci not detected on PATH; falling back to glab ci lint." >&2
+    else
+      echo "ERROR: neither glci nor glab is installed." >&2
+      print_install_pointers
+      exit 2
+    fi
+    ;;
+  glci)
+    if [ "$have_glci" != 1 ]; then
+      if [ -n "$broken_glci_path" ]; then
+        echo "ERROR: VALIDATE_BACKEND=glci but glci at $broken_glci_path is not executable." >&2
+        echo "  Fix it and re-run:" >&2
+        echo "    chmod +x $broken_glci_path" >&2
+      else
+        echo "ERROR: VALIDATE_BACKEND=glci but glci is not installed." >&2
+        print_install_pointers
+      fi
+      exit 2
+    fi
+    ;;
+  glab)
+    if [ "$have_glab" != 1 ]; then
+      echo "ERROR: VALIDATE_BACKEND=glab but glab is not installed." >&2
+      print_install_pointers
+      exit 2
+    fi
+    ;;
+  *)
+    echo "ERROR: unknown VALIDATE_BACKEND: $BACKEND (expected auto, glci, or glab)" >&2
+    exit 2
+    ;;
+esac
+
+case "$BACKEND" in
+  glci)
+    echo "Validating $FILE via glci lint..."
+    exec glci lint --quiet -f "$FILE"
+    ;;
+  glab)
+    PROJECT="$(resolve_glab_project)"
+    if [ -z "$PROJECT" ]; then
+      print_no_project_error
+      exit 2
+    fi
+    echo "Validating $FILE via glab ci lint (project: $PROJECT)..."
+    exec glab ci lint --repo "$PROJECT" "$FILE"
+    ;;
+esac

package/assets/claude/packs/integrations/skills/gitlab-ci-skill/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present GitLab Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.