bellwether 0.0.1

package/src/commands/hook-add.ts

@@ -0,0 +1,139 @@
+// Standalone hook installer — bypasses incur.
+// Configures PostToolUse hooks in Claude Code and Codex globally.
+// Idempotent: checks if already configured, updates if needed.
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOOK_COMMAND = "npx -y bellwether@latest hook-check";
+const HOOK_TIMEOUT = 15;
+const BELLWETHER_MARKER = "bellwether@latest hook-check";
+
+// ---------------------------------------------------------------------------
+// Claude Code: ~/.claude/settings.json
+// ---------------------------------------------------------------------------
+
+interface ClaudeHookEntry {
+  type: string;
+  command: string;
+  if?: string;
+  timeout?: number;
+}
+
+interface ClaudeMatcherGroup {
+  matcher: string;
+  hooks: ClaudeHookEntry[];
+}
+
+function buildClaudeHooks(): ClaudeMatcherGroup {
+  return {
+    matcher: "Bash",
+    hooks: [
+      { type: "command", if: "Bash(git push*)", command: HOOK_COMMAND, timeout: HOOK_TIMEOUT },
+      { type: "command", if: "Bash(gh pr create*)", command: HOOK_COMMAND, timeout: HOOK_TIMEOUT },
+      { type: "command", if: "Bash(gh pr ready*)", command: HOOK_COMMAND, timeout: HOOK_TIMEOUT },
+    ],
+  };
+}
+
+async function configureClaude(): Promise<string> {
+  const settingsPath = join(homedir(), ".claude", "settings.json");
+  let settings: Record<string, unknown> = {};
+
+  if (existsSync(settingsPath)) {
+    settings = JSON.parse(await readFile(settingsPath, "utf-8")) as Record<string, unknown>;
+  } else {
+    await mkdir(join(homedir(), ".claude"), { recursive: true });
+  }
+
+  const hooks = (settings.hooks ?? {}) as Record<string, unknown[]>;
+  const postToolUse = (hooks.PostToolUse ?? []) as ClaudeMatcherGroup[];
+
+  // Remove any existing bellwether hooks
+  const cleaned: ClaudeMatcherGroup[] = [];
+  for (const group of postToolUse) {
+    const filtered = group.hooks.filter((h) => !h.command.includes(BELLWETHER_MARKER));
+    if (filtered.length > 0) {
+      cleaned.push({ ...group, hooks: filtered });
+    }
+  }
+
+  // Add fresh bellwether hooks
+  cleaned.push(buildClaudeHooks());
+
+  hooks.PostToolUse = cleaned;
+  settings.hooks = hooks;
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return settingsPath;
+}
+
+// ---------------------------------------------------------------------------
+// Codex: ~/.codex/hooks.json
+// ---------------------------------------------------------------------------
+
+async function configureCodex(): Promise<string | null> {
+  const codexDir = join(homedir(), ".codex");
+  if (!existsSync(codexDir)) {
+    return null; // Codex not installed
+  }
+
+  const hooksPath = join(codexDir, "hooks.json");
+  let config: Record<string, unknown> = {};
+
+  if (existsSync(hooksPath)) {
+    config = JSON.parse(await readFile(hooksPath, "utf-8")) as Record<string, unknown>;
+  }
+
+  interface CodexMatcherGroup {
+    matcher: string;
+    hooks: { command: string; type: string; timeout?: number }[];
+  }
+
+  const hooks = (config.hooks ?? {}) as Record<string, unknown[]>;
+  const postToolUse = (hooks.PostToolUse ?? []) as CodexMatcherGroup[];
+
+  // Remove any existing bellwether hooks
+  const cleaned: CodexMatcherGroup[] = [];
+  for (const group of postToolUse) {
+    const filtered = group.hooks.filter((h) => !h.command.includes(BELLWETHER_MARKER));
+    if (filtered.length > 0) {
+      cleaned.push({ ...group, hooks: filtered });
+    }
+  }
+
+  // Add fresh codex hooks (no `if` — codex doesn't support it)
+  cleaned.push({
+    matcher: "^Bash$",
+    hooks: [{ type: "command", command: HOOK_COMMAND, timeout: HOOK_TIMEOUT }],
+  });
+
+  hooks.PostToolUse = cleaned;
+  config.hooks = hooks;
+
+  await writeFile(hooksPath, JSON.stringify(config, null, 2) + "\n");
+  return hooksPath;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+export async function run(): Promise<void> {
+  console.log("Configuring bellwether hooks...\n");
+
+  const claudePath = await configureClaude();
+  console.log(`  Claude Code: ${claudePath}`);
+
+  const codexPath = await configureCodex();
+  if (codexPath) {
+    console.log(`  Codex:       ${codexPath}`);
+  } else {
+    console.log("  Codex:       skipped (not installed)");
+  }
+
+  console.log("\nHooks will trigger when git push or gh pr create/ready is detected.");
+  console.log("The LLM will be prompted to run bellwether to monitor the PR.");
+}

package/src/commands/hook-check.ts

@@ -0,0 +1,35 @@
+// Standalone hook handler — bypasses incur for speed.
+// Reads Claude/Codex PostToolUse JSON from stdin.
+// If the command is a PR-related action, outputs additionalContext
+// telling the LLM to start monitoring with bellwether.
+
+const PR_PATTERN = /\bgit\s+push\b|\bgh\s+pr\s+(create|ready)\b/;
+
+export async function run(): Promise<void> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+
+  let command = "";
+  try {
+    const input = JSON.parse(Buffer.concat(chunks).toString()) as {
+      tool_input?: { command?: string };
+      hook_event_name?: string;
+    };
+    command = input.tool_input?.command ?? "";
+
+    if (PR_PATTERN.test(command)) {
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: input.hook_event_name ?? "PostToolUse",
+          additionalContext:
+            "PR pushed. Run `npx -y bellwether@latest check --watch` to monitor CI and reviews until merge-ready.",
+        },
+      };
+      process.stdout.write(JSON.stringify(output));
+    }
+  } catch {
+    // Malformed input — exit silently
+  }
+}

