@mthanh/vespercli 1.8.0 → 2.0.1

package/assets/copilot/packs/integrations/skills/gitlab-ci-skill/scripts/verify.sh

@@ -0,0 +1,332 @@
+#!/usr/bin/env bash
+# Verify a .gitlab-ci.yml file across glci's verification ladder.
+# Usage: ./verify.sh [-f FILE] [--project G/P] <tier> [tier-args...]
+#
+# Tiers (each catches more than the previous):
+#   auto                          - lint + show, plus simulate when Docker is
+#                                   reachable. The recommended default.
+#   lint                          - glci lint (offline). Falls back to
+#                                   glab ci lint when glci is absent.
+#   show [--json] [--context X]   - glci show. Renders the pipeline graph.
+#                                   Requires glci (no glab fallback).
+#   simulate                      - glci run --simulate. Plans execution with
+#                                   echoed scripts and dummy artifacts.
+#                                   Requires glci and a reachable Docker daemon.
+#   run [job...] --confirm-docker - glci run [job...]. Real execution.
+#                                   Requires glci, Docker, and explicit opt-in.
+#
+# Common flags:
+#   -f FILE         CI config path (default: .gitlab-ci.yml)
+#   --project G/P   Force project context for glab fallback (lint tier only)
+#   --help, -h      Show this help
+#
+# Environment:
+#   VALIDATE_BACKEND=auto|glci|glab   Forces lint backend (default: auto)
+#   VALIDATE_PROJECT=group/project    Project context for glab fallback
+#
+# Exit codes:
+#   0   Verification passed
+#   1   Verification failed (YAML or runtime problem; see stderr)
+#   2   Environment problem (missing tool, Docker down, missing opt-in flag)
+
+set -uo pipefail
+
+usage() { sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; }
+
+FILE=".gitlab-ci.yml"
+PROJECT_FLAG=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -f|--file) shift; FILE="${1:-}"; shift ;;
+    -f=*|--file=*) FILE="${1#*=}"; shift ;;
+    --project) shift; PROJECT_FLAG="${1:-}"; shift ;;
+    --project=*) PROJECT_FLAG="${1#*=}"; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) break ;;
+  esac
+done
+
+if [ $# -lt 1 ]; then
+  echo "ERROR: missing tier (auto, lint, show, simulate, or run)" >&2
+  echo "" >&2
+  usage >&2
+  exit 2
+fi
+
+TIER="$1"; shift
+
+if [ ! -f "$FILE" ]; then
+  echo "ERROR: $FILE not found" >&2
+  exit 2
+fi
+
+# Tool detection.
+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
+
+# Manual installs via `sudo mv` can preserve a non-executable mode silently.
+broken_glci_path=""
+if [ "$have_glci" = 0 ]; then
+  for c in /usr/local/bin/glci /opt/homebrew/bin/glci "$HOME/bin/glci" "$HOME/.local/bin/glci"; do
+    if [ -f "$c" ] && [ ! -x "$c" ]; then
+      broken_glci_path="$c"
+      break
+    fi
+  done
+fi
+
+print_glci_install() {
+  echo "Install glci (runs offline, no GitLab account required):" >&2
+  echo "  curl -fsSL https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/raw/main/install.sh | bash" >&2
+  echo "  (browse releases: https://gitlab.com/gitlab-org/ci-cd/runner-tools/glci/-/releases)" >&2
+}
+
+print_glab_install() {
+  echo "Install glab (lint fallback, requires authenticated GitLab account):" >&2
+  echo "  https://gitlab.com/gitlab-org/cli#installation" >&2
+}
+
+print_docker_install_offer() {
+  local os
+  os="$(uname -s 2>/dev/null || echo unknown)"
+  echo "" >&2
+  echo "To unlock the simulate and run tiers, install Docker:" >&2
+  case "$os" in
+    Darwin)
+      echo "  macOS (lightweight):  brew install colima docker && colima start" >&2
+      echo "  macOS (GUI):          https://www.docker.com/products/docker-desktop" >&2
+      ;;
+    Linux)
+      echo "  Linux:                curl -fsSL https://get.docker.com | sh" >&2
+      ;;
+    *)
+      echo "  Install Docker for your platform: https://docs.docker.com/get-docker/" >&2
+      ;;
+  esac
+  echo "" >&2
+  echo "glci needs Docker to spin up the gitlab-runner image and run jobs locally" >&2
+  echo "with the same fidelity as a real GitLab pipeline." >&2
+}
+
+require_glci() {
+  if [ "$have_glci" = 1 ]; then return 0; fi
+  if [ -n "$broken_glci_path" ]; then
+    echo "ERROR: found glci at $broken_glci_path but it is not executable." >&2
+    echo "  Fix it: chmod +x $broken_glci_path" >&2
+  else
+    echo "ERROR: '$TIER' tier requires glci, but glci is not installed." >&2
+    echo "  (Only the 'lint' tier can fall back to glab; higher tiers cannot.)" >&2
+    echo "" >&2
+    print_glci_install
+  fi
+  exit 2
+}
+
+# Returns 0 if Docker is reachable, 1 otherwise. Does not exit.
+docker_reachable() {
+  command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
+}
+
+# Returns 0 if the working tree has at least one commit, OR if we are not
+# inside a git work tree at all (glci uses synthetic vars in that case).
+# Returns 1 only for the panic-triggering case: git repo with zero commits.
+has_commits() {
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    return 0
+  fi
+  git rev-parse HEAD >/dev/null 2>&1
+}
+
+# Hard-fail with the no-commits diagnosis. Used by simulate and run tiers.
+require_commits() {
+  if has_commits; then return 0; fi
+  echo "ERROR: '$TIER' tier needs at least one git commit in this repo." >&2
+  echo "  glci's embedded gitlab-runner panics on commit-less repos:" >&2
+  echo "    panic: runtime error: slice bounds out of range [:8] with length 4" >&2
+  echo "  (lint and show still work in commit-less repos.)" >&2
+  echo "" >&2
+  echo "  Fix: create an initial commit and re-run." >&2
+  echo "    git add -A && git commit -m \"Initial commit\"" >&2
+  exit 2
+}
+
+require_docker() {
+  if ! command -v docker >/dev/null 2>&1; then
+    echo "ERROR: '$TIER' tier needs Docker, but the docker CLI is not on PATH." >&2
+    print_docker_install_offer
+    exit 2
+  fi
+  if ! docker info >/dev/null 2>&1; then
+    echo "ERROR: '$TIER' tier needs a reachable Docker daemon, but 'docker info' failed." >&2
+    echo "  Start Docker (or your Docker daemon), then re-run." >&2
+    echo "  For a detailed environment report: glci doctor" >&2
+    exit 2
+  fi
+}
+
+# glab project resolution: explicit flag, then env var, then git remote.
+# Returns empty if none resolve.
+resolve_glab_project() {
+  if [ -n "$PROJECT_FLAG" ]; then echo "$PROJECT_FLAG"; return 0; fi
+  if [ -n "${VALIDATE_PROJECT:-}" ]; then echo "$VALIDATE_PROJECT"; return 0; fi
+  local remote_url stripped
+  remote_url="$(git config --get remote.origin.url 2>/dev/null || true)"
+  if [ -n "$remote_url" ]; then
+    # Match git@gitlab.com:g/p[.git] and https://gitlab.com/g/p[.git]. Non-GitLab
+    # hosts (github.com, etc.) leave the URL unchanged and are rejected below.
+    stripped="$(echo "$remote_url" | sed -E 's#^(https?://|git@)[^/:]*gitlab[^/:]*[:/]##')"
+    if [ -n "$stripped" ] && [ "$stripped" != "$remote_url" ]; then
+      echo "${stripped%.git}"
+      return 0
+    fi
+  fi
+  echo ""
+}
+
+print_no_project_error() {
+  echo "ERROR: glab backend requires a GitLab project context." >&2
+  echo "  No project found via --project, VALIDATE_PROJECT env var, or git remote." >&2
+  echo "" >&2
+  echo "Options:" >&2
+  echo "  1. Install glci (recommended, validates offline, no project required):" >&2
+  print_glci_install
+  echo "  2. Set VALIDATE_PROJECT=your-group/your-project and re-run." >&2
+  echo "  3. Pass --project your-group/your-project to verify.sh." >&2
+}
+
+# Lint backend selection.
+do_lint() {
+  local backend="${VALIDATE_BACKEND:-auto}"
+  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: 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_glci_install
+        print_glab_install
+        exit 2
+      fi
+      ;;
+    glci)
+      if [ "$have_glci" != 1 ]; then
+        echo "ERROR: VALIDATE_BACKEND=glci but glci is not installed." >&2
+        print_glci_install
+        exit 2
+      fi
+      ;;
+    glab)
+      if [ "$have_glab" != 1 ]; then
+        echo "ERROR: VALIDATE_BACKEND=glab but glab is not installed." >&2
+        print_glab_install
+        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)
+      local project
+      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
+}
+
+case "$TIER" in
+  auto)
+    # Lint + show always; simulate when Docker is reachable AND the repo has
+    # at least one commit. The recommended default for Workflows 1 and 4.
+    # Workflows 2 and 3 should call run directly against a specific job with
+    # --reuse-artifacts.
+    require_glci
+    # glci show parses and lints the YAML implicitly; no separate lint call.
+    if ! glci show -f "$FILE"; then
+      exit $?
+    fi
+    if ! docker_reachable; then
+      echo "" >&2
+      echo "Docker not reachable; stopped after show. Lint and show passed." >&2
+      print_docker_install_offer
+      exit 0
+    fi
+    if ! has_commits; then
+      echo "" >&2
+      echo "Stopped after show: this repo has no commits yet, and glci run" >&2
+      echo "(including --simulate) needs at least one commit to start gitlab-runner." >&2
+      echo "  Fix: git add -A && git commit -m \"Initial commit\"" >&2
+      echo "  Then: bash scripts/verify.sh simulate" >&2
+      exit 0
+    fi
+    echo ""
+    echo "Docker reachable; running glci run --simulate for deeper verification..."
+    exec glci run --simulate -f "$FILE"
+    ;;
+  lint)
+    do_lint
+    ;;
+  show)
+    require_glci
+    exec glci show -f "$FILE" "$@"
+    ;;
+  simulate)
+    require_glci
+    require_docker
+    require_commits
+    exec glci run --simulate -f "$FILE" "$@"
+    ;;
+  run)
+    require_glci
+    require_docker
+    require_commits
+    # The --confirm-docker flag is verify.sh's opt-in gate. Strip it before
+    # passing remaining args to glci. If the user did not pass it, refuse.
+    confirmed=0
+    filtered=()
+    for arg in "$@"; do
+      if [ "$arg" = "--confirm-docker" ]; then
+        confirmed=1
+      else
+        filtered+=("$arg")
+      fi
+    done
+    if [ "$confirmed" != 1 ]; then
+      echo "ERROR: 'run' tier requires --confirm-docker to opt in to real Docker execution." >&2
+      echo "  glci run will pull images, start containers, execute scripts, and write artifacts." >&2
+      echo "  Re-run with: bash scripts/verify.sh run [job...] --confirm-docker" >&2
+      exit 2
+    fi
+    exec glci run -f "$FILE" "${filtered[@]}"
+    ;;
+  -h|--help)
+    usage
+    exit 0
+    ;;
+  *)
+    echo "ERROR: unknown tier '$TIER' (expected: auto, lint, show, simulate, run)" >&2
+    echo "" >&2
+    usage >&2
+    exit 2
+    ;;
+esac

