@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/prismer-github/references/repo-management.md

@@ -0,0 +1,484 @@
+# GitHub Repository Management
+
+> Prismer scope: read auth.md first. All mutations below are examples for an
+> explicitly authorized target/action, never an automatic checklist. Preserve the
+> current dirty tree and long-lived branch; resolve the actual base branch and
+> do not switch, commit, push, publish, merge, delete branches or send reviews
+> unless requested. Use structured JSON for dynamic payloads, not shell string
+> interpolation. Public visibility requires explicit intent. Collection reads
+> must use scripts/github-api.py (complete Link pagination) or gh api --paginate;
+> porcelain list limits and single-page curl output are not a complete inventory.
+> Run shell pipelines with pipefail, record each exit status, and read back writes.
+
+Create, clone, fork, configure, and manage GitHub repositories. Each section shows `gh` first, then the `git` + `curl` fallback.
+
+## Prerequisites
+
+Repository creation defaults below are private. Public publication needs explicit
+intent. A secret gist is unlisted, not access-controlled; never put secrets in it.
+
+- Authenticated with GitHub (see `auth.md` reference)
+
+### Setup
+
+```bash
+# Resolve SKILL_ROOT from the installed prismer-github entry, not cwd.
+source "$SKILL_ROOT/scripts/gh-env.sh"
+AUTH="$GH_AUTH_METHOD"
+OWNER="$GH_OWNER"
+REPO="$GH_REPO"
+OWNER_REPO="$GH_OWNER_REPO"
+# token-unverified needs a successful API identity check before remote work.
+```
+
+If you're inside a repo already:
+
+```bash
+source "$SKILL_ROOT/scripts/gh-env.sh"
+OWNER="$GH_OWNER"; REPO="$GH_REPO"
+```
+
+---
+
+## 1. Cloning Repositories
+
+Cloning is pure `git` — works identically either way:
+
+```bash
+# Clone via HTTPS (works with credential helper or token-embedded URL)
+git clone https://github.com/owner/repo-name.git
+
+# Clone into a specific directory
+git clone https://github.com/owner/repo-name.git ./my-local-dir
+
+# Shallow clone (faster for large repos)
+git clone --depth 1 https://github.com/owner/repo-name.git
+
+# Clone a specific branch
+git clone --branch develop https://github.com/owner/repo-name.git
+
+# Clone via SSH (if SSH is configured)
+git clone git@github.com:owner/repo-name.git
+```
+
+**With gh (shorthand):**
+
+```bash
+gh repo clone owner/repo-name
+gh repo clone owner/repo-name -- --depth 1
+```
+
+## 2. Creating Repositories
+
+**With gh:**
+
+```bash
+# Create a public repo and clone it
+gh repo create my-new-project --private --clone
+
+# Private, with description and license
+gh repo create my-new-project --private --description "A useful tool" --license MIT --clone
+
+# Under an organization
+gh repo create my-org/my-new-project --private --clone
+
+# From existing local directory
+cd /path/to/existing/project
+gh repo create my-project --source . --private --push
+```
+
+**With git + curl:**
+
+```bash
+# Create the remote repo via API
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/user/repos \
+  -d '{
+    "name": "my-new-project",
+    "description": "A useful tool",
+    "private": true,
+    "auto_init": true,
+    "license_template": "mit"
+  }'
+
+# Clone it
+git clone https://github.com/$GH_USER/my-new-project.git
+cd my-new-project
+
+# -- OR -- push an existing local directory to the new repo
+cd /path/to/existing/project
+git init
+git add -- <explicit-task-owned-files>
+git commit -m "Initial commit"
+git remote add origin https://github.com/$GH_USER/my-new-project.git
+git push -u origin main
+```
+
+To create under an organization:
+
+```bash
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/orgs/my-org/repos \
+  -d '{"name": "my-new-project", "private": true}'
+```
+
+### From a Template
+
+**With gh:**
+
+```bash
+gh repo create my-new-app --template owner/template-repo --private --clone
+```
+
+**With curl:**
+
+```bash
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/owner/template-repo/generate \
+  -d '{"owner": "'"$GH_USER"'", "name": "my-new-app", "private": true}'
+```
+
+## 3. Forking Repositories
+
+**With gh:**
+
+```bash
+gh repo fork owner/repo-name --clone
+```
+
+**With git + curl:**
+
+```bash
+# Create the fork via API
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/owner/repo-name/forks
+
+# Wait a moment for GitHub to create it, then clone
+sleep 3
+git clone https://github.com/$GH_USER/repo-name.git
+cd repo-name
+
+# Add the original repo as "upstream" remote
+git remote add upstream https://github.com/owner/repo-name.git
+```
+
+### Keeping a Fork in Sync
+
+```bash
+# Pure git — works everywhere
+git fetch upstream
+# Return to the recorded original branch only when the worktree permits; do not auto-switch.
+git merge upstream/main
+git push origin main
+```
+
+**With gh (shortcut):**
+
+```bash
+gh repo sync $GH_USER/repo-name
+```
+
+## 4. Repository Information
+
+**With gh:**
+
+```bash
+gh repo view owner/repo-name
+gh repo list --limit 20
+gh search repos "machine learning" --language python --sort stars
+```
+
+**With curl:**
+
+```bash
+# View repo details
+python3 "$SKILL_ROOT/scripts/github-api.py" https://api.github.com/repos/$OWNER/$REPO \
+  | python -c "
+import sys, json
+r = json.load(sys.stdin)
+print(f\"Name: {r['full_name']}\")
+print(f\"Description: {r['description']}\")
+print(f\"Stars: {r['stargazers_count']}  Forks: {r['forks_count']}\")
+print(f\"Default branch: {r['default_branch']}\")
+print(f\"Language: {r['language']}\")"
+
+# List your repos
+python3 "$SKILL_ROOT/scripts/github-api.py" "https://api.github.com/user/repos?per_page=20&sort=updated" \
+  | python -c "
+import sys, json
+for r in json.load(sys.stdin):
+    vis = 'private' if r['private'] else 'public'
+    print(f\"  {r['full_name']:40}  {vis:8}  {r.get('language', ''):10}  ★{r['stargazers_count']}\")"
+
+# Search repos
+curl --fail-with-body -sS --max-time 30 \
+  "https://api.github.com/search/repositories?q=machine+learning+language:python&sort=stars&per_page=10" \
+  | python -c "
+import sys, json
+for r in json.load(sys.stdin)['items']:
+    print(f\"  {r['full_name']:40}  ★{r['stargazers_count']:6}  {r['description'][:60] if r['description'] else ''}\")"
+```
+
+## 5. Repository Settings
+
+**With gh:**
+
+```bash
+gh repo edit --description "Updated description" --visibility public
+gh repo edit --enable-wiki=false --enable-issues=true
+gh repo edit --default-branch main
+gh repo edit --add-topic "machine-learning,python"
+gh repo edit --enable-auto-merge
+```
+
+**With curl:**
+
+```bash
+curl --fail-with-body -sS --max-time 30 -X PATCH \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO \
+  -d '{
+    "description": "Updated description",
+    "has_wiki": false,
+    "has_issues": true,
+    "allow_auto_merge": true
+  }'
+
+# Update topics
+curl --fail-with-body -sS --max-time 30 -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github.mercy-preview+json" \
+  https://api.github.com/repos/$OWNER/$REPO/topics \
+  -d '{"names": ["machine-learning", "python", "automation"]}'
+```
+
+## 6. Branch Protection
+
+```bash
+# View current protection
+python3 "$SKILL_ROOT/scripts/github-api.py" https://api.github.com/repos/$OWNER/$REPO/branches/main/protection
+
+# Set up branch protection
+curl --fail-with-body -sS --max-time 30 -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/branches/main/protection \
+  -d '{
+    "required_status_checks": {
+      "strict": true,
+      "contexts": ["ci/test", "ci/lint"]
+    },
+    "enforce_admins": false,
+    "required_pull_request_reviews": {
+      "required_approving_review_count": 1
+    },
+    "restrictions": null
+  }'
+```
+
+## 7. Secrets Management (GitHub Actions)
+
+**With gh:**
+
+```bash
+gh secret set API_KEY --body "your-secret-value"
+gh secret set SSH_KEY < ~/.ssh/id_rsa
+gh secret list
+gh secret delete API_KEY
+```
+
+**With curl:**
+
+Secrets require encryption with the repo's public key — more involved via API:
+
+```bash
+# Get the repo's public key for encrypting secrets
+python3 "$SKILL_ROOT/scripts/github-api.py" https://api.github.com/repos/$OWNER/$REPO/actions/secrets/public-key
+
+# Encrypt and set (requires Python with PyNaCl)
+python -c "
+from base64 import b64encode
+from nacl import encoding, public
+import json, sys
+
+# Get the public key
+key_id = '<key_id_from_above>'
+public_key = '<base64_key_from_above>'
+
+# Encrypt
+sealed = public.SealedBox(
+    public.PublicKey(public_key.encode('utf-8'), encoding.Base64Encoder)
+).encrypt('your-secret-value'.encode('utf-8'))
+print(json.dumps({
+    'encrypted_value': b64encode(sealed).decode('utf-8'),
+    'key_id': key_id
+}))"
+
+# Then PUT the encrypted secret
+curl --fail-with-body -sS --max-time 30 -X PUT \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/secrets/API_KEY \
+  -d '<output from python script above>'
+
+# List secrets (names only, values hidden)
+python3 "$SKILL_ROOT/scripts/github-api.py" https://api.github.com/repos/$OWNER/$REPO/actions/secrets \
+  | python -c "
+import sys, json
+for s in json.load(sys.stdin)['secrets']:
+    print(f\"  {s['name']:30}  updated: {s['updated_at']}\")"
+```
+
+Note: For secrets, `gh secret set` is dramatically simpler. If setting secrets is needed and `gh` isn't available, recommend installing it for just that operation.
+
+## 8. Releases
+
+**With gh:**
+
+```bash
+gh release create v1.0.0 --title "v1.0.0" --generate-notes
+gh release create v2.0.0-rc1 --draft --prerelease --generate-notes
+gh release create v1.0.0 ./dist/binary --title "v1.0.0" --notes "Release notes"
+gh release list
+gh release download v1.0.0 --dir ./downloads
+```
+
+**With curl:**
+
+```bash
+# Create a release
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/releases \
+  -d '{
+    "tag_name": "v1.0.0",
+    "name": "v1.0.0",
+    "body": "## Changelog\n- Feature A\n- Bug fix B",
+    "draft": false,
+    "prerelease": false,
+    "generate_release_notes": true
+  }'
+
+# List releases
+python3 "$SKILL_ROOT/scripts/github-api.py" https://api.github.com/repos/$OWNER/$REPO/releases \
+  | python -c "
+import sys, json
+for r in json.load(sys.stdin):
+    tag = r.get('tag_name', 'no tag')
+    print(f\"  {tag:15}  {r['name']:30}  {'draft' if r['draft'] else 'published'}\")"
+
+# Upload a release asset (binary file)
+RELEASE_ID=<id_from_create_response>
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Content-Type: application/octet-stream" \
+  "https://uploads.github.com/repos/$OWNER/$REPO/releases/$RELEASE_ID/assets?name=binary-amd64" \
+  --data-binary @./dist/binary-amd64
+```
+
+## 9. GitHub Actions Workflows
+
+**With gh:**
+
+```bash
+gh workflow list
+gh run list --limit 10
+gh run view <RUN_ID>
+gh run view <RUN_ID> --log-failed
+gh run rerun <RUN_ID>
+gh run rerun <RUN_ID> --failed
+gh workflow run ci.yml --ref main
+gh workflow run deploy.yml -f environment=staging
+```
+
+**With curl:**
+
+```bash
+# List workflows
+python3 "$SKILL_ROOT/scripts/github-api.py" https://api.github.com/repos/$OWNER/$REPO/actions/workflows \
+  | python -c "
+import sys, json
+for w in json.load(sys.stdin)['workflows']:
+    print(f\"  {w['id']:10}  {w['name']:30}  {w['state']}\")"
+
+# List recent runs
+python3 "$SKILL_ROOT/scripts/github-api.py" "https://api.github.com/repos/$OWNER/$REPO/actions/runs?per_page=10" \
+  | python -c "
+import sys, json
+for r in json.load(sys.stdin)['workflow_runs']:
+    print(f\"  Run {r['id']}  {r['name']:30}  {r['conclusion'] or r['status']}\")"
+
+# Download failed run logs
+RUN_ID=<run_id>
+curl --fail-with-body -sS --max-time 30 -L \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/logs \
+  -o ~/.hermes/cache/scratch/ci-logs.zip
+cd ~/.hermes/cache/scratch && unzip -o ci-logs.zip -d ci-logs
+
+# Re-run a failed workflow
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/rerun
+
+# Re-run only failed jobs
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/rerun-failed-jobs
+
+# Trigger a workflow manually (workflow_dispatch)
+WORKFLOW_ID=<workflow_id_or_filename>
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/repos/$OWNER/$REPO/actions/workflows/$WORKFLOW_ID/dispatches \
+  -d '{"ref": "main", "inputs": {"environment": "staging"}}'
+```
+
+## 10. Gists
+
+**With gh:**
+
+```bash
+gh gist create script.py --desc "Useful script"
+gh gist list
+```
+
+**With curl:**
+
+```bash
+# Create a gist
+curl --fail-with-body -sS --max-time 30 -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/gists \
+  -d '{
+    "description": "Useful script",
+    "public": false,
+    "files": {
+      "script.py": {"content": "print(\"hello\")"}
+    }
+  }'
+
+# List your gists
+python3 "$SKILL_ROOT/scripts/github-api.py" https://api.github.com/gists \
+  | python -c "
+import sys, json
+for g in json.load(sys.stdin):
+    files = ', '.join(g['files'].keys())
+    print(f\"  {g['id']}  {g['description'] or '(no desc)':40}  {files}\")"
+```
+
+## Quick Reference Table
+
+| Action | gh | git + curl |
+|--------|-----|-----------|
+| Clone | `gh repo clone o/r` | `git clone https://github.com/o/r.git` |
+| Create repo | `gh repo create name --private` | `curl POST /user/repos` |
+| Fork | `gh repo fork o/r --clone` | `curl POST /repos/o/r/forks` + `git clone` |
+| Repo info | `gh repo view o/r` | `curl GET /repos/o/r` |
+| Edit settings | `gh repo edit --...` | `curl PATCH /repos/o/r` |
+| Create release | `gh release create v1.0` | `curl POST /repos/o/r/releases` |
+| List workflows | `gh workflow list` | `curl GET /repos/o/r/actions/workflows` |
+| Rerun CI | `gh run rerun ID` | `curl POST /repos/o/r/actions/runs/ID/rerun` |
+| Set secret | `gh secret set KEY` | `curl PUT /repos/o/r/actions/secrets/KEY` (+ encryption) |

