prq-cli 0.7.0 → 0.9.0

package/README.md

@@ -95,19 +95,21 @@ prq skill --global   # install globally
 
 ## Pluggable Actions
 
-PRQ doesn't force a workflow. Every action is a configurable shell command template. Override the defaults or add your own in `.prqrc.json`:
+PRQ doesn't force a workflow. Every action is a configurable shell command template — inline commands or scripts. Override the defaults or add your own in `.prqrc.json`.
+
+Actions run with full terminal control. When you trigger an action, prq suspends its TUI, the command takes over the screen (interactive tools like Claude Code work as normal), and prq resumes when the command exits.
 
 ### Use Claude Code for reviews
 
 ```json
 {
   "actions": {
-    "review": "claude -p '/review {url}'"
+    "review": "claude '/review {url}'"
   }
 }
 ```
 
-Now `prq review 482` dispatches to Claude Code.
+Now `prq review 482` opens an interactive Claude Code session.
 
 ### Use Codex for reviews
 
@@ -119,6 +121,18 @@ Now `prq review 482` dispatches to Claude Code.
 }
 ```
 
+### Use a script for complex workflows
+
+```json
+{
+  "actions": {
+    "review": "./scripts/review.sh {number} {url}"
+  }
+}
+```
+
+The script handles its own logic — session management, resuming, branching, whatever you need.
+
 ### Use gh CLI to checkout
 
 ```json
@@ -143,9 +157,11 @@ With no config, `prq review` opens the files changed tab and `prq open` opens th
 | `{number}` | `482` |
 | `{owner}` | `org` |
 | `{repo}` | `repo` |
+| `{fullRepo}` | `org/repo` |
 | `{title}` | `fix: handle edge case` |
 | `{author}` | `alice` |
 | `{days}` | `5` |
+| `{category}` | `needs-re-review` |
 
 ## Agent & Automation
 
@@ -196,7 +212,7 @@ Full example:
   "repos": ["org/repo1", "org/repo2"],
   "staleDays": 5,
   "actions": {
-    "review": "claude -p '/review {url}'",
+    "review": "claude '/review {url}'",
     "checkout": "gh pr checkout {number} --repo {owner}/{repo}",
     "approve": "gh pr review {number} --repo {owner}/{repo} --approve"
   }

package/dist/bin/prq.js

