bellwether 0.0.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "bellwether",
+  "version": "0.0.1",
+  "description": "Drive PRs to merge-ready: watch CI, fix failures, resolve review comments. Self-contained watch loop that keeps going until pr.ready=true.",
+  "author": {
+    "name": "Roderik van der Veer",
+    "url": "https://github.com/roderik"
+  },
+  "repository": "https://github.com/roderik/bellwether",
+  "license": "MIT",
+  "keywords": ["ci", "pr", "review", "merge", "github", "watch"],
+  "skills": "./skills/"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roderik van der Veer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# bellwether
+
+Drive GitHub PRs to merge-ready: watch CI, fix failures, resolve review comments. Self-contained watch loop that keeps going until `pr.ready=true`.
+
+Built with [incur](https://github.com/wevm/incur). Inspired by [RTK](https://github.com/rtk-ai/rtk) (token-efficient CLI output filtering) and [agent-reviews](https://github.com/pbakaus/agent-reviews) (automated PR review resolution).
+
+## Install
+
+```bash
+npx -y bellwether@latest skills add 
+```
+
+## Usage
+
+```bash
+# CI status + review comments + merge state
+npx -y bellwether@latest check
+
+# Watch until CI completes
+npx -y bellwether@latest check --watch
+
+# Show only unresolved reviews
+npx -y bellwether@latest check --unresolved
+
+# Reply to a review comment and resolve
+npx -y bellwether@latest check --reply "456:Fixed in abc1234" --resolve
+
+# Full detail for a specific comment
+npx -y bellwether@latest check --detail 456
+
+# Full help
+npx -y bellwether@latest check --help
+```
+
+## Output
+
+```
+pr:
+  state: open
+  mergeable: clean
+  ready: true
+ci:
+  sha: abc1234
+  checks: "3 total, 3 passing, 0 failing, 0 pending"
+  passed: "build, lint, test"
+reviews:
+  total: "0 unresolved, 0 unanswered"
+```
+
+When CI fails, the output includes the actual error log (filtered, not raw GitHub metadata):
+
+```
+ci:
+  FAIL check: "TypeError: Cannot find name 'fetch'..."
+```
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) (package manager and dev runtime)
+- Node.js >= 22 (the published package runs on Node)
+
+### Setup
+
+```bash
+bun install
+```
+
+### Commands
+
+```bash
+bun run dev              # zile dev — symlinks dist/ to src/
+bun src/bin.ts check     # run directly from source
+bun run build            # compile to dist/
+bun check                # oxlint with type-aware rules
+bun run test             # vitest
+bun run test:coverage    # vitest with v8 coverage
+bun run format           # oxfmt
+```
+
+### Publishing
+
+Automated via GitHub Actions on tag push:
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+The workflow sets the version in `package.json` and `.claude-plugin/plugin.json`, builds, publishes to npm with provenance, and commits the version bump back to main.
+
+## Project structure
+
+```
+src/
+  bin.ts              # CLI entry point
+  cli.ts              # incur CLI definition
+  context.ts          # Bootstrap + PR resolution
+  commands/
+    check.ts          # unified check command (CI + reviews + merge state)
+    ci.ts             # CI data helpers (flatten, getCISection)
+    reviews.ts        # Review data helpers (list, detail, reply, watch)
+  github/
+    auth.ts           # GitHub token resolution
+    fetch.ts          # Proxy-aware fetch + pagination
+    repo.ts           # Git/repo helpers + merge state
+    checks.ts         # Check Runs API + job log filtering
+    comments.ts       # PR comments + review threads + GraphQL resolve
+    index.ts          # Re-exports
+skills/
+  bellwether/
+    SKILL.md          # Agent skill (shared across all install channels)
+.claude-plugin/
+  plugin.json         # Claude Code plugin manifest
+```
+
+## License
+
+[MIT](LICENSE)