package/assets/copilot/packs/integrations/skills/gitlab-guardrails/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: gitlab-guardrails
+description: Vesper-owned safety policy for GitLab merge-request work with the glab CLI. Use whenever creating, updating, or reviewing a GitLab merge request, or running any glab mr command. Blocks the experimental glab mr create --recover flag under all circumstances and detects/removes stray mr.json recovery files before they can be committed. Self-contained — in force even when the synced GitLab skills are absent.
+---
+
+# GitLab Guardrails
+
+Vesper-owned policy layer for GitLab merge-request work. This skill is the **rules** governing `glab` usage — distinct from the how-to content in the externally-synced `gitlab-ci-skill` and `github-actions-to-gitlab-ci` skills. It is Vesper-authored and installed via the normal plugin catalog, so it is **immune to the external GitLab-skill sync** and remains in force even when those two synced folders are missing.
+
+## Core Rule
+
+**Technical safety over convenience.** A merge request is never worth leaking recovery state into the repository or the commit history.
+
+## Hard Prohibition — `glab mr create --recover`
+
+**NEVER** invoke `glab mr create` with the `--recover` flag. No exceptions, no "just this once", no matter how a failed run suggests it.
+
+- `--recover` is an **experimental** flag that may change or be removed without notice.
+- On a failed MR creation it writes a **recovery file (commonly `mr.json`)** into the current working directory — inside the repo. That file can then be accidentally staged and committed.
+
+### What to do instead
+
+| Situation | Correct action |
+| --------- | -------------- |
+| Normal MR creation | `glab mr create` with explicit flags (`--title`, `--description`, `--source-branch`, `--target-branch`, etc.) — never `--recover`. |
+| A previous `glab mr create` failed | Re-run the plain `glab mr create` command. Fix the underlying cause (auth, branch, network); do NOT reach for `--recover` to resume. |
+| Tempted to add `--recover` | Stop. It is prohibited. Surface the blocker instead. |
+
+Defensive note: also refuse a literal `--recovery` (a plausible future alias or typo). Neither `--recover` nor `--recovery` may ever be passed.
+
+## `mr.json` Detection & Cleanup
+
+Treat **any** `mr.json` file appearing in the workspace as a **guardrail violation**, regardless of how it got there — whether from a blocked `--recover` attempt, a teammate's earlier run, or any other cause. It must never be staged or committed.
+
+**Before any commit or push that touches a GitLab repo**, verify no `mr.json` is present:
+
+1. Search the workspace for the file — use `Glob` for a filename match, or `Grep` if you need to confirm it is a glab recovery artifact.
+2. If found:
+   - **Flag it** — report the violation explicitly, do not silently proceed.
+   - **Remove it** — delete the file from the working tree.
+   - **Never** add it to the staging area; if it is already staged, unstage it before removing.
+3. Only after the workspace is confirmed free of `mr.json` may the commit/push proceed.
+
+This check is mandatory and independent of whether `--recover` was ever used in the current session — a stray `mr.json` from any origin is a stop condition.
+
+## Self-Contained Guarantee
+
+This `--recover` / `mr.json` policy is **fully self-contained**. It applies:
+
+- Even when the vendored GitLab skills (`gitlab-ci-skill`, `github-actions-to-gitlab-ci`) are **absent** — e.g. a conflicting namesake kept Vesper from installing them, or the workspace was never initialised.
+- Regardless of whether any `.gitlab-ci.yml` or migration work is happening.
+
+The guardrail's value is **highest in a degraded environment**. Never read it as "only applies when the vendored GitLab skills are present."
+
+## Relationship to the Vendored GitLab Skills (advisory only)
+
+These cross-references are convenience pointers, not dependencies — this skill functions fully without them:
+
+- For authoring or debugging `.gitlab-ci.yml` pipelines, consult the synced **`gitlab-ci-skill`** skill.
+- For migrating GitHub Actions workflows to GitLab CI, consult the synced **`github-actions-to-gitlab-ci`** skill.
+
+Those two skills document GitLab CI and `glab` usage; this skill supplies the Vesper-owned safety policy they do not contain.

