@cldmv/gh-broker 0.8.0 → 0.9.0

package/README.md

@@ -19,19 +19,19 @@ It runs as a dedicated `gh-broker` system user, holds a read-scoped and a write-
 
 ## ✨ What's New
 
-### Latest: v0.8.0 (October 2026)
+### Latest: v0.9.0 (November 2026)
 
-- **`npm_scaffold`: new npm packages without a manual first publish.** The new write verb publishes a broker-built `0.0.0-stage` placeholder and registers the repo's publish workflow as its trusted publisher, so CI publishes the first real release through OIDC. The npm token has no 2FA bypass: each write takes a one-time password from the user, so it's two calls, and the verb refuses any package that already exists.
-- **`ghcr_push`: container image pushes without a registry token.** Push a `docker save` archive from a drop directory to an allowlisted `ghcr.io/<owner>/<image>` as a background job, follow it with `ghcr_push_status` and check it with `ghcr_tags`. Release tags are never overwritten, and the classic PAT stays with the broker.
-- **Optional credentials.** The npm and GHCR tokens can be skipped at install; their tools stay hidden until the token is stored. The installer also takes tokens via `--secret <cred-name>=<token>`.
-- [View full v0.8.0 Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.8.0.md)
+- **Three report verbs for the release and fleet skills.** `report_alert_status` buckets each open Dependabot alert by where its fix stands (released but still open, fixed on `next`, open PR, closed PR, nothing). `report_release_changes` returns the PRs a release actually ships, grouped by changelog section, with the net `package.json` and dependency deltas. `report_dependents` finds every repo that declares an npm package, including dev-trunk repos on `dev`, and skips a `dev` that has fallen behind the default branch.
+- **`ciVerbosity` on `list_pull_requests`.** The same opt-in CI detail as `pull_request_read`, across a whole PR list with one shared call budget.
+- **Install from npm.** `sudo npx @cldmv/gh-broker <agent-user>` runs the installer from the prebuilt package. The tarball now ships only runtime files.
+- [View full v0.9.0 Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.9.0.md)
 
 ### Recent Releases
 
+- **v0.8.0** (November 2026) — `npm_scaffold` creates an npm package and its trusted publisher, `ghcr_push` pushes images without an agent-held token, and optional credentials hide their tools ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.8.0.md))
 - **v0.7.0** (October 2026) — `issue_labels` adds, removes or swaps single labels without replacing the set, and `issue_write` warns that its `labels` does ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.7.0.md))
 - **v0.6.1** (October 2026) — MCP SDK 1.32.0 (same-origin redirects only) and a refreshed vitest toolchain; no broker source changes ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.6.1.md))
 - **v0.6.0** (October 2026) — Compact per-repo roll-up, filters and flow tier for `report_security_alerts`, and release-readiness analysis for `report_release_prs` ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.6.0.md))
