@jagreehal/shepherd 0.0.0-stage → 0.2.0

package/src/garden.ts

@@ -0,0 +1,198 @@
+// The gardener's evidence: what shepherd did on a repository's recent PRs, read from GitHub (the record,
+// never a session), and scored by fixed signals. The `garden` skill turns the scores into skill edits and
+// the recurring lens findings into lint-rule proposals.
+import { execFileSync } from "node:child_process";
+import { z } from "zod";
+
+export const HEADER = "🤖 Automated comment by";
+
+export type Thread = { tag: string; severity: string; path: string; resolved: boolean; humanReplied: boolean };
+
+export type Commit = { sha: string; headline: string; skill: string | null; lens: string | null; fixes: string[]; date: string };
+
+export type PrRecord = {
+  number: number;
+  title: string;
+  state: string;
+  threads: Thread[];
+  commits: Commit[];
+  status: { state: string; description: string; updatedAt: string } | null;
+  rounds: number | null;
+  /** The author can push to the repository. Only then do the PR's Shepherd-Fixes trailers count. */
+  trusted: boolean;
+};
+
+const DAY = 864e5;
+
+export type Signal = "reverted_fix" | "human_replied" | "round_cap" | "stopped_short" | "loop_stalled" | "churn";
+
+const TAG = /\*\*\[(?:convergent: )?([^\]]+)\]\*\*\s*\S+\s*(CRITICAL|HIGH|MEDIUM|LOW|NIT)/;
+
+const ROUND = /\(round (\d+) @/;
+
+/** The lens rules in a finding's tag, `[convergent: a/b + c/d]` giving both. A bare lens name is no rule, and
+ * `checks/*` already comes from a tool, so neither is a candidate for a new lint rule. */
+const rulesOf = (tag: string) => tag.split(" + ").map((t) => t.trim()).filter((t) => t.includes("/") && !t.startsWith("checks/"));
+
+const isReverted = (commit: Commit, commits: Commit[]) => commits.some((r) => r.headline === `Revert "${commit.headline}"`);
+
+/** True when shepherd left any mark on the PR: a thread, a commit, a status, or a swarm summary. */
+const touched = (pr: PrRecord) => pr.threads.length > 0 || pr.commits.some((c) => c.skill) || pr.status !== null || pr.rounds !== null;
+
+/**
+ * Fixed signals per PR shepherd touched, and the lens rules triage fixed (Shepherd-Fixes) on at least `minPrs` PRs. A reply is
+ * only `human_replied`: whether it corrected shepherd is the gardener's reading. `loop_stalled` needs a day of
+ * silence, so a run in flight never counts.
+ */
+export function score(all: PrRecord[], minPrs = 3, now = Date.now()) {
+  const prs = all.filter(touched);
+
+  const scored = prs.map((pr) => {
+    const shepherdCommits = pr.commits.filter((c) => c.skill);
+    const reverted = shepherdCommits.filter((c) => isReverted(c, pr.commits));
+    const replied = pr.threads.filter((t) => t.humanReplied);
+    const lastActivity = Math.max(Date.parse(pr.status?.updatedAt ?? "") || 0, ...shepherdCommits.map((c) => Date.parse(c.date) || 0));
+    const final = pr.status?.state === "success" || pr.status?.state === "failure";
+    const signals: Signal[] = [];
+
+    if (reverted.length) signals.push("reverted_fix");
+
+    if (replied.length) signals.push("human_replied");
+
+    if ((pr.rounds ?? 0) >= 4) signals.push("round_cap");
+
+    if (pr.status?.state === "failure") signals.push("stopped_short");
+
+    if (shepherdCommits.length && !final && now - lastActivity > DAY) signals.push("loop_stalled");
+
+    if (shepherdCommits.length > 10) signals.push("churn");
+
+    return {
+      number: pr.number,
+      title: pr.title,
+      signals,
+      shepherdCommits: shepherdCommits.length,
+      reverted: reverted.map((c) => ({ sha: c.sha, headline: c.headline, skill: c.skill, lens: c.lens })),
+      replied: replied.map((t) => `${t.path} [${t.tag}]`),
+      threads: { posted: pr.threads.length, open: pr.threads.filter((t) => !t.resolved).length },
+      status: pr.status,
+      rounds: pr.rounds,
+    };
+  });
+
+  const byRule = new Map<string, { prs: Set<number>; paths: Set<string> }>();
+
+  // Accepted means triage fixed it and said so in a Shepherd-Fixes trailer. Triage also resolves findings it
+  // judged wrong, so a resolved thread proves nothing; and a thread a person argued in never counts.
+  for (const pr of prs.filter((p) => p.trusted)) {
+    const acceptedCommits = pr.commits.filter((c) => !isReverted(c, pr.commits));
+
+    for (const rule of new Set(acceptedCommits.flatMap((c) => c.fixes).flatMap(rulesOf))) {
+      const argued = pr.threads.some((t) => t.humanReplied && rulesOf(t.tag).includes(rule));
+
+      if (argued) continue;
+      const entry = byRule.get(rule) ?? { prs: new Set(), paths: new Set() };
+      entry.prs.add(pr.number);
+
+      for (const t of pr.threads.filter((x) => rulesOf(x.tag).includes(rule))) entry.paths.add(t.path);
+      byRule.set(rule, entry);
+    }
+  }
+
+  const recurring = [...byRule]
+    .flatMap(([rule, e]) => (e.prs.size >= minPrs ? [{ rule, prs: [...e.prs].sort((a, b) => a - b), paths: [...e.paths].sort() }] : []))
+    .sort((a, b) => b.prs.length - a.prs.length || a.rule.localeCompare(b.rule));
+
+  return { prs: scored, recurring };
+}
+
+/** Parse one shepherd thread's first comment and its replies; null when the thread is not shepherd's. */
+export function parseThread(path: string, resolved: boolean, comments: { author: string; bot: boolean; body: string }[]): Thread | null {
+  const [first, ...replies] = comments;
+
+  if (!first?.body.includes(HEADER)) return null;
+  const m = TAG.exec(first.body);
+
+  if (!m) return null;
+  const humanReplied = replies.some((c) => !c.body.includes(HEADER) && !c.bot);
+
+  return { tag: m[1]!, severity: m[2]!, path, resolved, humanReplied };
+}
+
+/** One commit's shepherd trailers, from its full message. */
+export function parseCommit(sha: string, message: string, date = ""): Commit {
+  const trailer = (key: string) => new RegExp(`^${key}: (\\S+)`, "m").exec(message)?.[1] ?? null;
+
+  const fixes = [...message.matchAll(/^Shepherd-Fixes: (\S+)/gm)].map((m) => m[1]!);
+
+  return { sha, headline: message.split("\n")[0] ?? "", skill: trailer("Shepherd"), lens: trailer("Shepherd-Lens"), fixes, date };
+}
+
+export const roundsOf = (summaryBody: string | undefined) => (summaryBody ? Number(ROUND.exec(summaryBody)?.[1] ?? 0) || null : null);
+
+const gh = (args: string[]) => execFileSync("gh", args, { encoding: "utf8", maxBuffer: 64 << 20, stdio: ["ignore", "pipe", "pipe"] }); // stderr rides on the thrown error
+
+const PrList = z.array(z.object({ number: z.number(), title: z.string(), state: z.string(), headRefOid: z.string(), author: z.object({ login: z.string() }) }));
+
+const Permission = z.object({ permission: z.string() });
+
+const Threads = z.object({
+  data: z.object({
+    repository: z.object({
+      pullRequest: z.object({
+        reviewThreads: z.object({
+          nodes: z.array(
+            z.object({
+              isResolved: z.boolean(),
+              path: z.string(),
+              comments: z.object({ nodes: z.array(z.object({ author: z.object({ login: z.string(), __typename: z.string() }).nullable(), body: z.string() })) }),
+            }),
+          ),
+        }),
+      }),
+    }),
+  }),
+});
+
+const Commits = z.array(z.object({ sha: z.string(), commit: z.object({ message: z.string(), committer: z.object({ date: z.string() }).nullable() }) }));
+
+const Statuses = z.object({ statuses: z.array(z.object({ context: z.string(), state: z.string(), description: z.string().nullable(), updated_at: z.string() })) });
+
+const Comments = z.array(z.object({ body: z.string() }));
+
+/** Read shepherd's record on the PRs updated since `since` (YYYY-MM-DD). */
+export function collect(repo: string, since: string): PrRecord[] {
+  const [owner, name] = repo.split("/");
+  const prs = PrList.parse(JSON.parse(gh(["pr", "list", "-R", repo, "--state", "all", "--search", `updated:>=${since}`, "--limit", "100", "--json", "number,title,state,headRefOid,author"])));
+  const canPush = new Map<string, boolean>();
+
+  const trusted = (login: string) => {
+    if (!canPush.has(login)) {
+      let permission = "none";
+
+      try {
+        permission = Permission.parse(JSON.parse(gh(["api", `repos/${repo}/collaborators/${login}/permission`]))).permission;
+      } catch {
+        // Not a collaborator, or the token cannot say: treat as untrusted.
+      }
+
+      canPush.set(login, ["admin", "maintain", "write"].includes(permission));
+    }
+
+    return canPush.get(login) === true;
+  };
+
+  return prs.map((pr) => {
+    const query = "query($owner:String!,$name:String!,$n:Int!){repository(owner:$owner,name:$name){pullRequest(number:$n){reviewThreads(first:100){nodes{isResolved path comments(first:50){nodes{author{login __typename} body}}}}}}}";
+
+    const threads = Threads.parse(JSON.parse(gh(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `n=${pr.number}`])))
+      .data.repository.pullRequest.reviewThreads.nodes.flatMap((t) => parseThread(t.path, t.isResolved, t.comments.nodes.map((c) => ({ author: c.author?.login ?? "ghost", bot: c.author?.__typename === "Bot", body: c.body }))) ?? []);
+
+    const commits = Commits.parse(JSON.parse(gh(["api", "--paginate", "--slurp", `repos/${repo}/pulls/${pr.number}/commits`])).flat()).map((c) => parseCommit(c.sha, c.commit.message, c.commit.committer?.date ?? ""));
+
+    const status = Statuses.parse(JSON.parse(gh(["api", `repos/${repo}/commits/${pr.headRefOid}/status`]))).statuses.find((s) => s.context === "shepherd");
+    const summary = Comments.parse(JSON.parse(gh(["api", "--paginate", "--slurp", `repos/${repo}/issues/${pr.number}/comments`])).flat()).find((c) => c.body.includes("<!-- shepherd-swarm-summary -->"));
+
+    return { number: pr.number, title: pr.title, state: pr.state, threads, commits, status: status ? { state: status.state, description: status.description ?? "", updatedAt: status.updated_at } : null, rounds: roundsOf(summary?.body), trusted: trusted(pr.author.login) };
+  });
+}

