lastlight 0.1.8 → 0.2.0

package/skills/github/github-pr-workflow/SKILL.md

@@ -1,395 +0,0 @@
----
-name: github-pr-workflow
-description: Full pull request lifecycle — create branches, commit changes, open PRs, monitor CI status, auto-fix failures, and merge. Works with gh CLI or falls back to git + GitHub REST API via curl.
-version: 1.1.0
-author: Hermes Agent
-license: MIT
-metadata:
-  hermes:
-    tags: [GitHub, Pull-Requests, CI/CD, Git, Automation, Merge]
-    related_skills: [github-auth, github-code-review]
----
-
-# GitHub Pull Request Workflow
-
-Complete guide for managing the PR lifecycle. Each section shows the `gh` way first, then the `git` + `curl` fallback for machines without `gh`.
-
-## Prerequisites
-
-- Authenticated with GitHub (see `github-auth` skill)
-- Inside a git repository with a GitHub remote
-
-### Quick Auth Detection
-
-```bash
-# Determine which method to use throughout this workflow
-if command -v gh &>/dev/null && gh auth status &>/dev/null; then
-  AUTH="gh"
-else
-  AUTH="git"
-  # Ensure we have a token for API calls
-  if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
-    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
-      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
-    fi
-  fi
-fi
-echo "Using: $AUTH"
-```
-
-### Extracting Owner/Repo from the Git Remote
-
-Many `curl` commands need `owner/repo`. Extract it from the git remote:
-
-```bash
-# Works for both HTTPS and SSH remote URLs
-REMOTE_URL=$(git remote get-url origin)
-OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
-OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
-REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
-echo "Owner: $OWNER, Repo: $REPO"
-```
-
----
-
-## 1. Branch Creation
-
-This part is pure `git` — identical either way:
-
-```bash
-# Make sure you're up to date
-git fetch origin
-git checkout main && git pull origin main
-
-# Create and switch to a new branch
-git checkout -b feat/add-user-authentication
-```
-
-Branch naming conventions:
-- `feat/description` — new features
-- `fix/description` — bug fixes
-- `refactor/description` — code restructuring
-- `docs/description` — documentation
-- `ci/description` — CI/CD changes
-
-## 2. Making Commits
-
-Use the agent's file tools (`write_file`, `patch`) to make changes, then commit:
-
-```bash
-# Stage specific files
-git add src/auth.py src/models/user.py tests/test_auth.py
-
-# Commit with a conventional commit message
-git commit -m "feat: add JWT-based user authentication
-
-- Add login/register endpoints
-- Add User model with password hashing
-- Add auth middleware for protected routes
-- Add unit tests for auth flow"
-```
-
-Commit message format (Conventional Commits):
-```
-type(scope): short description
-
-Longer explanation if needed. Wrap at 72 characters.
-```
-
-Types: `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`, `perf`
-
-## 3. Pushing and Creating a PR
-
-### Push the Branch (same either way)
-
-```bash
-git push -u origin HEAD
-```
-
-### Auth setup
-
-The token file (`.gh-token`) and git config (`.gitconfig-bot`) are auto-synced into the sandbox by Hermes before each command via `terminal.credential_files`. To activate:
-
-1. Call `setup_git_auth` MCP tool (refreshes the token)
-2. Run the returned `configure_git` command (one-time per session)
-3. `git push -u origin HEAD` should just work
-
-### MCP fallback when git push fails
-
-If `git push` fails with `Invalid username or token` / `Authentication failed`, fall back to the GitHub MCP tools:
-
-1. Create the remote branch with `mcp_github_create_branch`
-2. Push changed files with `mcp_github_push_files`
-3. Open the PR with `mcp_github_create_pull_request`
-
-Limitation: `mcp_github_push_files` supports creating/updating files, but **not deleting/renaming** files. Prefer `git push` when possible.
-
-### Last resort when no push path works
-
-If both `git push` and MCP push fail, post a concise issue comment summarizing:
-- what was implemented locally
-- exact validation commands/results
-- local commit SHA and commit message
-- files touched
-- that PR creation was blocked by sandbox auth
-
-This gives the maintainer a reproducible handoff instead of a vague failure report.
-
-### Create the PR
-
-**With gh:**
-
-```bash
-gh pr create \
-  --title "feat: add JWT-based user authentication" \
-  --body "## Summary
-- Adds login and register API endpoints
-- JWT token generation and validation
-
-## Test Plan
-- [ ] Unit tests pass
-
-Closes #42"
-```
-
-Options: `--draft`, `--reviewer user1,user2`, `--label "enhancement"`, `--base develop`
-
-**With git + curl:**
-
-```bash
-BRANCH=$(git branch --show-current)
-
-curl -s -X POST \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  -H "Accept: application/vnd.github.v3+json" \
-  https://api.github.com/repos/$OWNER/$REPO/pulls \
-  -d "{
-    \"title\": \"feat: add JWT-based user authentication\",
-    \"body\": \"## Summary\nAdds login and register API endpoints.\n\nCloses #42\",
-    \"head\": \"$BRANCH\",
-    \"base\": \"main\"
-  }"
-```
-
-The response JSON includes the PR `number` — save it for later commands.
-
-To create as a draft, add `"draft": true` to the JSON body.
-
-## 4. Monitoring CI Status
-
-### Check CI Status
-
-**With gh:**
-
-```bash
-# One-shot check
-gh pr checks
-
-# Watch until all checks finish (polls every 10s)
-gh pr checks --watch
-```
-
-**With git + curl:**
-
-```bash
-# Get the latest commit SHA on the current branch
-SHA=$(git rev-parse HEAD)
-
-# Query the combined status
-curl -s \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
-  | python3 -c "
-import sys, json
-data = json.load(sys.stdin)
-print(f\"Overall: {data['state']}\")
-for s in data.get('statuses', []):
-    print(f\"  {s['context']}: {s['state']} - {s.get('description', '')}\")"
-
-# Also check GitHub Actions check runs (separate endpoint)
-curl -s \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/check-runs \
-  | python3 -c "
-import sys, json
-data = json.load(sys.stdin)
-for cr in data.get('check_runs', []):
-    print(f\"  {cr['name']}: {cr['status']} / {cr['conclusion'] or 'pending'}\")"
-```
-
-### Poll Until Complete (git + curl)
-
-```bash
-# Simple polling loop — check every 30 seconds, up to 10 minutes
-SHA=$(git rev-parse HEAD)
-for i in $(seq 1 20); do
-  STATUS=$(curl -s \
-    -H "Authorization: token $GITHUB_TOKEN" \
-    https://api.github.com/repos/$OWNER/$REPO/commits/$SHA/status \
-    | python3 -c "import sys,json; print(json.load(sys.stdin)['state'])")
-  echo "Check $i: $STATUS"
-  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failure" ] || [ "$STATUS" = "error" ]; then
-    break
-  fi
-  sleep 30
-done
-```
-
-## 5. Auto-Fixing CI Failures
-
-When CI fails, diagnose and fix. This loop works with either auth method.
-
-### Step 1: Get Failure Details
-
-**With gh:**
-
-```bash
-# List recent workflow runs on this branch
-gh run list --branch $(git branch --show-current) --limit 5
-
-# View failed logs
-gh run view <RUN_ID> --log-failed
-```
-
-**With git + curl:**
-
-```bash
-BRANCH=$(git branch --show-current)
-
-# List workflow runs on this branch
-curl -s \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  "https://api.github.com/repos/$OWNER/$REPO/actions/runs?branch=$BRANCH&per_page=5" \
-  | python3 -c "
-import sys, json
-runs = json.load(sys.stdin)['workflow_runs']
-for r in runs:
-    print(f\"Run {r['id']}: {r['name']} - {r['conclusion'] or r['status']}\")"
-
-# Get failed job logs (download as zip, extract, read)
-RUN_ID=<run_id>
-curl -s -L \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/logs \
-  -o /tmp/ci-logs.zip
-cd /tmp && unzip -o ci-logs.zip -d ci-logs && cat ci-logs/*.txt
-```
-
-### Step 2: Fix and Push
-
-After identifying the issue, use file tools (`patch`, `write_file`) to fix it:
-
-```bash
-git add <fixed_files>
-git commit -m "fix: resolve CI failure in <check_name>"
-git push
-```
-
-### Step 3: Verify
-
-Re-check CI status using the commands from Section 4 above.
-
-### Auto-Fix Loop Pattern
-
-When asked to auto-fix CI, follow this loop:
-
-1. Check CI status → identify failures
-2. Read failure logs → understand the error
-3. Use `read_file` + `patch`/`write_file` → fix the code
-4. `git add . && git commit -m "fix: ..." && git push`
-5. Wait for CI → re-check status
-6. Repeat if still failing (up to 3 attempts, then ask the user)
-
-## 6. Merging
-
-**With gh:**
-
-```bash
-# Squash merge + delete branch (cleanest for feature branches)
-gh pr merge --squash --delete-branch
-
-# Enable auto-merge (merges when all checks pass)
-gh pr merge --auto --squash --delete-branch
-```
-
-**With git + curl:**
-
-```bash
-PR_NUMBER=<number>
-
-# Merge the PR via API (squash)
-curl -s -X PUT \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/merge \
-  -d "{
-    \"merge_method\": \"squash\",
-    \"commit_title\": \"feat: add user authentication (#$PR_NUMBER)\"
-  }"
-
-# Delete the remote branch after merge
-BRANCH=$(git branch --show-current)
-git push origin --delete $BRANCH
-
-# Switch back to main locally
-git checkout main && git pull origin main
-git branch -d $BRANCH
-```
-
-Merge methods: `"merge"` (merge commit), `"squash"`, `"rebase"`
-
-### Enable Auto-Merge (curl)
-
-```bash
-# Auto-merge requires the repo to have it enabled in settings.
-# This uses the GraphQL API since REST doesn't support auto-merge.
-PR_NODE_ID=$(curl -s \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
-  | python3 -c "import sys,json; print(json.load(sys.stdin)['node_id'])")
-
-curl -s -X POST \
-  -H "Authorization: token $GITHUB_TOKEN" \
-  https://api.github.com/graphql \
-  -d "{\"query\": \"mutation { enablePullRequestAutoMerge(input: {pullRequestId: \\\"$PR_NODE_ID\\\", mergeMethod: SQUASH}) { clientMutationId } }\"}"
-```
-
-## 7. Complete Workflow Example
-
-```bash
-# 1. Start from clean main
-git checkout main && git pull origin main
-
-# 2. Branch
-git checkout -b fix/login-redirect-bug
-
-# 3. (Agent makes code changes with file tools)
-
-# 4. Commit
-git add src/auth/login.py tests/test_login.py
-git commit -m "fix: correct redirect URL after login
-
-Preserves the ?next= parameter instead of always redirecting to /dashboard."
-
-# 5. Push
-git push -u origin HEAD
-
-# 6. Create PR (picks gh or curl based on what's available)
-# ... (see Section 3)
-
-# 7. Monitor CI (see Section 4)
-
-# 8. Merge when green (see Section 6)
-```
-
-## Useful PR Commands Reference
-
-| Action | gh | git + curl |
-|--------|-----|-----------|
-| List my PRs | `gh pr list --author @me` | `curl -s -H "Authorization: token $GITHUB_TOKEN" "https://api.github.com/repos/$OWNER/$REPO/pulls?state=open"` |
-| View PR diff | `gh pr diff` | `git diff main...HEAD` (local) or `curl -H "Accept: application/vnd.github.diff" ...` |
-| Add comment | `gh pr comment N --body "..."` | `curl -X POST .../issues/N/comments -d '{"body":"..."}'` |
-| Request review | `gh pr edit N --add-reviewer user` | `curl -X POST .../pulls/N/requested_reviewers -d '{"reviewers":["user"]}'` |
-| Close PR | `gh pr close N` | `curl -X PATCH .../pulls/N -d '{"state":"closed"}'` |
-| Check out someone's PR | `gh pr checkout N` | `git fetch origin pull/N/head:pr-N && git checkout pr-N` |

