Skip to content

Commit b62010a

Browse files
lordhumunguzlordhumunguz
committed
Initial implementation of prpr CLI v0.1.0
- Core CLI commands: sync, ls, reply, check-new - GitHub API integration via gh CLI - Comment classification (self/teammate/ai_bot) - JSON-based thread storage - 90% test coverage with unit and integration tests - CI/CD pipeline with GitHub Actions - Full documentation and MIT license
1 parent bcb1ca9 commit b62010a

25 files changed

Lines changed: 2208 additions & 0 deletions

‎.claude/settings.local.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(poetry run:*)"
5+
],
6+
"deny": []
7+
}
8+
}

‎.coverage‎

52 KB
Binary file not shown.

‎.github/workflows/ci.yml‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.10", "3.11"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python ${{ matrix.python-version }}
20+
uses: actions/setup-python@v4
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
24+
- name: Install Poetry
25+
uses: snok/install-poetry@v1
26+
with:
27+
version: 1.6.1
28+
virtualenvs-create: true
29+
virtualenvs-in-project: true
30+
31+
- name: Load cached venv
32+
id: cached-poetry-dependencies
33+
uses: actions/cache@v3
34+
with:
35+
path: .venv
36+
key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
37+
38+
- name: Install dependencies
39+
if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
40+
run: poetry install --no-interaction --no-root
41+
42+
- name: Install project
43+
run: poetry install --no-interaction
44+
45+
- name: Run linting with ruff
46+
run: poetry run ruff check prpr/
47+
48+
- name: Run formatting check with black
49+
run: poetry run black --check prpr/
50+
51+
- name: Run tests with coverage
52+
run: poetry run pytest --cov=prpr --cov-report=xml --cov-report=term-missing --cov-fail-under=90
53+
54+
- name: Upload coverage to Codecov
55+
uses: codecov/codecov-action@v3
56+
with:
57+
file: ./coverage.xml
58+
flags: unittests
59+
name: codecov-umbrella
60+
fail_ci_if_error: false
61+
62+
acceptance:
63+
runs-on: ubuntu-latest
64+
needs: test
65+
66+
steps:
67+
- uses: actions/checkout@v4
68+
69+
- name: Set up Python 3.10
70+
uses: actions/setup-python@v4
71+
with:
72+
python-version: "3.10"
73+
74+
- name: Install Poetry
75+
uses: snok/install-poetry@v1
76+
with:
77+
version: 1.6.1
78+
virtualenvs-create: true
79+
virtualenvs-in-project: true
80+
81+
- name: Install dependencies
82+
run: poetry install --no-interaction
83+
84+
- name: Install GitHub CLI
85+
run: |
86+
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
87+
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
88+
sudo apt update
89+
sudo apt install gh
90+
91+
- name: Test CLI help
92+
run: poetry run prpr --help
93+
94+
- name: Test pipx installation
95+
run: |
96+
pip install pipx
97+
pipx install .
98+
prpr --help
99+
100+
build:
101+
runs-on: ubuntu-latest
102+
needs: [test, acceptance]
103+
104+
steps:
105+
- uses: actions/checkout@v4
106+
107+
- name: Set up Python 3.10
108+
uses: actions/setup-python@v4
109+
with:
110+
python-version: "3.10"
111+
112+
- name: Install Poetry
113+
uses: snok/install-poetry@v1
114+
with:
115+
version: 1.6.1
116+
117+
- name: Build package
118+
run: poetry build
119+
120+
- name: Upload build artifacts
121+
uses: actions/upload-artifact@v3
122+
with:
123+
name: dist
124+
path: dist/

