@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/github-actions/references/oidc-deploys.md

@@ -0,0 +1,130 @@
+# OIDC cloud deploys (AWS / GCP / Azure)
+
+The goal: a deploy job assumes a cloud identity with **no stored long-lived keys**. GitHub mints a short-lived OIDC JWT for the run; the cloud provider validates it against a trust you configured and hands back a token scoped to that job for minutes. The job needs `permissions: id-token: write`.
+
+The recurring footgun across all three clouds is an **over-permissioned trust**: scoping it to `repo:ORG/*` (any repo in the org) instead of one repo + ref. Always pin the `sub` claim down to repo + ref, and for prod down to environment.
+
+## The OIDC `sub` claim — scope it tight
+
+GitHub puts the run's identity in the JWT `sub`. The cloud trust matches on it. Pick the narrowest that still works:
+
+| `sub` value | Grants to | Use for |
+| --- | --- | --- |
+| `repo:ORG/REPO:ref:refs/heads/main` | only `main` of one repo | branch deploys |
+| `repo:ORG/REPO:ref:refs/tags/v*` | tag pushes of one repo | release deploys |
+| `repo:ORG/REPO:environment:production` | the `production` environment of one repo | gated prod deploys (preferred) |
+| `repo:ORG/*` | **any repo in the org** | almost never — this is the footgun |
+
+Scoping to `environment:production` is strongest: the deploy only works from a job that names that environment, and the environment carries the required-reviewer gate.
+
+## AWS — IAM role + `configure-aws-credentials`
+
+One-time setup: create an IAM OIDC identity provider for `token.actions.githubusercontent.com`, then a role whose trust policy matches the `sub`.
+
+```json
+{
+  "Effect": "Allow",
+  "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
+  "Action": "sts:AssumeRoleWithWebIdentity",
+  "Condition": {
+    "StringEquals": {
+      "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
+      "token.actions.githubusercontent.com:sub": "repo:ORG/REPO:environment:production"
+    }
+  }
+}
+```
+
+In the workflow:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+steps:
+  - uses: aws-actions/configure-aws-credentials@<full-40-char-sha>  # pin it
+    with:
+      role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
+      aws-region: eu-west-1
+```
+
+## GCP — Workload Identity Federation
+
+Create a Workload Identity Pool + provider mapping `assertion.sub` to a principal, bind it to a service account.
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+steps:
+  - uses: google-github-actions/auth@<full-40-char-sha>
+    with:
+      workload_identity_provider: projects/123/locations/global/workloadIdentityPools/gh/providers/gh
+      service_account: gh-deploy@my-project.iam.gserviceaccount.com
+```
+
+Add an attribute condition on the provider so only your repo + ref can mint a token:
+`assertion.sub == 'repo:ORG/REPO:ref:refs/heads/main'`.
+
+## Azure — federated credentials
+
+On the app registration, add a federated credential with issuer `https://token.actions.githubusercontent.com`, subject `repo:ORG/REPO:environment:production`, audience `api://AzureADTokenExchange`.
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+steps:
+  - uses: azure/login@<full-40-char-sha>
+    with:
+      client-id: ${{ vars.AZURE_CLIENT_ID }}
+      tenant-id: ${{ vars.AZURE_TENANT_ID }}
+      subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+```
+
+`client-id`/`tenant-id`/`subscription-id` are identifiers, not secrets — keep them in `vars`, not `secrets`.
+
+## Full deploy-on-tag workflow with environment approval
+
+```yaml
+name: Release
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-production
+  cancel-in-progress: false      # never interrupt a release
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with: { node-version: 24, cache: npm }
+      - run: npm ci && npm run build
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: production        # required-reviewer gate; pauses here for approval
+    permissions:
+      id-token: write              # OIDC; no static keys
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: aws-actions/configure-aws-credentials@<full-40-char-sha>
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
+          aws-region: eu-west-1
+      - run: aws s3 sync dist/ s3://my-bucket --delete
+```
+
+The `environment: production` line is what makes GitHub pause for a reviewer before the deploy job starts — configure the required reviewers on the environment in repo settings, not in YAML.

package/skills/shared/github-actions/scripts/verify.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# verify.sh — static lint for GitHub Actions workflows.
+# Read-only. No network, no install, no run. Heuristic and advisory.
+#
+# Checks .github/workflows/*.{yml,yaml} in the target dir:
+#   ERROR (exit 1): pull_request_target together with a checkout of the PR head
+#                   (runs untrusted fork code with full secrets).
+#   WARN: third-party uses: (not actions/* or github/*) not pinned to a 40-hex SHA.
+#   WARN: a workflow with no permissions: block (default token may be write).
+#   WARN: a step using secrets.AWS_/GCP_/AZURE_ creds while the file lacks id-token: write (OIDC nudge).
+# Runs `actionlint` if it is on PATH and surfaces its output.
+#
+# Exits non-zero ONLY on ERROR, so it works as a CI gate.
+# Exits 0 on a clean/empty target (no .github/workflows -> nothing to check).
+#
+# Usage: scripts/verify.sh [dir]   (defaults to current directory)
+set -euo pipefail
+
+DIR="${1:-.}"
+ERRORS=0
+WARN=0
+
+if [ ! -d "$DIR" ]; then
+  echo "verify.sh: '$DIR' is not a directory" >&2
+  exit 2
+fi
+
+err()  { echo "ERROR: $*"; ERRORS=$((ERRORS + 1)); }
+warn() { echo "WARN:  $*"; WARN=$((WARN + 1)); }
+
+WF_DIR="$DIR/.github/workflows"
+if [ ! -d "$WF_DIR" ]; then
+  echo "verify.sh: no .github/workflows under '$DIR' — skill not applied yet, nothing to check."
+  exit 0
+fi
+
+# bash 3.2 (macOS) friendly: newline-delimited list, no mapfile.
+FILES="$(
+  find "$WF_DIR" -maxdepth 1 -type f \( -name '*.yml' -o -name '*.yaml' \) 2>/dev/null
+)"
+
+if [ -z "$FILES" ]; then
+  echo "verify.sh: .github/workflows has no .yml/.yaml files — nothing to check."
+  exit 0
+fi
+
+# Optional: actionlint if available (advisory; its exit code does not gate us).
+if command -v actionlint >/dev/null 2>&1; then
+  echo "verify.sh: running actionlint..."
+  actionlint "$WF_DIR"/*.yml "$WF_DIR"/*.yaml 2>/dev/null || \
+    warn "actionlint reported issues (see above)."
+else
+  echo "verify.sh: actionlint not on PATH — running built-in checks only."
+fi
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+
+  # --- ERROR: pull_request_target + checkout of the PR head ---
+  if grep -Eq 'pull_request_target' "$f"; then
+    if grep -Eq 'github\.event\.pull_request\.head|head\.sha|head\.ref' "$f"; then
+      err "$f uses pull_request_target AND checks out the PR head — runs untrusted code with secrets (RCE). Use pull_request, or never check out head.* here."
+    fi
+  fi
+
+  # --- WARN: no permissions: block at all ---
+  if ! grep -Eq '^[[:space:]]*permissions[[:space:]]*:' "$f"; then
+    warn "$f has no permissions: block — the default GITHUB_TOKEN may be write. Set 'permissions: contents: read' and widen per job."
+  fi
+
+  # --- WARN: third-party uses: not pinned to a 40-hex SHA ---
+  # Lines like:  - uses: owner/repo@ref   (ignore ./local and docker:// forms)
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    ref="${line#*@}"                       # everything after the first @
+    owner="${line%%/*}"                    # owner segment of the action path
+    owner="${owner##*uses:}"
+    owner="$(echo "$owner" | tr -d ' ')"
+    # skip first-party actions/* and github/*
+    case "$owner" in
+      actions|github) continue ;;
+    esac
+    # accept exactly 40 hex chars (optionally followed by whitespace/comment)
+    if ! echo "$ref" | grep -Eq '^[0-9a-fA-F]{40}([[:space:]]|#|$)'; then
+      short="$(echo "$line" | sed -E 's/^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*//' | cut -c1-60)"
+      warn "$f: third-party action not SHA-pinned: $short — pin to a full 40-char commit SHA (tags are mutable; cf. tj-actions 2025)."
+    fi
+  done <<EOF
+$(grep -E '^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*[^./][^@]+@[^[:space:]]+' "$f" | grep -vE 'uses:[[:space:]]*\./|docker://' || true)
+EOF
+
+  # --- WARN: cloud secrets used but no id-token: write (OIDC nudge) ---
+  if grep -Eq 'secrets\.(AWS|GCP|GOOGLE|AZURE)[A-Z_]*' "$f"; then
+    if ! grep -Eq 'id-token[[:space:]]*:[[:space:]]*write' "$f"; then
+      warn "$f references cloud secrets (AWS/GCP/AZURE) but sets no 'id-token: write' — prefer OIDC over long-lived keys."
+    fi
+  fi
+done <<EOF
+$FILES
+EOF
+
+echo
+echo "verify.sh: $ERRORS error(s), $WARN warning(s)."
+[ "$ERRORS" -gt 0 ] && exit 1
+exit 0

package/skills/shared/gitlab-auth/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: gitlab-auth
+description: "GitLab self-managed (gitlab.v3.onnadigital.com) authentication for agents: PAT from .ai-hub/.env, smoke test, security rules, Playwright fallback for UI-only flows."
+license: MIT
+compatibility: Requires curl or Node and a GitLab personal access token with the "api" scope.
+metadata:
+  author: ai-hub
+  version: "1.0"
+origin: ai-hub
+---
+
+# GitLab Auth — self-managed con Personal Access Token
+
+## Cuándo usar esta skill
+
+- Antes de cualquier operación de GitLab (issues, MRs, pipelines): cargar el entorno y verificar identidad.
+- Para diagnosticar 401/403 y para rotar tokens.
+- El día a día de operaciones vive en `gitlab-workflow`.
+
+## Contrato de credenciales
+
+Ruta: `.ai-hub/.env` (local; NUNCA versionado — patrón `*.env` del `.gitignore`).
+Plantilla: `.ai-hub/.env.example`.
+
+| Variable | Obligatoria | Uso |
+|---|---|---|
+| `GITLAB_URL` | sí | Base sin `/api` (por defecto `https://gitlab.v3.onnadigital.com`) |
+| `GITLAB_TOKEN` | sí | PAT con scope `api` |
+| `GITLAB_PROJECT_PATH` | sí (workflow) | Path URL-encoded del proyecto (por ejemplo, `group%2Fproject`) |
+| `GITLAB_USER` | no | Solo fallback UI (Playwright) |
+| `GITLAB_PASSWORD` | no | Solo fallback UI (Playwright) |
+
+Crear el PAT: GitLab → avatar → Edit profile → Access Tokens
+(`https://gitlab.v3.onnadigital.com/-/user_settings/personal_access_tokens`),
+nombre `ai-hub-agent`, expiración 90-180 días, scope `api`. El valor `glpat-...`
+se muestra UNA sola vez.
+
+## Cargar el entorno
+
+bash / git-bash:
+
+```
+source .ai-hub/bootstrap/load-env.sh
+```
+
+PowerShell:
+
+```
+Get-Content .ai-hub/.env | ForEach-Object {
+  if ($_ -match '^\s*([A-Z_]+)\s*=\s*(.*)\s*$') {
+    [Environment]::SetEnvironmentVariable($matches[1], $matches[2].Trim('"'), 'Process')
+  }
+}
+```
+
+## Prueba de humo (obligatoria antes de operar)
+
+bash:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "$GITLAB_URL/api/v4/user"
+```
+
+PowerShell:
+
+```
+curl.exe -s -H "PRIVATE-TOKEN: $env:GITLAB_TOKEN" "$env:GITLAB_URL/api/v4/user"
+```
+
+- 200 → JSON con `id`, `username`, `name`: token válido.
+- 401 → token inválido, revocado o caducado: reponer uno nuevo.
+- 403 → falta scope `api` (o el usuario no tiene permiso en el recurso).
+
+## Reglas de seguridad (duras)
+
+1. NUNCA imprimir, loggear, citar ni pegar el token en chats, prompts, informes o `.md`.
+2. NUNCA escribirlo en archivos versionados; su único sitio es `.ai-hub/.env`.
+3. No usar `curl -v` ni `--trace` con cabeceras de autenticación (filtran el header).
+4. Ante un error, reportar «token inválido o caducado» sin incluir su valor.
+5. Rotación: revocar en Access Tokens y sustituirlo en `.env`; repetir la prueba de humo.
+
+## Fallback de navegador (Playwright) — solo flujos UI-only
+
+Solo cuando la operación no exista en la API (ajustes de UI o formularios sin endpoint).
+
+1. Verificar `GITLAB_USER` y `GITLAB_PASSWORD` en el entorno; si faltan, pedirlos al usuario.
+2. Abrir `https://gitlab.v3.onnadigital.com/users/sign_in`, rellenar y enviar.
+3. Nunca escribir la contraseña en logs ni capturas con el campo visible.
+4. Si hay 2FA/passkey, pedir al usuario que complete el login manualmente.
+
+## Troubleshooting
+
+| Síntoma | Causa probable | Acción |
+|---|---|---|
+| 401 en API | Token inválido o caducado | Reponer PAT y actualizar `.env` |
+| 403 en API | Scope insuficiente | PAT con scope `api` |
+| 404 en proyecto | Path mal codificado | Codificar el path en `GITLAB_PROJECT_PATH` (por ejemplo, `group%2Fproject`) |
+| Error SSL | Certificado interno | Pedir al usuario el certificado raíz |
+| `glab` ausente | No instalado | Usar curl/Node (no requiere glab) |