package/built-in-skills/prismer-github/references/review-output-template.md

@@ -0,0 +1,84 @@
+# Review Output Template
+
+> Prismer scope: read auth.md first. All mutations below are examples for an
+> explicitly authorized target/action, never an automatic checklist. Preserve the
+> current dirty tree and long-lived branch; resolve the actual base branch and
+> do not switch, commit, push, publish, merge, delete branches or send reviews
+> unless requested. Use structured JSON for dynamic payloads, not shell string
+> interpolation. Public visibility requires explicit intent. Collection reads
+> must use scripts/github-api.py (complete Link pagination) or gh api --paginate;
+> porcelain list limits and single-page curl output are not a complete inventory.
+> Run shell pipelines with pipefail, record each exit status, and read back writes.
+
+Use this as the structure for PR review summary comments. Copy and fill in the sections.
+
+## For PR Summary Comment
+
+```markdown
+## Code Review Summary
+
+**Verdict: [Approved ✅ | Changes Requested 🔴 | Reviewed 💬]** ([N] issues, [N] suggestions)
+
+**PR:** #[number] — [title]
+**Author:** @[username]
+**Files changed:** [N] (+[additions] -[deletions])
+
+### 🔴 Critical
+<!-- Issues that MUST be fixed before merge -->
+- **file.py:line** — [description]. Suggestion: [fix].
+
+### ⚠️ Warnings
+<!-- Issues that SHOULD be fixed, but not strictly blocking -->
+- **file.py:line** — [description].
+
+### 💡 Suggestions
+<!-- Non-blocking improvements, style preferences, future considerations -->
+- **file.py:line** — [description].
+
+### ✅ Looks Good
+<!-- Call out things done well — positive reinforcement -->
+- [aspect that was done well]
+
+---
+*Reviewed by Hermes Agent*
+```
+
+## Severity Guide
+
+| Level | Icon | When to use | Blocks merge? |
+|-------|------|-------------|---------------|
+| Critical | 🔴 | Security vulnerabilities, data loss risk, crashes, broken core functionality | Yes |
+| Warning | ⚠️ | Bugs in non-critical paths, missing error handling, missing tests for new code | Usually yes |
+| Suggestion | 💡 | Style improvements, refactoring ideas, performance hints, documentation gaps | No |
+| Looks Good | ✅ | Clean patterns, good test coverage, clear naming, smart design decisions | N/A |
+
+## Verdict Decision
+
+- **Approved ✅** — Zero critical/warning items. Only suggestions or all clear.
+- **Changes Requested 🔴** — Any critical or warning item exists.
+- **Reviewed 💬** — Observations only (draft PRs, uncertain findings, informational).
+
+## For Inline Comments
+
+Prefix inline comments with the severity icon so they're scannable:
+
+```
+🔴 **Critical:** User input passed directly to SQL query — use parameterized queries to prevent injection.
+```
+
+```
+⚠️ **Warning:** This error is silently swallowed. At minimum, log it.
+```
+
+```
+💡 **Suggestion:** This could be simplified with a dict comprehension:
+`{k: v for k, v in items if v is not None}`
+```
+
+```
+✅ **Nice:** Good use of context manager here — ensures cleanup on exceptions.
+```
+
+## For Local (Pre-Push) Review
+
+When reviewing locally before push, use the same structure but present it as a message to the user instead of a PR comment. Skip the PR metadata header and just start with the severity sections.

