pr-shepherd 0.15.2 → 0.16.0

package/bin/commands/status.mjs

@@ -1,126 +0,0 @@
-/**
- * `shepherd status PR1 [PR2 PR3 …]`
- *
- * Fetches readiness status for one or more PRs and prints a table.
- * Issues a single GraphQL request with one alias per PR number rather than
- * N separate requests, so the round-trip count is always 1 (plus optional
- * per-PR pagination calls when a PR has > 100 review threads).
- *
- * Exit code: 0 if all PRs are READY, non-zero otherwise.
- */
-import { graphql, getRepoInfo } from "../github/client.mjs";
-import { MULTI_PR_STATUS_QUERY_WITH_CURSOR } from "../github/queries.mjs";
-export async function runStatus(opts) {
-    if (opts.prNumbers.length === 0)
-        return [];
-    const repo = await getRepoInfo();
-    const doc = buildBatchStatusQuery(opts.prNumbers);
-    const result = await graphql(doc, {
-        owner: repo.owner,
-        repo: repo.name,
-    });
-    const summaries = await Promise.all(opts.prNumbers.map((pr) => {
-        const rawPr = result.data.repository[`pr_${pr}`];
-        if (!rawPr) {
-            throw new Error(`PR #${pr} not found in ${repo.owner}/${repo.name}`);
-        }
-        return paginateAndBuild(pr, rawPr, repo.owner, repo.name);
-    }));
-    return summaries;
-}
-// ---------------------------------------------------------------------------
-// Internal
-// ---------------------------------------------------------------------------
-function buildBatchStatusQuery(prNumbers) {
-    const uniquePrs = [...new Set(prNumbers.filter((n) => n > 0))];
-    const f = "number title state isDraft mergeStateStatus reviewDecision " +
-        "reviewThreads(last:100){totalCount pageInfo{hasPreviousPage startCursor} nodes{isResolved}} " +
-        "commits(last:1){nodes{commit{statusCheckRollup{state}}}}";
-    const aliases = uniquePrs.map((n) => `pr_${n}:pullRequest(number:${n}){${f}}`).join(" ");
-    return `query MultiPrStatusBatch($owner:String!,$repo:String!){repository(owner:$owner,name:$repo){${aliases}}}`;
-}
-async function paginateAndBuild(pr, p, owner, repo) {
-    let allNodes = p.reviewThreads.nodes;
-    if (p.reviewThreads.totalCount > p.reviewThreads.nodes.length) {
-        const MAX_THREAD_PAGES = 10;
-        let pagesFetched = 0;
-        const totalCount = p.reviewThreads.totalCount;
-        let cursor = p.reviewThreads.pageInfo?.startCursor ?? null;
-        while (cursor !== null) {
-            if (++pagesFetched > MAX_THREAD_PAGES) {
-                process.stderr.write(`pr-shepherd: thread pagination cap reached for PR #${pr}: fetched ${allNodes.length} of ${totalCount} threads\n`);
-                break;
-            }
-            // eslint-disable-next-line no-await-in-loop
-            const extra = await graphql(MULTI_PR_STATUS_QUERY_WITH_CURSOR, {
-                owner,
-                repo,
-                pr,
-                cursor,
-            });
-            const p2 = extra.data.repository.pullRequest;
-            if (!p2)
-                break;
-            allNodes = [...p2.reviewThreads.nodes, ...allNodes];
-            if (!p2.reviewThreads.pageInfo?.hasPreviousPage || !p2.reviewThreads.pageInfo.startCursor) {
-                break;
-            }
-            cursor = p2.reviewThreads.pageInfo.startCursor;
-        }
-    }
-    const unresolvedThreads = allNodes.filter((n) => !n.isResolved).length;
-    const ciState = p.commits.nodes[0]?.commit.statusCheckRollup?.state ?? null;
-    const threadsTruncated = p.reviewThreads.totalCount > allNodes.length;
-    return {
-        number: p.number,
-        title: p.title,
-        state: p.state,
-        isDraft: p.isDraft,
-        mergeStateStatus: p.mergeStateStatus,
-        reviewDecision: p.reviewDecision,
-        unresolvedThreads,
-        ciState,
-        threadsTruncated,
-    };
-}
-// ---------------------------------------------------------------------------
-// Output helpers
-// ---------------------------------------------------------------------------
-export function formatStatusTable(summaries, repoFull) {
-    const heading = `# ${repoFull} — PR status (${summaries.length})`;
-    if (summaries.length === 0)
-        return heading;
-    const rows = summaries.map((s) => {
-        const raw = s.title.length > 50 ? `${s.title.slice(0, 47)}...` : s.title;
-        const title = raw.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\n/g, " ");
-        return `| #${s.number} | ${title} | ${deriveVerdict(s)} | ${s.ciState ?? "—"} |`;
-    });
-    const table = ["| PR | Title | Verdict | CI |", "| --- | --- | --- | --- |", ...rows].join("\n");
-    const footnotes = summaries
-        .filter((s) => s.threadsTruncated)
-        .map((s) => `> Note: PR #${s.number} threads truncated — run \`pr-shepherd check ${s.number}\` for full count.`);
-    return [heading, table, ...footnotes].join("\n\n");
-}
-export function deriveVerdict(s) {
-    if (s.state === "MERGED")
-        return "MERGED";
-    if (s.state === "CLOSED")
-        return "CLOSED";
-    if (s.isDraft)
-        return "DRAFT";
-    if (s.mergeStateStatus === "CLEAN" &&
-        s.unresolvedThreads === 0 &&
-        s.ciState === "SUCCESS" &&
-        s.reviewDecision !== "CHANGES_REQUESTED") {
-        return "READY";
-    }
-    if (s.mergeStateStatus === "BLOCKED" || s.mergeStateStatus === "HAS_HOOKS")
-        return "BLOCKED";
-    if (s.mergeStateStatus === "DIRTY")
-        return "CONFLICTS";
-    if (s.ciState === "PENDING" || s.ciState === "EXPECTED")
-        return "IN PROGRESS";
-    if (s.ciState === "FAILURE" || s.ciState === "ERROR")
-        return "FAILING";
-    return s.mergeStateStatus;
-}