package/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: bellwether
+description: >-
+  Bring the current PR to a mergeable state: CI green, all review comments resolved,
+  no merge conflicts. Self-contained — watches CI, fixes issues, watches again until
+  merge-ready. Use when the user wants to keep a PR green, auto-fix CI, resolve
+  review comments, or says "get this merged".
+user-invocable: true
+---
+
+# Bellwether — Drive PR to Merge-Ready
+
+Self-contained cycle: watch CI → fix failures → address reviews → watch again → until merge-ready.
+
+## The Loop
+
+```
+1. npx -y bellwether@latest check --watch        (blocks until CI completes)
+2. If pr.ready=true → done, report "merge-ready"
+3. If pr.state=merged|closed → done, report status
+4. If CI failures → fix them (Step 2), push, go to 1
+5. If unresolved reviews → address them (Step 3), push, go to 1
+6. If pr.mergeable=dirty|behind → /sync, push, go to 1
+7. If timed out → go to 1 (restart watch)
+```
+
+## What `npx -y bellwether@latest check --watch` returns
+
+Three sections:
+
+- **pr** — `state` (open/closed/merged), `mergeable` (clean/dirty/behind/blocked/unstable), `ready` (true when all conditions met)
+- **ci** — SHA, check summary, and for each failing check: the filtered error log with file paths and line numbers
+- **reviews** — unresolved review comments with full body, file path, and line number
+
+## Step 2: Fix CI failures
+
+For each `FAIL` key in the CI section:
+
+1. **Read the error log** — it contains actual compiler/test output with file paths and line numbers.
+2. **Fix the code** — minimal change that resolves the root cause.
+3. **Verify locally** — run the same check that failed.
+4. **Stage, commit, push** — stage files by name (never `git add -A`).
+5. **Go to step 1** — restart the watch. New CI runs, new bot comments may arrive.
+
+## Step 3: Address review comments
+
+For each `REVIEW` key in the reviews section:
+
+### Classify
+
+**Bot comments** (CodeRabbit, Copilot, Cursor Bugbot):
+- **True positive** — real bug → fix the code
+- **False positive** — bot doesn't understand the pattern → won't fix
+- **Uncertain** — ask the user
+
+**Human comments**:
+- **Actionable** — fix the code
+- **Discussion** — ask the user
+- **Already addressed** — reply only
+
+### Fix and commit
+
+Fix all true positives and actionable items in a single commit. Verify locally, push.
+
+### Reply
+
+For inline code review comments (with file path), reply individually with `--resolve`:
+
+```bash
+npx -y bellwether@latest check --reply "<id>:Fixed in <hash>. <description>" --resolve
+```
+
+For top-level bot comments (no file path), post a single summary reply:
+
+```
+Addressed review findings in <hash>:
+- REVIEW 456: Fixed null check in src/foo.ts
+- REVIEW 789: Won't fix — pattern is intentional
+```
+
+Every comment gets a response. Use `--resolve` on every reply.
+
+After all replies, go to step 1 — restart the watch.
+
+## Principles
+
+- **One fix per watch cycle** — fix CI OR reviews, not both. Push and restart watch.
+- **Minimal changes** — don't refactor unrelated code.
+- **Every comment gets a response** — no silent ignores.
+- **Ask when uncertain** — don't guess on architectural questions.
+- **Verify before pushing** — always run the failing check locally first.
+- **Never stop until terminal** — if `pr.ready` is false, keep going.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+const cmd = process.argv[2];
+// Fast path for hook commands — bypass incur entirely for speed
+if (cmd === "hook-check") {
+    const { run } = await import("./commands/hook-check.js");
+    await run();
+}
+else if (cmd === "hook-add") {
+    const { run } = await import("./commands/hook-add.js");
+    await run();
+}
+else {
+    const { cli } = await import("./cli.js");
+    void cli.serve();
+}
+export {};
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE5B,gEAAgE;AAChE,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;IACzB,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACzD,MAAM,GAAG,EAAE,CAAC;AACd,CAAC;KAAM,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;IAC9B,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;IACvD,MAAM,GAAG,EAAE,CAAC;AACd,CAAC;KAAM,CAAC;IACN,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;IACzC,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+import { Cli, z } from "incur";
+import { type Context } from "./context.js";
+declare const cli: Cli.Cli<{}, z.ZodObject<{
+    ctx: z.ZodCustom<Context, Context>;
+}, z.core.$strip>, z.ZodObject<{
+    GITHUB_TOKEN: z.ZodOptional<z.ZodString>;
+    GH_TOKEN: z.ZodOptional<z.ZodString>;
+    GH_REPO: z.ZodOptional<z.ZodString>;
+    HTTPS_PROXY: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export { cli };
+export default cli;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvD,QAAA,MAAM,GAAG;;;;;;;kBAwBP,CAAC;AASH,OAAO,EAAE,GAAG,EAAE,CAAC;AACf,eAAe,GAAG,CAAC"}

package/dist/cli.js

@@ -0,0 +1,36 @@
+import { Cli, z } from "incur";
+import { bootstrap } from "./context.js";
+import { checkCommand } from "./commands/check.js";
+const cli = Cli.create("bellwether", {
+    version: "0.0.1",
+    description: "Monitor GitHub PRs — review comments and CI status",
+    vars: z.object({
+        ctx: z.custom(),
+    }),
+    env: z.object({
+        GITHUB_TOKEN: z
+            .string()
+            .optional()
+            .describe("GitHub personal access token (also reads GH_TOKEN, .env.local, gh CLI)"),
+        GH_TOKEN: z.string().optional().describe("Alternative GitHub token env var"),
+        GH_REPO: z.string().optional().describe("Override repository in owner/repo format"),
+        HTTPS_PROXY: z.string().optional().describe("HTTPS proxy URL for corporate/cloud environments"),
+    }),
+    sync: {
+        include: ["_root"],
+        suggestions: [
+            "check CI and reviews for this PR",
+            "check CI and reviews for PR 123",
+            "watch CI until complete",
+            "reply to review comment 12345",
+        ],
+    },
+});
+cli.use(async (c, next) => {
+    c.set("ctx", await bootstrap());
+    await next();
+});
+cli.command("check", checkCommand);
+export { cli };
+export default cli;
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAgB,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE;IACnC,OAAO,EAAE,OAAO;IAChB,WAAW,EAAE,oDAAoD;IACjE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,GAAG,EAAE,CAAC,CAAC,MAAM,EAAW;KACzB,CAAC;IACF,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC;QACZ,YAAY,EAAE,CAAC;aACZ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,wEAAwE,CAAC;QACrF,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;QAC5E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;QACnF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;KAChG,CAAC;IACF,IAAI,EAAE;QACJ,OAAO,EAAE,CAAC,OAAO,CAAC;QAClB,WAAW,EAAE;YACX,kCAAkC;YAClC,iCAAiC;YACjC,yBAAyB;YACzB,+BAA+B;SAChC;KACF;CACF,CAAC,CAAC;AAEH,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;IACxB,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,SAAS,EAAE,CAAC,CAAC;IAChC,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC,CAAC;AAEH,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,YAA4D,CAAC,CAAC;AAEnF,OAAO,EAAE,GAAG,EAAE,CAAC;AACf,eAAe,GAAG,CAAC"}

package/dist/commands/check.d.ts

@@ -0,0 +1,191 @@
+import { z } from "incur";
+import { type Context } from "../context.js";
+interface CheckCommandContext {
+    var: {
+        ctx: Context;
+    };
+    args: {
+        pr?: number;
+    };
+    options: {
+        watch: boolean;
+        interval: number;
+        timeout: number;
+        unresolved: boolean;
+        unanswered: boolean;
+        botsOnly: boolean;
+        humansOnly: boolean;
+        reply?: string;
+        resolve: boolean;
+        detail?: number;
+    };
+    ok: (data: Record<string, unknown>, meta?: Record<string, unknown>) => unknown;
+    error: (data: {
+        message: string;
+    }) => unknown;
+}
+export declare const checkCommand: {
+    description: string;
+    hint: string;
+    args: z.ZodObject<{
+        pr: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>;
+    options: z.ZodObject<{
+        watch: z.ZodDefault<z.ZodBoolean>;
+        interval: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        timeout: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        unresolved: z.ZodDefault<z.ZodBoolean>;
+        unanswered: z.ZodDefault<z.ZodBoolean>;
+        botsOnly: z.ZodDefault<z.ZodBoolean>;
+        humansOnly: z.ZodDefault<z.ZodBoolean>;
+        reply: z.ZodOptional<z.ZodString>;
+        resolve: z.ZodDefault<z.ZodBoolean>;
+        detail: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>;
+    alias: {
+        watch: string;
+        interval: string;
+        unresolved: string;
+        unanswered: string;
+        botsOnly: string;
+        humansOnly: string;
+        reply: string;
+        detail: string;
+    };
+    usage: ({
+        args?: undefined;
+        options?: undefined;
+    } | {
+        args: {
+            pr: boolean;
+        };
+        options?: undefined;
+    } | {
+        options: {
+            watch: boolean;
+            detail?: undefined;
+            reply?: undefined;
+            resolve?: undefined;
+        };
+        args?: undefined;
+    } | {
+        options: {
+            detail: boolean;
+            watch?: undefined;
+            reply?: undefined;
+            resolve?: undefined;
+        };
+        args?: undefined;
+    } | {
+        options: {
+            reply: boolean;
+            watch?: undefined;
+            detail?: undefined;
+            resolve?: undefined;
+        };
+        args?: undefined;
+    } | {
+        options: {
+            reply: boolean;
+            resolve: boolean;
+            watch?: undefined;
+            detail?: undefined;
+        };
+        args?: undefined;
+    })[];
+    output: z.ZodObject<{
+        pr: z.ZodOptional<z.ZodObject<{
+            state: z.ZodString;
+            mergeable: z.ZodString;
+            ready: z.ZodBoolean;
+        }, z.core.$strip>>;
+        ci: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        reviews: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        comment: z.ZodOptional<z.ZodObject<{
+            id: z.ZodNumber;
+            type: z.ZodEnum<{
+                review_comment: "review_comment";
+                issue_comment: "issue_comment";
+                review: "review";
+            }>;
+            user: z.ZodString;
+            isBot: z.ZodBoolean;
+            path: z.ZodNullable<z.ZodString>;
+            line: z.ZodNullable<z.ZodNumber>;
+            diffHunk: z.ZodNullable<z.ZodString>;
+            body: z.ZodString;
+            createdAt: z.ZodString;
+            updatedAt: z.ZodString;
+            url: z.ZodString;
+            replies: z.ZodArray<z.ZodObject<{
+                id: z.ZodNumber;
+                user: z.ZodString;
+                body: z.ZodString;
+                createdAt: z.ZodString;
+                isBot: z.ZodBoolean;
+            }, z.core.$strip>>;
+            hasHumanReply: z.ZodBoolean;
+            hasAnyReply: z.ZodBoolean;
+            isResolved: z.ZodBoolean;
+        }, z.core.$strip>>;
+        replied: z.ZodOptional<z.ZodBoolean>;
+        commentId: z.ZodOptional<z.ZodNumber>;
+        message: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        resolved: z.ZodOptional<z.ZodBoolean>;
+        allPassing: z.ZodOptional<z.ZodBoolean>;
+        timedOut: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    examples: ({
+        description: string;
+        options?: undefined;
+    } | {
+        options: {
+            watch: boolean;
+            unresolved?: undefined;
+            detail?: undefined;
+            reply?: undefined;
+            resolve?: undefined;
+        };
+        description: string;
+    } | {
+        options: {
+            unresolved: boolean;
+            watch?: undefined;
+            detail?: undefined;
+            reply?: undefined;
+            resolve?: undefined;
+        };
+        description: string;
+    } | {
+        options: {
+            detail: number;
+            watch?: undefined;
+            unresolved?: undefined;
+            reply?: undefined;
+            resolve?: undefined;
+        };
+        description: string;
+    } | {
+        options: {
+            reply: string;
+            watch?: undefined;
+            unresolved?: undefined;
+            detail?: undefined;
+            resolve?: undefined;
+        };
+        description: string;
+    } | {
+        options: {
+            reply: string;
+            resolve: boolean;
+            watch?: undefined;
+            unresolved?: undefined;
+            detail?: undefined;
+        };
+        description: string;
+    })[];
+    run(c: CheckCommandContext): Promise<unknown>;
+};
+export {};
+//# sourceMappingURL=check.d.ts.map

package/dist/commands/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AA4BxD,UAAU,mBAAmB;IAC3B,GAAG,EAAE;QAAE,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;IACtB,IAAI,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,OAAO,EAAE;QACP,KAAK,EAAE,OAAO,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,OAAO,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAC/E,KAAK,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;CAC/C;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAqEV,mBAAmB;CAqIjC,CAAC"}