package/src/install.ts

@@ -0,0 +1,86 @@
+// Copies (or links) the bundled skills and commands into an agent's skills directory.
+// A destination this installer did not create is never replaced without --force: it
+// may be the user's own skill that happens to share a name.
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export const MARKER = ".shepherd-installed";
+
+// Command files are single files, so they carry the marker as a comment line instead.
+const COMMAND_MARKER = "<!-- shepherd-installed -->";
+
+export type Outcome = { name: string; dest: string; action: "installed" | "replaced" | "skipped" | "removed" };
+
+export const bundledSkills = (skillsRoot: string) =>
+  readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(path.join(skillsRoot, d.name, "SKILL.md")))
+    .map((d) => d.name)
+    .sort();
+
+/** True when `dest` came from this installer: a link into our bundle, or a copy carrying our marker. */
+function ours(dest: string, bundleRoot: string): boolean {
+  const stat = lstatSync(dest, { throwIfNoEntry: false });
+
+  if (!stat) return false;
+
+  if (stat.isSymbolicLink()) return path.resolve(path.dirname(dest), readlinkSync(dest)).startsWith(path.resolve(bundleRoot) + path.sep);
+
+  return stat.isDirectory() ? existsSync(path.join(dest, MARKER)) : readFileSync(dest, "utf8").includes(COMMAND_MARKER);
+}
+
+function place(src: string, dest: string, bundleRoot: string, link: boolean, force: boolean): Outcome["action"] {
+  const present = lstatSync(dest, { throwIfNoEntry: false }) !== undefined;
+
+  if (present && !ours(dest, bundleRoot) && !force) return "skipped";
+
+  if (present) rmSync(dest, { recursive: true, force: true });
+
+  mkdirSync(path.dirname(dest), { recursive: true });
+
+  if (link) symlinkSync(src, dest);
+  else {
+    cpSync(src, dest, { recursive: true });
+
+    if (lstatSync(dest).isDirectory()) writeFileSync(path.join(dest, MARKER), "installed by @jagreehal/shepherd; safe to delete with `shepherd uninstall`\n");
+  }
+
+  return present ? "replaced" : "installed";
+}
+
+/** Install every bundled skill into `skillsDest`, and every command into `commandsDest` when given. */
+export function install(bundleRoot: string, skillsDest: string, commandsDest: string | null, link: boolean, force: boolean): Outcome[] {
+  const skillsRoot = path.join(bundleRoot, "skills");
+
+  const outcomes = bundledSkills(skillsRoot).map((name) => {
+    const dest = path.join(skillsDest, name);
+
+    return { name, dest, action: place(path.join(skillsRoot, name), dest, bundleRoot, link, force) };
+  });
+
+  if (commandsDest === null) return outcomes;
+  const commandsRoot = path.join(bundleRoot, "commands");
+
+  for (const file of existsSync(commandsRoot) ? readdirSync(commandsRoot).filter((f) => f.endsWith(".md")) : []) {
+    const dest = path.join(commandsDest, file);
+    outcomes.push({ name: `/${path.basename(file, ".md")}`, dest, action: place(path.join(commandsRoot, file), dest, bundleRoot, link, force) });
+  }
+
+  return outcomes;
+}
+
+/** Remove what this installer placed; anything else with a bundled name stays. */
+export function uninstall(bundleRoot: string, skillsDest: string, commandsDest: string | null): Outcome[] {
+  const targets = bundledSkills(path.join(bundleRoot, "skills")).map((name) => ({ name, dest: path.join(skillsDest, name) }));
+  const commandsRoot = path.join(bundleRoot, "commands");
+
+  if (commandsDest !== null && existsSync(commandsRoot)) {
+    for (const file of readdirSync(commandsRoot).filter((f) => f.endsWith(".md"))) targets.push({ name: `/${path.basename(file, ".md")}`, dest: path.join(commandsDest, file) });
+  }
+
+  return targets.map(({ name, dest }) => {
+    if (!ours(dest, bundleRoot)) return { name, dest, action: "skipped" as const };
+    rmSync(dest, { recursive: true, force: true });
+
+    return { name, dest, action: "removed" as const };
+  });
+}

