@jagreehal/shepherd 0.3.0 → 0.5.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 (55) hide show
  1. package/AGENTS.md +5 -0
  2. package/README.md +41 -419
  3. package/THIRD_PARTY_NOTICES.md +11 -0
  4. package/lenses/dotnet/SKILL.md +32 -0
  5. package/lenses/go/SKILL.md +30 -0
  6. package/lenses/java/SKILL.md +31 -0
  7. package/lenses/nextjs/SKILL.md +33 -0
  8. package/lenses/node-api/SKILL.md +32 -0
  9. package/lenses/nx-monorepo/SKILL.md +30 -0
  10. package/lenses/observability/SKILL.md +18 -11
  11. package/lenses/owasp-asvs/SKILL.md +50 -0
  12. package/lenses/owasp-llm/SKILL.md +44 -0
  13. package/lenses/python/SKILL.md +32 -0
  14. package/lenses/react/SKILL.md +33 -0
  15. package/lenses/rust/SKILL.md +31 -0
  16. package/package.json +17 -8
  17. package/packs/dotnet.yml +6 -0
  18. package/packs/go.yml +6 -0
  19. package/packs/java.yml +6 -0
  20. package/packs/nextjs.yml +7 -0
  21. package/packs/node-api.yml +7 -0
  22. package/packs/nx-monorepo.yml +6 -0
  23. package/packs/observability.yml +6 -0
  24. package/packs/owasp-asvs.yml +6 -0
  25. package/packs/owasp-llm.yml +8 -0
  26. package/packs/python.yml +6 -0
  27. package/packs/react.yml +6 -0
  28. package/packs/rust.yml +6 -0
  29. package/skills/ci-repair/SKILL.md +6 -1
  30. package/skills/garden/SKILL.md +28 -3
  31. package/skills/garden/references/telemetry.md +50 -0
  32. package/skills/incident/SKILL.md +6 -1
  33. package/skills/lens-import/SKILL.md +185 -0
  34. package/skills/lens-import/references/conversion.md +96 -0
  35. package/skills/lens-import/scripts/check-import.mjs +154 -0
  36. package/skills/shepherd/SKILL.md +121 -6
  37. package/skills/shepherd/references/dispatch.md +12 -0
  38. package/skills/shepherd/references/models.md +20 -7
  39. package/skills/shepherd/references/policy.md +9 -5
  40. package/skills/shepherd/references/stories.md +102 -0
  41. package/skills/swarm/SKILL.md +16 -1
  42. package/skills/swarm/references/custom-lenses.md +50 -7
  43. package/skills/triage/SKILL.md +19 -0
  44. package/src/cli.ts +210 -16
  45. package/src/config.ts +137 -21
  46. package/src/garden-traces.ts +461 -0
  47. package/src/garden.ts +2 -1
  48. package/src/install.ts +3 -0
  49. package/src/lens.ts +159 -8
  50. package/src/notify.ts +138 -0
  51. package/src/stack.ts +121 -0
  52. package/src/trace.ts +180 -0
  53. package/templates/shepherd-audit.yml +178 -0
  54. package/templates/shepherd-incident.yml +180 -0
  55. package/templates/shepherd.yml +427 -0
package/src/lens.ts CHANGED
@@ -5,7 +5,9 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
5
5
  import path from "node:path";
6
6
  import { parse, stringify } from "yaml";
7
7
  import { z } from "zod";
8
- import { type Config, ConfigSchema, type Lens, LensSchema, lensCache, ModelId, TEAM_FILES } from "./config.ts";
8
+ import { type Config, ConfigSchema, type Lens, LensSchema, lensCache, ModelId, SEVERITIES, TEAM_FILES } from "./config.ts";
9
+
10
+ type Severity = (typeof SEVERITIES)[number];
9
11
 
10
12
  export const BUILT_IN_LENSES = ["correctness", "security", "simplicity", "maintainability", "slop", "spec"];
11
13
 