‎CLAUDE.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# prpr CLI Development Guide
2+
3+
## Project Overview
4+
**prpr** is a Python CLI tool for managing GitHub pull request comments, designed to be both human and AI agent friendly. This MVP (v0.1.0) focuses on four core commands: `sync`, `ls`, `reply`, and `check-new`.
5+
6+
## Technical Requirements
7+
8+
### Core Commands
9+
- `prpr sync` - Fetch PR threads and create `.prpr/threads.json`
10+
- `prpr ls` - Filter and display threads as JSON to stdout
11+
- `prpr reply <thread-id> "<msg>"` - Post replies to GitHub
12+
- `prpr check-new --since <ISO>` - List new comments (nice-to-have)
13+
14+
### Architecture
15+
- **Python 3.10+** with Poetry for dependency management
16+
- **Typer** for CLI interface
17+
- **GitHub CLI (`gh`)** as external dependency
18+
- **JSON-based** data storage and API communication
19+
- **TOML configuration** in `~/.prpr.toml`
20+
21+
### Directory Structure (Required)
22+
```
23+
prpr/
24+
├─ prpr/
25+
│ ├─ __main__.py # Typer entry point
26+
│ ├─ gh.py # GitHub CLI wrapper
27+
│ ├─ classifier.py # Comment classification logic
28+
│ ├─ io.py # JSON read/write operations
29+
│ └─ config.py # Configuration loader
30+
├─ tests/
31+
│ ├─ unit/
32+
│ ├─ integration/
33+
│ └─ data/sample_gh.json
34+
├─ pyproject.toml # Poetry configuration
35+
└─ .github/workflows/ci.yml
36+
```
37+
38+
## Development Guidelines
39+
40+
### Exit Codes
41+
- `0` - Success
42+
- `9` - Missing dependency (GitHub CLI not found)
43+
- `10` - API failure
44+
- `11` - Invalid arguments
45+
46+
### JSON Schema (v0.1.0)
47+
```json
48+
{
49+
"schema_version": "0.1.0",
50+
"pr": 123,
51+
"updated_at": "2025-07-10T18:00:00Z",
52+
"threads": [
53+
{
54+
"id": "THR_abc123",
55+
"file": "src/app.py",
56+
"line": 42,
57+
"state": "open",
58+
"author_login": "alice",
59+
"author_type": "teammate",
60+
"body": "Nit: rename var",
61+
"created_at": "2025-07-09T12:34:56Z"
62+
}
63+
]
64+
}
65+
```
66+
67+
### Comment Classification
68+
Author types: `self`, `teammate`, `ai_bot`
69+
- Configuration via `~/.prpr.toml` with `ai_author_patterns` array
70+
- Default patterns should include common bot names
71+
72+
### Testing Requirements
73+
- **90%+ test coverage** (enforced by CI)
74+
- **Unit tests** for all core logic
75+
- **Integration tests** for CLI commands
76+
- **Mocked GitHub API** calls (no real API hits in tests)
77+
- **pytest-cov** for coverage reporting
78+
79+
## Quality Standards
80+
81+
### Code Formatting
82+
- **ruff** for linting
83+
- **black** for code formatting
84+
- Both checked in CI pipeline
85+
86+
### CI/CD Requirements
87+
- **GitHub Actions** workflow
88+
- **Python 3.10 & 3.11** test matrix
89+
- **Coverage reporting** with badge
90+
- **All 6 acceptance tests** must pass
91+
92+
### Documentation
93+
- **README** with quick-start section
94+
- **MIT License** file
95+
- **Coverage badge** in README
96+
- **Help text** for all commands
97+
98+
## Development Commands
99+
100+
### Setup
101+
```bash
102+
poetry install
103+
poetry run prpr --help
104+
```
105+
106+
### Testing
107+
```bash
108+
poetry run pytest --cov=prpr tests/
109+
poetry run pytest tests/unit/
110+
poetry run pytest tests/integration/
111+
```
112+
113+
### Code Quality
114+
```bash
115+
poetry run ruff check prpr/
116+
poetry run black --check prpr/
117+
poetry run ruff format prpr/
118+
poetry run black prpr/
119+
```
120+
121+
## Key Implementation Notes
122+
123+
1. **GitHub CLI Dependency**: Always check for `gh` binary in PATH
124+
2. **PR Detection**: Must work with `refs/pull/123/head` checkout
125+
3. **Configuration**: Support `~/.prpr.toml` for user preferences
126+
4. **Error Handling**: Proper exit codes and error messages
127+
5. **JSON Output**: Clean, parseable JSON for machine consumption
128+
129+
## Repository
130+
- **GitHub**: `source-medium/prpr`
131+
- **License**: MIT
132+
- **Python**: 3.10+
133+
- **Installation**: `pipx install .`
134+
135+
## Done Definition Checklist
136+
- [ ] All six CI tests pass on GitHub Actions
137+
- [ ] `prpr --help` shows all four verbs with options
138+
- [ ] README quick-start section works when copy-pasted
139+
- [ ] `pipx install .` succeeds on Python 3.10 & 3.11
140+
- [ ] MIT license file present
141+
- [ ] Code formatted by ruff & black, checked in CI
142+
- [ ] Coverage badge added to README

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 prpr contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)