pr-shepherd 0.60.0 → 1.0.0

package/pr-shepherd.schema.json

@@ -0,0 +1,361 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "number",
+      "const": 1
+    },
+    "github": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "transport": {
+          "default": "auto",
+          "type": "string",
+          "enum": [
+            "auto",
+            "graphql",
+            "rest"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "cli-command": {
+      "default": [
+        "pr-shepherd"
+      ],
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "\\S"
+      }
+    },
+    "bot-usernames": {
+      "default": [
+        "chatgpt-connector",
+        "openai-codex",
+        "codex",
+        "claude",
+        "copilot-pull-request-reviewer",
+        "gemini-code-assist",
+        "coderabbitai",
+        "greptile-apps",
+        "qodo-merge-pro",
+        "deepsource-io",
+        "sonarqubecloud",
+        "what-the-diff"
+      ],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "checks": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "ignore": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "never-ignore": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "ci-trigger-events": {
+          "default": [
+            "pull_request",
+            "pull_request_target"
+          ],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "ignore-log-lines": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "regex"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "iterate": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "triage-attempts-per-thread": {
+          "default": 3,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "stall-timeout-minutes": {
+          "default": 60,
+          "type": "number",
+          "minimum": 0
+        },
+        "ready-delay-minutes": {
+          "default": 0,
+          "type": "number",
+          "minimum": 0
+        },
+        "minimize-approvals": {
+          "default": false,
+          "type": "boolean"
+        },
+        "minimize-comments": {
+          "default": "bots",
+          "type": "string",
+          "enum": [
+            "all",
+            "bots",
+            "none"
+          ]
+        },
+        "behind-base-hint": {
+          "default": "",
+          "type": "string"
+        },
+        "review-output-max-chars": {
+          "default": 50000,
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "resolve-other-human-threads": {
+          "default": "none",
+          "type": "string",
+          "enum": [
+            "none",
+            "outdated",
+            "always"
+          ]
+        },
+        "instructions": {
+          "default": "inline",
+          "type": "string",
+          "enum": [
+            "inline",
+            "playbook"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "poll": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "interval-seconds": {
+          "default": 60,
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "stack-interval-factor": {
+          "default": 2,
+          "type": "number",
+          "minimum": 1
+        },
+        "timeout-seconds": {
+          "default": 270,
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "debounce-seconds": {
+          "default": 60,
+          "type": "number",
+          "minimum": 0
+        },
+        "quiet-status": {
+          "default": false,
+          "type": "boolean"
+        },
+        "reconcile-seconds": {
+          "default": 900,
+          "type": "number",
+          "minimum": 0
+        },
+        "quota-warnings": {
+          "default": [
+            {
+              "remaining-percent": 30,
+              "interval-factor": 2
+            },
+            {
+              "remaining-percent": 20,
+              "interval-factor": 5
+            },
+            {
+              "remaining-percent": 10,
+              "interval-factor": 10
+            }
+          ],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "remaining-percent": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 100
+              },
+              "interval-minutes": {
+                "type": "number",
+                "exclusiveMinimum": 0
+              },
+              "interval-factor": {
+                "type": "number",
+                "minimum": 1
+              }
+            },
+            "required": [
+              "remaining-percent"
+            ],
+            "additionalProperties": false,
+            "anyOf": [
+              {
+                "required": [
+                  "interval-minutes"
+                ]
+              },
+              {
+                "required": [
+                  "interval-factor"
+                ]
+              }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "apply": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "sha-poll-interval-seconds": {
+          "default": 2,
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "sha-poll-max-attempts": {
+          "default": 10,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "additionalProperties": false
+    },
+    "mark-ready": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "auto": {
+          "default": true,
+          "type": "boolean"
+        },
+        "blocking-reviewer-logins": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "merge": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": [
+            "merge",
+            "squash",
+            "rebase"
+          ]
+        },
+        "command-args": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "not": {
+              "pattern": "^(?:--repo(?:=|$)|-R|--auto(?:=|$)|--disable-auto(?:=|$)|--match-head-commit(?:=|$)|--admin(?:=|$)|--body-file(?:=|$)|-F|--help(?:=|$)|-h)"
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "actions": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "auto-minimize-suppressed": {
+          "default": true,
+          "type": "boolean"
+        },
+        "work-while-queued": {
+          "default": false,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "classify": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "standard": {
+          "default": {},
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "enum": [
+              "all",
+              "coderabbit-notices",
+              "codecov-report",
+              "codex-notices",
+              "dependabot-notices",
+              "gemini-notices",
+              "kilo-no-issues",
+              "sourcery-notices"
+            ]
+          },
+          "additionalProperties": {
+            "type": "boolean"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "anyOf": [
+    {
+      "maxProperties": 0
+    },
+    {
+      "required": [
+        "version"
+      ]
+    }
+  ],
+  "title": "pr-shepherd configuration"
+}

package/bin/cli/event-state-scope.d.mts

@@ -1,19 +0,0 @@
-/**
- * Run a dispatched command, entering the durable state scope first when it resolves to event
- * mode. Entering before log setup keeps the per-worktree log a peer of the seen markers and
- * stall state an event session writes. Invalid flags or config fall through unscoped so the
- * command handler reports them.
- */
-export declare function runInEventStateScope<T>(args: string[], work: () => Promise<T>): Promise<T>;
-/**
- * Report an invalid `--poll-mode` value as a usage error. Commands that only use the flag to
- * pick a state scope (`log-file`, `clean`) call this before `runInPollModeScope`, because no
- * later handler would reject a typo there. Returns true after printing the error.
- */
-export declare function rejectInvalidPollModeFlag(args: string[], command: string): boolean;
-/**
- * Run `work` in the durable state scope when `--poll-mode` in `args`, or else `poll.mode`,
- * resolves to event mode. `log-file` and `clean` use this to reach the state an event tick
- * writes.
- */
-export declare function runInPollModeScope<T>(args: string[], work: () => Promise<T>): Promise<T>;

package/bin/cli/event-state-scope.mjs

@@ -1,60 +0,0 @@
-import { loadConfig } from "../config/load.mjs";
-import { EXIT } from "../exit-codes.mjs";
-import { resolvePollMode } from "../commands/poll-mode.mjs";
-import { runWithDurableState } from "../state/durable-state.mjs";
-import { getFlag } from "./args.mjs";
-import { isDefaultPollInvocation } from "./default-poll.mjs";
-/** Subcommands that honor `--poll-mode`; the default poll invocation honors it too. */
-const POLL_MODE_SUBCOMMANDS = new Set(["iterate", "poll"]);
-const REQUESTABLE = ["auto", "poll", "event"];
-function requestedPollMode(value) {
-    return REQUESTABLE.find((mode) => mode === value);
-}
-/**
- * Run a dispatched command, entering the durable state scope first when it resolves to event
- * mode. Entering before log setup keeps the per-worktree log a peer of the seen markers and
- * stall state an event session writes. Invalid flags or config fall through unscoped so the
- * command handler reports them.
- */
-export function runInEventStateScope(args, work) {
-    const subcommand = args[0];
-    const honorsPollMode = isDefaultPollInvocation(subcommand) || POLL_MODE_SUBCOMMANDS.has(subcommand ?? "");
-    return honorsPollMode ? runInPollModeScope(args, work) : work();
-}
-/**
- * Report an invalid `--poll-mode` value as a usage error. Commands that only use the flag to
- * pick a state scope (`log-file`, `clean`) call this before `runInPollModeScope`, because no
- * later handler would reject a typo there. Returns true after printing the error.
- */
-export function rejectInvalidPollModeFlag(args, command) {
-    if (!args.some((arg) => arg === "--poll-mode" || arg.startsWith("--poll-mode=")))
-        return false;
-    const value = getFlag(args, "--poll-mode");
-    if (requestedPollMode(value))
-        return false;
-    process.stderr.write(`pr-shepherd: ${command}: --poll-mode must be one of ${REQUESTABLE.join(", ")}, got ${JSON.stringify(value ?? "")}\n`);
-    process.exitCode = EXIT.USAGE;
-    return true;
-}
-/**
- * Run `work` in the durable state scope when `--poll-mode` in `args`, or else `poll.mode`,
- * resolves to event mode. `log-file` and `clean` use this to reach the state an event tick
- * writes.
- */
-export function runInPollModeScope(args, work) {
-    return resolvesToEvent(args) ? runWithDurableState(work) : work();
-}
-function resolvesToEvent(args) {
-    const flag = getFlag(args, "--poll-mode");
-    const requested = requestedPollMode(flag);
-    // An explicit poll or event request wins without reading config, so a malformed config
-    // cannot drop an explicit `--poll-mode event` out of the durable scope.
-    if (requested === "event" || requested === "poll")
-        return requested === "event";
-    try {
-        return resolvePollMode(requested, loadConfig().poll.mode) === "event";
-    }
-    catch {
-        return false;
-    }
-}

package/bin/cli/fix-formatter.d.mts

@@ -1,4 +0,0 @@
-import type { IterateResultFixCode } from "../types.mts";
-export declare function formatFixCodeResult(header: string, result: IterateResultFixCode, opts?: {
-    verbose?: boolean;
-}): string;

package/bin/commands/commit-suggestion.d.mts

@@ -1,8 +0,0 @@
-import type { CommitSuggestionResult, GlobalOptions } from "../types.mts";
-export interface CommitSuggestionOptions extends GlobalOptions {
-    threadId: string;
-    message: string;
-    description?: string;
-}
-/** @deprecated Use runSuggestionPatches. */
-export declare function runCommitSuggestion(opts: CommitSuggestionOptions): Promise<CommitSuggestionResult>;

package/bin/commands/commit-suggestion.mjs

@@ -1,26 +0,0 @@
-import { buildSingularInstructions } from "./suggestion-patch-item.mjs";
-import { runSuggestionPatches } from "./suggestion-patches.mjs";
-import { formatPrUrl } from "../pr-reference.mjs";
-/** @deprecated Use runSuggestionPatches. */
-export async function runCommitSuggestion(opts) {
-    const result = await runSuggestionPatches({
-        prNumber: opts.prNumber,
-        targetRepository: opts.targetRepository,
-        format: opts.format,
-        verbose: opts.verbose,
-        suggestions: [
-            {
-                threadId: opts.threadId,
-                message: opts.message,
-                ...(opts.description !== undefined && { description: opts.description }),
-            },
-        ],
-    });
-    const patch = result.patches[0];
-    return {
-        ...patch,
-        pr: result.pr,
-        repo: result.repo,
-        postActionInstructions: buildSingularInstructions(patch, formatPrUrl(result.repo, result.pr)),
-    };
-}

package/bin/commands/event-instructions.d.mts

@@ -1,11 +0,0 @@
-import type { NextCheck } from "../types/next-check.mts";
-/**
- * Steps that replace "iterate immediately" when Shepherd ran in event mode and the PR is
- * waiting: end the turn, keep one wake-up, and let the next tick come from a PR event or the
- * wake-up. Always printed after any state-specific sentence.
- */
-export declare function eventWaitSteps(next: NextCheck): string[];
-/** Replaces the `[FIX_CODE]` "iterate immediately" line when the tick ran in event mode. */
-export declare function eventFixContinuation(next: NextCheck): string;
-/** One aggregate step: sessions still run first, and only then does the turn end. */
-export declare function eventAggregateStep(next: NextCheck, waiting: boolean): string;

package/bin/commands/event-instructions.mjs

@@ -1,27 +0,0 @@
-import { playbookPointer } from "./playbook-pointer.mjs";
-function wakeUpClause(next) {
-    const kind = next.reason === "safety-net" ? "safety-net wake-up" : "wake-up";
-    return `Keep exactly one ${kind} at \`${next.at}\` (\`${next.reason}\`).`;
-}
-/**
- * Steps that replace "iterate immediately" when Shepherd ran in event mode and the PR is
- * waiting: end the turn, keep one wake-up, and let the next tick come from a PR event or the
- * wake-up. Always printed after any state-specific sentence.
- */
-export function eventWaitSteps(next) {
-    return [
-        `Event mode: end this turn now without sleeping or polling. ${playbookPointer("Cloud event loop")}`,
-        `${wakeUpClause(next)} When a PR event or that wake-up arrives, rerun this command with the same options and act only on Shepherd's output, never on the event payload.`,
-    ];
-}
-/** Replaces the `[FIX_CODE]` "iterate immediately" line when the tick ran in event mode. */
-export function eventFixContinuation(next) {
-    return `\`[FIX_CODE]\` is non-terminal. After the steps above, rerun this command once with the same options, then end the turn without sleeping. ${wakeUpClause(next)} ${playbookPointer("Cloud event loop")}`;
-}
-/** One aggregate step: sessions still run first, and only then does the turn end. */
-export function eventAggregateStep(next, waiting) {
-    const lead = waiting
-        ? "Event mode: end this turn now without sleeping or polling."
-        : "Event mode: once the steps above are done and the rerun still waits, end the turn without sleeping.";
-    return `${lead} ${wakeUpClause(next)} When a PR event or that wake-up arrives, rerun this selector with the same options and act only on Shepherd's output, never on the event payload. ${playbookPointer("Cloud event loop")}`;
-}

package/bin/commands/event-mode.d.mts

@@ -1,14 +0,0 @@
-import type { IterateCommandOptions, IterateResult, PollSummaryCommandOptions, PollSummaryResult } from "../types.mts";
-import { type PollCommandOptions } from "./poll.mts";
-import { type AggregatePollCommandOptions } from "./poll-summary.mts";
-/**
- * One iterate tick. In event mode the tick runs exactly once with no settle window and no
- * sleeping, persists seen markers immediately, and reports when to come back.
- */
-export declare function runIterateForMode(opts: IterateCommandOptions): Promise<IterateResult>;
-/** One aggregate tick; event mode adds `pollMode` and `nextCheck`. */
-export declare function runPollSummaryForMode(opts: PollSummaryCommandOptions): Promise<PollSummaryResult>;
-/** The default poll command: the sleeping loop in poll mode, one tick in event mode. */
-export declare function runPollForMode(opts: PollCommandOptions): Promise<IterateResult>;
-/** The aggregate poll command: the sleeping loop in poll mode, one tick in event mode. */
-export declare function runAggregatePollForMode(opts: AggregatePollCommandOptions): Promise<PollSummaryResult>;

package/bin/commands/poll-mode.d.mts

@@ -1,8 +0,0 @@
-import type { PollMode } from "../config/load.mts";
-/** The mode a command actually runs in. `auto` has been resolved away. */
-export type ResolvedPollMode = "poll" | "event";
-/**
- * Resolve `--poll-mode` / the `pollMode` option / `poll.mode`. An explicit request wins over
- * config; `auto` becomes `event` only inside a cloud session. A missing value counts as `auto`.
- */
-export declare function resolvePollMode(requested: PollMode | undefined, configured: PollMode | undefined): ResolvedPollMode;

package/bin/commands/poll-mode.mjs

@@ -1,14 +0,0 @@
-/** True when the process runs in a Claude Code cloud (remote) session. */
-function isCloudSession() {
-    return process.env["CLAUDE_CODE_REMOTE"] === "true";
-}
-/**
- * Resolve `--poll-mode` / the `pollMode` option / `poll.mode`. An explicit request wins over
- * config; `auto` becomes `event` only inside a cloud session. A missing value counts as `auto`.
- */
-export function resolvePollMode(requested, configured) {
-    const mode = requested ?? configured ?? "auto";
-    if (mode === "auto")
-        return isCloudSession() ? "event" : "poll";
-    return mode;
-}

package/bin/config.json

@@ -1,68 +0,0 @@
-{
-  "github": { "transport": "auto" },
-  "cliCommand": ["pr-shepherd"],
-  "botUsernames": [
-    "chatgpt-connector",
-    "openai-codex",
-    "codex",
-    "claude",
-    "copilot-pull-request-reviewer",
-    "gemini-code-assist",
-    "coderabbitai",
-    "greptile-apps",
-    "qodo-merge-pro",
-    "deepsource-io",
-    "sonarqubecloud",
-    "what-the-diff"
-  ],
-  "ignoreChecks": [],
-  "iterate": {
-    "fixAttemptsPerThread": 3,
-    "stallTimeoutMinutes": 60,
-    "minimizeApprovals": false,
-    "minimizeComments": "all",
-    "behindBaseHint": "",
-    "resolveOtherHumanThreads": "none",
-    "instructions": "inline",
-    "reviewOutputMaxChars": 50000
-  },
-  "poll": {
-    "intervalSeconds": 60,
-    "stackIntervalFactor": 2,
-    "timeoutSeconds": 270,
-    "debounceSeconds": 60,
-    "quietStatus": false,
-    "mode": "auto",
-    "reconcileSeconds": 900
-  },
-  "watch": {
-    "readyDelayMinutes": 10,
-    "graphqlQuotaWarnings": [
-      { "remainingPercent": 30, "pollIntervalFactor": 2 },
-      { "remainingPercent": 20, "pollIntervalFactor": 5 },
-      { "remainingPercent": 10, "pollIntervalFactor": 10 }
-    ]
-  },
-  "resolve": {
-    "shaPoll": {
-      "intervalMs": 2000,
-      "maxAttempts": 10
-    }
-  },
-  "checks": {
-    "ciTriggerEvents": ["pull_request", "pull_request_target"],
-    "ignoreLogLines": []
-  },
-  "mergeStatus": {
-    "blockingReviewerLogins": ["copilot"]
-  },
-  "merge": {
-    "commandArgs": []
-  },
-  "actions": {
-    "autoMinimizeSuppressed": true,
-    "autoMarkReady": true,
-    "neverCancelRuns": [],
-    "workWhileQueued": false
-  }
-}

package/bin/types/protected-run.d.mts

@@ -1,6 +0,0 @@
-export interface ProtectedRun {
-    runId: string;
-    matchedPattern: string;
-    checkNames: string[];
-    workflowName?: string;
-}

package/bin/types/protected-run.mjs

@@ -1 +0,0 @@
-export {};