package/src/commands/reviews.ts

@@ -0,0 +1,225 @@
+import { z } from "zod";
+import { type Context } from "../context.js";
+import {
+  fetchPRComments,
+  processComments,
+  filterComments,
+  replyToComment,
+  resolveThread,
+  type ProcessedComment,
+  type ProxyFetch,
+} from "../github/index.js";
+
+export const replySchema = z.object({
+  id: z.number().describe("Reply ID"),
+  user: z.string().describe("Author login"),
+  body: z.string().describe("Reply body (cleaned)"),
+  createdAt: z.string().describe("ISO timestamp"),
+  isBot: z.boolean().describe("Whether author is a bot"),
+});
+
+export const commentSchema = z.object({
+  id: z.number().describe("Comment ID (use with --detail or --reply)"),
+  type: z
+    .enum(["review_comment", "issue_comment", "review"])
+    .describe("CODE = inline, COMMENT = PR-level, REVIEW = review summary"),
+  user: z.string().describe("Author login"),
+  isBot: z.boolean().describe("Whether author is a bot"),
+  path: z.string().nullable().describe("File path (inline comments only)"),
+  line: z.number().nullable().describe("Line number (inline comments only)"),
+  diffHunk: z.string().nullable().describe("Surrounding diff context"),
+  body: z.string().describe("Comment body (cleaned of bot boilerplate)"),
+  createdAt: z.string().describe("ISO timestamp"),
+  updatedAt: z.string().describe("ISO timestamp of last update"),
+  url: z.string().describe("GitHub URL"),
+  replies: z.array(replySchema).describe("Thread replies"),
+  hasHumanReply: z.boolean().describe("Whether a human has replied"),
+  hasAnyReply: z.boolean().describe("Whether any reply exists"),
+  isResolved: z.boolean().describe("Whether the thread is resolved"),
+});
+
+// ---------------------------------------------------------------------------
+// Pure logic functions
+// ---------------------------------------------------------------------------
+
+export async function getReviewsList(
+  ctx: Context,
+  prNumber: number,
+  filterOpts: {
+    unresolved: boolean;
+    unanswered: boolean;
+    botsOnly: boolean;
+    humansOnly: boolean;
+  },
+): Promise<{ comments: ProcessedComment[]; total: number }> {
+  const { token, repoInfo, proxyFetch } = ctx;
+
+  const rawData = await fetchPRComments(repoInfo.owner, repoInfo.repo, prNumber, token, proxyFetch);
+  const processed = processComments(rawData);
+  const filtered = filterComments(processed, {
+    botsOnly: filterOpts.botsOnly,
+    humansOnly: filterOpts.humansOnly,
+    filter: filterOpts.unresolved ? "unresolved" : filterOpts.unanswered ? "unanswered" : null,
+  });
+
+  return { comments: filtered, total: filtered.length };
+}
+
+export async function getReviewDetail(
+  ctx: Context,
+  prNumber: number,
+  commentId: number,
+): Promise<ProcessedComment | undefined> {
+  const { token, repoInfo, proxyFetch } = ctx;
+
+  const rawData = await fetchPRComments(repoInfo.owner, repoInfo.repo, prNumber, token, proxyFetch);
+  const processed = processComments(rawData);
+  return processed.find((cm) => cm.id === commentId);
+}
+
+export async function postReply(
+  ctx: Context,
+  prNumber: number,
+  replyStr: string,
+  shouldResolve: boolean,
+): Promise<{
+  replied: boolean;
+  commentId: number;
+  message: string;
+  url: string;
+  resolved?: boolean;
+  resolveError?: string;
+}> {
+  const { token, repoInfo, proxyFetch } = ctx;
+
+  const colonIdx = replyStr.indexOf(":");
+  if (colonIdx === -1) {
+    throw new Error("--reply format is <id>:<message>");
+  }
+  const commentId = Number(replyStr.slice(0, colonIdx));
+  const message = replyStr.slice(colonIdx + 1);
+
+  const result = await replyToComment(
+    repoInfo.owner,
+    repoInfo.repo,
+    prNumber,
+    commentId,
+    message,
+    token,
+    proxyFetch,
+  );
+
+  let resolved: boolean | undefined;
+  let resolveError: string | undefined;
+  if (shouldResolve) {
+    try {
+      const res = await resolveThread(
+        repoInfo.owner,
+        repoInfo.repo,
+        prNumber,
+        commentId,
+        token,
+        proxyFetch,
+      );
+      resolved = "resolved" in res && res.resolved;
+    } catch (error: unknown) {
+      resolved = false;
+      resolveError = error instanceof Error ? error.message : "Failed to resolve thread";
+    }
+  }
+
+  return { replied: true, commentId, message, url: result.html_url, resolved, resolveError };
+}
+
+// ---------------------------------------------------------------------------
+// Format helper
+// ---------------------------------------------------------------------------
+
+export function formatReviewsSection(
+  comments: ProcessedComment[],
+): Record<string, string | number> {
+  const unresolvedCount = comments.filter((c) => !(c.isResolved || c.hasHumanReply)).length;
+  const unansweredCount = comments.filter((c) => !c.hasAnyReply).length;
+
+  const result: Record<string, string | number> = {
+    total: `${unresolvedCount} unresolved, ${unansweredCount} unanswered`,
+  };
+
+  for (const comment of comments) {
+    const location = comment.path
+      ? `${comment.path}${comment.line ? `:${comment.line}` : ""}`
+      : null;
+    const key = location ? `REVIEW ${comment.id} ${location}` : `REVIEW ${comment.id}`;
+
+    const body = comment.body;
+
+    result[key] = body;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Watch helper
+// ---------------------------------------------------------------------------
+
+export async function watchForComments(
+  context: {
+    owner: string;
+    repo: string;
+    prNumber: number;
+    token: string;
+    proxyFetch: ProxyFetch;
+  },
+  options: {
+    botsOnly?: boolean;
+    humansOnly?: boolean;
+    filter?: "unresolved" | "unanswered" | null;
+    watchInterval: number;
+    watchTimeout: number;
+  },
+) {
+  const { owner, repo, prNumber, token, proxyFetch } = context;
+  const seenIds = new Set<number>();
+  const startTime = Date.now();
+
+  const initialData = await fetchPRComments(owner, repo, prNumber, token, proxyFetch);
+  const initialProcessed = processComments(initialData);
+  const initialFiltered = filterComments(initialProcessed, options);
+  for (const comment of initialFiltered) {
+    seenIds.add(comment.id);
+  }
+
+  while (true) {
+    await new Promise<void>((r) => setTimeout(r, options.watchInterval * 1000));
+
+    const rawData = await fetchPRComments(owner, repo, prNumber, token, proxyFetch);
+    const processed = processComments(rawData);
+    const filtered = filterComments(processed, options);
+    const newComments = filtered.filter((cm) => !seenIds.has(cm.id));
+
+    if (newComments.length > 0) {
+      for (const cm of newComments) {
+        seenIds.add(cm.id);
+      }
+
+      // Grace period for bot batches
+      await new Promise<void>((r) => setTimeout(r, 5_000));
+      const graceData = await fetchPRComments(owner, repo, prNumber, token, proxyFetch);
+      const graceProcessed = processComments(graceData);
+      const graceFiltered = filterComments(graceProcessed, options);
+      for (const cm of graceFiltered) {
+        if (!seenIds.has(cm.id)) {
+          seenIds.add(cm.id);
+          newComments.push(cm);
+        }
+      }
+
+      return { newComments, total: newComments.length, timedOut: false };
+    }
+
+    if (Math.round((Date.now() - startTime) / 1000) >= options.watchTimeout) {
+      return { newComments: [], total: 0, timedOut: true };
+    }
+  }
+}

package/src/context.ts

@@ -0,0 +1,86 @@
+import * as clack from "@clack/prompts";
+import {
+  getGitHubToken,
+  getProxyFetch,
+  getRepoInfo,
+  getCurrentBranch,
+  findPRForBranch,
+  listOpenPRs,
+  type RepoInfo,
+  type ProxyFetch,
+} from "./github/index.js";
+
+export interface Context {
+  token: string;
+  repoInfo: RepoInfo;
+  proxyFetch: ProxyFetch;
+}
+
+export async function bootstrap(): Promise<Context> {
+  const token = await getGitHubToken();
+  if (!token) {
+    throw new Error(
+      [
+        "GitHub token not found.",
+        "Fix: set GITHUB_TOKEN or GH_TOKEN env var, add to .env.local, or run `gh auth login`.",
+      ].join(" "),
+    );
+  }
+
+  const repoInfo = getRepoInfo();
+  if (!repoInfo) {
+    throw new Error(
+      [
+        "Could not determine repository.",
+        "Fix: run from a git repo with a github.com remote, or set GH_REPO=owner/repo.",
+      ].join(" "),
+    );
+  }
+
+  return { token, repoInfo, proxyFetch: getProxyFetch() };
+}
+
+export async function resolvePR(
+  ctx: Context,
+  prArg?: number,
+): Promise<{ prNumber: number; prUrl: string; headSha?: string }> {
+  const { repoInfo, token, proxyFetch } = ctx;
+
+  if (prArg) {
+    return {
+      prNumber: prArg,
+      prUrl: `https://github.com/${repoInfo.owner}/${repoInfo.repo}/pull/${prArg}`,
+    };
+  }
+
+  const branch = getCurrentBranch();
+  if (branch && branch !== "main" && branch !== "master") {
+    const pr = await findPRForBranch(repoInfo.owner, repoInfo.repo, branch, token, proxyFetch);
+    if (pr) {
+      return { prNumber: pr.number, prUrl: pr.html_url, headSha: pr.head.sha };
+    }
+  }
+
+  const prs = await listOpenPRs(repoInfo.owner, repoInfo.repo, token, proxyFetch);
+  if (prs.length === 0) {
+    throw new Error(
+      "No open PRs found. Fix: pass a PR number as argument, e.g. `bellwether check 123`.",
+    );
+  }
+
+  const selected = await clack.select({
+    message: "Select a PR",
+    options: prs.map((pr) => ({
+      value: pr.number,
+      label: `#${pr.number} ${pr.title}`,
+      hint: pr.head.ref,
+    })),
+  });
+
+  if (clack.isCancel(selected)) {
+    process.exit(0);
+  }
+
+  const pr = prs.find((p) => p.number === selected)!;
+  return { prNumber: pr.number, prUrl: pr.html_url, headSha: pr.head.sha };
+}

package/src/github/auth.ts

@@ -0,0 +1,40 @@
+import { join } from "node:path";
+import { readFile, access } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { getRepoRoot } from "./repo.js";
+
+function spawnText(cmd: string[]): string | null {
+  const [command, ...args] = cmd;
+  if (!command) {return null;}
+  const result = spawnSync(command, args, { encoding: "utf-8" });
+  if (result.status !== 0) {return null;}
+  return result.stdout.trim();
+}
+
+/**
+ * Resolve a GitHub token from (in priority order):
+ * 1. GITHUB_TOKEN env var
+ * 2. GH_TOKEN env var
+ * 3. .env.local file in the repo root
+ * 4. `gh auth token` CLI
+ */
+export async function getGitHubToken(): Promise<string | null> {
+  if (process.env.GITHUB_TOKEN) {return process.env.GITHUB_TOKEN;}
+  if (process.env.GH_TOKEN) {return process.env.GH_TOKEN;}
+
+  const root = getRepoRoot();
+  if (root) {
+    const envPath = join(root, ".env.local");
+    try {
+      await access(envPath);
+      const content = await readFile(envPath, "utf-8");
+      const match = content.match(/^GITHUB_TOKEN=["']?([^"'\n]+)["']?/m);
+      if (match?.[1]) {return match[1];}
+    } catch {}
+  }
+
+  const token = spawnText(["gh", "auth", "token"]);
+  if (token) {return token;}
+
+  return null;
+}