winter-super-cli 2026.6.24 → 2026.6.27

package/resources/local/hermes-agent-core/skills/github/github-auth/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: github-auth
+description: "GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login."
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [GitHub, Authentication, Git, gh-cli, SSH, Setup]
+    related_skills: [github-pr-workflow, github-code-review, github-issues, github-repo-management]
+---
+
+# GitHub Authentication Setup
+
+This skill sets up authentication so the agent can work with GitHub repositories, PRs, issues, and CI. It covers two paths:
+
+- **`git` (always available)** — uses HTTPS personal access tokens or SSH keys
+- **`gh` CLI (if installed)** — richer GitHub API access with a simpler auth flow
+
+## Detection Flow
+
+When a user asks you to work with GitHub, run this check first:
+
+```bash
+# Check what's available
+git --version
+gh --version 2>/dev/null || echo "gh not installed"
+
+# Check if already authenticated
+gh auth status 2>/dev/null || echo "gh not authenticated"
+git config --global credential.helper 2>/dev/null || echo "no git credential helper"
+```
+
+**Decision tree:**
+1. If `gh auth status` shows authenticated → you're good, use `gh` for everything
+2. If `gh` is installed but not authenticated → use "gh auth" method below
+3. If `gh` is not installed → use "git-only" method below (no sudo needed)
+
+---
+
+## Method 1: Git-Only Authentication (No gh, No sudo)
+
+This works on any machine with `git` installed. No root access needed.
+
+### Option A: HTTPS with Personal Access Token (Recommended)
+
+This is the most portable method — works everywhere, no SSH config needed.
+
+**Step 1: Create a personal access token**
+
+Tell the user to go to: **https://github.com/settings/tokens**
+
+- Click "Generate new token (classic)"
+- Give it a name like "hermes-agent"
+- Select scopes:
+  - `repo` (full repository access — read, write, push, PRs)
+  - `workflow` (trigger and manage GitHub Actions)
+  - `read:org` (if working with organization repos)
+- Set expiration (90 days is a good default)
+- Copy the token — it won't be shown again
+
+**Step 2: Configure git to store the token**
+
+```bash
+# Set up the credential helper to cache credentials
+# "store" saves to ~/.git-credentials in plaintext (simple, persistent)
+git config --global credential.helper store
+
+# Now do a test operation that triggers auth — git will prompt for credentials
+# Username: <their-github-username>
+# Password: <paste the personal access token, NOT their GitHub password>
+git ls-remote https://github.com/<their-username>/<any-repo>.git
+```
+
+After entering credentials once, they're saved and reused for all future operations.
+
+**Alternative: cache helper (credentials expire from memory)**
+
+```bash
+# Cache in memory for 8 hours (28800 seconds) instead of saving to disk
+git config --global credential.helper 'cache --timeout=28800'
+```
+
+**Alternative: set the token directly in the remote URL (per-repo)**
+
+```bash
+# Embed token in the remote URL (avoids credential prompts entirely)
+git remote set-url origin https://<username>:<token>@github.com/<owner>/<repo>.git
+```
+
+**Step 3: Configure git identity**
+
+```bash
+# Required for commits — set name and email
+git config --global user.name "Their Name"
+git config --global user.email "their-email@example.com"
+```
+
+**Step 4: Verify**
+
+```bash
+# Test push access (this should work without any prompts now)
+git ls-remote https://github.com/<their-username>/<any-repo>.git
+
+# Verify identity
+git config --global user.name
+git config --global user.email
+```
+
+### Option B: SSH Key Authentication
+
+Good for users who prefer SSH or already have keys set up.
+
+**Step 1: Check for existing SSH keys**
+
+```bash
+ls -la ~/.ssh/id_*.pub 2>/dev/null || echo "No SSH keys found"
+```
+
+**Step 2: Generate a key if needed**
+
+```bash
+# Generate an ed25519 key (modern, secure, fast)
+ssh-keygen -t ed25519 -C "their-email@example.com" -f ~/.ssh/id_ed25519 -N ""
+
+# Display the public key for them to add to GitHub
+cat ~/.ssh/id_ed25519.pub
+```
+
+Tell the user to add the public key at: **https://github.com/settings/keys**
+- Click "New SSH key"
+- Paste the public key content
+- Give it a title like "hermes-agent-<machine-name>"
+
+**Step 3: Test the connection**
+
+```bash
+ssh -T git@github.com
+# Expected: "Hi <username>! You've successfully authenticated..."
+```
+
+**Step 4: Configure git to use SSH for GitHub**
+
+```bash
+# Rewrite HTTPS GitHub URLs to SSH automatically
+git config --global url."git@github.com:".insteadOf "https://github.com/"
+```
+
+**Step 5: Configure git identity**
+
+```bash
+git config --global user.name "Their Name"
+git config --global user.email "their-email@example.com"
+```
+
+---
+
+## Method 2: gh CLI Authentication
+
+If `gh` is installed, it handles both API access and git credentials in one step.
+
+### Interactive Browser Login (Desktop)
+
+```bash
+gh auth login
+# Select: GitHub.com
+# Select: HTTPS
+# Authenticate via browser
+```
+
+### Token-Based Login (Headless / SSH Servers)
+
+```bash
+echo "<THEIR_TOKEN>" | gh auth login --with-token
+
+# Set up git credentials through gh
+gh auth setup-git
+```
+
+### Verify
+
+```bash
+gh auth status
+```
+
+---
+
+## Using the GitHub API Without gh
+
+When `gh` is not available, you can still access the full GitHub API using `curl` with a personal access token. This is how the other GitHub skills implement their fallbacks.
+
+### Setting the Token for API Calls
+
+```bash
+# Option 1: Export as env var (preferred — keeps it out of commands)
+export GITHUB_TOKEN="<token>"
+
+# Then use in curl calls:
+curl -s -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/user
+```
+
+### Extracting the Token from Git Credentials
+
+If git credentials are already configured (via credential.helper store), the token can be extracted:
+
+```bash
+# Read from git credential store
+grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|'
+```
+
+### Helper: Detect Auth Method
+
+Use this pattern at the start of any GitHub workflow:
+
+```bash
+# Try gh first, fall back to git + curl
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  echo "AUTH_METHOD=gh"
+elif [ -n "$GITHUB_TOKEN" ]; then
+  echo "AUTH_METHOD=curl"
+elif [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+  export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+  echo "AUTH_METHOD=curl"
+elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+  export GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+  echo "AUTH_METHOD=curl"
+else
+  echo "AUTH_METHOD=none"
+  echo "Need to set up authentication first"
+fi
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `git push` asks for password | GitHub disabled password auth. Use a personal access token as the password, or switch to SSH |
+| `remote: Permission to X denied` | Token may lack `repo` scope — regenerate with correct scopes |
+| `fatal: Authentication failed` | Cached credentials may be stale — run `git credential reject` then re-authenticate |
+| `ssh: connect to host github.com port 22: Connection refused` | Try SSH over HTTPS port: add `Host github.com` with `Port 443` and `Hostname ssh.github.com` to `~/.ssh/config` |
+| Credentials not persisting | Check `git config --global credential.helper` — must be `store` or `cache` |
+| Multiple GitHub accounts | Use SSH with different keys per host alias in `~/.ssh/config`, or per-repo credential URLs |
+| `gh: command not found` + no sudo | Use git-only Method 1 above — no installation needed |

package/resources/local/hermes-agent-core/skills/github/github-auth/scripts/gh-env.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# GitHub environment detection helper for Hermes Agent skills.
+#
+# Usage (via terminal tool):
+#   source skills/github/github-auth/scripts/gh-env.sh
+#
+# After sourcing, these variables are set:
+#   GH_AUTH_METHOD  - "gh", "curl", or "none"
+#   GITHUB_TOKEN    - personal access token (set if method is "curl")
+#   GH_USER         - GitHub username
+#   GH_OWNER        - repo owner  (only if inside a git repo with a github remote)
+#   GH_REPO         - repo name   (only if inside a git repo with a github remote)
+#   GH_OWNER_REPO   - owner/repo  (only if inside a git repo with a github remote)
+
+# --- Auth detection ---
+
+GH_AUTH_METHOD="none"
+GITHUB_TOKEN="${GITHUB_TOKEN:-}"
+GH_USER=""
+
+if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
+    GH_AUTH_METHOD="gh"
+    GH_USER=$(gh api user --jq '.login' 2>/dev/null)
+elif [ -n "$GITHUB_TOKEN" ]; then
+    GH_AUTH_METHOD="curl"
+elif [ -f "$HOME/.hermes/.env" ] && grep -q "^GITHUB_TOKEN=" "$HOME/.hermes/.env" 2>/dev/null; then
+    GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$HOME/.hermes/.env" | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if [ -n "$GITHUB_TOKEN" ]; then
+        GH_AUTH_METHOD="curl"
+    fi
+elif [ -f "$HOME/.git-credentials" ] && grep -q "github.com" "$HOME/.git-credentials" 2>/dev/null; then
+    GITHUB_TOKEN=$(grep "github.com" "$HOME/.git-credentials" | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
+    if [ -n "$GITHUB_TOKEN" ]; then
+        GH_AUTH_METHOD="curl"
+    fi
+fi
+
+# Resolve username for curl method
+if [ "$GH_AUTH_METHOD" = "curl" ] && [ -z "$GH_USER" ]; then
+    GH_USER=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
+        https://api.github.com/user 2>/dev/null \
+        | python3 -c "import sys,json; print(json.load(sys.stdin).get('login',''))" 2>/dev/null)
+fi
+
+# --- Repo detection (if inside a git repo with a GitHub remote) ---
+
+GH_OWNER=""
+GH_REPO=""
+GH_OWNER_REPO=""
+
+_remote_url=$(git remote get-url origin 2>/dev/null)
+if [ -n "$_remote_url" ] && echo "$_remote_url" | grep -q "github.com"; then
+    GH_OWNER_REPO=$(echo "$_remote_url" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+    GH_OWNER=$(echo "$GH_OWNER_REPO" | cut -d/ -f1)
+    GH_REPO=$(echo "$GH_OWNER_REPO" | cut -d/ -f2)
+fi
+unset _remote_url
+
+# --- Summary ---
+
+echo "GitHub Auth: $GH_AUTH_METHOD"
+[ -n "$GH_USER" ]       && echo "User: $GH_USER"
+[ -n "$GH_OWNER_REPO" ] && echo "Repo: $GH_OWNER_REPO"
+[ "$GH_AUTH_METHOD" = "none" ] && echo "⚠ Not authenticated — see github-auth skill"
+
+export GH_AUTH_METHOD GITHUB_TOKEN GH_USER GH_OWNER GH_REPO GH_OWNER_REPO