@jagreehal/shepherd 0.15.0 → 0.17.0

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.
Files changed (82) hide show
  1. package/AGENTS.md +3 -3
  2. package/README.md +40 -27
  3. package/THIRD_PARTY_NOTICES.md +2 -0
  4. package/gate/.shepherd/gate.schema.json +657 -0
  5. package/gate/.shepherd/gate.yml +123 -0
  6. package/gate/.shepherd/review-guidance.md +95 -0
  7. package/gate/src/actions.ts +32 -0
  8. package/gate/src/cli.ts +1046 -0
  9. package/gate/src/config.ts +102 -0
  10. package/gate/src/delta.ts +29 -0
  11. package/gate/src/env.ts +30 -0
  12. package/gate/src/eval.ts +292 -0
  13. package/gate/src/familiarity.ts +461 -0
  14. package/gate/src/github.ts +761 -0
  15. package/gate/src/inline.ts +59 -0
  16. package/gate/src/isolated-cli.ts +281 -0
  17. package/gate/src/leads.ts +257 -0
  18. package/gate/src/llm.ts +647 -0
  19. package/gate/src/notify.ts +57 -0
  20. package/gate/src/policy.ts +1313 -0
  21. package/gate/src/prices.ts +62 -0
  22. package/gate/src/provider-errors.ts +80 -0
  23. package/gate/src/retention.ts +86 -0
  24. package/gate/src/reviewer.ts +739 -0
  25. package/gate/src/signals.ts +105 -0
  26. package/gate/src/smoke-live.ts +64 -0
  27. package/gate/src/stack.ts +87 -0
  28. package/gate/src/stories.ts +297 -0
  29. package/gate/templates/policy-strict.yml +128 -0
  30. package/gate/templates/reviewer.Dockerfile +8 -0
  31. package/gate/templates/rules/observability/SKILL.md +33 -0
  32. package/gate/templates/shepherd-gate-actions.yml +35 -0
  33. package/gate/templates/shepherd-gate-edited.yml +29 -0
  34. package/gate/templates/shepherd-gate.yml +111 -0
  35. package/lenses/dotnet/SKILL.md +1 -1
  36. package/lenses/go/SKILL.md +1 -1
  37. package/lenses/java/SKILL.md +1 -1
  38. package/lenses/nextjs/SKILL.md +1 -1
  39. package/lenses/node-api/SKILL.md +1 -1
  40. package/lenses/nx-monorepo/SKILL.md +1 -1
  41. package/lenses/observability/SKILL.md +1 -1
  42. package/lenses/owasp-asvs/SKILL.md +1 -1
  43. package/lenses/owasp-llm/SKILL.md +1 -1
  44. package/lenses/pstack/SKILL.md +1 -1
  45. package/lenses/python/SKILL.md +1 -1
  46. package/lenses/react/SKILL.md +1 -1
  47. package/lenses/rust/SKILL.md +1 -1
  48. package/package.json +21 -7
  49. package/schema/config.json +1 -1
  50. package/skills/branch-review/SKILL.md +123 -0
  51. package/skills/ci-repair/SKILL.md +79 -35
  52. package/skills/garden/SKILL.md +8 -8
  53. package/skills/garden/references/telemetry.md +4 -4
  54. package/skills/incident/SKILL.md +9 -9
  55. package/skills/lens-import/SKILL.md +7 -7
  56. package/skills/review-slop/SKILL.md +1 -1
  57. package/skills/shepherd/SKILL.md +43 -41
  58. package/skills/shepherd/references/degradation.md +3 -3
  59. package/skills/shepherd/references/dispatch.md +1 -1
  60. package/skills/shepherd/references/formats.md +5 -5
  61. package/skills/shepherd/references/models.md +2 -2
  62. package/skills/shepherd/references/policy.md +9 -9
  63. package/skills/swarm/SKILL.md +21 -17
  64. package/skills/swarm/references/custom-lenses.md +2 -2
  65. package/skills/swarm/references/formats.md +1 -1
  66. package/skills/triage/SKILL.md +10 -10
  67. package/src/bin.ts +10 -0
  68. package/src/cli.ts +285 -42
  69. package/src/config.ts +26 -25
  70. package/src/doctor.ts +31 -18
  71. package/src/garden-traces.ts +13 -13
  72. package/src/garden.ts +4 -4
  73. package/src/lens.ts +19 -7
  74. package/src/setup.ts +72 -0
  75. package/src/stack.ts +2 -2
  76. package/src/status.ts +80 -0
  77. package/src/summary.ts +52 -9
  78. package/src/trace.ts +4 -4
  79. package/src/working.ts +30 -0
  80. package/templates/shepherd-audit.yml +7 -15
  81. package/templates/shepherd-incident.yml +7 -12
  82. package/templates/shepherd.yml +39 -40