-- **v0.5.1** (October 2026) — The installer keeps the existing secrets backend instead of prompting on every upgrade ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.5.1.md))
 
 📚 For the complete version history, see the [docs/changelog/](https://github.com/CLDMV/gh-broker/tree/master/docs/changelog/) folder.
 
@@ -51,7 +51,7 @@ A tool not listed in `config.tools` is neither advertised nor executable. Adding
 
 ### 📊 **CI Visibility Without Per-Call Log Fetches**
 
-`report_ci_status` answers "does this PR have failing checks" at whatever detail level you ask for — counts only by default, escalating to which job failed, which step failed, and a tail of the failing job's actual log — paying for that detail only on runs that are genuinely failing. The same status can ride inline on a normal `pull_request_read` via an opt-in `ciVerbosity` parameter.
+`report_ci_status` answers "does this PR have failing checks" at whatever detail level you ask for — counts only by default, escalating to which job failed, which step failed, and a tail of the failing job's actual log — paying for that detail only on runs that are genuinely failing. The same status can ride inline on a normal `pull_request_read` or `list_pull_requests` via an opt-in `ciVerbosity` parameter.
 
 ```json
 { "owner": "cldmv", "repo": "droidsock", "pull": 35, "verbosity": 2 }
@@ -91,12 +91,30 @@ npm only accepts a trusted publisher on a package that already exists, so every
 
 🛡️ **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#report_security_alerts)**
 
+### 🩹 **Where Each Alert's Fix Stands**
+
+`report_alert_status` puts every open Dependabot alert in one bucket — `released-still-open`, `fixed-on-next`, `open-pr`, `closed-unmerged` or `no-pr` — by reading the lockfile nearest the alert's manifest on the default branch, `next` and `hotfixes`, and the repo's PR history. An alert that reads open because its fix is waiting on `next` stops looking like work to do.
+
+🩹 **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#report_alert_status)**
+
 ### 🚢 **Release PR Discovery**
 
 `report_release_prs` finds every open release PR across an owner's repos and says which ones still lack their per-version changelog file — the list an agent needs during a mass update.
 
 🚢 **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#report_release_prs)**
 
+### 📝 **Changelog Source Material**
+
+`report_release_changes` returns the PRs one release actually ships — already-released and reverted PRs dropped — grouped by changelog section at the detail level you ask for, with the release's `package.json` and dependency deltas and an optional skeleton in the per-version template.
+
+📝 **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#report_release_changes)**
+
+### 📦 **Package Dependents**
+
+`report_dependents` finds every repo an owner has that declares an npm package, with the declared range, the lockfile-resolved version and the repo's flow tier — where a fleet-wide version bump starts. It reads `dev` branches too, so dev-trunk repos are included, and skips a `dev` whose version has fallen behind the default branch.
+
+📦 **Full parameter reference: [docs/TOOLS.md](docs/TOOLS.md#report_dependents)**
+
 ### 🐳 **Container Image Pushes Without a Registry Token**
 
 `ghcr_push` pushes a `docker save` archive to `ghcr.io/<owner>/<image>:<tag>` with a classic `write:packages` PAT the agent never sees. The image must be on an allowlist, the archive must sit in a dedicated drop directory (symlinks, hard links and paths outside it are refused), and an existing release tag is never overwritten. The push runs as a background job, uploads only the blobs the registry doesn't already have, and is tracked with `ghcr_push_status`; `ghcr_tags` checks the result.
@@ -132,7 +150,15 @@ The broker presents its **own** MCP contract to the agent — a proxied tool's s
 
 ### Install
 
-gh-broker is published on npm as [`@cldmv/gh-broker`](https://www.npmjs.com/package/@cldmv/gh-broker), but it is a system service, not a library or a global CLI. Install it from a checkout with the installer, which handles both the first install and every upgrade:
+gh-broker is a system service, not a library. The installer handles both the first install and every upgrade, and you can run it from npm or from a checkout.
+
+From npm ([`@cldmv/gh-broker`](https://www.npmjs.com/package/@cldmv/gh-broker)), with the prebuilt bundle:
+
+```sh
+sudo npx @cldmv/gh-broker <agent-user>
+```
+
+From a checkout:
 
 ```sh
 git clone https://github.com/CLDMV/gh-broker.git
@@ -140,7 +166,7 @@ cd gh-broker
 sudo node deploy/install.mjs <agent-user>
 ```
 
-The installer creates the service user and the socket group, builds as the checkout's owner, merges the shipped defaults with the deployed config, stores the PATs in the backend you pick, installs the unit and runs a smoke test. Prerequisites, PAT scopes, unattended installs and every flag: [deploy/README.md](deploy/README.md).
+Both take the same flags. The installer creates the service user and the socket group, builds as the checkout's owner when there's no bundle yet, merges the shipped defaults with the deployed config, stores the PATs in the backend you pick, installs the unit and runs a smoke test. Prerequisites, PAT scopes, unattended installs and every flag: [deploy/README.md](deploy/README.md).
 
 ---
 
@@ -179,6 +205,10 @@ src/
     report_unlabeled.ts  issues/PRs with no labels, one repo or org-wide
     report_security_alerts.ts  open Dependabot/CodeQL/secret alerts, one repo or org-wide
     report_release_prs.ts  open release PRs + whether each has its changelog file
+    report_dependents.ts  repos that declare an npm package, with range, resolved version and flow tier
+    report_alert_status.ts  where each open Dependabot alert's fix stands (lockfiles + PRs)
+    report_release_changes.ts  the PRs a release ships, grouped, with net package/dependency deltas
+    lockfile.ts          npm / pnpm / yarn lockfile readers shared by the report verbs
     report_ci_status.ts  tiered CI status for a PR or every open PR in a repo
     rest-client.ts       shared rate-limit-floor + call-budget REST helpers
     issue_labels.ts      add/remove/swap/set labels on an issue or PR (write PAT)
@@ -208,7 +238,7 @@ config.sample.json   a full config with placeholder values, for reference only
 
 ## 📚 Documentation
 
-- **[Tools Reference](docs/TOOLS.md)** — every custom and augmented tool: `report_unlabeled`, `report_security_alerts`, `report_release_prs`, `report_ci_status`, the `pull_request_read` `ciVerbosity` extension, `issue_labels`, `npm_scaffold`, `resolve_review_thread`/`reply_review_thread`, `ghcr_push`/`ghcr_push_status`/`ghcr_tags`, and how to add a new one
+- **[Tools Reference](docs/TOOLS.md)** — every custom and augmented tool: `report_unlabeled`, `report_security_alerts`, `report_alert_status`, `report_release_prs`, `report_release_changes`, `report_dependents`, `report_ci_status`, the `pull_request_read` and `list_pull_requests` `ciVerbosity` extensions, `issue_labels`, `npm_scaffold`, `resolve_review_thread`/`reply_review_thread`, `ghcr_push`/`ghcr_push_status`/`ghcr_tags`, and how to add a new one
 - **[Agent-as-Separate-User Model](docs/agent-user-model.md)** — the isolation model behind "use ≠ possession": users, groups, filesystem permissions, verified against a real host
 - **[Deploy Architecture](docs/deploy-architecture.md)** — config merge, secret store backends, node handling, the installer's full flow
 - **[Install Guide](deploy/README.md)** — prerequisites, PAT scopes, install/upgrade command, flags

package/config.example.json

@@ -28,7 +28,8 @@
 		},
 		{
 			"name": "list_pull_requests",
-			"mode": "read"
+			"mode": "read",
+			"augment": true
 		},
 		{
 			"name": "pull_request_read",
@@ -265,11 +266,26 @@
 			"mode": "read",
 			"custom": true
 		},
+		{
+			"name": "report_dependents",
+			"mode": "read",
+			"custom": true
+		},
 		{
 			"name": "report_release_prs",
 			"mode": "read",
 			"custom": true
 		},
+		{
+			"name": "report_release_changes",
+			"mode": "read",
+			"custom": true
+		},
+		{
+			"name": "report_alert_status",
+			"mode": "read",
+			"custom": true
+		},
 		{
 			"name": "report_ci_status",
 			"mode": "read",

package/deploy/README.md

@@ -27,10 +27,11 @@ The installer also creates the drop directory from `ghcr.dropDir` (default `/srv
 ## 2. Install (first install AND upgrade — same command)
 
 ```sh
-sudo node deploy/install.mjs [agent-user]
+sudo npx @cldmv/gh-broker [agent-user]      # from npm
+sudo node deploy/install.mjs [agent-user]   # from a checkout
 ```
 
-`agent-user` defaults to `$SUDO_USER` (the account you ran `sudo` from). The installer walks the whole thing and is idempotent:
+Both run the same installer and take the same flags; the npm package ships a prebuilt `dist/`, so step 5 has nothing to build. `agent-user` defaults to `$SUDO_USER` (the account you ran `sudo` from). The installer walks the whole thing and is idempotent:
 
 1. checks prerequisites,
 2. **creates or confirms the agent user** (stops if it can't — no silent half-install),

package/deploy/install.mjs

@@ -17,7 +17,8 @@
 /**
  * gh-broker installer — one command for first install AND upgrade.
  *
- *   sudo node deploy/install.mjs [agent-user] [flags]
+ *   sudo npx @cldmv/gh-broker [agent-user] [flags]   (from npm)
+ *   sudo node deploy/install.mjs [agent-user] [flags] (from a checkout)
  *
  * Prerequisite: node >= 20. Idempotent: re-run to upgrade (config regenerated by
  * layering, existing secrets kept). Interactive by default; pass flags plus
@@ -68,7 +69,8 @@ function readJson(path) {
 
 const HELP = `gh-broker installer — install and upgrade in one command.
 
-Usage: sudo node deploy/install.mjs [agent-user] [flags]
+Usage: sudo npx @cldmv/gh-broker [agent-user] [flags]     (from npm)
+       sudo node deploy/install.mjs [agent-user] [flags]   (from a checkout)
 
 Flags:
   --agent-user <name>     the unprivileged user the agent runs as
@@ -159,7 +161,7 @@ async function main() {
 		}
 	}
 
-	if (!isRoot()) die("must run as root: sudo node deploy/install.mjs [agent-user] [flags]");
+	if (!isRoot()) die("must run as root: sudo npx @cldmv/gh-broker [agent-user] [flags], or sudo node deploy/install.mjs from a checkout");
 	if (process.platform !== "linux") {
 		die(`only Linux is implemented today (platform: ${process.platform}). The path/secret/service seams are ready; the impls are not.`);
 	}