package/bin/github/gql/multi-pr-status-paged.gql

@@ -1,31 +0,0 @@
-query MultiPrStatusPaged($owner: String!, $repo: String!, $pr: Int!, $cursor: String) {
-  repository(owner: $owner, name: $repo) {
-    pullRequest(number: $pr) {
-      number
-      title
-      state
-      isDraft
-      mergeStateStatus
-      reviewDecision
-      reviewThreads(last: 100, before: $cursor) {
-        totalCount
-        pageInfo {
-          hasPreviousPage
-          startCursor
-        }
-        nodes {
-          isResolved
-        }
-      }
-      commits(last: 1) {
-        nodes {
-          commit {
-            statusCheckRollup {
-              state
-            }
-          }
-        }
-      }
-    }
-  }
-}

package/bin/reporters/check-instructions.mjs

@@ -1,69 +0,0 @@
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
-/**
- * Build the numbered instruction steps for the agent to follow after a `check` run.
- * All rebase policy, CI budget policy, and ready-to-merge gating live here so the
- * skill stays a thin dispatcher and these rules co-evolve with the CLI data model.
- */
-export function buildCheckInstructions(report, opts) {
-    const runtime = opts?.runtime ?? "claude";
-    const { mergeStatus, checks, threads, comments, changesRequestedReviews, status } = report;
-    const instructions = [];
-    // 1. Summary
-    const totalActionable = threads.actionable.length +
-        threads.resolutionOnly.length +
-        comments.actionable.length +
-        changesRequestedReviews.length;
-    const total = checks.passing.length +
-        checks.failing.length +
-        checks.inProgress.length +
-        checks.skipped.length;
-    const copilotNote = mergeStatus.copilotReviewInProgress ? " (Copilot review in progress)" : "";
-    instructions.push(`Report: merge status is ${mergeStatus.status}${copilotNote}, CI ${checks.passing.length}/${total} passed` +
-        (checks.failing.length > 0 ? ` (${checks.failing.length} failing)` : "") +
-        (checks.inProgress.length > 0 ? ` (${checks.inProgress.length} in progress)` : "") +
-        `, ${totalActionable} actionable review item(s).`);
-    // 2. Rebase policy (only emit when relevant)
-    if (mergeStatus.status === "CONFLICTS") {
-        instructions.push("Rebase required: the branch has merge conflicts that must be resolved before this PR can land.");
-    }
-    else if (mergeStatus.status === "BEHIND") {
-        instructions.push("The PR is behind the base branch. A rebase is optional if all CI checks pass.");
-    }
-    // 3. CI budget policy — one instruction per failing check
-    for (const c of checks.failing) {
-        const stepHint = c.failedStep ? ` (failed step: \`${c.failedStep}\`)` : "";
-        const diagnosisHint = c.runId
-            ? c.conclusion === "CANCELLED"
-                ? `cancelled — if unintended, rerun with \`gh run rerun ${c.runId}\``
-                : c.conclusion === "STARTUP_FAILURE"
-                    ? `startup failure — run \`gh run view ${c.runId}\` to inspect the workflow run; rerun with \`gh run rerun ${c.runId}\` if appropriate`
-                    : `run \`gh run view ${c.runId} --log-failed\`${stepHint} to diagnose — if transient, rerun with \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
-            : c.detailsUrl
-                ? `open the check details (${c.detailsUrl}) to diagnose the failure`
-                : `no run or details URL available — escalate to a human`;
-        instructions.push(`Failing check: \`${c.name}\` — ${diagnosisHint}.`);
-    }
-    // 4. Ready-to-merge gate
-    const isClean = mergeStatus.mergeStateStatus === "CLEAN";
-    const isReady = isClean && status === "READY" && !mergeStatus.copilotReviewInProgress;
-    if (isReady) {
-        instructions.push("This PR is ready to merge: mergeStateStatus is CLEAN, status is READY, and no Copilot review is in progress.");
-    }
-    else {
-        const blockers = [];
-        if (!isClean)
-            blockers.push(`mergeStateStatus is ${mergeStatus.mergeStateStatus} (not CLEAN)`);
-        if (status !== "READY")
-            blockers.push(`status is ${status} (not READY)`);
-        if (mergeStatus.copilotReviewInProgress)
-            blockers.push("Copilot review is still in progress");
-        instructions.push(`Do not declare this PR ready to merge: ${blockers.join("; ")}.`);
-    }
-    // 5. Continuous monitoring pointer (suppressed only when truly ready to merge)
-    if (!isReady) {
-        instructions.push(runtime === "codex"
-            ? `This is a one-shot check. For follow-up monitoring, run \`${buildPrShepherdCommand([String(report.pr)], { runner: opts?.runner }).text}\`.`
-            : "This is a one-shot check. For continuous monitoring that acts on these signals automatically, use `/pr-shepherd:monitor`.");
-    }
-    return instructions;
-}