package/skills/github/github-pr-workflow/references/ci-troubleshooting.md

@@ -1,183 +0,0 @@
-# CI Troubleshooting Quick Reference
-
-Common CI failure patterns and how to diagnose them from the logs.
-
-## Reading CI Logs
-
-```bash
-# With gh
-gh run view <RUN_ID> --log-failed
-
-# With curl — download and extract
-curl -sL -H "Authorization: token $GITHUB_TOKEN" \
-  https://api.github.com/repos/$GH_OWNER/$GH_REPO/actions/runs/<RUN_ID>/logs \
-  -o /tmp/ci-logs.zip && unzip -o /tmp/ci-logs.zip -d /tmp/ci-logs
-```
-
-## Common Failure Patterns
-
-### Test Failures
-
-**Signatures in logs:**
-```
-FAILED tests/test_foo.py::test_bar - AssertionError
-E       assert 42 == 43
-ERROR tests/test_foo.py - ModuleNotFoundError
-```
-
-**Diagnosis:**
-1. Find the test file and line number from the traceback
-2. Use `read_file` to read the failing test
-3. Check if it's a logic error in the code or a stale test assertion
-4. Look for `ModuleNotFoundError` — usually a missing dependency in CI
-
-**Common fixes:**
-- Update assertion to match new expected behavior
-- Add missing dependency to requirements.txt / pyproject.toml
-- Fix flaky test (add retry, mock external service, fix race condition)
-
----
-
-### Lint / Formatting Failures
-
-**Signatures in logs:**
-```
-src/auth.py:45:1: E302 expected 2 blank lines, got 1
-src/models.py:12:80: E501 line too long (95 > 88 characters)
-error: would reformat src/utils.py
-```
-
-**Diagnosis:**
-1. Read the specific file:line numbers mentioned
-2. Check which linter is complaining (flake8, ruff, black, isort, mypy)
-
-**Common fixes:**
-- Run the formatter locally: `black .`, `isort .`, `ruff check --fix .`
-- Fix the specific style violation by editing the file
-- If using `patch`, make sure to match existing indentation style
-
----
-
-### Type Check Failures (mypy / pyright)
-
-**Signatures in logs:**
-```
-src/api.py:23: error: Argument 1 to "process" has incompatible type "str"; expected "int"
-src/models.py:45: error: Missing return statement
-```
-
-**Diagnosis:**
-1. Read the file at the mentioned line
-2. Check the function signature and what's being passed
-
-**Common fixes:**
-- Add type cast or conversion
-- Fix the function signature
-- Add `# type: ignore` comment as last resort (with explanation)
-
----
-
-### Build / Compilation Failures
-
-**Signatures in logs:**
-```
-ModuleNotFoundError: No module named 'some_package'
-ERROR: Could not find a version that satisfies the requirement foo==1.2.3
-npm ERR! Could not resolve dependency
-```
-
-**Diagnosis:**
-1. Check requirements.txt / package.json for the missing or incompatible dependency
-2. Compare local vs CI Python/Node version
-
-**Common fixes:**
-- Add missing dependency to requirements file
-- Pin compatible version
-- Update lockfile (`pip freeze`, `npm install`)
-
----
-
-### Permission / Auth Failures
-
-**Signatures in logs:**
-```
-fatal: could not read Username for 'https://github.com': No such device or address
-Error: Resource not accessible by integration
-403 Forbidden
-```
-
-**Diagnosis:**
-1. Check if the workflow needs special permissions (token scopes)
-2. Check if secrets are configured (missing `GITHUB_TOKEN` or custom secrets)
-
-**Common fixes:**
-- Add `permissions:` block to workflow YAML
-- Verify secrets exist: `gh secret list` or check repo settings
-- For fork PRs: some secrets aren't available by design
-
----
-
-### Timeout Failures
-
-**Signatures in logs:**
-```
-Error: The operation was canceled.
-The job running on runner ... has exceeded the maximum execution time
-```
-
-**Diagnosis:**
-1. Check which step timed out
-2. Look for infinite loops, hung processes, or slow network calls
-
-**Common fixes:**
-- Add timeout to the specific step: `timeout-minutes: 10`
-- Fix the underlying performance issue
-- Split into parallel jobs
-
----
-
-### Docker / Container Failures
-
-**Signatures in logs:**
-```
-docker: Error response from daemon
-failed to solve: ... not found
-COPY failed: file not found in build context
-```
-
-**Diagnosis:**
-1. Check Dockerfile for the failing step
-2. Verify the referenced files exist in the repo
-
-**Common fixes:**
-- Fix path in COPY/ADD command
-- Update base image tag
-- Add missing file to `.dockerignore` exclusion or remove from it
-
----
-
-## Auto-Fix Decision Tree
-
-```
-CI Failed
-├── Test failure
-│   ├── Assertion mismatch → update test or fix logic
-│   └── Import/module error → add dependency
-├── Lint failure → run formatter, fix style
-├── Type error → fix types
-├── Build failure
-│   ├── Missing dep → add to requirements
-│   └── Version conflict → update pins
-├── Permission error → update workflow permissions (needs user)
-└── Timeout → investigate perf (may need user input)
-```
-
-## Re-running After Fix
-
-```bash
-git add <fixed_files> && git commit -m "fix: resolve CI failure" && git push
-
-# Then monitor
-gh pr checks --watch 2>/dev/null || \
-  echo "Poll with: curl -s -H 'Authorization: token ...' https://api.github.com/repos/.../commits/$(git rev-parse HEAD)/status"
-```