@@ -29,7 +31,7 @@ export const repoLensFile = (repoRoot: string) => {
29
31
 
30
32
  const readFile = (file: string): LensFile => (existsSync(file) ? LensFileSchema.parse(parse(readFileSync(file, "utf8")) ?? {}) : { lenses: {} });
31
33
 
32
- export const readLenses = (file: string): Record<string, Lens> => readFile(file).lenses;
34
+ export const readLenses = (file: string) => readFile(file).lenses;
33
35
 
34
36
  /**
35
37
  * OpenCode agents for a harness whose subagent tool takes no model (OpenCode 1.x): one per rung,
@@ -37,7 +39,7 @@ export const readLenses = (file: string): Record<string, Lens> => readFile(file)
37
39
  * OPENCODE_CONFIG_CONTENT; swarm and the loop then dispatch by agent name.
38
40
  */
39
41
  export function opencodeAgents(choice: { ladder: string[] | null; models: Record<string, string> }) {
40
- const agent = (model: string, about: string) => ({ mode: "subagent", model, description: `shepherd runner on ${model} (${about})` });
42
+ const agent = (model: string, about: string) => ({ mode: "subagent", model: opencodeModel(model), description: `shepherd runner on ${model} (${about})` });
41
43
 
42
44
  return {
43
45
  agent: Object.fromEntries([
@@ -47,6 +49,20 @@ export function opencodeAgents(choice: { ladder: string[] | null; models: Record
47
49
  };
48
50
  }
49
51
 
52
+ // stamp's `provider:model` names where OpenCode's provider id differs; every other provider keeps its name.
53
+ const OPENCODE_PROVIDER = new Map([["bedrock", "amazon-bedrock"], ["vertex", "google-vertex"]]);
54
+
55
+ /**
56
+ * A model id as OpenCode spells it. stamp's canonical `provider:model` (`bedrock:eu.anthropic.claude-…-v1:0`)
57
+ * becomes `provider/model` (`amazon-bedrock/eu.anthropic.claude-…-v1:0`), so one ladder serves both tools.
58
+ * An OpenCode id or a Claude Code alias passes through.
59
+ */
60
+ export function opencodeModel(id: string): string {
61
+ const m = /^([a-z][a-z0-9-]*):(.+)$/.exec(id);
62
+
63
+ return m ? `${OPENCODE_PROVIDER.get(m[1]!) ?? m[1]}/${m[2]}` : id;
64
+ }
65
+
50
66
  /** Pin `name` (a lens or runner) to `model`, keeping everything else in the file. */
51
67
  export function pinModel(file: string, name: string, model: string): void {
52
68
  if (!LENS_NAME.test(name)) throw new Error(`"${name}" must be lowercase letters, digits, and dashes`);
@@ -55,6 +71,33 @@ export function pinModel(file: string, name: string, model: string): void {
55
71
  write(file, { ...current, models: { ...current.models, [name]: ModelId.parse(model) } });
56
72
  }
57
73
 
74
+ /** Name a model: `tier` becomes usable in the ladder and in pins, and swapping its model swaps it everywhere. */
75
+ export function setTier(file: string, tier: string, model: string): void {
76
+ if (!LENS_NAME.test(tier)) throw new Error(`"${tier}" must be lowercase letters, digits, and dashes`);
77
+ const current = readFile(file);
78
+
79
+ write(file, { ...current, tiers: { ...current.tiers, [tier]: ModelId.parse(model) } });
80
+ }
81
+
82
+ // The environment variable each OpenCode provider reads its key from. SHEPHERD_API_KEY fills the one the session
83
+ // model's provider needs, so a single-provider team sets one secret.
84
+ const PROVIDER_KEY_ENV = new Map([
85
+ ["opencode", "OPENCODE_API_KEY"],
86
+ ["opencode-go", "OPENCODE_API_KEY"],
87
+ ["anthropic", "ANTHROPIC_API_KEY"],
88
+ ["openai", "OPENAI_API_KEY"],
89
+ ["openrouter", "OPENROUTER_API_KEY"],
90
+ ["deepseek", "DEEPSEEK_API_KEY"],
91
+ ["groq", "GROQ_API_KEY"],
92
+ ["mistral", "MISTRAL_API_KEY"],
93
+ ["google", "GOOGLE_GENERATIVE_AI_API_KEY"],
94
+ ["xai", "XAI_API_KEY"],
95
+ ["amazon-bedrock", "AWS_BEARER_TOKEN_BEDROCK"],
96
+ ]);
97
+
98
+ /** The key variable for an OpenCode model id's provider, or null when shepherd does not know it. */
99
+ export const providerKeyEnv = (opencodeId: string): string | null => PROVIDER_KEY_ENV.get(opencodeId.split("/")[0]!) ?? null;
100
+
58
101
  /** Replace the ladder, cheapest model first. */
59
102
  export function setLadder(file: string, ladder: string[]): void {
60
103
  write(file, { ...readFile(file), ladder: z.array(ModelId).min(1).parse(ladder) });
@@ -97,7 +140,33 @@ fixes by its own rules. Nothing here can loosen shepherd's rules.
97
140
  - Escalate: <changes that go to the author instead of being fixed>.
98
141
  `;
99
142
 
100
- const RULE_ID = /^- \*\*([a-z0-9][a-z0-9-]*)\*\*/gm;
143
+ // `- **<id>**: <rule>`, or `- **<id>** [refuse|escalate|note]: <rule>` to set that rule's severity for stamp.
144
+ const RULE = /^- \*\*([a-z0-9][a-z0-9-]*)\*\*(?: \[(refuse|escalate|note)\])?:/gm;
145
+
146
+ export type LensRule = { id: string; severity?: Severity };
147
+
148
+ /** The rules in a lens's `## Review` section, with any severity tag; null when the section is missing. */
149
+ export function reviewRules(text: string): LensRule[] | null {
150
+ const review = /^## Review\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(text.replace(/\r\n/g, "\n"))?.[1];
151
+
152
+ if (review === undefined) return null;
153
+
154
+ return [...review.matchAll(RULE)].map((m) => {
155
+ const rule: LensRule = { id: m[1]! };
156
+ const severity = z.enum(SEVERITIES).optional().parse(m[2]);
157
+
158
+ if (severity) rule.severity = severity;
159
+
160
+ return rule;
161
+ });
162
+ }
163
+
164
+ /** Whether a lens entry's `only` and `disable` keep this rule. */
165
+ export const keepsRule = (lens: Pick<Lens, "only" | "disable">, id: string) => {
166
+ const hit = (globs: string[]) => globs.some((g) => new Bun.Glob(g).match(id));
167
+
168
+ return (!lens.only || hit(lens.only)) && !(lens.disable && hit(lens.disable));
169
+ };
101
170
 
102
171
  const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
103
172
 
@@ -112,17 +181,25 @@ export function lensProblems(lens: Lens, home: string, repoRoot: string): string
112
181
  const problems: string[] = [];
113
182
 
114
183
  if (front === undefined || !skillDescription(dir)) problems.push(`${file}: frontmatter needs a description`);
184
+ const ownLens = path.posix.normalize(lens.skill.replaceAll("\\", "/")).startsWith(".shepherd/lenses/");
115
185
 
116
- if (!path.posix.normalize(lens.skill.replaceAll("\\", "/")).startsWith(".shepherd/lenses/")) return problems;
117
- const review = /^## Review\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(text)?.[1];
186
+ // Rule ids are required under .shepherd/lenses/, and wherever only or disable must match them.
187
+ if (!ownLens && !lens.only && !lens.disable) return problems;
188
+ const rules = reviewRules(text);
118
189
 
119
- if (review === undefined) return [...problems, `${file}: add a "## Review" section`];
120
- const ids = [...review.matchAll(RULE_ID)].map((m) => m[1]);
190
+ if (rules === null) return [...problems, `${file}: add a "## Review" section`];
191
+ const ids = rules.map((r) => r.id);
121
192
 
122
193
  if (ids.length === 0) problems.push(`${file}: "## Review" has no rules; write each as "- **<id>**: <rule>", the id lowercase with dashes`);
123
194
 
124
195
  for (const id of new Set(ids.filter((id, i) => ids.indexOf(id) !== i))) problems.push(`${file}: rule id "${id}" is used more than once`);
125
196
 
197
+ for (const g of [...(lens.only ?? []), ...(lens.disable ?? [])]) {
198
+ if (!ids.some((id) => new Bun.Glob(g).match(id))) problems.push(`${file}: "${g}" in only or disable matches no rule id`);
199
+ }
200
+
201
+ if (ids.length && !ids.some((id) => keepsRule(lens, id))) problems.push(`${file}: only and disable leave no rule`);
202
+
126
203
  return problems;
127
204
  }
128
205
 
@@ -153,6 +230,64 @@ export function newLens(repoRoot: string, name: string, lens: Omit<Lens, "skill"
153
230
  return dir;
154
231
  }
155
232
 
233
+ /** The bundled packs (packs/<name>.yml): one starter lens each, with the files it applies to and its gate. */
234
+ export const PACKS_DIR = path.resolve(import.meta.dir, "..", "packs");
235
+
236
+ /** The lens entry a bundled pack declares for its own lens, minus the skill path. */
237
+ export function packLens(stack: string): Omit<Lens, "skill"> {
238
+ const { skill: _, ...rest } = LensSchema.parse(ConfigSchema.parse(parse(readFileSync(path.join(PACKS_DIR, `${stack}.yml`), "utf8"))).lenses[stack]);
239
+
240
+ return rest;
241
+ }
242
+
243
+ // A dependency in any package.json that marks a stack. next implies react: its pack extends react's.
244
+ const NPM_STACKS: [RegExp, string[]][] = [
245
+ [/^next$/, ["react", "nextjs"]],
246
+ [/^(react|react-dom)$/, ["react"]],
247
+ [/^(express|fastify|hono|koa|@nestjs\/core)$/, ["node-api"]],
248
+ ];
249
+
250
+ // A tracked file, anywhere in the repository, that marks a stack.
251
+ const FILE_STACKS: [RegExp, string][] = [
252
+ [/(^|\/)go\.mod$/, "go"],
253
+ [/(^|\/)Cargo\.toml$/, "rust"],
254
+ [/(^|\/)(pom\.xml|build\.gradle(\.kts)?)$/, "java"],
255
+ [/\.(csproj|fsproj|sln)$/, "dotnet"],
256
+ [/(^|\/)(pyproject\.toml|setup\.py|requirements\.txt)$/, "python"],
257
+ [/(^|\/)nx\.json$/, "nx-monorepo"],
258
+ ];
259
+
260
+ const PackageJson = z.object({ dependencies: z.record(z.string(), z.string()).optional(), devDependencies: z.record(z.string(), z.string()).optional() });
261
+
262
+ /** JSON, or null when malformed: a broken package.json marks nothing. */
263
+ const parseJson = (text: string) => {
264
+ try {
265
+ return JSON.parse(text);
266
+ } catch {
267
+ return null;
268
+ }
269
+ };
270
+
271
+ /** The bundled stack packs this repository's tracked files point at, sorted by name. `files` is `git ls-files`. */
272
+ export function detectStacks(files: string[], read: (rel: string) => string | null): string[] {
273
+ const found = new Set<string>();
274
+
275
+ for (const f of files) {
276
+ for (const [re, stack] of FILE_STACKS) if (re.test(f)) found.add(stack);
277
+
278
+ if (!/(^|\/)package\.json$/.test(f)) continue;
279
+ const pkg = PackageJson.safeParse(parseJson(read(f) ?? "{}"));
280
+ const deps = pkg.success ? Object.keys({ ...pkg.data.dependencies, ...pkg.data.devDependencies }) : [];
281
+
282
+ for (const [re, stacks] of NPM_STACKS) if (deps.some((d) => re.test(d))) for (const s of stacks) found.add(s);
283
+ }
284
+
285
+ // ASVS holds for every language, so any detected stack brings it.
286
+ if (found.size) found.add("owasp-asvs");
287
+
288
+ return lensTemplates().filter((t) => found.has(t));
289
+ }
290
+
156
291
  /** The directory holding the skill's SKILL.md: a path against the repository, or a name in the usual skills directories. */
157
292
  export function resolveSkill(ref: string, home: string, repoRoot: string): string | null {
158
293
  const pinned = lensCache(home, ref);
@@ -176,3 +311,19 @@ export function skillDescription(skillDir: string): string | null {
176
311
 
177
312
  return parsed.success ? parsed.data.description.replace(/\s+/g, " ").trim() : null;
178
313
  }
314
+
315
+ /**
316
+ * A detected stack's lens, copied from its starter into .shepherd/lenses/<stack> so the team owns and trims it,
317
+ * with the pack's applies_to and gate. An existing lens directory is kept as it is.
318
+ */
319
+ export function stackLens(repoRoot: string, stack: string): Lens {
320
+ const skill = path.posix.join(".shepherd", "lenses", stack);
321
+ const dir = path.join(repoRoot, skill);
322
+
323
+ if (!existsSync(path.join(dir, "SKILL.md"))) {
324
+ mkdirSync(dir, { recursive: true });
325
+ writeFileSync(path.join(dir, "SKILL.md"), fromTemplate(stack, stack));
326
+ }
327
+
328
+ return { skill, ...packLens(stack) };
329
+ }
package/src/notify.ts ADDED
@@ -0,0 +1,138 @@
1
+ // Outbound notifications. Off until SHEPHERD_NOTIFY_WEBHOOK is set. A Slack Incoming Webhook URL gets a
2
+ // Slack message; any other URL gets the event as JSON, for Discord relays, Teams, n8n, Zapier or an agent
3
+ // platform's trigger. The caller runs `shepherd notify` right after setting the commit status; this
4
+ // module drops repeats (a local record across heads, a `shepherd/notify` status on the head for fresh CI
5
+ // runners), so a /loop or a rerun tells people once per change of state, not every iteration. People answer
6
+ // on the PR, where the next iteration's triage reads them.
7
+ import { execFileSync } from "node:child_process";
8
+ import { createHash } from "node:crypto";
9
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
10
+ import path from "node:path";
11
+ import { z } from "zod";
12
+ import { stateDir } from "./local.ts";
13
+
14
+ export const STATES = ["success", "failure", "pending", "error"] as const;
15
+
16
+ export type State = (typeof STATES)[number];
17
+
18
+ export type NotifyEvent = {
19
+ event: "shepherd.state";
20
+ repo: string;
21
+ pr: number;
22
+ url: string;
23
+ head_sha: string;
24
+ state: State;
25
+ description: string;
26
+ };
27
+
28
+ /** States that notify unless SHEPHERD_NOTIFY_ON says otherwise: done, needs a person, and stopped by an error. */
29
+ export const NOTIFY_DEFAULT: State[] = ["success", "failure", "error"];
30
+
31
+ export function notifyOn(raw: string | undefined): State[] {
32
+ const asked = new Set((raw ?? "").split(",").map((s) => s.trim().toLowerCase()));
33
+ const list = STATES.filter((s) => asked.has(s));
34
+
35
+ return list.length ? list : NOTIFY_DEFAULT;
36
+ }
37
+
38
+ const LABEL: Record<State, string> = { success: "ready to merge", failure: "needs you", pending: "working", error: "stopped" };
39
+
40
+ // Descriptions can quote PR titles, reviewers and bot output; Slack reads <...> as links and mentions (<!channel>).
41
+ export const slackEscape = (t: string) => t.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
42
+
43
+ export const isSlack = (url: string) => url.startsWith("https://hooks.slack.com/services/");
44
+
45
+ export function payload(url: string, e: NotifyEvent): string {
46
+ return JSON.stringify(isSlack(url) ? { text: `*shepherd ${LABEL[e.state]}* <${e.url}|${e.repo}#${e.pr}>\n${slackEscape(e.description)}` } : e);
47
+ }
48
+
49
+ export type Sent = "sent" | "unchanged" | "off" | "failed";
50
+
51
+ /** Where the last delivered (or deliberately skipped) state is kept. Written only after it is settled. */
52
+ export type Ledger = { read(): string | null; write(token: string): void };
53
+
54
+ const token = (e: NotifyEvent) => createHash("sha256").update(`${e.state}\n${e.description}`).digest("hex").slice(0, 16);
55
+
56
+ /** A file under the git directory: survives a local /loop across heads. */
57
+ export function fileLedger(repoRoot: string, pr: number): Ledger {
58
+ // Resolved on use: outside a repository, read and write throw and notify treats that as no record.
59
+ const file = () => path.join(stateDir(repoRoot), `notified-${pr}`);
60
+
61
+ return {
62
+ read: () => (existsSync(file()) ? readFileSync(file(), "utf8").trim() : null),
63
+ write: (t) => {
64
+ mkdirSync(path.dirname(file()), { recursive: true });
65
+ writeFileSync(file(), t);
66
+ },
67
+ };
68
+ }
69
+
70
+ const Statuses = z.array(z.object({ context: z.string(), description: z.string().nullable() }));
71
+
72
+ export const LEDGER_CONTEXT = "shepherd/notify";
73
+
74
+ /**
75
+ * A `shepherd/notify` commit status on the head: survives fresh CI runners, and is separate from the `shepherd`
76
+ * status, so a status that was set but never delivered is retried. GitHub lists statuses newest first.
77
+ */
78
+ export function statusLedger(repo: string, head: string, cwd: string): Ledger {
79
+ const gh = (args: string[]) => execFileSync("gh", args, { cwd, encoding: "utf8", timeout: 15_000 });
80
+
81
+ return {
82
+ read: () => {
83
+ const latest = Statuses.parse(JSON.parse(gh(["api", `repos/${repo}/commits/${head}/statuses?per_page=100`]))).find((st) => st.context === LEDGER_CONTEXT);
84
+
85
+ return /([0-9a-f]{16})$/.exec(latest?.description ?? "")?.[1] ?? null;
86
+ },
87
+ write: (t) => {
88
+ gh(["api", `repos/${repo}/statuses/${head}`, "-f", `context=${LEDGER_CONTEXT}`, "-f", "state=success", "-f", `description=last notified ${t}`]);
89
+ },
90
+ };
91
+ }
92
+
93
+ /**
94
+ * Posts the event when its state is wanted and differs from the last one settled for this PR. A state that is
95
+ * not wanted is settled without a post, so failure → pending → failure tells people twice. A failed post is
96
+ * not settled, so the next call retries it. A ledger that cannot be read or written never stops the call.
97
+ * Never throws.
98
+ */
99
+ export async function notify(url: string | undefined, e: NotifyEvent, on: State[], ledgers: Ledger[], post: typeof fetch = fetch): Promise<Sent> {
100
+ if (!url) return "off";
101
+ const t = token(e);
102
+
103
+ for (const l of ledgers) {
104
+ try {
105
+ if (l.read() === t) return "unchanged";
106
+ } catch {
107
+ // unreadable: treat as not sent
108
+ }
109
+ }
110
+
111
+ const settle = () => {
112
+ for (const l of ledgers) {
113
+ try {
114
+ l.write(t);
115
+ } catch {
116
+ // a repeat next time is better than failing this iteration
117
+ }
118
+ }
119
+ };
120
+
121
+ if (!on.includes(e.state)) {
122
+ settle();
123
+
124
+ return "off";
125
+ }
126
+
127
+ try {
128
+ const res = await post(url, { method: "POST", headers: { "content-type": "application/json" }, body: payload(url, e), signal: AbortSignal.timeout(10_000) });
129
+
130
+ if (!res.ok) return "failed";
131
+ } catch {
132
+ return "failed";
133
+ }
134
+
135
+ settle();
136
+
137
+ return "sent";
138
+ }
package/src/stack.ts ADDED
@@ -0,0 +1,121 @@
1
+ // Stacked PRs and wrong bases, detected the way stamp detects them before it reviews. A PR's base...head
2
+ // diff is what lands when it merges, which is right for a lone PR and wrong for two common shapes: a PR stacked on another open PR into the same base (its diff
3
+ // carries the parent's change), and a PR branched from one long-lived branch but opened against another
4
+ // (its diff carries everything the two branches differ by). Everything here is git ancestry on immutable
5
+ // SHAs; nothing a PR author writes (body, title, "stacked on #n") is read.
6
+ import { execFileSync } from "node:child_process";
7
+ import path from "node:path";
8
+ import { z } from "zod";
9
+
10
+ export type StackDeps = {
11
+ /** `git rev-list --topo-order <head> ^<base>`: this PR's commits, newest first. */
12
+ commits: (head: string, base: string) => string[];
13
+ /** How many of this PR's commits are not on `branch` (a remote-tracking ref). */
14
+ notOn: (head: string, base: string, branch: string) => number;
15
+ /** Remote branch names, `git ls-remote --heads origin`. */
16
+ branches: () => string[];
17
+ /** Fetch these branches into their remote-tracking refs. */
18
+ fetch: (branches: string[]) => void;
19
+ };
20
+
21
+ export type WrongBase = { branch: string; on: number; total: number };
22
+
23
+ /**
24
+ * The long-lived branch this PR's commits mostly already sit on, when that is not its base: it was branched
25
+ * from there and opened against the wrong target. A branch holding every commit of the PR is not flagged
26
+ * (a backport or a promotion PR), and neither is the PR's own head branch.
27
+ */
28
+ export function wrongBase(pr: { headSha: string; baseSha: string; baseRef: string; headRef: string }, longLived: string[], deps: StackDeps): WrongBase | null {
29
+ if (!longLived.length) return null;
30
+ const candidates = deps.branches().filter((b) => b !== pr.baseRef && b !== pr.headRef && longLived.some((g) => path.matchesGlob(b, g)));
31
+
32
+ if (!candidates.length) return null;
33
+ const total = deps.commits(pr.headSha, pr.baseSha).length;
34
+
35
+ if (total < 2) return null;
36
+ deps.fetch(candidates);
37
+ let worst: WrongBase | null = null;
38
+
39
+ for (const branch of candidates) {
40
+ const off = deps.notOn(pr.headSha, pr.baseSha, branch);
41
+ const on = total - off;
42
+
43
+ if (off > 0 && on * 2 > total && (!worst || on > worst.on)) worst = { branch, on, total };
44
+ }
45
+
46
+ return worst;
47
+ }
48
+
49
+ /**
50
+ * The nearest open PR into the same base whose head is one of this PR's own commits: the parent this PR is
51
+ * stacked on. Its head being in base..head is the whole test, so a PR already merged into the base, or one
52
+ * that only shares history, never counts.
53
+ */
54
+ export function stackedParent(pr: { number: number; headSha: string; baseSha: string }, open: { number: number; headRefOid: string }[], deps: Pick<StackDeps, "commits">): { parent: number; parentHead: string } | null {
55
+ const others = open.filter((p) => p.number !== pr.number && p.headRefOid !== pr.headSha);
56
+
57
+ if (!others.length) return null;
58
+ const order = deps.commits(pr.headSha, pr.baseSha);
59
+ let best: { parent: number; parentHead: string; at: number } | null = null;
60
+
61
+ for (const p of others) {
62
+ const at = order.indexOf(p.headRefOid);
63
+
64
+ if (at >= 0 && (!best || at < best.at)) best = { parent: p.number, parentHead: p.headRefOid, at };
65
+ }
66
+
67
+ return best && { parent: best.parent, parentHead: best.parentHead };
68
+ }
69
+
70
+ // The same default stamp's policy carries: branches a PR is opened from and merged into, never feature branches.
71
+ export const LONG_LIVED = ["main", "master", "develop", "release", "release/*", "staging"];
72
+
73
+ const View = z.object({ number: z.number(), headRefName: z.string(), headRefOid: z.string(), baseRefName: z.string() });
74
+
75
+ const Open = z.array(z.object({ number: z.number(), headRefOid: z.string(), isCrossRepository: z.boolean() }));
76
+
77
+ export type Stack = {
78
+ pr: number;
79
+ head_sha: string;
80
+ base_ref: string;
81
+ /** Set when most of the PR's commits already sit on another long-lived branch: retarget it, review nothing. */
82
+ wrong_base: WrongBase | null;
83
+ /** The open PR this one is stacked on; review `range` instead of the whole PR. */
84
+ parent: { number: number; head: string } | null;
85
+ /** The git range to review: the delta over the parent, or base...head. */
86
+ range: string;
87
+ };
88
+
89
+ /** Fetch what the checks need (the PR head, its base, full history), then run them against GitHub's open PRs. */
90
+ export function prStack(number: number, repoRoot: string): Stack {
91
+ const run = (cmd: string, ...args: string[]) => execFileSync(cmd, args, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 << 20 }).trim();
92
+ // Fetches authenticate through gh, since a CI checkout keeps no token for a private origin.
93
+ const git = (...args: string[]) => run("git", "-c", "credential.helper=", "-c", "credential.helper=!gh auth git-credential", ...args);
94
+ const view = View.parse(JSON.parse(run("gh", "pr", "view", String(number), "--json", "number,headRefName,headRefOid,baseRefName")));
95
+ const baseRef = `refs/remotes/origin/${view.baseRefName}`;
96
+
97
+ if (git("rev-parse", "--is-shallow-repository") === "true") git("fetch", "-q", "--unshallow", "origin");
98
+ git("fetch", "-q", "origin", `refs/pull/${number}/head`, `+refs/heads/${view.baseRefName}:${baseRef}`);
99
+ const baseSha = git("rev-parse", baseRef);
100
+
101
+ const deps: StackDeps = {
102
+ commits: (head, base) => git("rev-list", "--topo-order", head, `^${base}`).split("\n").filter(Boolean),
103
+ notOn: (head, base, branch) => Number(git("rev-list", "--count", head, `^${base}`, `^refs/remotes/origin/${branch}`)),
104
+ branches: () => git("ls-remote", "--heads", "origin").split("\n").flatMap((l) => l.split("\trefs/heads/")[1] ?? []),
105
+ fetch: (branches) => void git("fetch", "-q", "origin", ...branches.map((b) => `+refs/heads/${b}:refs/remotes/origin/${b}`)),
106
+ };
107
+
108
+ const pr = { number, headSha: view.headRefOid, baseSha, baseRef: view.baseRefName, headRef: view.headRefName };
109
+ const wrong = wrongBase(pr, LONG_LIVED, deps);
110
+ const open = wrong ? [] : Open.parse(JSON.parse(run("gh", "pr", "list", "--state", "open", "--base", view.baseRefName, "--limit", "100", "--json", "number,headRefOid,isCrossRepository"))).filter((p) => !p.isCrossRepository);
111
+ const parent = stackedParent(pr, open, deps);
112
+
113
+ return {
114
+ pr: number,
115
+ head_sha: view.headRefOid,
116
+ base_ref: view.baseRefName,
117
+ wrong_base: wrong,
118
+ parent: parent && { number: parent.parent, head: parent.parentHead },
119
+ range: `${parent?.parentHead ?? baseSha}...${view.headRefOid}`,
120
+ };
121
+ }
package/src/trace.ts ADDED
@@ -0,0 +1,180 @@
1
+ // Iteration traces. The agent drives shepherd's steps, so this CLI cannot watch them run. The skill marks each
2
+ // step's start and end with `shepherd trace event`, which takes the time from this machine, and
3
+ // `shepherd trace flush` turns the record into one `shepherd.iteration` span with a child span per step.
4
+ // Spans export through autotel only when OTEL_EXPORTER_OTLP_ENDPOINT is set. Model usage inside a step is the
5
+ // harness's to report: these spans time the steps and record their outcomes, nothing inside them.
6
+ import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
7
+ import path from "node:path";
8
+ import { z } from "zod";
9
+ import { stateDir } from "./local.ts";
10
+
11
+ // `stamp` is the wait for stamp's verdict.
12
+ export const STAGES = ["checks", "swarm", "verify", "triage", "simplify", "ci-repair", "stamp"] as const;
13
+
14
+ const Event = z.object({
15
+ at: z.string(),
16
+ stage: z.enum(STAGES),
17
+ phase: z.enum(["start", "end"]),
18
+ round: z.number().int().positive().optional(),
19
+ outcome: z.enum(["ok", "failed", "skipped"]).optional(),
20
+ retries: z.number().int().nonnegative().optional(),
21
+ head_sha: z.string().regex(/^[0-9a-f]{7,40}$/).optional(),
22
+ });
23
+
24
+ export type TraceEvent = z.infer<typeof Event>;
25
+
26
+ export type Stage = {
27
+ stage: TraceEvent["stage"];
28
+ round: number | undefined;
29
+ start: string;
30
+ end: string;
31
+ outcome: "ok" | "failed" | "skipped" | "unfinished";
32
+ retries: number;
33
+ head_sha: string | undefined;
34
+ };
35
+
36
+ /** The record for one PR's current iteration, inside the git directory like shepherd's other state. */
37
+ export const traceFile = (repoRoot: string, pr: number) => path.join(stateDir(repoRoot), `trace-${pr}.jsonl`);
38
+
39
+ /** A step event as the CLI receives it, before validation. */
40
+ export type EventInput = { stage: string; phase: string; round?: number | undefined; outcome?: string | undefined; retries?: number | undefined; head_sha?: string | undefined };
41
+
42
+ /** Append one step event, stamped now. Throws on an unknown stage or a malformed field. */
43
+ export function recordEvent(file: string, event: EventInput, now = new Date()): TraceEvent {
44
+ const parsed = Event.safeParse({ ...event, at: now.toISOString() });
45
+
46
+ if (!parsed.success) throw new Error(`trace event: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
47
+
48
+ const e = parsed.data;
49
+
50
+ mkdirSync(path.dirname(file), { recursive: true });
51
+ appendFileSync(file, JSON.stringify(e) + "\n");
52
+
53
+ return e;
54
+ }
55
+
56
+ const parseLine = (line: string): TraceEvent[] => {
57
+ try {
58
+ const parsed = Event.safeParse(JSON.parse(line));
59
+
60
+ return parsed.success ? [parsed.data] : [];
61
+ } catch {
62
+ return [];
63
+ }
64
+ };
65
+
66
+ /** The steps of one iteration, and when its first event happened. */
67
+ export type StageRecord = { start: string | null; stages: Stage[] };
68
+
69
+ /**
70
+ * Steps from the record: each start pairs with the next end of the same stage and round, or of the same stage
71
+ * when the end's round differs from every open start's. A start with no end closes at `now` as unfinished; an
72
+ * end with no start, or a line that does not parse, is dropped.
73
+ */
74
+ export function stagesFrom(text: string, now: Date): StageRecord {
75
+ const events = text.split("\n").filter((l) => l.trim()).flatMap(parseLine);
76
+ const open = new Map<string, TraceEvent>();
77
+ const stages: Stage[] = [];
78
+
79
+ for (const e of events) {
80
+ const exact = `${e.stage}#${e.round ?? 0}`;
81
+ const key = e.phase === "end" && !open.has(exact) ? ([...open.keys()].filter((k) => k.startsWith(`${e.stage}#`)).at(-1) ?? exact) : exact;
82
+ const started = open.get(key);
83
+
84
+ if (e.phase === "start") open.set(key, e);
85
+ else if (started) {
86
+ open.delete(key);
87
+ stages.push({ stage: e.stage, round: started.round ?? e.round, start: started.at, end: e.at, outcome: e.outcome ?? "ok", retries: e.retries ?? 0, head_sha: e.head_sha ?? started.head_sha });
88
+ }
89
+ }
90
+
91
+ for (const s of open.values()) stages.push({ stage: s.stage, round: s.round, start: s.at, end: now.toISOString(), outcome: "unfinished", retries: s.retries ?? 0, head_sha: s.head_sha });
92
+
93
+ return { start: events[0]?.at ?? null, stages: stages.sort((a, b) => a.start.localeCompare(b.start)) };
94
+ }
95
+
96
+ /** What ties an iteration to the PR, the CI run and other traces: stamp's review, a CI run's trace. */
97
+ export type Iteration = {
98
+ repo: string;
99
+ pr: number;
100
+ headSha: string;
101
+ baseSha: string | undefined;
102
+ outcome: string;
103
+ ciRun: number | undefined;
104
+ ciAttempt: number | undefined;
105
+ // W3C traceparent values; each becomes a span link, so separate processes join without one long trace.
106
+ links: string[];
107
+ };
108
+
109
+ const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
110
+
111
+ /** The iteration span's attributes, named like stamp's so one query finds both. An absent value stays undefined. */
112
+ export const iterationAttributes = (it: Iteration, stages: Stage[]) => ({
113
+ "vcs.repository.name": it.repo,
114
+ "vcs.change.id": String(it.pr),
115
+ "vcs.ref.head.revision": it.headSha,
116
+ "vcs.ref.base.revision": it.baseSha,
117
+ "cicd.pipeline.run.id": it.ciRun === undefined ? undefined : String(it.ciRun),
118
+ "shepherd.ci.attempt": it.ciAttempt,
119
+ "shepherd.outcome": it.outcome,
120
+ "shepherd.rounds": Math.max(0, ...stages.map((s) => s.round ?? 0)),
121
+ "shepherd.retries": stages.reduce((n, s) => n + s.retries, 0),
122
+ });
123
+
124
+ export const stageAttributes = (s: Stage) => ({
125
+ "shepherd.stage": s.stage,
126
+ "shepherd.outcome": s.outcome,
127
+ "shepherd.retries": s.retries,
128
+ "shepherd.round": s.round,
129
+ "vcs.ref.head.revision": s.head_sha,
130
+ });
131
+
132
+ // OpenTelemetry rejects an undefined attribute value, so absent ones are left off.
133
+ const defined = (attrs: ReturnType<typeof iterationAttributes> | ReturnType<typeof stageAttributes>) => Object.fromEntries(Object.entries(attrs).filter(([, v]) => v !== undefined));
134
+
135
+ /** Export the iteration and its steps through autotel. The SDK loads only here, so an unset endpoint costs nothing. */
136
+ async function exportSpans(start: string, it: Iteration, stages: Stage[], now: Date): Promise<void> {
137
+ const { init, shutdown, getTracer, runWithSpan, SpanStatusCode } = await import("autotel");
138
+
139
+ init({ service: process.env.OTEL_SERVICE_NAME || "shepherd" });
140
+
141
+ const tracer = getTracer("shepherd");
142
+
143
+ const links = it.links.flatMap((l) => {
144
+ const m = TRACEPARENT.exec(l);
145
+
146
+ return m ? [{ context: { traceId: m[1]!, spanId: m[2]!, traceFlags: parseInt(m[3]!, 16) } }] : [];
147
+ });
148
+
149
+ const root = tracer.startSpan("shepherd.iteration", { startTime: new Date(start), links, attributes: defined(iterationAttributes(it, stages)) });
150
+
151
+ for (const s of stages) {
152
+ const span = runWithSpan(root, () => tracer.startSpan(`shepherd.${s.stage}`, { startTime: new Date(s.start), attributes: defined(stageAttributes(s)) }));
153
+
154
+ if (s.outcome === "failed" || s.outcome === "unfinished") span.setStatus({ code: SpanStatusCode.ERROR });
155
+ span.end(new Date(s.end));
156
+ }
157
+
158
+ root.end(now);
159
+ await shutdown();
160
+ }
161
+
162
+ /**
163
+ * Close the iteration: read its record, export it when an endpoint is set, and clear the record for the next one.
164
+ * The record clears whether or not the export reaches the collector, and the result carries the export's error.
165
+ */
166
+ export async function flush(file: string, it: Iteration, now = new Date()): Promise<{ stages: Stage[]; exported: boolean; error?: string }> {
167
+ const { start, stages } = stagesFrom(existsSync(file) ? readFileSync(file, "utf8") : "", now);
168
+
169
+ try {
170
+ if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT || !start) return { stages, exported: false };
171
+
172
+ await exportSpans(start, it, stages, now);
173
+
174
+ return { stages, exported: true };
175
+ } catch (e) {
176
+ return { stages, exported: false, error: e instanceof Error ? e.message : String(e) };
177
+ } finally {
178
+ rmSync(file, { force: true });
179
+ }
180
+ }