@@ -6424,7 +6424,7 @@ function getAction(name, config) {
 function listActions(config) {
   return { ...DEFAULT_ACTIONS, ...config.actions };
 }
-function buildContext(pr) {
+function buildContext(pr, category = "") {
   const days = Math.floor((Date.now() - new Date(pr.updatedAt || Date.now()).getTime()) / 86400000);
   return {
     url: pr.url,
@@ -6434,7 +6434,8 @@ function buildContext(pr) {
     fullRepo: `${pr.owner}/${pr.repo}`,
     title: pr.title,
     author: pr.author,
-    days
+    days,
+    category
   };
 }
 function interpolate(template, context) {
@@ -6481,98 +6482,62 @@ Available actions: ${available}`);
 // src/commands/skill.ts
 var SKILL_CONTENT = `---
 name: prq
-description: PR review queue manager. Use when the user wants to check their PR review queue, review PRs, nudge stale PRs, or manage code review workflow. Triggers on mentions of "review queue", "PRs waiting", "stale PRs", "what needs review", or "prq".
+description: PR review queue manager. Use when the user wants to check their PR review queue, review PRs, nudge stale PRs, open PRs, or manage code review workflow. Triggers on mentions of "review queue", "PRs waiting", "stale PRs", "what needs review", "open PR", "nudge", or "prq".
 ---
 
-# PRQ — PR Review Queue
+# PRQ CLI
 
-You have access to the \`prq\` CLI tool installed on this machine. Use it to help the user manage their code review queue.
+\`prq\` is a CLI tool for managing code review queues. It's installed on this machine.
 
-## Step 1: Get the queue
-
-Run this command to get the user's current review queue:
+## Commands
 
 \`\`\`bash
+# Show the review queue (JSON for parsing)
 prq status --json
-\`\`\`
 
-This returns a JSON object with categorized PRs:
-- **needs-re-review** — PRs where the user left a review but new commits were pushed after
-- **requested** — PRs where the user is a requested reviewer
-- **stale** — PRs with no activity for N days
-- **waiting-on-others** — PRs the user authored that are waiting on someone else
+# Open a PR in the browser
+prq open <number>
+prq open <owner/repo#number>
 
-## Step 2: Present the queue
+# Open files changed tab for review
+prq review <number>
 
-Show the results in a clear, scannable format grouped by category. For each PR, show:
-- The category symbol (◆ needs re-review, ● requested, ○ stale, ◇ waiting)
-- The repo and PR number
-- The title
-- The detail (e.g., "new commits since your review 2d ago")
+# Post a nudge comment on a stale PR
+prq nudge <number> --yes
+prq nudge <number> --message "Custom message" --yes
 
-Then ask what the user wants to do.
+# Run any configured action
+prq run <action> <number>
+\`\`\`
 
-## Step 3: Act on PRs
+## JSON output
 
-When the user asks to act on a PR, check the \`.prqrc.json\` file in the current directory (or \`~/.config/prq/config.json\`) for custom actions:
+\`prq status --json\` returns:
 
 \`\`\`json
 {
-  "actions": {
-    "review": "/review {url}",
-    "nudge": "shell:prq nudge {number} --yes"
-  }
+  "user": "caio-pizzol",
+  "prs": [
+    {
+      "category": "needs-re-review",
+      "repo": "org/repo",
+      "number": 2439,
+      "title": "fix: something",
+      "author": "alice",
+      "url": "https://github.com/org/repo/pull/2439",
+      "detail": "New commits since your review 1d ago"
+    }
+  ]
 }
 \`\`\`
 
-### Action resolution
-
-For each action template:
-- **Starts with \`/\`** — it's a Claude Code skill. Invoke it by running the skill with the interpolated value. For example, \`/review https://github.com/org/repo/pull/123\`
-- **Starts with \`shell:\`** — it's a shell command. Run it with the Bash tool. For example, \`prq nudge 123 --yes\`
-- **Otherwise** — treat it as a prompt. Send it as a message.
-
-### Template variables
-
-Replace these in the action template:
-- \`{url}\` — full PR URL
-- \`{number}\` — PR number
-- \`{owner}\` — repo owner
-- \`{repo}\` — repo name
-- \`{title}\` — PR title
-- \`{author}\` — PR author
-
-### Default actions (if no config found)
-
-If no actions are configured, use these defaults:
-- **review** — invoke \`/review {url}\` if the /review skill exists, otherwise run \`prq review {number}\` to open files changed in browser
-- **nudge** — run \`prq nudge {number} --yes\`
-- **open** — run \`prq open {number}\`
-
-## Step 4: Batch operations
-
-If the user says things like "review all needs-re-review PRs" or "nudge all stale PRs":
-
-1. Filter the queue JSON by the requested category
-2. Confirm the list with the user: "I'll review these 3 PRs: #2439, #2380, #2352. Proceed?"
-3. Execute the action on each PR sequentially
-
-## Examples
-
-**User:** "check my review queue"
-→ Run \`prq status --json\`, present results, ask what to do
-
-**User:** "review 2439"
-→ Look up action for "review", interpolate with PR data, execute
-
-**User:** "nudge all stale PRs"
-→ Filter stale PRs from queue, confirm, run nudge on each
+Categories: \`needs-re-review\`, \`requested\`, \`stale\`, \`waiting-on-others\`.
 
-**User:** "what PRs are waiting on me?"
-→ Run \`prq status --json\`, show only needs-re-review and requested categories
+## Usage
 
-**User:** "/prq" with no context
-→ Run \`prq status --json\`, present full queue, ask what to do
+- When the user asks about their review queue, run \`prq status --json\` and present the results grouped by category.
+- When the user asks to open, review, or nudge a PR, use the corresponding \`prq\` command.
+- For batch operations ("nudge all stale PRs"), filter the JSON output and confirm with the user before acting.
 `;
 function skillCommand(global) {
   if (global) {
@@ -6797,14 +6762,34 @@ function render(state) {
   process.stdout.write(lines.join(`
 `));
 }
-async function runAction(actionName, template, pr, state) {
-  const cmd = interpolate(template, buildContext(toResolvedPR(pr)));
-  state.message = source_default.dim(`running ${actionName} on ${pr.repo}#${pr.number}...`);
+function suspend() {
+  process.stdin.setRawMode(false);
+  process.stdin.pause();
+  process.stdin.removeAllListeners("data");
+  process.stdout.write("\x1B[?25h\x1B[2J\x1B[H");
+}
+function resume(state, onData) {
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+  process.stdout.write("\x1B[?25l");
+  process.stdin.on("data", onData);
   render(state);
+}
+async function runAction(actionName, template, pr, state, onData) {
+  const context = buildContext(toResolvedPR(pr), pr.category);
+  const cmd = interpolate(template, context);
+  suspend();
+  process.stdout.write(source_default.dim(`
+  running ${actionName} on ${pr.repo}#${pr.number}...
+
+`));
   try {
     await executeCommand(cmd);
+    resume(state, onData);
     return source_default.green(`${actionName}: ${pr.repo}#${pr.number}`);
   } catch {
+    resume(state, onData);
     return source_default.red(`${actionName} failed`);
   }
 }
@@ -6828,33 +6813,22 @@ async function interactiveMode(result, config) {
 `);
     return;
   }
-  process.stdin.setRawMode(true);
-  process.stdin.resume();
-  process.stdin.setEncoding("utf8");
-  process.stdout.write("\x1B[?25l");
-  render(state);
   return new Promise((resolve) => {
-    const cleanup = () => {
-      process.stdin.setRawMode(false);
-      process.stdin.pause();
-      process.stdin.removeAllListeners("data");
-      process.stdout.write("\x1B[?25h\x1B[2J\x1B[H");
-    };
-    process.stdin.on("data", async (key) => {
+    const onData = async (key) => {
       const pr = result.prs[state.selectedIndex];
       if (state.actionMenu) {
         if (key === "q" || key === "\x1B" || key === "a") {
           state.actionMenu = null;
           state.message = "";
         } else if (key === "\x03") {
-          cleanup();
+          suspend();
           resolve();
           return;
         } else {
           const idx = parseInt(key, 10);
           if (idx >= 1 && idx <= state.actionMenu.length) {
             const action = state.actionMenu[idx - 1];
-            state.message = await runAction(action.name, action.template, pr, state);
+            state.message = await runAction(action.name, action.template, pr, state, onData);
             state.actionMenu = null;
           }
         }
@@ -6864,7 +6838,7 @@ async function interactiveMode(result, config) {
       switch (key) {
         case "q":
         case "\x03":
-          cleanup();
+          suspend();
           resolve();
           return;
         case "\x1B[A":
@@ -6878,21 +6852,21 @@ async function interactiveMode(result, config) {
         case "o": {
           const template = allActions.open;
           if (template) {
-            state.message = await runAction("open", template, pr, state);
+            state.message = await runAction("open", template, pr, state, onData);
           }
           break;
         }
         case "r": {
           const template = allActions.review;
           if (template) {
-            state.message = await runAction("review", template, pr, state);
+            state.message = await runAction("review", template, pr, state, onData);
           }
           break;
         }
         case "n": {
           const template = allActions.nudge;
           if (template) {
-            state.message = await runAction("nudge", template, pr, state);
+            state.message = await runAction("nudge", template, pr, state, onData);
           }
           break;
         }
@@ -6920,7 +6894,8 @@ async function interactiveMode(result, config) {
           break;
       }
       render(state);
-    });
+    };
+    resume(state, onData);
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "prq-cli",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"description": "PR Queue — see what code reviews need your attention",
 	"type": "module",
 	"bin": {