package/skills/github/github-pr-workflow/references/conventional-commits.md

@@ -1,71 +0,0 @@
-# Conventional Commits Quick Reference
-
-Format: `type(scope): description`
-
-## Types
-
-| Type | When to use | Example |
-|------|------------|---------|
-| `feat` | New feature or capability | `feat(auth): add OAuth2 login flow` |
-| `fix` | Bug fix | `fix(api): handle null response from /users endpoint` |
-| `refactor` | Code restructuring, no behavior change | `refactor(db): extract query builder into separate module` |
-| `docs` | Documentation only | `docs: update API usage examples in README` |
-| `test` | Adding or updating tests | `test(auth): add integration tests for token refresh` |
-| `ci` | CI/CD configuration | `ci: add Python 3.12 to test matrix` |
-| `chore` | Maintenance, dependencies, tooling | `chore: upgrade pytest to 8.x` |
-| `perf` | Performance improvement | `perf(search): add index on users.email column` |
-| `style` | Formatting, whitespace, semicolons | `style: run black formatter on src/` |
-| `build` | Build system or external deps | `build: switch from setuptools to hatch` |
-| `revert` | Reverts a previous commit | `revert: revert "feat(auth): add OAuth2 login flow"` |
-
-## Scope (optional)
-
-Short identifier for the area of the codebase: `auth`, `api`, `db`, `ui`, `cli`, etc.
-
-## Breaking Changes
-
-Add `!` after type or `BREAKING CHANGE:` in footer:
-
-```
-feat(api)!: change authentication to use bearer tokens
-
-BREAKING CHANGE: API endpoints now require Bearer token instead of API key header.
-Migration guide: https://docs.example.com/migrate-auth
-```
-
-## Multi-line Body
-
-Wrap at 72 characters. Use bullet points for multiple changes:
-
-```
-feat(auth): add JWT-based user authentication
-
-- Add login/register endpoints with input validation
-- Add User model with argon2 password hashing
-- Add auth middleware for protected routes
-- Add token refresh endpoint with rotation
-
-Closes #42
-```
-
-## Linking Issues
-
-In the commit body or footer:
-
-```
-Closes #42          ← closes the issue when merged
-Fixes #42           ← same effect
-Refs #42            ← references without closing
-Co-authored-by: Name <email>
-```
-
-## Quick Decision Guide
-
-- Added something new? → `feat`
-- Something was broken and you fixed it? → `fix`
-- Changed how code is organized but not what it does? → `refactor`
-- Only touched tests? → `test`
-- Only touched docs? → `docs`
-- Updated CI/CD pipelines? → `ci`
-- Updated dependencies or tooling? → `chore`
-- Made something faster? → `perf`

package/skills/github/github-pr-workflow/templates/pr-body-bugfix.md

@@ -1,35 +0,0 @@
-## Bug Description
-
-<!-- What was happening? -->
-
-Fixes #
-
-## Root Cause
-
-<!-- What was causing the bug? -->
-
-## Fix
-
-<!-- What does this PR change to fix it? -->
-
--
-
-## How to Verify
-
-<!-- Steps a reviewer can follow to confirm the fix -->
-
-1.
-2.
-3.
-
-## Test Plan
-
-- [ ] Added regression test for this bug
-- [ ] Existing tests still pass
-- [ ] Manual verification of the fix
-
-## Risk Assessment
-
-<!-- Could this fix break anything else? What's the blast radius? -->
-
-Low / Medium / High — <!-- explanation -->