package/built-in-skills/prismer-github/scripts/ensure-gh.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Install missing gh; verify version and authentication independently."""
+import argparse
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import platform
+import re
+import shutil
+import subprocess
+import tarfile
+import stat
+import zipfile
+import urllib.request
+
+
+def run_command(argv):
+    try:
+        return subprocess.run(argv, capture_output=True, text=True, timeout=600, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return subprocess.CompletedProcess(argv, 1, '', 'unavailable or timed out')
+
+
+def download(url, limit):
+    with urllib.request.urlopen(url, timeout=30) as response:
+        data = response.read(limit + 1)
+    if len(data) > limit:
+        raise ValueError('download exceeds limit')
+    return data
+
+
+def install_binary(system, fetch=download):
+    """Official release plus SHA256; extract only one regular executable."""
+    arch = {'x86_64': 'amd64', 'amd64': 'amd64', 'aarch64': 'arm64', 'arm64': 'arm64'}.get(platform.machine().lower())
+    if system not in ('Linux', 'Darwin') or not arch:
+        raise ValueError('unsupported host architecture')
+    release = json.loads(fetch('https://api.github.com/repos/cli/cli/releases/latest', 2_000_000))
+    tag = release.get('tag_name', '') if isinstance(release, dict) else ''
+    if not re.fullmatch(r'v2\.\d+\.\d+', tag):
+        raise ValueError('unrecognized stable release')
+    version = tag[1:]
+    stem = f"gh_{version}_{'linux' if system == 'Linux' else 'macOS'}_{arch}"
+    name = stem + ('.tar.gz' if system == 'Linux' else '.zip')
+    base = f'https://github.com/cli/cli/releases/download/{tag}/'
+    sums = fetch(base + f'gh_{version}_checksums.txt', 200_000).decode('ascii')
+    expected = [line.split()[0] for line in sums.splitlines() if len(line.split()) == 2 and line.split()[1] == name]
+    if len(expected) != 1 or not re.fullmatch('[0-9a-fA-F]{64}', expected[0]):
+        raise ValueError('missing release checksum')
+    archive = fetch(base + name, 50_000_000)
+    if hashlib.sha256(archive).hexdigest() != expected[0].lower():
+        raise ValueError('checksum mismatch')
+    if system == 'Darwin':
+        with zipfile.ZipFile(io.BytesIO(archive)) as zipped:
+            members = [m for m in zipped.infolist() if m.filename == stem + '/bin/gh']
+            if (len(members) != 1 or members[0].is_dir() or
+                    stat.S_ISLNK(members[0].external_attr >> 16) or members[0].file_size > 100_000_000):
+                raise ValueError('unexpected executable entry')
+            data = zipped.read(members[0])
+    else:
+        with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
+            members = [m for m in tar.getmembers() if m.name == stem + '/bin/gh']
+            if len(members) != 1 or not members[0].isfile() or members[0].size > 100_000_000:
+                raise ValueError('unexpected executable entry')
+            data = tar.extractfile(members[0]).read(100_000_001)
+    target = Path.home() / '.local' / 'bin' / 'gh'
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open('xb') as handle:
+        handle.write(data)
+    target.chmod(0o755)
+    return str(target)
+
+
+def ensure(run=run_command, binary_installer=install_binary, check_only=False, host='github.com'):
+    if not re.fullmatch(r'[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?', host):
+        return {'state': 'invalid-host', 'installed': False, 'authenticated': False}
+    executable = find_gh()
+    result = {'state': 'missing', 'installed': False, 'authenticated': False, 'host': host}
+    if not executable:
+        if check_only:
+            return result
+        system = platform.system()
+        brew = shutil.which('brew') if system in ('Darwin', 'Linux') else None
+        winget = shutil.which('winget') if system == 'Windows' else None
+        command = ([brew, 'install', 'gh'] if brew else
+                   [winget, 'install', '--id', 'GitHub.cli', '--exact', '--source', 'winget', '--silent', '--disable-interactivity'] if winget else None)
+        try:
+            if command:
+                if run(command).returncode:
+                    return {**result, 'state': 'install-failed'}
+                executable = find_gh() or 'gh'
+            else:
+                executable = binary_installer(system)
+        except (OSError, ValueError, KeyError, tarfile.TarError, zipfile.BadZipFile):
+            return {**result, 'state': 'install-failed'}
+    version = run([executable, '--version'])
+    match = re.search(r'^gh version (\d+)\.(\d+)\.(\d+)\b', version.stdout, re.MULTILINE)
+    if version.returncode or not match or int(match[1]) < 2:
+        return {**result, 'state': 'version-check-failed', 'executable': executable}
+    result.update(installed=True, executable=executable, version=match[0])
+    auth = run([executable, 'auth', 'status', '--hostname', host])
+    result.update(authenticated=auth.returncode == 0,
+                  state='ready-for-repository-check' if auth.returncode == 0 else 'authentication-required')
+    return result
+
+
+def find_gh():
+    found = shutil.which('gh')
+    if found:
+        return found
+    candidates = [Path.home() / '.local/bin/gh']
+    if platform.system() == 'Windows':
+        if os.environ.get('ProgramFiles'):
+            candidates.append(Path(os.environ['ProgramFiles']) / 'GitHub CLI/gh.exe')
+        if os.environ.get('LOCALAPPDATA'):
+            candidates.append(Path(os.environ['LOCALAPPDATA']) / 'Microsoft/WinGet/Links/gh.exe')
+    return next((str(p) for p in candidates if p.is_file()), None)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--check-only', action='store_true')
+    parser.add_argument('--host', default='github.com')
+    args = parser.parse_args()
+    result = ensure(check_only=args.check_only, host=args.host)
+    print(json.dumps(result))
+    return 0 if result['authenticated'] else 1
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())