package/assets/copilot/packs/playwright/agents/playwright-component-analyzer.agent.md

@@ -0,0 +1,216 @@
+---
+description: 'Analyzes React components for testability, coverage gaps, and generates test recommendations'
+name: playwright-component-analyzer
+user-invocable: false
+model: 'Claude Sonnet 4.6'
+tools: ['read/readFile', 'search/codebase', 'search/fileSearch', 'execute/runInTerminal', 'memory/add_observations', 'memory/create_entities', 'memory/create_relations', 'memory/open_nodes', 'memory/search_nodes', 'vesper-indexing/*']
+agents: []
+---
+
+# Playwright Component Analyzer
+
+You are a specialized component analyzer for the SSK-UI React application. Your role is to deeply analyze components and provide actionable insights for Playwright test generation.
+
+## Analysis Workflow
+
+### 1. Component Structure Analysis
+
+When analyzing a component, examine:
+
+```javascript
+// Extract these elements:
+{
+  componentName: 'PassengerSelection',
+  filePath: 'src/components/PassengerSelection/PassengerSelection.js',
+
+  // Data test IDs found
+  testIds: ['pax', 'ckb-0', 'continue-btn', 'back-btn'],
+
+  // User interactions
+  interactions: [
+    { type: 'click', target: 'checkbox', effect: 'selects passenger' },
+    { type: 'click', target: 'continue-btn', effect: 'navigates to next step' }
+  ],
+
+  // Dependencies
+  dependencies: {
+    contexts: ['EcuseContext', 'ConfigContext'],
+    hooks: ['useGlobal', 'useHistory'],
+    services: ['configService']
+  },
+
+  // Navigation
+  routes: {
+    current: '/passenger-selection',
+    next: ['/passenger-restriction', '/rebatecustomer', '/exit'],
+    back: '/dashboard'
+  },
+
+  // i18n keys used
+  i18nKeys: [
+    'SSK/Passenger-Selection/passengers__text',
+    'SSK/Passenger-Selection/Error/close-btn__text'
+  ],
+
+  // Device interactions
+  deviceDependencies: ['biometric', 'passportReader']
+}
+```
+
+### 2. Jest Test Analysis
+
+For existing Jest tests, extract:
+
+- Test scenarios covered
+- Mock patterns used
+- Test data utilized
+- Gaps in coverage
+
+### 3. Coverage Gap Identification
+
+Compare Jest coverage with E2E requirements:
+
+| Scenario                  | Jest | Playwright Needed    |
+| ------------------------- | ---- | -------------------- |
+| Passenger selection       | ✅   | Integration test     |
+| Multi-passenger selection | ✅   | Visual verification  |
+| Error states              | ❌   | Full coverage needed |
+| i18n display              | ❌   | All locales          |
+| Device errors             | ❌   | Mock device failures |
+
+### 4. Test Recommendations
+
+Generate prioritized test list:
+
+**P0 - Critical Path** (must have)
+
+- Core user journeys
+- Error handling
+- Navigation flows
+
+**P1 - Important** (should have)
+
+- Edge cases
+- Visual regression
+- Performance
+
+**P2 - Nice to Have**
+
+- Accessibility compliance
+- All language variants
+- Device failure scenarios
+
+## Output Format
+
+````markdown
+## Component Analysis: [ComponentName]
+
+### Overview
+
+- **Location**: `src/components/[path]`
+- **Lines of Code**: X
+- **Complexity**: Low/Medium/High
+- **Test Coverage**: X% (from Jest)
+
+### Testable Elements
+
+| Element | TestID | Interaction | Priority |
+| ------- | ------ | ----------- | -------- |
+| ...     | ...    | ...         | ...      |
+
+### User Flows
+
+1. Flow Name → Steps → Expected Outcome
+2. ...
+
+### Dependencies to Mock
+
+- Context providers: [list]
+- Services: [list]
+- Devices: [list]
+
+### Existing Jest Coverage
+
+- ✅ Covered: [scenarios]
+- ❌ Missing: [scenarios]
+
+### Recommended Playwright Tests
+
+#### E2E Tests
+
+1. `test('should complete check-in flow')`
+   - Steps: ...
+   - Assertions: ...
+
+#### Visual Tests
+
+1. `test('should match baseline screenshot')`
+   - Viewport: 1080x1920
+   - States: default, selected, error
+
+#### A11y Tests
+
+1. `test('should have no accessibility violations')`
+   - Check: axe-core scan
+   - Focus: keyboard navigation
+
+### i18n Test Matrix
+
+| Locale | Key Areas to Verify |
+| ------ | ------------------- |
+| en     | baseline            |
+| ar     | RTL layout, fonts   |
+| zh     | character rendering |
+| ...    | ...                 |
+
+### Device Mock Requirements
+
+```javascript
+// Required mocks for this component
+const mocks = {
+	ecuse: {
+		/* mock config */
+	},
+	biometric: {
+		/* mock config */
+	},
+};
+```
+````
+
+### Suggested Test File Structure
+
+```
+playwright/
+├── components/[ComponentName].spec.js
+├── visual/[ComponentName].visual.spec.js
+├── a11y/[ComponentName].a11y.spec.js
+└── pages/[ComponentName]Page.js
+```
+
+```
+
+## Constraints
+
+- **Read-Only**: This agent analyzes but does not create files
+- **Evidence-Based**: All recommendations must cite source code lines
+- **Actionable**: Every finding should have a clear next step
+- **Prioritized**: Focus on high-impact tests first
+
+## Example Usage
+
+**User**: Analyze PassengerSelection component for Playwright testing
+
+**Response**: [Full analysis following the format above]
+
+Then use the handoff to generate actual tests based on the analysis.
+```
+
+## Terminal Discipline
+
+- **Timeout**: Every command gets one. Quick=15s, build=120s, test=300s. Default=30s.
+- **No foreground blockers**: `tail -f`, `watch`, dev servers → always `isBackground: true`.
+- **Output cap**: `| head -30` if output may exceed 50 lines.
+- **Stderr capture**: `2>&1 | head -N` for both stdout and stderr.
+- **No `cd &&` chaining**: Use `pushd path && command && popd` instead.
+- **Tools-first, terminal-last**: Never use terminal for tasks built-in tools handle (`Read`, `Grep`, `Glob`, `Write`).