package/bin/reporters/json.mjs

@@ -1,10 +0,0 @@
-/**
- * Machine-readable JSON reporter for shepherd check output.
- *
- * Slash commands parse this output to extract IDs, status, and actionable items
- * without string-scraping the human-readable text reporter.
- */
-import { buildCheckInstructions } from "./check-instructions.mjs";
-export function formatJson(report, opts) {
-    return JSON.stringify({ ...report, instructions: buildCheckInstructions(report, opts) }, null, 2);
-}

package/bin/reporters/text.mjs

@@ -1,156 +0,0 @@
-import { buildCheckInstructions } from "./check-instructions.mjs";
-import { renderThreadBullet, renderCommentBullet, renderFirstLookStatusTag, renderReviewListSection, renderThreadResolutionStatusTag, } from "../cli/list-formatters.mjs";
-import { joinSections } from "../util/markdown.mjs";
-export function formatText(report, opts) {
-    const header = [
-        `# PR #${report.pr} [CHECK] — ${report.repo}`,
-        `Status: ${report.status}`,
-        `Base: ${report.baseBranch}`,
-    ].join("\n");
-    const ms = report.mergeStatus;
-    const mergeStatusSection = [
-        "## Merge Status",
-        "",
-        `- status: \`${ms.status}\``,
-        `- mergeStateStatus: \`${ms.mergeStateStatus}\``,
-        `- mergeable: \`${ms.mergeable}\``,
-        `- reviewDecision: \`${ms.reviewDecision ?? "(none)"}\``,
-        `- isDraft: \`${ms.isDraft}\``,
-        `- copilotReviewInProgress: \`${ms.copilotReviewInProgress}\``,
-    ].join("\n");
-    const { passing, failing, inProgress, skipped } = report.checks;
-    const total = passing.length + failing.length + inProgress.length + skipped.length;
-    const ciSubsections = [`${passing.length}/${total} passed`];
-    if (failing.length > 0) {
-        const lines = [`### Failed (${failing.length})`, ""];
-        for (const c of failing) {
-            const triaged = c;
-            const prefix = triaged.workflowName ? `${triaged.workflowName} › ` : "";
-            lines.push(`- ${prefix}${c.name}: ${c.conclusion ?? c.status}`);
-            if (triaged.failedStep) {
-                lines.push(`    failed step: ${triaged.failedStep}`);
-            }
-            if (triaged.summary) {
-                lines.push(`    summary: ${triaged.summary}`);
-            }
-        }
-        ciSubsections.push(lines.join("\n"));
-    }
-    if (inProgress.length > 0) {
-        const lines = [`### In Progress (${inProgress.length})`, ""];
-        for (const c of inProgress) {
-            lines.push(`- ${c.name}: ${c.status}`);
-        }
-        ciSubsections.push(lines.join("\n"));
-    }
-    if (skipped.length > 0) {
-        ciSubsections.push(`### Skipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
-    }
-    if (report.checks.filtered.length > 0) {
-        const lines = [
-            `### Filtered non-PR-trigger (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`,
-            "",
-        ];
-        if (report.checks.blockedByFilteredCheck) {
-            lines.push("> Note: PR is BLOCKED and all filtered checks are non-PR-trigger — one of these filtered checks may be a required status check blocking merge.");
-        }
-        else if (report.mergeStatus.status === "BLOCKED") {
-            lines.push("> Note: one or more of these filtered checks may be a required status check blocking merge.");
-        }
-        ciSubsections.push(lines.join("\n"));
-    }
-    const ciSection = `## CI Checks\n\n${ciSubsections.join("\n\n")}`;
-    const { actionable: actionableThreads, resolutionOnly: resolutionOnlyThreads, autoResolved, autoResolveErrors, firstLook: firstLookThreads, } = report.threads;
-    const hasThreadSection = autoResolved.length > 0 ||
-        autoResolveErrors.length > 0 ||
-        actionableThreads.length > 0 ||
-        resolutionOnlyThreads.length > 0;
-    let threadsSection = null;
-    if (hasThreadSection) {
-        const subparts = [];
-        if (autoResolved.length > 0) {
-            const lines = [`Auto-resolved outdated (${autoResolved.length}):`];
-            for (const t of autoResolved) {
-                lines.push(renderThreadBullet(t));
-            }
-            subparts.push(lines.join("\n"));
-        }
-        if (autoResolveErrors.length > 0) {
-            const lines = [`Auto-resolve errors (${autoResolveErrors.length}):`];
-            for (const e of autoResolveErrors) {
-                lines.push(`- ${e}`);
-            }
-            subparts.push(lines.join("\n"));
-        }
-        if (actionableThreads.length > 0) {
-            const lines = [`### Actionable (${actionableThreads.length})`, ""];
-            for (const t of actionableThreads) {
-                lines.push(renderThreadBullet(t));
-            }
-            subparts.push(lines.join("\n"));
-        }
-        if (resolutionOnlyThreads.length > 0) {
-            const lines = [`### Needs resolution only (${resolutionOnlyThreads.length})`, ""];
-            for (const t of resolutionOnlyThreads) {
-                lines.push(renderThreadBullet(t, { statusTag: renderThreadResolutionStatusTag(t) }));
-            }
-            subparts.push(lines.join("\n"));
-        }
-        threadsSection = `## Review Threads\n\n${subparts.join("\n\n")}`;
-    }
-    const { actionable: actionableComments, firstLook: firstLookComments } = report.comments;
-    let commentsSection = null;
-    if (actionableComments.length > 0) {
-        const lines = [`### Actionable (${actionableComments.length})`, ""];
-        for (const c of actionableComments) {
-            lines.push(renderCommentBullet(c));
-        }
-        commentsSection = `## PR Comments\n\n${lines.join("\n")}`;
-    }
-    const changesRequestedSection = renderReviewListSection("CHANGES_REQUESTED Reviews", report.changesRequestedReviews);
-    const allSummaries = [...report.firstLookSummaries, ...report.reviewSummaries];
-    const reviewSummariesSection = renderReviewListSection("Review Summaries", allSummaries);
-    const approvedReviewsSection = renderReviewListSection("Approved Reviews", report.approvedReviews);
-    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
-    let firstLookSection = null;
-    if (firstLookTotal > 0) {
-        const lines = [
-            `## First-look items (${firstLookTotal}) — acknowledge status before acting`,
-            "",
-        ];
-        for (const t of firstLookThreads) {
-            lines.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
-        }
-        for (const c of firstLookComments) {
-            const editedSuffix = c.edited ? ", edited" : "";
-            lines.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
-        }
-        firstLookSection = lines.join("\n");
-    }
-    const totalActionable = actionableThreads.length +
-        resolutionOnlyThreads.length +
-        actionableComments.length +
-        report.changesRequestedReviews.length;
-    const counts = [];
-    if (totalActionable > 0)
-        counts.push(`${totalActionable} actionable`);
-    if (firstLookTotal > 0)
-        counts.push(`${firstLookTotal} first-look`);
-    const summaryLine = counts.join(", ") || "0 actionable — no unresolved review items";
-    const summarySection = `## Summary\n\n${summaryLine}`;
-    const instructions = buildCheckInstructions(report, opts);
-    const instructionsSection = `## Instructions\n\n${instructions.map((step, i) => `${i + 1}. ${step}`).join("\n")}`;
-    return joinSections([
-        header,
-        mergeStatusSection,
-        ciSection,
-        threadsSection,
-        commentsSection,
-        changesRequestedSection,
-        reviewSummariesSection,
-        approvedReviewsSection,
-        firstLookSection,
-        summarySection,
-        instructionsSection,
-    ]);
-}

