@codragraph/cli 1.6.3 → 2.0.0

package/skills/codragraph-gh-issue-workflow.md

@@ -0,0 +1,178 @@
+---
+name: codragraph-gh-issue-workflow
+description: "Use for issue management via GitHub CLI — create, triage, label, assign, link to PRs, manage projects (v2), close with reason. Examples: \"open an issue\", \"triage issues\", \"add labels\", \"link this PR to issue\", \"close issue\", \"manage GitHub projects\""
+---
+
+# Issue Workflow with `gh`
+
+## When to Use
+
+- "Open an issue for this bug."
+- "Triage the open issues — sort by labels / priority."
+- "Link this PR to issue #42 so it auto-closes on merge."
+- "Add this issue to my project board."
+- "Bulk-relabel old issues."
+
+## Lifecycle commands
+
+### Create
+
+```bash
+# Quick create:
+gh issue create --title "…" --body "…" --label bug --assignee "@me"
+
+# Multi-line body via HEREDOC:
+gh issue create --title "Auth times out after 30s" --body "$(cat <<'EOF'
+## Repro
+1. Login as user X
+2. Wait 30s
+3. Click anywhere
+
+## Expected
+Session refresh transparent.
+
+## Actual
+Hard logout with no warning.
+
+## Environment
+- App version: …
+- Browser: …
+EOF
+)"
+
+# From a template (.github/ISSUE_TEMPLATE/<x>.md):
+gh issue create --template bug_report.md
+```
+
+### List / search / view
+
+```bash
+gh issue list                                     # open issues
+gh issue list --state all --limit 100             # everything
+gh issue list --label "bug,priority:high"          # filter
+gh issue list --search "in:title auth"             # full-text in title/body
+gh issue list --assignee "@me"                    # assigned to you
+
+gh issue view <N>                                 # one issue
+gh issue view <N> --comments                      # include comments
+gh issue status                                   # issues needing your attention
+```
+
+### Triage / edit
+
+```bash
+gh issue edit <N> --add-label "bug,needs-repro" --add-assignee @teammate
+gh issue edit <N> --remove-label "stale" --milestone "v1.7.0"
+gh issue comment <N> --body "Cannot repro. Could you share <X>?"
+gh issue pin <N>                                  # pin to top of issues page
+gh issue unpin <N>
+gh issue lock <N>                                 # freeze further comments
+gh issue unlock <N>
+```
+
+### Link issues to PRs
+
+GitHub auto-closes the issue when a PR with `Closes #N` / `Fixes #N` /
+`Resolves #N` in the body merges. From the CLI:
+
+```bash
+gh pr create --body "$(cat <<'EOF'
+Fixes #42.
+
+## Summary
+…
+EOF
+)"
+```
+
+For sub-issues / dependencies (no auto-close, just visual link):
+
+```
+Related: #43, #44
+Blocks: #50
+```
+
+### Close / reopen
+
+```bash
+# State reasons (GitHub Issue State Reasons API):
+gh issue close <N> --reason completed             # default
+gh issue close <N> --reason "not planned"         # won't fix
+gh issue close <N> --reason duplicate --comment "duplicate of #M"
+
+gh issue reopen <N>
+```
+
+## Triage workflow (recurring)
+
+A weekly / per-stand-up triage pass:
+
+```bash
+# 1. Surface issues with no labels (the worst offender):
+gh issue list --search "no:label" --limit 50
+
+# 2. Surface "needs repro" stale-bait:
+gh issue list --label "needs-repro" \
+  --search "updated:<$(date -u -d '14 days ago' +%Y-%m-%d)" --limit 50
+
+# 3. Bulk-label or bulk-close (loop with gh):
+for n in $(gh issue list --label "needs-repro" \
+  --search "updated:<$(date -u -d '30 days ago' +%Y-%m-%d)" \
+  --json number --jq '.[].number'); do
+  gh issue close "$n" --reason "not planned" \
+    --comment "Closing for inactivity. Reopen with a fresh repro."
+done
+```
+
+## Projects (v2)
+
+GitHub Projects v2 is the modern board. The CLI has first-class support
+via `gh project`:
+
+```bash
+gh project list --owner <org-or-user>
+gh project view <number> --owner <org>            # full board contents
+gh project item-add <project-number> --owner <org> --url <issue-url>
+gh project item-edit --id <item-id> --field-id <fid> --single-select-option-id <oid>
+```
+
+Adding from issue context (one-liner):
+
+```bash
+gh project item-add <pn> --owner <org> --url $(gh issue view <N> --json url --jq .url)
+```
+
+## Why CodraGraph helps here
+
+When triaging a bug, jump straight from issue text to the suspect code:
+
+```
+1. gh issue view 42 --comments
+   → "validateUser fails for users with X"
+
+2. codragraph_query({query: "validateUser X"})
+   → suspect symbols ranked
+
+3. codragraph_context({name: "validateUser"})
+   → callers + callees + processes
+
+4. codragraph_impact({target: "validateUser", direction: "upstream"})
+   → which flows are affected — confirms the bug's blast radius
+
+5. Comment on the issue with concrete next steps:
+   gh issue comment 42 --body "Fix likely in src/auth/validate.ts:42 …"
+```
+
+Combine with the `codragraph-debugging` skill for full bug-investigation
+workflow.
+
+## Pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Issue body forgets the repro | Always include "Repro / Expected / Actual / Env" in the template |
+| Closing without a reason | Use `--reason "not planned"` so the state is searchable |
+| Linking to PR via `#N` only | Use `Fixes #N` in PR body — that's what triggers auto-close |
+| Bulk-relabeling without a `--dry-run` | gh has no built-in dry run; do `gh issue list` first to preview |
+| Mixing v1 boards (deprecated) and v2 | New automation: only `gh project` (v2). Old `gh project` v1 commands removed in CLI 2.20+ |
+```

package/skills/codragraph-gh-pr-workflow.md

@@ -0,0 +1,176 @@
+---
+name: codragraph-gh-pr-workflow
+description: "Use for any pull-request workflow via GitHub CLI — create draft, convert ready, request review, address comments, check CI, merge with the right strategy, manage stacked PRs. Examples: \"open a PR\", \"draft PR\", \"merge this PR\", \"check PR status\", \"address review comments\", \"stacked PRs\""
+---
+
+# Pull Request Workflow with `gh`
+
+## When to Use
+
+- "Open a PR for this branch."
+- "Convert this draft to ready-for-review."
+- "Check the status of my PRs."
+- "Merge PR #N — which strategy should I use?"
+- "Address review comments and push fixes."
+- "I have stacked PRs — how do I manage them?"
+
+## Lifecycle commands
+
+### Open
+
+```bash
+# After pushing your branch:
+gh pr create --title "feat: …" --body "…" --reviewer @teammate
+gh pr create --draft                              # ship as draft
+gh pr create --fill                               # use the most recent commit message
+gh pr create --base main --head my-branch         # explicit base/head
+
+# Multi-line body (HEREDOC) — preferred for real PRs:
+gh pr create --title "feat: X" --body "$(cat <<'EOF'
+## Summary
+- Bullet 1
+- Bullet 2
+
+## Test plan
+- [ ] Unit
+- [ ] Integration
+- [ ] Manual repro of the bug
+EOF
+)"
+```
+
+### Inspect
+
+```bash
+gh pr list                                        # PRs in this repo (yours by default)
+gh pr list --state all --author "@me"             # all your PRs ever
+gh pr status                                      # PRs needing attention (created by you, requesting your review)
+gh pr view <N>                                    # one PR's metadata
+gh pr view <N> --comments                         # include review comments
+gh pr diff <N>                                    # raw diff
+gh pr checks <N>                                  # CI status per check
+```
+
+### Update
+
+```bash
+# Push fixes to the same branch:
+git push                                          # PR auto-updates
+
+# Convert draft <-> ready:
+gh pr ready <N>                                   # draft → ready-for-review
+gh pr ready --undo <N>                            # ready → draft
+
+# Edit metadata:
+gh pr edit <N> --title "…" --add-reviewer @teammate --add-label "bug"
+```
+
+### Address review comments
+
+```bash
+# Pull the conversation:
+gh pr view <N> --comments
+
+# Push your fixes (same branch):
+git add <files> && git commit -m "address review: <topic>"
+git push
+
+# Mark conversations resolved (UI only, no CLI flag) or reply:
+gh pr comment <N> --body "fixed in <new-sha>"
+```
+
+### Merge
+
+| Strategy | When | gh command |
+|---|---|---|
+| **Squash** | One logical change, want one commit on main | `gh pr merge <N> --squash --delete-branch` |
+| **Rebase** | Multiple already-tidy commits, no merge bubble | `gh pr merge <N> --rebase --delete-branch` |
+| **Merge commit** | Long-running release branch, preserve topology | `gh pr merge <N> --merge --delete-branch` |
+| **Auto-merge** | Merge as soon as CI green + reviews approved | `gh pr merge <N> --auto --squash --delete-branch` |
+
+See `codragraph-git-rebase-vs-merge` for the decision rule. Default to
+**squash** for typical feature PRs.
+
+### Close / reopen
+
+```bash
+gh pr close <N> --comment "superseded by #<other>"
+gh pr reopen <N>
+```
+
+## Stacked PR pattern (`gh pr` with branches that depend on each other)
+
+When PR #2 depends on PR #1's branch, point #2's base at #1's branch:
+
+```bash
+git switch feat/step-1
+gh pr create --base main --title "feat: step 1"
+
+git switch -c feat/step-2 feat/step-1
+# … edit …
+git push -u origin feat/step-2
+gh pr create --base feat/step-1 --title "feat: step 2 (depends on #N)"
+
+# When step-1 merges, automatically retarget step-2 to main:
+gh pr edit <step-2-pr> --base main
+```
+
+## Why CodraGraph helps here
+
+The PR review GitHub Action (codragraph-pr-review) ALREADY automates the
+diff-comment side. As an author, you should ALSO run impact locally
+before requesting review — it catches the "I forgot to update a caller"
+class of problem that a reviewer is most likely to flag:
+
+```bash
+codragraph_detect_changes({scope: "compare", base_ref: "main"})
+# → list of changed symbols + affected execution flows
+
+# For each non-trivial changed symbol:
+codragraph_impact({target: "<symbol>", direction: "upstream"})
+# → d=1 callers. Are they all updated in the PR?
+```
+
+If d=1 callers exist OUTSIDE your PR diff, that's the breakage waiting
+to happen. Either update them or document the migration path before
+review.
+
+## Author checklist before requesting review
+
+```
+- [ ] Branch rebased onto main (or merged main in, if shared)
+- [ ] CI green: gh pr checks <N>
+- [ ] codragraph_detect_changes — confirm scope is what you intended
+- [ ] codragraph_impact on each public symbol you changed — d=1 callers updated
+- [ ] PR title is conventional (feat: / fix: / docs: / etc.)
+- [ ] PR body has Summary + Test plan
+- [ ] Reviewers and labels set
+- [ ] gh pr ready <N> if it was draft
+```
+
+## Reviewer checklist (if you're reviewing)
+
+```
+- [ ] Pull the diff: gh pr diff <N> | less
+- [ ] Use codragraph-pr-review skill: detect_changes + impact + context
+- [ ] Run tests locally: gh pr checkout <N> && npm test
+- [ ] Approve / request-changes / comment via gh pr review <N>
+```
+
+```bash
+gh pr review <N> --approve --body "LGTM. Verified the impact graph clean."
+gh pr review <N> --request-changes --body "…"
+gh pr review <N> --comment --body "…"
+
+# Inline comments require the GitHub UI (gh CLI doesn't support them yet).
+```
+
+## Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Created PR from main | "There isn't anything to compare" | Push to a feature branch first |
+| Wrong base | PR shows commits from main | `gh pr edit <N> --base <correct-base>` |
+| Squash-merged a stacked PR's parent | Child PR shows 0 commits | `git rebase main` on child, force-push |
+| `gh pr merge --auto` without branch protection | Merges immediately, not on green | Configure branch-protection rules first |
+| Closing instead of merging | Commits don't land on main | `gh pr merge` not `gh pr close` |

package/skills/codragraph-gh-release-workflow.md

@@ -0,0 +1,187 @@
+---
+name: codragraph-gh-release-workflow
+description: "Use for the release workflow — semver bump, tag, generate release notes, attach assets, draft vs published, prerelease tagging, and propagating to npm. Examples: \"cut a release\", \"create a GitHub release\", \"draft release notes\", \"upload binaries to release\", \"prerelease v2 alpha\""
+---
+
+# Release Workflow with `gh`
+
+## When to Use
+
+- "Cut a 1.7.0 release."
+- "Draft release notes from commits."
+- "Attach the built binaries to the release."
+- "Mark this as a prerelease (alpha / beta / RC)."
+- "Re-publish notes after I edited them."
+
+## Pre-release checklist (do these BEFORE `gh release create`)
+
+```
+- [ ] Branch is main / release/x.y, fully synced
+- [ ] CHANGELOG.md updated (or ready to be auto-generated)
+- [ ] Version bumped in package.json / Cargo.toml / pyproject.toml
+- [ ] All commits since last tag intentional (no leftover wip)
+- [ ] CI green on the release commit (gh pr checks <N>)
+- [ ] codragraph diff <last-tag> HEAD --semantic — review removed APIs
+      (any removed public API = SemVer major; document loudly in notes)
+```
+
+## Cutting the release
+
+```bash
+# 1. Bump + commit version
+npm version 1.7.0 --no-git-tag-version            # or pnpm version, or manual edit
+git add package.json package-lock.json
+git commit -m "chore(release): 1.7.0"
+git push origin main
+
+# 2. Tag (annotated, signed if you have GPG):
+git tag -a v1.7.0 -m "Release 1.7.0"              # annotated
+git tag -s v1.7.0 -m "Release 1.7.0"              # signed (requires GPG setup)
+git push origin v1.7.0
+
+# 3. Create GitHub release. Auto-generate notes from commits since the previous tag:
+gh release create v1.7.0 --generate-notes
+```
+
+`--generate-notes` uses `.github/release.yml` (if present) for category
+filtering, or falls back to a flat list of commit titles.
+
+## Custom notes
+
+```bash
+# Notes from a file:
+gh release create v1.7.0 --notes-file RELEASE_NOTES.md
+
+# Inline (HEREDOC, the right way):
+gh release create v1.7.0 --notes "$(cat <<'EOF'
+## What's new
+- npx zero-install entry — no more 3-step setup
+- PR review GitHub Action (deterministic + LLM modes)
+- 17 built-in workflow skills
+
+## Breaking
+- None.
+
+## Upgrade
+\`\`\`
+npm i -g @codragraph/cli@1.7.0
+\`\`\`
+EOF
+)"
+
+# Edit notes after publishing:
+gh release edit v1.7.0 --notes-file new-notes.md
+```
+
+## Attach assets
+
+```bash
+# After creating the release, upload binaries / source bundles:
+gh release upload v1.7.0 dist/cli-linux-x64.tar.gz dist/cli-darwin-arm64.tar.gz
+
+# Or in one shot at create time:
+gh release create v1.7.0 dist/*.tar.gz dist/*.zip --generate-notes
+```
+
+## Draft vs published vs prerelease
+
+```bash
+# Draft (visible only to maintainers, not yet announced):
+gh release create v1.7.0 --draft --generate-notes
+
+# Promote draft → published:
+gh release edit v1.7.0 --draft=false
+
+# Prerelease (alpha / beta / RC — semver string ends with -alpha.N etc.):
+gh release create v2.0.0-alpha.1 --prerelease --generate-notes
+
+# Mark an existing release as latest (otherwise GitHub picks by semver):
+gh release edit v1.7.0 --latest
+```
+
+## Re-publish a release after editing
+
+```bash
+# View existing release:
+gh release view v1.7.0
+
+# Edit notes:
+gh release edit v1.7.0 --notes-file fixed-notes.md
+
+# Upload missing asset:
+gh release upload v1.7.0 dist/cli-windows-x64.zip
+```
+
+## Coordinating with npm publish
+
+For a TypeScript / Node package, the GitHub release and the npm publish
+are TWO separate events:
+
+```bash
+# Order: tag → npm publish → GH release (so the release links a version
+# users can `npm install`).
+
+git tag v1.7.0 && git push origin v1.7.0
+npm publish --access public                       # for scoped packages
+gh release create v1.7.0 --generate-notes
+```
+
+You can automate this in a workflow that triggers on `push` of a `v*` tag:
+
+```yaml
+on:
+  push:
+    tags: ['v*']
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci && npm run build
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+```
+
+## Why CodraGraph helps here
+
+The structural diff between two tags is the most honest changelog you'll
+ever produce — it's derived from the graph, not from commit messages
+that lie:
+
+```bash
+codragraph diff v1.6.4 v1.7.0 --semantic --json > /tmp/diff.json
+
+# What changed:
+jq '.semantic.addedAPIs | length, .semantic.removedAPIs | length, .semantic.classifiedModifications | length' /tmp/diff.json
+
+# Generate a structured "API changes" section for the release notes:
+jq -r '
+  "### Added APIs\n" +
+  ([.semantic.addedAPIs[] | "- `" + (.name // .id) + "`"] | join("\n")) +
+  "\n\n### Removed APIs (BREAKING)\n" +
+  ([.semantic.removedAPIs[] | "- `" + (.name // .id) + "`"] | join("\n"))
+' /tmp/diff.json
+```
+
+Removed APIs = SemVer major. Modified signatures with parameter-count
+changes = SemVer major. Use this to keep your bump honest.
+
+## Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Forgot to push the tag | GH release creation fails | `git push origin v1.7.0` |
+| `npm publish` before the tag | Tag not on the published commit | publish AFTER pushing the tag |
+| Removed an API but bumped only minor | Breaking change in non-major release | Always run `codragraph diff <prev> HEAD --semantic` and bump major if removedAPIs is non-empty |
+| `--generate-notes` produces noise | All commit messages flat-listed | Add `.github/release.yml` to categorize by labels / paths |
+| Wrong release marked `latest` | Older release stays as latest | `gh release edit <new-version> --latest` |
+| Released a prerelease as stable | Users on `latest` channel get unstable code | Always `--prerelease` for alpha / beta / RC |
+```