package/src/lens.ts

@@ -0,0 +1,178 @@
+// Custom lenses: any skill, wrapped by swarm as a review-only reviewer whose `## Fix` section steers
+// triage. This file reads and writes the lens files and finds skills on disk; swarm itself reads the
+// repository's file from the default branch at review time (skills/swarm/references/custom-lenses.md).
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { z } from "zod";
+import { type Config, ConfigSchema, type Lens, LensSchema, lensCache, ModelId, TEAM_FILES } from "./config.ts";
+
+export const BUILT_IN_LENSES = ["correctness", "security", "simplicity", "maintainability", "slop", "spec"];
+
+const LENS_NAME = /^[a-z][a-z0-9-]*$/;
+
+// The lens file is the team policy file: lens commands write lenses, ladder and pins and keep every other key.
+const LensFileSchema = ConfigSchema;
+
+type LensFile = Config;
+
+export type { Lens };
+
+export const globalLensFile = (home: string) => path.join(home, ".config", "shepherd", "lenses.yml");
+
+/** The repository's policy file: `.shepherd/config.yml`, or the older `.shepherd/lenses.yml` when only that exists. */
+export const repoLensFile = (repoRoot: string) => {
+  const [config, legacy] = TEAM_FILES.map((f) => path.join(repoRoot, f));
+
+  return existsSync(config!) || !existsSync(legacy!) ? config! : legacy!;
+};
+
+const readFile = (file: string): LensFile => (existsSync(file) ? LensFileSchema.parse(parse(readFileSync(file, "utf8")) ?? {}) : { lenses: {} });
+
+export const readLenses = (file: string): Record<string, Lens> => readFile(file).lenses;
+
+/**
+ * OpenCode agents for a harness whose subagent tool takes no model (OpenCode 1.x): one per rung,
+ * `shepherd-r<i>`, and one per pin, `shepherd-pin-<name>`, each fixed to its model. Merge the result into
+ * OPENCODE_CONFIG_CONTENT; swarm and the loop then dispatch by agent name.
+ */
+export function opencodeAgents(choice: { ladder: string[] | null; models: Record<string, string> }) {
+  const agent = (model: string, about: string) => ({ mode: "subagent", model, description: `shepherd runner on ${model} (${about})` });
+
+  return {
+    agent: Object.fromEntries([
+      ...(choice.ladder ?? []).map((model, i) => [`shepherd-r${i}`, agent(model, `rung ${i}`)] as const),
+      ...Object.entries(choice.models).map(([name, model]) => [`shepherd-pin-${name}`, agent(model, `pinned for ${name}`)] as const),
+    ]),
+  };
+}
+
+/** Pin `name` (a lens or runner) to `model`, keeping everything else in the file. */
+export function pinModel(file: string, name: string, model: string): void {
+  if (!LENS_NAME.test(name)) throw new Error(`"${name}" must be lowercase letters, digits, and dashes`);
+  const current = readFile(file);
+
+  write(file, { ...current, models: { ...current.models, [name]: ModelId.parse(model) } });
+}
+
+/** Replace the ladder, cheapest model first. */
+export function setLadder(file: string, ladder: string[]): void {
+  write(file, { ...readFile(file), ladder: z.array(ModelId).min(1).parse(ladder) });
+}
+
+function write(file: string, contents: LensFile): void {
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, stringify(contents));
+}
+
+/** Add or replace one lens, keeping every other entry in the file. */
+export function addLens(file: string, name: string, lens: Lens): void {
+  if (!LENS_NAME.test(name)) throw new Error(`lens name "${name}" must be lowercase letters, digits, and dashes`);
+
+  if (BUILT_IN_LENSES.includes(name)) throw new Error(`"${name}" is a built-in lens; pick another name`);
+  const current = readFile(file);
+
+  write(file, { ...current, lenses: { ...current.lenses, [name]: LensSchema.parse(lens) } });
+}
+
+const lensTemplate = (name: string, description: string) => `---
+${stringify({ name, description })}---
+
+# ${name}
+
+## Review
+
+What to flag, most important first. Give each rule an id so findings read
+\`[${name}/<id>]\`.
+
+- **<id>**: <the rule>. Flag: <what breaking it looks like>. Why: <the cost>.
+
+## Fix
+
+How triage should fix a \`[${name}/...]\` finding. Optional; without it triage
+fixes by its own rules. Nothing here can loosen shepherd's rules.
+
+- Prefer: <the pattern or existing helper to reach for>.
+- Never touch: <files or APIs a fix must leave alone>.
+- Escalate: <changes that go to the author instead of being fixed>.
+`;
+
+const RULE_ID = /^- \*\*([a-z0-9][a-z0-9-]*)\*\*/gm;
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/** What would stop swarm or triage using a lens, one line each; empty when it is ready. Section rules apply to lenses under .shepherd/lenses/. */
+export function lensProblems(lens: Lens, home: string, repoRoot: string): string[] {
+  const dir = resolveSkill(lens.skill, home, repoRoot);
+
+  if (!dir) return [lensCache(home, lens.skill) ? `"${lens.skill}" is not fetched yet: shepherd config explain fetches pinned pack lenses` : `no SKILL.md found for "${lens.skill}"`];
+  const file = path.join(dir, "SKILL.md");
+  const text = readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+  const front = FRONTMATTER.exec(text)?.[1];
+  const problems: string[] = [];
+
+  if (front === undefined || !skillDescription(dir)) problems.push(`${file}: frontmatter needs a description`);
+
+  if (!path.posix.normalize(lens.skill.replaceAll("\\", "/")).startsWith(".shepherd/lenses/")) return problems;
+  const review = /^## Review\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(text)?.[1];
+
+  if (review === undefined) return [...problems, `${file}: add a "## Review" section`];
+  const ids = [...review.matchAll(RULE_ID)].map((m) => m[1]);
+
+  if (ids.length === 0) problems.push(`${file}: "## Review" has no rules; write each as "- **<id>**: <rule>", the id lowercase with dashes`);
+
+  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`);
+
+  return problems;
+}
+
+/** Scaffold a lens skill at .shepherd/lenses/<name> and register it. Returns the skill directory. */
+/** Starter lenses shipped with shepherd, copied into a repository by `lens new --from`. */
+export const TEMPLATES_DIR = path.resolve(import.meta.dir, "..", "lenses");
+
+export const lensTemplates = (): string[] => readdirSync(TEMPLATES_DIR).filter((d) => existsSync(path.join(TEMPLATES_DIR, d, "SKILL.md"))).sort();
+
+/** A starter lens's SKILL.md, renamed to `name` so its findings read `[<name>/<id>]`. */
+function fromTemplate(template: string, name: string): string {
+  if (!lensTemplates().includes(template)) throw new Error(`no lens template "${template}"; available: ${lensTemplates().join(", ")}`);
+
+  return readFileSync(path.join(TEMPLATES_DIR, template, "SKILL.md"), "utf8").replace(/^name: .*$/m, `name: ${name}`).replace(/^# .*$/m, `# ${name}`);
+}
+
+export function newLens(repoRoot: string, name: string, lens: Omit<Lens, "skill">, template?: string): string {
+  const skill = path.posix.join(".shepherd", "lenses", name); // lenses.yml paths are posix on every OS
+  const dir = path.join(repoRoot, skill);
+
+  if (existsSync(dir)) throw new Error(`${skill} already exists`);
+  const text = template ? fromTemplate(template, name) : lensTemplate(name, lens.description ?? `Reviews code against the team's ${name} rules.`);
+
+  addLens(repoLensFile(repoRoot), name, { skill, ...lens });
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, "SKILL.md"), text);
+
+  return dir;
+}
+
+/** The directory holding the skill's SKILL.md: a path against the repository, or a name in the usual skills directories. */
+export function resolveSkill(ref: string, home: string, repoRoot: string): string | null {
+  const pinned = lensCache(home, ref);
+
+  if (pinned) return existsSync(path.join(pinned, "SKILL.md")) ? pinned : null;
+  const expanded = ref.startsWith("~/") ? path.join(home, ref.slice(2)) : ref;
+
+  const candidates = expanded.includes("/")
+    ? [path.resolve(repoRoot, expanded)]
+    : [".claude/skills", ".agents/skills", ".codex/skills"].map((d) => path.join(home, d, expanded)).concat([".claude/skills", ".agents/skills"].map((d) => path.join(repoRoot, d, expanded)));
+
+  return candidates.find((dir) => existsSync(path.join(dir, "SKILL.md"))) ?? null;
+}
+
+/** The `description` from a skill's frontmatter, folded to one line. */
+export function skillDescription(skillDir: string): string | null {
+  const front = FRONTMATTER.exec(readFileSync(path.join(skillDir, "SKILL.md"), "utf8"))?.[1];
+
+  if (front === undefined) return null;
+  const parsed = z.object({ description: z.string() }).passthrough().safeParse(parse(front));
+
+  return parsed.success ? parsed.data.description.replace(/\s+/g, " ").trim() : null;
+}