Metadata-Version: 2.5
Name: pr-comments
Version: 1.0.0
Summary: Extract every pull request comment (including deactivated authors) into CSV and a local review dashboard.
Project-URL: Homepage, https://github.com/framedparadox/pr-comments
Project-URL: Repository, https://github.com/framedparadox/pr-comments
Project-URL: Issues, https://github.com/framedparadox/pr-comments/issues
Author: framedparadox
License: MIT
License-File: LICENSE
Keywords: agent-skills,code-review,csv,github,pull-request
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# PR comment extractor

An **installable Agent Skills pack** that documents every pull request comment on a repository — including replies and comments from accounts that were later deactivated — then saves a local CSV and a review dashboard.

It is not a Claude Code or Copilot project layout. Coding agents install the skills into *their* skill directories.

## Install

Any Agent Skills client (Claude Code, Codex, Copilot, Cursor, OpenCode, and others):

```bash
npx skills add framedparadox/pr-comments
```

CLI (PyPI):

```bash
pip install pr-comments
# or
uv tool install pr-comments
pr-comments extract --repo owner/name
```

CLI (npm):

```bash
npm install -g pr-comments
# or one-shot
npx pr-comments extract --repo owner/name
```

The npm CLI still needs Python 3.10+ (and optionally `uv`) on `PATH`.

From Git, without waiting for a PyPI release:

```bash
uv tool install git+https://github.com/framedparadox/pr-comments
uvx --from git+https://github.com/framedparadox/pr-comments pr-comments extract --repo owner/name
```

From a checkout of this pack:

```bash
uv run pr-comments extract --git-dir /path/to/the/repo
# or
npx . extract --git-dir /path/to/the/repo
```

## What it does

1. Lists every pull request that **targets the main / default branch** (open, closed, merged).
2. Fetches conversation comments, inline review comments, replies, and review summaries.
3. Keeps humans, bots, and later-deactivated accounts (`comment_by=ghost`).
4. Writes `comments.csv` (commit id, PR date, comment date, comment by, comment body, and related fields).
5. Writes a self-contained `dashboard.html` for filtering and reading threads.

## Skills

All skill source lives in [`skills/`](skills/) (the layout `npx skills add` discovers). Coding agents load these when you ask to archive PR comments or browse the local dashboard.

### `extract-pr-comments`

Fetches **every** comment on pull requests that target the repository’s main / default branch and writes a local archive. Use it when documenting PR history, exporting review feedback, or building a comment CSV.

It resolves the repo from `--repo owner/name` or from `origin` of `--git-dir` / the current checkout, then resolves the base branch (`--base-branch` → GitHub default → `origin/HEAD` → `main`). Only PRs targeting that branch are included — open, closed, and merged.

Three GitHub sources are merged:

| Kind | What is kept |
| --- | --- |
| Conversation | Discussion-tab comments on those PRs |
| Inline review | Diff comments and their replies (`commit_id`, path, line) |
| Review summary | Non-empty review bodies (empty “reviewed” events are skipped) |

Authors are never filtered. Humans, bots (including Dependabot), and later-deactivated accounts are all kept. When GitHub returns `"user": null`, the row is stored as `comment_by=ghost` with `author_type=deleted`.

```bash
pr-comments extract \
  [--repo owner/name] [--git-dir PATH] [--host github.com] \
  [--base-branch main] [--out DIR] [--since 2024-01-01T00:00:00Z]
```

Checkout fallback: `python3 skills/extract-pr-comments/scripts/extract.py --repo owner/name`.

CSV columns always include commit id, PR created date, comment date, comment by, and comment body (see [`skills/extract-pr-comments/references/fields.md`](skills/extract-pr-comments/references/fields.md)). After the extract, the agent should report the CSV and dashboard paths; browsing is the `review-pr-comments` skill.

### `review-pr-comments`

Opens the archive produced by `extract-pr-comments`. It does **not** call GitHub again unless you ask for a fresh extract. Use it to browse, filter, or re-read comments — including `ghost` / deleted authors.

`dashboard.html` is self-contained (comment data is embedded) and works offline. Prefer opening that file in a browser. If `file://` is blocked, serve the export directory:

```bash
pr-comments serve --out pr-comments-export/<host>--<owner>--<repo>
```

Then open `http://127.0.0.1:8765/dashboard.html`. Checkout fallback: `python3 skills/review-pr-comments/scripts/serve.py --out DIR`.

In the dashboard you can:

- Filter by comment by, author type (`user` / `bot` / `deleted`), kind, PR, and comment date
- Search text, path, and commit SHA
- Expand a row for the full body, commit SHA, PR created date, links, and thread replies
- Toggle light and dark mode from the sun / moon control at the bottom of the sidebar
- Download the current filtered view as CSV (the full archive remains `comments.csv`)

## Artifacts

Default directory: `pr-comments-export/<host>--<owner>--<repo>/`

| File | Role |
| --- | --- |
| `comments.csv` | Spreadsheet archive (UTF-8 BOM, Excel-safe) |
| `comments.json` / `comments.jsonl` | Full records including diff hunks |
| `dashboard.html` | Local review UI (data embedded; works offline) |
| `meta.json` | Extract timestamp and counts |

```bash
pr-comments serve --out pr-comments-export/github.com--owner--repo
```

## Credentials

| Host | Preferred CLI | Environment fallback |
| --- | --- | --- |
| GitHub | `gh` | `GH_TOKEN` / `GITHUB_TOKEN` |

GitHub Enterprise: pass `--host your.ghe.example`.

## Future Enhancements

- Support extracting and reviewing comments for **multiple projects** in one run, with dashboard support across those projects.
- Update an existing extract in place when the export is already present, instead of always writing a full new archive.

## Tests

```bash
python3 -m unittest discover -s tests -v
```

## Publish to PyPI and npm

The project name is `pr-comments` on both [PyPI](https://pypi.org/project/pr-comments/) and [npm](https://www.npmjs.com/package/pr-comments). Maintainers:

1. Create the projects and add **Trusted Publishers** for this GitHub repository:
   - PyPI: workflow `publish.yml`, environment `pypi`
   - npm: workflow `publish.yml`, environment `npm`
2. Merge the release onto the `release` branch, tag it `v*`, and push both:

```bash
git checkout release
git merge --ff-only main   # or your release commit
git tag v1.0.0
git push origin release
git push origin v1.0.0
```

The [Publish](.github/workflows/publish.yml) workflow runs **only** for `v*` tags whose commit is on `release`. It builds and uploads the Python sdist/wheel and the npm package with OIDC (no tokens in the repo). Pushes to `release` without a `v*` tag, or `v*` tags on other branches, do not publish.

Locally:

```bash
uv build
uv publish
npm publish --access public
```