package/plugin/skills/check/SKILL.md

@@ -1,37 +0,0 @@
----
-name: check
-description: "Check GitHub CI status and review comments for the current PR"
-argument-hint: "[PR number or URL ...]"
-user-invocable: true
-allowed-tools: ["Bash"]
----
-
-# pr-shepherd check — PR Status
-
-## Arguments: $ARGUMENTS
-
-## Steps
-
-1. **Parse `$ARGUMENTS`:** extract PR numbers or GitHub PR URLs. If none, infer:
-   `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
-   If no PR found, report an error and stop.
-
-2. **Short-circuit if merged:**
-
-   ```bash
-   gh pr view <N> --json state --jq '.state'
-   ```
-
-   If `MERGED`, output: `PR #N is already merged. Nothing to check.` and skip.
-
-3. **Run the check and follow instructions:**
-   Use the repository package runner selected by `packageManager` or lockfile
-   (for example, `pnpm exec`, `yarn run`, or `npx --no-install`).
-
-   ```bash
-   <runner> pr-shepherd check <N>
-   ```
-
-   Print the full output. Follow the `## Instructions` section exactly.
-
-4. For multiple PRs, repeat steps 2–3 for each.

package/plugin/skills/monitor/SKILL.md

@@ -1,40 +0,0 @@
----
-name: monitor
-description: "Start continuous CI monitoring — marks PR ready for review when all checks pass"
-argument-hint: "[PR number or URL]"
-user-invocable: true
-allowed-tools:
-  [
-    "Bash",
-    "Read",
-    "Grep",
-    "Edit",
-    "Write",
-    "Glob",
-    "Skill",
-    "ScheduleWakeup",
-    "CronList",
-    "CronDelete",
-  ]
----
-
-# pr-shepherd monitor — Continuous PR Monitor
-
-## Arguments: $ARGUMENTS
-
-## Steps
-
-1. **Resolve PR number:**
-   - If `$ARGUMENTS` contains a PR number or GitHub PR URL, extract the number.
-   - Otherwise, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
-   - If no PR found, report an error and stop.
-
-2. **Run the bootstrap command and follow its instructions:**
-   Use the repository package runner selected by `packageManager` or lockfile
-   (for example, `pnpm exec`, `yarn run`, or `npx --no-install`).
-
-   ```bash
-   <runner> pr-shepherd monitor <PR_NUMBER>
-   ```
-
-   Print the full output. Follow the `## Instructions` section exactly.