@@ -0,0 +1,62 @@
1
+ import { z } from "zod";
2
+ import { parseModelId } from "./llm.ts";
3
+
4
+ /** One `pricing:` entry in `.shepherd/gate.yml`, as `gate init` writes it. */
5
+ export interface PriceEntry {
6
+ inputPer1M: number;
7
+ outputPer1M: number;
8
+ cachedInputPer1M?: number;
9
+ as_of: string;
10
+ source: string;
11
+ }
12
+
13
+ const DEFAULT_URL = "https://models.dev/api.json";
14
+
15
+ /** Shepherd's provider names, as models.dev spells them. */
16
+ const MODELS_DEV_PROVIDER = new Map([
17
+ ["bedrock", "amazon-bedrock"],
18
+ ["gateway", "vercel"],
19
+ ]);
20
+
21
+ /** A Bedrock cross-region inference profile prefix, which models.dev may list only on the foundation id. */
22
+ const PROFILE_PREFIX = /^(?:eu|us|us-gov|apac|au|jp|in|global)\./;
23
+
24
+ const Cost = z.object({ input: z.number(), output: z.number(), cache_read: z.number().optional() });
25
+
26
+ /** One provider's slice of models.dev's catalogue: model id → entry. Only this provider is validated, so an odd entry elsewhere cannot hide a price. */
27
+ const ProviderModels = z.object({ models: z.record(z.string(), z.object({ cost: z.unknown() }).loose()) }).loose();
28
+
29
+ /**
30
+ * Today's list price for a model from models.dev's public catalogue, dated and sourced, or null when the
31
+ * catalogue has none or cannot be read. Shepherd ships no prices: this one is written into the repo's
32
+ * reviewed policy, where the team can see its date and change it.
33
+ * `SHEPHERD_PRICES_URL=off` skips the lookup; any other value replaces the catalogue's URL.
34
+ */
35
+ export async function catalogPrice(modelId: string, o: { fetch?: (url: string, init: RequestInit) => Promise<Response>; url?: string; today?: string } = {}): Promise<{ key: string; price: PriceEntry } | null> {
36
+ const url = o.url ?? process.env.SHEPHERD_PRICES_URL ?? DEFAULT_URL;
37
+
38
+ if (url === "off") return null;
39
+
40
+ const { provider, model } = parseModelId(modelId);
41
+ const catalogProvider = MODELS_DEV_PROVIDER.get(provider) ?? provider;
42
+ let models: z.infer<typeof ProviderModels>["models"];
43
+
44
+ try {
45
+ const res = await (o.fetch ?? fetch)(url, { signal: AbortSignal.timeout(10_000) });
46
+
47
+ if (!res.ok) return null;
48
+ models = ProviderModels.parse(z.record(z.string(), z.unknown()).parse(await res.json())[catalogProvider]).models;
49
+ } catch {
50
+ return null; // offline, slow or an unexpected shape: init still succeeds, and prints how to add a price
51
+ }
52
+
53
+ const cost = [model, model.replace(PROFILE_PREFIX, "")].map((id) => Cost.safeParse(models[id]?.cost)).find((r) => r.success)?.data;
54
+
55
+ if (!cost) return null;
56
+
57
+ const price: PriceEntry = { inputPer1M: cost.input, outputPer1M: cost.output, as_of: o.today ?? new Date().toISOString().slice(0, 10), source: `models.dev ${catalogProvider} list price` };
58
+
59
+ if (cost.cache_read !== undefined) price.cachedInputPer1M = cost.cache_read;
60
+
61
+ return { key: model, price };
62
+ }
@@ -0,0 +1,80 @@
1
+ // Turns a provider's error text ("Forbidden", a JSON dump, a 400 naming a spend cap) into the fix an ERROR review shows.
2
+ // Advisory: verdicts stay as they are.
3
+ import { z } from "zod";
4
+
5
+ const BILLING = "Out of credit or over a spending cap: top up the account or raise the cap";
6
+
7
+ const AUTH = "The provider refused the key: `gate config` shows which key is set, and the run log names the one used";
8
+
9
+ const RATE = "Rate limited: rerun with `/gate` once it clears, or raise the provider's limit";
10
+
11
+ const OUTAGE = "A provider outage, not this PR: rerun with `/gate`";
12
+
13
+ // Provider wordings, lowercase, most specific remedy first. They come ahead of the status code: billing errors often
14
+ // arrive as a 401 or 429.
15
+ const SPECIFIC: [string, string[]][] = [
16
+ [BILLING, ["creditserror", "freeusagelimiterror", "insufficient balance", "insufficient credits", "insufficient account funds", "no credits remaining", "out of credits", "credit balance is too low", "used all available credits", "requires more credits", "spending cap", "spending limit", "key limit exceeded", "check your plan and billing", "free_tier_requests", "specified api usage limits", "free usage exceeded"]],
17
+ ["A plan's usage window ran out: wait for it to reset or raise the limit", ["usage limit has been reached", "hit your usage limit", "usage limit reached", "usage limit exceeded"]],
18
+ ["The router's data policy or guardrails exclude every provider of this model: widen them or pick another model", ["no endpoints available matching"]],
19
+ ["The provider does not serve this model: check `model` in .shepherd/gate.yml", ["model not found", "model_not_found", "modelnotfound", "does not exist or you do not have access"]],
20
+ ["The prompt exceeds the model's context window: use a model with a longer one, or a human reviews this PR", ["prompt is too long", "exceeds context window", "maximum context length", "context_length_exceeded"]],
21
+ ];
22
+
23
+ // Read when no status code settled it. "rate limit" needs its separator, which keeps `x-ratelimit-*` headers out.
24
+ const GENERAL: [string, string[]][] = [
25
+ [AUTH, ["user not found", "invalid authentication", "no auth credentials", "invalid api key", "invalid_api_key"]],
26
+ [RATE, ["rate limit", "rate_limit", "resource_exhausted", "insufficient_quota", "exceeded your current quota"]],
27
+ [OUTAGE, ["overloaded", "provider_unavailable", "model is at capacity"]],
28
+ ];
29
+
30
+ const matching = (table: [string, string[]][], text: string) => table.find(([, says]) => says.some((s) => text.includes(s)))?.[0];
31
+
32
+ /** The remedy for a status code written beside its key, so a commit SHA holding "429" is no rate limit. */
33
+ function byStatus(text: string): string | undefined {
34
+ const code = Number(/\b(?:http[_ ]?)?status(?:[_ ]?code)?["']?\s*[:=]\s*["']?(\d{3})\b/.exec(text)?.[1]);
35
+
36
+ if (code === 401 || code === 403) return AUTH;
37
+
38
+ if (code === 429) return RATE;
39
+
40
+ return code >= 500 ? OUTAGE : undefined;
41
+ }
42
+
43
+ // Where each provider's billing lives, by gate's provider name.
44
+ const BILLING_PAGE = new Map([
45
+ ["anthropic", "https://platform.claude.com/settings/billing"],
46
+ ["bedrock", "https://console.aws.amazon.com/billing/home"],
47
+ ["openai", "https://platform.openai.com/settings/organization/billing/overview"],
48
+ ["opencode", "https://opencode.ai/zen"],
49
+ ["opencode-go", "https://opencode.ai/go"],
50
+ ["openrouter", "https://openrouter.ai/settings/credits"],
51
+ ["deepseek", "https://platform.deepseek.com/top_up"],
52
+ ]);
53
+
54
+ const ApiFailure = z.object({ statusCode: z.number().optional(), responseBody: z.string().optional() });
55
+
56
+ const Failure = ApiFailure.extend({ lastError: ApiFailure.optional() });
57
+
58
+ /** Everything an error says about its cause. The AI SDK keeps the status and body off the message, and a retried call inside `lastError`. */
59
+ export function failureText(e: Error): string {
60
+ const f = Failure.safeParse(e);
61
+
62
+ if (!f.success) return e.message;
63
+
64
+ return [e.message, ...[f.data, f.data.lastError].flatMap((x) => [x?.responseBody ?? "", x?.statusCode ? `status: ${x.statusCode}` : ""])].filter(Boolean).join("\n");
65
+ }
66
+
67
+ /**
68
+ * The fix for a provider's error, or null for any other text. `reviewer …`, `review stopped …` and `claude returned …` are gate's
69
+ * own errors and quote the model, so they stay out. `provider`, on the api backend, adds the billing page.
70
+ */
71
+ export function explainFailure(text: string, provider?: string): string | null {
72
+ if (/^(reviewer |review stopped|claude returned)/.test(text)) return null;
73
+ const lower = text.toLowerCase();
74
+ const fix = matching(SPECIFIC, lower) ?? byStatus(lower) ?? matching(GENERAL, lower);
75
+
76
+ if (!fix) return null;
77
+ const page = fix === BILLING && provider ? BILLING_PAGE.get(provider) : undefined;
78
+
79
+ return `${fix}${page ? ` (${page})` : ""}.`;
80
+ }
@@ -0,0 +1,86 @@
1
+ // Approval retention: keep a standing gate approval when a push left the PR's
2
+ // own diff byte-identical (typical case: merging a base that touched none of the PR's files).
3
+ //
4
+ // The deliberate exception to dismiss-first. Fail closed on anything ambiguous:
5
+ // empty diffs, binary markers, GitHub errors, missing reviewed marker, a failed
6
+ // gate, or a PR that moved while it was being checked.
7
+ import { compareDiff, evidenceUnseen, isOurs, listReviews, reviewedShas, unchanged, type PR, type ReviewRecord } from "./github.ts";
8
+
9
+ const BINARY_MARKER_RE = /^Binary files\b.*differ$/m;
10
+
11
+ /**
12
+ * Whether the PR's own diff is byte-identical to the one that was approved. A base merge that leaves
13
+ * every file the PR touches alone keeps it so; one that edits such a file changes its blob ids, and the
14
+ * PR goes back for review, since the base edit can change what the PR's code does.
15
+ */
16
+ export function approvedDiffUnchanged(approvedDiff: string, currentDiff: string): boolean {
17
+ if (!approvedDiff.trim() || !currentDiff.trim()) return false;
18
+
19
+ if (BINARY_MARKER_RE.test(approvedDiff) || BINARY_MARKER_RE.test(currentDiff)) return false;
20
+
21
+ return approvedDiff === currentDiff;
22
+ }
23
+
24
+ export type StandingApproval = { reviewId: number; approvedHead: string; approvedBase: string; evidenceUnseen: boolean };
25
+
26
+ /** Our still-active approval of a head other than `headSha`, with the marker retention needs. A dismissed one lists as DISMISSED. */
27
+ export function standingApproval(reviews: ReviewRecord[], headSha: string, botLogin: string): StandingApproval | null {
28
+ for (const r of reviews) {
29
+ if (!isOurs(r, botLogin) || r.state !== "APPROVED") continue;
30
+ const covered = reviewedShas(r);
31
+
32
+ if (!covered || covered.head === headSha) continue; // no marker: fail closed; the live head itself: nothing to retain
33
+
34
+ return { reviewId: r.id, approvedHead: covered.head, approvedBase: covered.base, evidenceUnseen: evidenceUnseen(r) };
35
+ }
36
+
37
+ return null;
38
+ }
39
+
40
+ const findStandingApproval = (pr: PR, botLogin: string, cwd: string) => standingApproval(listReviews(pr.repo, pr.number, cwd), pr.headSha, botLogin);
41
+
42
+ /**
43
+ * Retention's last word, called after everything else passed: the PR still has the head and base it
44
+ * was checked at, and the approval being kept is still active. A push after this triggers its own run.
45
+ */
46
+ const retentionHolds = (pr: PR, reviewId: number, cwd: string) =>
47
+ unchanged(pr, cwd) && listReviews(pr.repo, pr.number, cwd).some((r) => r.id === reviewId && r.state === "APPROVED");
48
+
49
+ export type RetentionResult =
50
+ | { kept: true; approval: StandingApproval; pr: PR }
51
+ | { kept: false; reason: "not_posting" | "check_failed" | "rereview_requested" | "withdrawn" | "no_standing" | "evidence_unseen" | "compare_failed" | "diff_changed" | "gates_failed" | "pr_moved" };
52
+
53
+ const github = { findStandingApproval, compareDiff, retentionHolds };
54
+
55
+ /**
56
+ * Keep a standing approval only when its PR diff is byte-identical to the live one, every gate passes
57
+ * against today's trusted policy, and, checked last, the PR still matches what was checked.
58
+ * Otherwise fail closed to the normal dismiss path.
59
+ */
60
+ export function tryRetainApproval(pr: PR, botLogin: string, cwd: string, gatesPass: () => boolean, deps = github): RetentionResult {
61
+ const standing = deps.findStandingApproval(pr, botLogin, cwd);
62
+
63
+ if (!standing) return { kept: false, reason: "no_standing" };
64
+
65
+ // Approved without the CI test evidence policy asks for: review again, now that it may be there.
66
+ if (standing.evidenceUnseen) return { kept: false, reason: "evidence_unseen" };
67
+ let approvedDiff: string;
68
+ let currentDiff: string;
69
+
70
+ try {
71
+ approvedDiff = deps.compareDiff(pr.repo, standing.approvedBase, standing.approvedHead, cwd);
72
+ currentDiff = deps.compareDiff(pr.repo, pr.baseSha, pr.headSha, cwd);
73
+ } catch {
74
+ return { kept: false, reason: "compare_failed" };
75
+ }
76
+
77
+ if (!approvedDiffUnchanged(approvedDiff, currentDiff)) return { kept: false, reason: "diff_changed" };
78
+
79
+ // A byte-identical diff says nothing about policy tightened since, a new CHANGES_REQUESTED, or a conflict.
80
+ if (!gatesPass()) return { kept: false, reason: "gates_failed" };
81
+
82
+ // Last, because every check above read state that a push, retarget or manual dismissal can change.
83
+ if (!deps.retentionHolds(pr, standing.reviewId, cwd)) return { kept: false, reason: "pr_moved" };
84
+
85
+ return { kept: true, approval: standing, pr };
86
+ }