package/skills/shared/gitlab-workflow/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: gitlab-workflow
+description: "Daily GitLab operations for the self-managed instance via REST API v4: my assigned issues, issue detail and comments, labels and state, merge requests and pipelines."
+license: MIT
+compatibility: Requires gitlab-auth (GITLAB_URL/GITLAB_TOKEN/GITLAB_PROJECT_PATH in environment) and curl or Node.
+metadata:
+  author: ai-hub
+  version: "1.0"
+origin: ai-hub
+---
+
+# GitLab Workflow — operación diaria contra la API v4
+
+## Prerrequisito
+
+`gitlab-auth`: entorno cargado y prueba de humo (`GET /api/v4/user`) en verde.
+
+Constantes:
+
+- `BASE = {GITLAB_URL}/api/v4`
+- Header: `PRIVATE-TOKEN: {GITLAB_TOKEN}`
+- Proyecto: `$GITLAB_PROJECT_PATH` (path URL-encoded, por ejemplo `group%2Fproject`)
+
+## Reglas
+
+- Lecturas primero. Operaciones de escritura (comentar, etiquetar, cerrar) solo cuando el usuario lo pida, con SU texto y SUS valores.
+- Nada destructivo sin confirmación explícita (cerrar/reabrir, borrar, force).
+- Paginar con `per_page` (máx 100) y `page`; no asumir que la primera página lo tiene todo.
+- Parsear JSON con python3 o Node; nunca `grep` frágil sobre la respuesta.
+- Nunca incluir el token en URLs, logs ni mensajes de error.
+
+## Recetas (bash / git-bash)
+
+Mis issues asignadas:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_URL/api/v4/issues?scope=assigned_to_me&state=opened&per_page=50"
+```
+
+Issues abiertas del proyecto:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/issues?state=opened&per_page=100"
+```
+
+Detalle de una issue:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/issues/<iid>"
+```
+
+Comentarios (notas) de una issue:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/issues/<iid>/notes?sort=asc&per_page=100"
+```
+
+Comentar una issue (cuerpo aprobado por el usuario):
+
+```
+curl -s -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --data-urlencode "body=<texto>" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/issues/<iid>/notes"
+```
+
+Etiquetas y estado:
+
+```
+curl -s -X PUT -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --data-urlencode "labels=En curso" \
+  --data-urlencode "state_event=close" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/issues/<iid>"
+```
+
+(`state_event` admite `close` o `reopen`; omitirlo si solo se cambian etiquetas.)
+
+Merge requests asignadas:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_URL/api/v4/merge_requests?scope=assigned_to_me&state=opened&per_page=50"
+```
+
+MR de una rama:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/merge_requests?source_branch=<rama>&state=opened"
+```
+
+Pipelines del proyecto:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/pipelines?per_page=10"
+```
+
+Jobs de un pipeline:
+
+```
+curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/pipelines/<id>/jobs"
+```
+
+Crear MR (solo con confirmación; sin merges automáticos):
+
+```
+curl -s -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  --data-urlencode "source_branch=<rama>" \
+  --data-urlencode "target_branch=main" \
+  --data-urlencode "title=<titulo aprobado>" \
+  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_PATH/merge_requests"
+```
+
+## Variante PowerShell
+
+```
+$h = @{ "PRIVATE-TOKEN" = $env:GITLAB_TOKEN }
+Invoke-RestMethod -Headers $h -Uri "$env:GITLAB_URL/api/v4/issues?scope=assigned_to_me&state=opened"
+```
+
+Para POST con cuerpo:
+
+```
+Invoke-RestMethod -Method Post -Headers $h -Body @{ body = "<texto>" } `
+  -Uri "$env:GITLAB_URL/api/v4/projects/$env:GITLAB_PROJECT_PATH/issues/<iid>/notes"
+```
+
+## Presentación al usuario
+
+- Issues: proyecto, `#iid`, título, etiquetas, assignee y URL web.
+- Notas: fecha, autor y primeras líneas; enlazar a la issue.
+- MRs: título, rama origen → destino, estado y URL.
+- Pipelines: estado, ref, duración y URL.