package/plugin/skills/resolve/SKILL.md

@@ -1,38 +0,0 @@
----
-name: resolve
-description: "Resolve all inline review comments on the current PR"
-argument-hint: "[PR number or URL]"
-user-invocable: true
-allowed-tools: ["Bash", "Read", "Grep", "Edit", "Write", "Glob", "Skill"]
----
-
-# pr-shepherd resolve — Fix and Resolve Review Comments
-
-Resolve unresolved review threads and minimize PR comments on the current PR — from ALL authors.
-
-## Arguments: $ARGUMENTS
-
-## Steps
-
-1. **Resolve PR number:**
-   - If `$ARGUMENTS` contains a PR number or GitHub PR URL, extract the number.
-   - Otherwise, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
-   - If no PR found, report an error and stop.
-
-2. **Short-circuit if merged:**
-
-   ```bash
-   gh pr view <N> --json state --jq '.state'
-   ```
-
-   If `MERGED`, invoke `/loop cancel` via the Skill tool, output a merged message, and stop.
-
-3. **Fetch and follow instructions:**
-   Use the repository package runner selected by `packageManager` or lockfile
-   (for example, `pnpm exec`, `yarn run`, or `npx --no-install`).
-
-   ```bash
-   <runner> pr-shepherd resolve <N> --fetch
-   ```
-
-   Print the full output. Follow the `## Instructions` section exactly.