prgenie 0.0.0-stage → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +10 -0
- package/LICENSE +21 -0
- package/README.md +199 -2
- package/markdownlint-prose-defaults.jsonc +8 -0
- package/package.json +36 -4
- package/runner.cjs +8962 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.2 — unreleased
|
|
4
|
+
|
|
5
|
+
- Publishable `prgenie` npm package with `prgenie` CLI (`mcp`, `serve`, `init`, `doctor`).
|
|
6
|
+
- Stdio MCP exposes runner tools (jobs + settings); shared job store lock for concurrent serve/MCP.
|
|
7
|
+
- Copy-paste MCP client setup in README; release workflow prepared (publish is manual).
|
|
8
|
+
- Every stdio/HTTP MCP reply carries `jsonrpc: "2.0"` and echoes the request id; `ping` is answered, malformed JSON gets a `-32700` parse error, and the stdio server exits once the client closes stdin.
|
|
9
|
+
- `continue_job` MCP tool; `prgenie config --client claude-code`; config snippets use the `prgenie-runner` server id.
|
|
10
|
+
- MIT `LICENSE` ships in the tarball.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PR Genie
|
|
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.
|
package/README.md
CHANGED
|
@@ -1,3 +1,200 @@
|
|
|
1
|
-
#
|
|
1
|
+
# prgenie (npm)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Local **implement → PR → review → fix** runner for agent workstations. Install once, wire your MCP client to **stdio** (`npx -y prgenie mcp`), and start jobs without running a long-lived HTTP server or bearer token.
|
|
4
|
+
|
|
5
|
+
Optional: `prgenie serve` for a browser dashboard and HTTP MCP (localhost + token).
|
|
6
|
+
|
|
7
|
+
Requires **Node.js 22+**, **git**, **GitHub CLI (`gh`)**, and **`cursor-agent`** for real (non–dry-run) jobs.
|
|
8
|
+
|
|
9
|
+
## Install (recommended: system-level)
|
|
10
|
+
|
|
11
|
+
The runner is a per-machine tool, so register it once for every repo rather than per project:
|
|
12
|
+
|
|
13
|
+
- **`npx` (recommended, no install):** every snippet below runs `npx -y prgenie mcp`. npm caches the package after the first launch.
|
|
14
|
+
- **Global install (pin a version):** `npm install -g prgenie` (or `npm install -g prgenie@0.1.2`), then use `"command": "prgenie", "args": ["mcp"]` in place of `npx -y prgenie mcp`. Upgrade with `npm install -g prgenie@latest`.
|
|
15
|
+
|
|
16
|
+
A repo-local devDependency also works but is optional; see [Optional: project devDependency](#optional-project-devdependency).
|
|
17
|
+
|
|
18
|
+
## Quick start — MCP client config
|
|
19
|
+
|
|
20
|
+
All snippets use the published CLI. No token is required for stdio. The server id `prgenie-runner` keeps this separate from the Cursor plugin's `prgenie` steward MCP.
|
|
21
|
+
|
|
22
|
+
### Cursor (`.cursor/mcp.json` in your repo or user config)
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"mcpServers": {
|
|
27
|
+
"prgenie-runner": {
|
|
28
|
+
"type": "stdio",
|
|
29
|
+
"command": "npx",
|
|
30
|
+
"args": ["-y", "prgenie", "mcp"]
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Use a **different server id** than the Cursor plugin’s `prgenie` steward MCP (e.g. `prgenie-runner` above) so both can coexist.
|
|
37
|
+
|
|
38
|
+
Print the same snippet: `npx -y prgenie config --client cursor`
|
|
39
|
+
|
|
40
|
+
### Claude Code (`claude mcp add`)
|
|
41
|
+
|
|
42
|
+
Register the stdio server for all your projects (verified with Claude Code 2.1):
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
claude mcp add --scope user prgenie-runner -- npx -y prgenie mcp
|
|
46
|
+
claude mcp list
|
|
47
|
+
# prgenie-runner: npx -y prgenie mcp - ✔ Connected
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- Everything after `--` is the server command, so Claude Code does not parse `-y` as its own flag.
|
|
51
|
+
- `--scope user` makes it available in every project (stored in `~/.claude.json`). `--scope project` writes a shareable `.mcp.json` in the repo root instead; the default `--scope local` applies to the current project only.
|
|
52
|
+
- With a global install: `claude mcp add --scope user prgenie-runner -- prgenie mcp`.
|
|
53
|
+
- Make every job a dry-run while you try it out: `claude mcp add --scope user prgenie-runner -e PRGENIE_RUNNER_DRY_RUN=1 -- npx -y prgenie mcp` (keep the server name before `-e`).
|
|
54
|
+
- Check it with `claude mcp get prgenie-runner`; remove it with `claude mcp remove prgenie-runner -s user`.
|
|
55
|
+
|
|
56
|
+
Print the same command: `npx -y prgenie config --client claude-code`
|
|
57
|
+
|
|
58
|
+
### Claude Desktop (`claude_desktop_config.json`)
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"mcpServers": {
|
|
63
|
+
"prgenie-runner": {
|
|
64
|
+
"command": "npx",
|
|
65
|
+
"args": ["-y", "prgenie", "mcp"]
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### VS Code (`.vscode/mcp.json`)
|
|
72
|
+
|
|
73
|
+
```json
|
|
74
|
+
{
|
|
75
|
+
"servers": {
|
|
76
|
+
"prgenie-runner": {
|
|
77
|
+
"type": "stdio",
|
|
78
|
+
"command": "npx",
|
|
79
|
+
"args": ["-y", "prgenie", "mcp"]
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Print the same snippet: `npx -y prgenie config --client vscode`
|
|
86
|
+
|
|
87
|
+
### Generic stdio client
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"mcpServers": {
|
|
92
|
+
"prgenie-runner": {
|
|
93
|
+
"type": "stdio",
|
|
94
|
+
"command": "npx",
|
|
95
|
+
"args": ["-y", "prgenie", "mcp"]
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Optional: project devDependency
|
|
102
|
+
|
|
103
|
+
**Optional — not the recommended setup.** Use this only when a repo must pin its own runner version. Prefer the system-level `npx` or global install above: MCP clients launch servers from their own working directory, and the runner's job store (`~/.prgenie/local-runner`) is per machine anyway.
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
pnpm add -D prgenie # or: npm install -D prgenie / yarn add -D prgenie
|
|
107
|
+
pnpm exec prgenie mcp
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Point the client at the repo-local binary, for example `"command": "pnpm", "args": ["exec", "prgenie", "mcp"]` in a project-scoped `.cursor/mcp.json`, or `claude mcp add --scope project prgenie-runner -- pnpm exec prgenie mcp`.
|
|
111
|
+
|
|
112
|
+
## First job walkthrough
|
|
113
|
+
|
|
114
|
+
1. **Initialize data dir + token (for `serve` later)**
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
npx -y prgenie init
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Creates `~/.prgenie/local-runner` (override with `PRGENIE_RUNNER_DATA_DIR`) and `runner.token` for HTTP mode.
|
|
121
|
+
|
|
122
|
+
2. **Check prerequisites**
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npx -y prgenie doctor
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Verifies Node, git, `gh auth`, and `cursor-agent` on PATH.
|
|
129
|
+
|
|
130
|
+
3. **Dry-run job over MCP** (no real agent; safe smoke test)
|
|
131
|
+
|
|
132
|
+
In your MCP client, call tool `start_job` with:
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"branch": "chore/runner-smoke",
|
|
137
|
+
"promptFile": "README.md",
|
|
138
|
+
"repoPath": "/path/to/your/git/repo",
|
|
139
|
+
"dryRun": true,
|
|
140
|
+
"maxRounds": 1
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Then `get_job` with the returned `id`.
|
|
145
|
+
|
|
146
|
+
4. **Real job on a test branch**
|
|
147
|
+
|
|
148
|
+
Same as above with `dryRun: false` (or omit it), a real `repoPath` / `remote`, and `cursor-agent` available. Use a throwaway branch name.
|
|
149
|
+
|
|
150
|
+
## MCP tools
|
|
151
|
+
|
|
152
|
+
| Tool | Purpose |
|
|
153
|
+
| ----------------------------- | --------------------------------- |
|
|
154
|
+
| `start_job` | Start the loop |
|
|
155
|
+
| `get_job` | Status + log tail |
|
|
156
|
+
| `list_jobs` | Dashboard list |
|
|
157
|
+
| `steer_job` | Queue follow-up prompt |
|
|
158
|
+
| `stop_job` | Stop running job |
|
|
159
|
+
| `archive_job` / `restore_job` | Remove / restore finished jobs |
|
|
160
|
+
| `continue_job` | Extra fix→review round(s) |
|
|
161
|
+
| `restart_runner` | Graceful restart adoption preview |
|
|
162
|
+
| `settings` | Read or patch runner settings |
|
|
163
|
+
|
|
164
|
+
Stdio and `serve` share one on-disk job store (file lock when both run).
|
|
165
|
+
|
|
166
|
+
## Optional HTTP dashboard
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
export PRGENIE_RUNNER_TOKEN="$(cat ~/.prgenie/local-runner/runner.token)"
|
|
170
|
+
npx -y prgenie serve
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Open `http://127.0.0.1:9473/` (default). MCP over HTTP: `POST /mcp` with `Authorization: Bearer $PRGENIE_RUNNER_TOKEN`.
|
|
174
|
+
|
|
175
|
+
## Troubleshooting
|
|
176
|
+
|
|
177
|
+
| Symptom | What to do |
|
|
178
|
+
| ----------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
179
|
+
| **`gh` not authenticated** | Run `gh auth login`; re-run `prgenie doctor`. Jobs need `gh` for PR/CI. |
|
|
180
|
+
| **`cursor-agent` missing** | Install Cursor CLI; or pick another driver in `settings` after `serve`. |
|
|
181
|
+
| **Branch held by another worktree** | Another job or git worktree uses that branch. Stop/archive the other job or pick a new branch. |
|
|
182
|
+
| **Model unavailable on your plan** | Override `model` in `start_job` or set defaults via `settings` / Setup UI. |
|
|
183
|
+
| **Job stuck (watchdog)** | Check dashboard logs; `stop_job`, then `archive_job`. Tune watchdog via `settings` or Setup. |
|
|
184
|
+
|
|
185
|
+
## Environment
|
|
186
|
+
|
|
187
|
+
| Variable | Purpose |
|
|
188
|
+
| --------------------------------------------- | --------------------------------------------------------------- |
|
|
189
|
+
| `PRGENIE_RUNNER_DATA_DIR` | Job store (default `~/.prgenie/local-runner`) |
|
|
190
|
+
| `PRGENIE_RUNNER_TOKEN` | Bearer for **`serve` only** (or use `runner.token` from `init`) |
|
|
191
|
+
| `PRGENIE_RUNNER_DRY_RUN` | `1` — global dry-run default |
|
|
192
|
+
| `PRGENIE_RUNNER_HOST` / `PRGENIE_RUNNER_PORT` | HTTP bind (default `127.0.0.1:9473`) |
|
|
193
|
+
|
|
194
|
+
## Monorepo development
|
|
195
|
+
|
|
196
|
+
Source lives under `local-runner/` in [github.com/radiancelux/prgenie](https://github.com/radiancelux/prgenie). From the repo root: `pnpm build && pnpm local-runner mcp`.
|
|
197
|
+
|
|
198
|
+
## License
|
|
199
|
+
|
|
200
|
+
MIT — see [`LICENSE`](LICENSE) (shipped in the npm package).
|
package/package.json
CHANGED
|
@@ -1,6 +1,38 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "prgenie",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.2",
|
|
4
|
+
"description": "PR Genie local runner — MCP stdio job loop (implement → PR → review → fix)",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "https://github.com/radiancelux/prgenie.git",
|
|
9
|
+
"directory": "packages/npm-prgenie"
|
|
10
|
+
},
|
|
11
|
+
"bugs": "https://github.com/radiancelux/prgenie/issues",
|
|
12
|
+
"homepage": "https://github.com/radiancelux/prgenie/tree/main/packages/npm-prgenie#readme",
|
|
13
|
+
"author": "PR Genie contributors",
|
|
14
|
+
"type": "commonjs",
|
|
15
|
+
"engines": {
|
|
16
|
+
"node": ">=22"
|
|
17
|
+
},
|
|
18
|
+
"bin": {
|
|
19
|
+
"prgenie": "./runner.cjs"
|
|
20
|
+
},
|
|
21
|
+
"files": [
|
|
22
|
+
"runner.cjs",
|
|
23
|
+
"markdownlint-prose-defaults.jsonc",
|
|
24
|
+
"README.md",
|
|
25
|
+
"CHANGELOG.md",
|
|
26
|
+
"LICENSE"
|
|
27
|
+
],
|
|
28
|
+
"publishConfig": {
|
|
29
|
+
"access": "public",
|
|
30
|
+
"provenance": true
|
|
31
|
+
},
|
|
32
|
+
"keywords": [
|
|
33
|
+
"mcp",
|
|
34
|
+
"cursor",
|
|
35
|
+
"local-runner",
|
|
36
|
+
"pull-request"
|
|
37
|
+
]
|
|
38
|
+
}
|