@cldmv/gh-broker 0.7.0 → 0.9.0

package/src/verbs/rest-client.ts

@@ -1,181 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/rest-client.ts
- *	@Date: 2026-09-29T02:39:40+00:00 (1790649580)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-02T11:30:58-07:00 (1790965858)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-import type { Octokit } from "@octokit/core";
-
-/**
- * Shared REST-call machinery for custom verbs that compose plain `octokit.request()`
- * calls instead of proxying a hosted-MCP tool (currently `report_unlabeled` and
- * `report_ci_status`). Factored out once a second verb needed the identical
- * rate-limit/call-budget handling — see report_unlabeled.ts's original version for
- * the rationale (kept here, not duplicated).
- *
- * Rate-limit floor: proactively stops once remaining requests drop to 2% of the
- * token's OWN limit (read from `x-ratelimit-limit` on every response — never
- * hardcode GitHub's number, it can differ by token type/tier), floored at an
- * absolute minimum for low-limit tokens. Leaves headroom for other broker traffic
- * sharing the same PAT, rather than waiting to actually get a 403.
- */
-
-const PAGE_SIZE = 100;
-const RATE_LIMIT_FLOOR_RATIO = 0.02;
-const RATE_LIMIT_FLOOR_MIN = 20;
-
-export class RateLimited extends Error {
-	readonly retryAfterSeconds?: number;
-	constructor(retryAfterSeconds?: number) {
-		super("rate limited");
-		this.retryAfterSeconds = retryAfterSeconds;
-	}
-}
-
-export class CallBudgetExhausted extends Error {
-	constructor() {
-		super("call budget exhausted");
-	}
-}
-
-export class CallBudget {
-	private remaining: number;
-	constructor(max: number) {
-		this.remaining = max;
-	}
-	/** Throws CallBudgetExhausted once the budget is spent. */
-	spend(): void {
-		if (this.remaining <= 0) throw new CallBudgetExhausted();
-		this.remaining--;
-	}
-}
-
-/**
- * A 403 is only a rate limit when GitHub says so — a Retry-After header, an exhausted
- * `x-ratelimit-remaining`, or a rate-limit/abuse message. Any other 403 is a permission
- * or feature-disabled answer (e.g. code scanning off for a repo) and must surface to the
- * caller with its status intact instead of being mistaken for throttling.
- */
-function looksRateLimited(err: Error, headers: Record<string, string> | undefined): boolean {
-	if (headers?.["retry-after"] !== undefined) return true;
-	if (headers?.["x-ratelimit-remaining"] === "0") return true;
-	return /rate limit|abuse|secondary/i.test(err.message);
-}
-
-/** Runs one octokit.request call, charging the budget and enforcing the rate-limit floor. */
-async function doRequest(octokit: Octokit, budget: CallBudget, route: string, params: Record<string, unknown>): Promise<{ data: unknown }> {
-	budget.spend();
-	try {
-		const res = await octokit.request(route, params);
-		const headers = res.headers as Record<string, string> | undefined;
-		const remainingHeader = headers?.["x-ratelimit-remaining"];
-		if (remainingHeader !== undefined) {
-			const remaining = Number(remainingHeader);
-			const limit = Number(headers?.["x-ratelimit-limit"]);
-			const floor = Number.isFinite(limit) ? Math.max(RATE_LIMIT_FLOOR_MIN, Math.ceil(limit * RATE_LIMIT_FLOOR_RATIO)) : RATE_LIMIT_FLOOR_MIN;
-			if (remaining <= floor) throw new RateLimited();
-		}
-		return res;
-	} catch (err) {
-		if (err instanceof RateLimited) throw err;
-		const status = (err as { status?: number }).status;
-		const headers = (err as { response?: { headers?: Record<string, string> } }).response?.headers;
-		if (status === 429 || (status === 403 && looksRateLimited(err as Error, headers))) {
-			const retryAfter = headers?.["retry-after"];
-			throw new RateLimited(retryAfter ? Number(retryAfter) : undefined);
-		}
-		throw err;
-	}
-}
-
-/**
- * Runs one octokit.request call expected to return a listing. `extract` pulls the
- * item array out of the response body — plain for bare-array endpoints
- * (issues/pulls/repos), overridden for endpoints that wrap the array in a named
- * field (e.g. Actions: `{ workflow_runs: [...] }`).
- */
-export async function req<T>(
-	octokit: Octokit,
-	budget: CallBudget,
-	route: string,
-	params: Record<string, unknown>,
-	extract: (data: unknown) => T[] = (d) => d as T[]
-): Promise<T[]> {
-	const res = await doRequest(octokit, budget, route, params);
-	return extract(res.data);
-}
-
-/** Runs one octokit.request call expected to return a single resource (not a listing). */
-export async function reqOne<T>(octokit: Octokit, budget: CallBudget, route: string, params: Record<string, unknown>): Promise<T> {
-	const res = await doRequest(octokit, budget, route, params);
-	return res.data as T;
-}
-
-/** Paginates a listing endpoint up to `limit` items, stopping at a short last page. */
-export async function paginate<T>(
-	octokit: Octokit,
-	budget: CallBudget,
-	route: string,
-	params: Record<string, unknown>,
-	limit: number,
-	extract?: (data: unknown) => T[]
-): Promise<T[]> {
-	const out: T[] = [];
-	let page = 1;
-	while (out.length < limit) {
-		const batch = await req<T>(octokit, budget, route, { ...params, per_page: PAGE_SIZE, page }, extract);
-		if (batch.length === 0) break;
-		out.push(...batch);
-		if (batch.length < PAGE_SIZE) break;
-		page++;
-	}
-	return out.length > limit ? out.slice(0, limit) : out;
-}
-
-/**
- * Paginates a listing endpoint that uses cursor pagination (`after`) instead of `page` —
- * Dependabot's alert endpoints. Follows the `rel="next"` cursor in the Link header and
- * stops at the last page or once `limit` items are collected.
- */
-export async function paginateAfter<T>(octokit: Octokit, budget: CallBudget, route: string, params: Record<string, unknown>, limit: number): Promise<T[]> {
-	const out: T[] = [];
-	let after: string | undefined;
-	while (out.length < limit) {
-		const res = await doRequest(octokit, budget, route, { ...params, per_page: PAGE_SIZE, ...(after ? { after } : {}) });
-		const batch = res.data;
-		if (!Array.isArray(batch) || batch.length === 0) break;
-		out.push(...(batch as T[]));
-		const link = (res as { headers?: Record<string, string> }).headers?.link;
-		const next = link ? /<[^>]*[?&]after=([^&>]+)[^>]*>;\s*rel="next"/.exec(link) : null;
-		if (!next) break;
-		after = decodeURIComponent(next[1]!);
-	}
-	return out.length > limit ? out.slice(0, limit) : out;
-}
-
-interface RawRepo {
-	name: string;
-	archived?: boolean;
-}
-
-/** Lists non-archived repo names for an owner — tries the org endpoint, falls back to user. */
-export async function listOwnerRepos(octokit: Octokit, budget: CallBudget, owner: string, maxRepos: number): Promise<string[]> {
-	let raw: RawRepo[];
-	try {
-		raw = await paginate<RawRepo>(octokit, budget, "GET /orgs/{owner}/repos", { owner, type: "all" }, maxRepos);
-	} catch (err) {
-		if (err instanceof RateLimited || err instanceof CallBudgetExhausted) throw err;
-		if ((err as { status?: number }).status !== 404) throw err;
-		raw = await paginate<RawRepo>(octokit, budget, "GET /users/{username}/repos", { username: owner, type: "all" }, maxRepos);
-	}
-	return raw.filter((r) => !r.archived).map((r) => r.name);
-}

package/src/verbs/review_thread.ts

@@ -1,138 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/review_thread.ts
- *	@Date: 2026-07-11T10:24:46-07:00 (1783790686)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-02T11:30:58-07:00 (1790965858)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-import type { Octokit } from "@octokit/core";
-
-/**
- * Custom verbs: reply_review_thread + resolve_review_thread — respond to and resolve
- * pull-request review threads (e.g. Copilot's review comments).
- *
- * Why custom verbs:
- *  - The hosted GitHub MCP can READ review threads (`pull_request_read` →
- *    `get_review_comments`, which returns each thread's node id + `isResolved`), but
- *    exposes NO tool to reply inside a thread or to resolve/unresolve one. Those are
- *    GraphQL mutations (`addPullRequestReviewThreadReply`, `resolveReviewThread`,
- *    `unresolveReviewThread`) with no hosted-MCP wrapper, so they can't be proxied.
- *  - Unlike `link_issue`'s App-token-only mutation, these ARE available to a
- *    fine-grained PAT with **Pull requests: write** — the same permission the broker's
- *    write cred already uses for `create_pull_request` / `update_pull_request` /
- *    `add_issue_comment`. So they run on the resolved write PAT (least privilege), not
- *    the App token.
- *
- * Uses Octokit (`octokit.graphql`) — GitHub's official SDK.
- *
- * The `threadId` is the review-thread NODE id (e.g. "PRRT_kwDO…"), taken verbatim from
- * `pull_request_read` (`get_review_comments`) — each returned thread carries it as `id`.
- */
-
-export interface ResolveReviewThreadInput {
-	owner: string;
-	repo?: string;
-	/** Review-thread node id (e.g. "PRRT_…") from pull_request_read get_review_comments. */
-	threadId: string;
-	/** true → resolve (default); false → unresolve. */
-	resolve?: boolean;
-}
-
-export interface ReplyReviewThreadInput {
-	owner: string;
-	repo?: string;
-	/** Review-thread node id (e.g. "PRRT_…") to reply into. */
-	threadId: string;
-	/** Reply body (Markdown). */
-	body: string;
-}
-
-const RESOLVE_THREAD = `
-	mutation($threadId: ID!) {
-		resolveReviewThread(input: { threadId: $threadId }) {
-			thread { id isResolved }
-		}
-	}`;
-
-const UNRESOLVE_THREAD = `
-	mutation($threadId: ID!) {
-		unresolveReviewThread(input: { threadId: $threadId }) {
-			thread { id isResolved }
-		}
-	}`;
-
-const REPLY_THREAD = `
-	mutation($threadId: ID!, $body: String!) {
-		addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $threadId, body: $body }) {
-			comment { id url }
-		}
-	}`;
-
-/** Resolve (or unresolve) a review thread. Returns the thread id and its new resolved state. */
-export async function resolveReviewThread(
-	octokit: Octokit,
-	input: ResolveReviewThreadInput
-): Promise<{ threadId: string; isResolved: boolean }> {
-	const unresolve = input.resolve === false;
-	const data = await octokit.graphql<{
-		resolveReviewThread?: { thread: { id: string; isResolved: boolean } };
-		unresolveReviewThread?: { thread: { id: string; isResolved: boolean } };
-	}>(unresolve ? UNRESOLVE_THREAD : RESOLVE_THREAD, { threadId: input.threadId });
-	const thread = (data.resolveReviewThread ?? data.unresolveReviewThread)?.thread;
-	if (!thread) throw new Error(`resolve_review_thread: no thread returned for "${input.threadId}"`);
-	return { threadId: thread.id, isResolved: thread.isResolved };
-}
-
-/** Post a reply inside a review thread. Returns the new comment's node id + html url. */
-export async function replyReviewThread(
-	octokit: Octokit,
-	input: ReplyReviewThreadInput
-): Promise<{ commentId: string; url: string }> {
-	if (!input.body || !input.body.trim()) throw new Error("reply_review_thread: body is required");
-	const data = await octokit.graphql<{
-		addPullRequestReviewThreadReply: { comment: { id: string; url: string } };
-	}>(REPLY_THREAD, { threadId: input.threadId, body: input.body });
-	const comment = data.addPullRequestReviewThreadReply?.comment;
-	if (!comment) throw new Error(`reply_review_thread: reply failed for "${input.threadId}"`);
-	return { commentId: comment.id, url: comment.url };
-}
-
-/** JSON Schema advertised to the agent for resolve_review_thread. */
-export const RESOLVE_REVIEW_THREAD_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "threadId"],
-	additionalProperties: false,
-	properties: {
-		owner: { type: "string", description: "repository owner (org/user login) — selects the write credential" },
-		repo: { type: "string", description: "repository name (optional; for the audit log only)" },
-		threadId: {
-			type: "string",
-			description: 'review-thread node id (e.g. "PRRT_…"), taken verbatim from pull_request_read get_review_comments'
-		},
-		resolve: { type: "boolean", description: "true to resolve (default), false to unresolve", default: true }
-	}
-};
-
-/** JSON Schema advertised to the agent for reply_review_thread. */
-export const REPLY_REVIEW_THREAD_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "threadId", "body"],
-	additionalProperties: false,
-	properties: {
-		owner: { type: "string", description: "repository owner (org/user login) — selects the write credential" },
-		repo: { type: "string", description: "repository name (optional; for the audit log only)" },
-		threadId: {
-			type: "string",
-			description: 'review-thread node id (e.g. "PRRT_…") to reply into, from pull_request_read get_review_comments'
-		},
-		body: { type: "string", description: "reply body (Markdown)" }
-	}
-};

package/tests/appauth.test.vitest.mts

@@ -1,76 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-
-const { createAppAuthMock, octokitCtor } = vi.hoisted(() => ({
-	createAppAuthMock: vi.fn(),
-	// Constructable mock (arrow fns can't be `new`-ed).
-	octokitCtor: vi.fn(function (this: any, opts: unknown) {
-		this.__opts = opts;
-	})
-}));
-
-vi.mock("@octokit/core", () => ({ Octokit: octokitCtor }));
-vi.mock("@octokit/auth-app", () => ({ createAppAuth: createAppAuthMock }));
-
-import { Octokit } from "@octokit/core";
-import { createAppAuth } from "@octokit/auth-app";
-import { AppAuth } from "../src/appauth.ts";
-
-function config(overrides: Record<string, unknown> = {}): any {
-	return {
-		listen: "unix:/x",
-		upstream: "https://x",
-		tools: [],
-		app: { appId: 555, privateKey: "cred:app-key" },
-		owners: {
-			cldmv: { read: "cred:r", write: "cred:w", installationId: 42 },
-			noapp: { read: "cred:r2", write: "cred:w2" }
-		},
-		...overrides
-	};
-}
-
-describe("AppAuth", () => {
-	let secrets: { resolve: ReturnType<typeof vi.fn> };
-
-	beforeEach(() => {
-		vi.clearAllMocks();
-		secrets = { resolve: vi.fn((ref: string) => (ref === "cred:app-key" ? "PEM-PRIVATE-KEY" : "other")) };
-	});
-
-	it("throws when the config has no app section", () => {
-		expect(() => new AppAuth(config({ app: undefined }), secrets as any)).toThrow(/no app config/);
-	});
-
-	it("resolves the App private key at construction", () => {
-		new AppAuth(config(), secrets as any);
-		expect(secrets.resolve).toHaveBeenCalledWith("cred:app-key");
-	});
-
-	it("returns null for an owner without an installationId", () => {
-		const auth = new AppAuth(config(), secrets as any);
-		expect(auth.octokitFor("noapp")).toBeNull();
-	});
-
-	it("returns null for an unknown owner", () => {
-		const auth = new AppAuth(config(), secrets as any);
-		expect(auth.octokitFor("nobody")).toBeNull();
-	});
-
-	it("builds an App-authed Octokit for an owner with an installationId", () => {
-		const auth = new AppAuth(config(), secrets as any);
-		const ok = auth.octokitFor("cldmv");
-		expect(ok).not.toBeNull();
-		expect(Octokit).toHaveBeenCalledWith({
-			authStrategy: createAppAuth,
-			auth: { appId: 555, privateKey: "PEM-PRIVATE-KEY", installationId: 42 }
-		});
-	});
-
-	it("caches the Octokit per installation id", () => {
-		const auth = new AppAuth(config(), secrets as any);
-		const first = auth.octokitFor("cldmv");
-		const second = auth.octokitFor("cldmv");
-		expect(first).toBe(second);
-		expect(Octokit).toHaveBeenCalledTimes(1);
-	});
-});

package/tests/audit.test.vitest.mts

@@ -1,48 +0,0 @@
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { audit } from "../src/audit.ts";
-
-describe("audit", () => {
-	afterEach(() => {
-		vi.restoreAllMocks();
-	});
-
-	it("emits a single JSON line with a timestamp and the entry fields", () => {
-		const spy = vi.spyOn(console, "log").mockImplementation(() => {});
-		audit({ tool: "get_me", owner: "cldmv", mode: "read", repo: "cldmv/gh-broker", decision: "forward", ok: true });
-		expect(spy).toHaveBeenCalledTimes(1);
-		const line = spy.mock.calls[0]![0] as string;
-		const parsed = JSON.parse(line);
-		expect(parsed).toMatchObject({
-			tool: "get_me",
-			owner: "cldmv",
-			mode: "read",
-			repo: "cldmv/gh-broker",
-			decision: "forward",
-			ok: true
-		});
-		expect(typeof parsed.ts).toBe("string");
-		expect(new Date(parsed.ts).toISOString()).toBe(parsed.ts); // valid ISO timestamp
-	});
-
-	it("never emits a token — no cred value or Authorization content in the line", () => {
-		const spy = vi.spyOn(console, "log").mockImplementation(() => {});
-		// The audit API has no token field; even if a caller mistakenly passed extra
-		// fields, only the AuditEntry keys are what the router hands it. Assert the
-		// emitted line carries no token-shaped content for the fields it does take.
-		audit({ tool: "create_pull_request", owner: "cldmv", mode: "write", repo: "cldmv/x", decision: "custom", ok: true, detail: "done" });
-		const line = spy.mock.calls[0]![0] as string;
-		expect(line).not.toMatch(/token/i);
-		expect(line).not.toMatch(/bearer/i);
-		expect(line).not.toMatch(/cred:/);
-		const parsed = JSON.parse(line);
-		expect(Object.keys(parsed).sort()).toEqual(["decision", "detail", "mode", "ok", "owner", "repo", "tool", "ts"].sort());
-	});
-
-	it("emits a minimal deny entry", () => {
-		const spy = vi.spyOn(console, "log").mockImplementation(() => {});
-		audit({ tool: "rm_rf", decision: "deny", detail: "not in allowlist" });
-		const parsed = JSON.parse(spy.mock.calls[0]![0] as string);
-		expect(parsed).toMatchObject({ tool: "rm_rf", decision: "deny", detail: "not in allowlist" });
-		expect(parsed.owner).toBeUndefined();
-	});
-});

package/tests/catalog.test.vitest.mts

@@ -1,180 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { buildCatalog } from "../src/catalog.ts";
-
-function makeConfig(tools: any[], owners: Record<string, unknown> = { cldmv: { read: "cred:r", write: "cred:w" } }): any {
-	return { listen: "unix:/x", upstream: "https://api.githubcopilot.com/mcp/", tools, owners };
-}
-
-describe("buildCatalog", () => {
-	let secrets: { resolve: ReturnType<typeof vi.fn> };
-	let upstream: { listToolsFor: ReturnType<typeof vi.fn> };
-	let errSpy: ReturnType<typeof vi.spyOn>;
-
-	beforeEach(() => {
-		secrets = { resolve: vi.fn(() => "tok") };
-		upstream = { listToolsFor: vi.fn() };
-		errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-	});
-
-	afterEach(() => {
-		vi.restoreAllMocks();
-		delete process.env.GH_BROKER_CATALOG_TIMEOUT_MS;
-	});
-
-	it("uses upstream schemas, emits local schemas for custom verbs, and skips unexposed proxied tools", async () => {
-		const upstreamTool = { name: "get_me", description: "real", inputSchema: { type: "object", properties: {} } };
-		upstream.listToolsFor.mockResolvedValue([upstreamTool]);
-		const config = makeConfig([
-			{ name: "get_me", mode: "read" },
-			{ name: "not_exposed", mode: "read" },
-			{ name: "link_issue", mode: "write", custom: true },
-			{ name: "resolve_review_thread", mode: "write", custom: true },
-			{ name: "reply_review_thread", mode: "write", custom: true },
-			{ name: "mystery_custom", mode: "read", custom: true }
-		]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-
-		expect(secrets.resolve).toHaveBeenCalledWith("cred:r");
-		const names = catalog.map((t) => t.name);
-		// get_me is served from upstream; not_exposed is dropped (fetched but absent);
-		// the two wired custom verbs get local schemas; link_issue is DEFERRED (its
-		// catalog branch is commented out) and mystery_custom matches no branch — both
-		// are silently skipped even when allowlisted.
-		expect(names).toEqual(["get_me", "resolve_review_thread", "reply_review_thread"]);
-		expect(names).not.toContain("link_issue");
-		expect(catalog[0]).toBe(upstreamTool);
-		expect(catalog.find((t) => t.name === "resolve_review_thread")?.inputSchema).toMatchObject({ type: "object" });
-		expect(errSpy).toHaveBeenCalledWith(expect.stringMatching(/allowlisted tool "not_exposed" is NOT exposed/));
-	});
-
-	it("advertises report_unlabeled with its local schema", async () => {
-		upstream.listToolsFor.mockResolvedValue([]);
-		const config = makeConfig([{ name: "report_unlabeled", mode: "read", custom: true }]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(catalog).toHaveLength(1);
-		expect(catalog[0]).toMatchObject({ name: "report_unlabeled" });
-		expect(catalog[0]?.inputSchema).toMatchObject({ type: "object", required: ["owner"] });
-	});
-
-	it("advertises report_security_alerts with its local schema", async () => {
-		upstream.listToolsFor.mockResolvedValue([]);
-		const config = makeConfig([{ name: "report_security_alerts", mode: "read", custom: true }]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(catalog).toHaveLength(1);
-		expect(catalog[0]).toMatchObject({ name: "report_security_alerts" });
-		expect(catalog[0]?.inputSchema).toMatchObject({ type: "object", required: ["owner"] });
-	});
-
-	it("advertises report_release_prs with its local schema", async () => {
-		upstream.listToolsFor.mockResolvedValue([]);
-		const config = makeConfig([{ name: "report_release_prs", mode: "read", custom: true }]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(catalog).toHaveLength(1);
-		expect(catalog[0]).toMatchObject({ name: "report_release_prs" });
-		expect(catalog[0]?.inputSchema).toMatchObject({ type: "object", required: ["owner"] });
-	});
-
-	it("advertises issue_labels with its local schema", async () => {
-		upstream.listToolsFor.mockResolvedValue([]);
-		const config = makeConfig([{ name: "issue_labels", mode: "write", custom: true }]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(catalog).toHaveLength(1);
-		expect(catalog[0]).toMatchObject({ name: "issue_labels" });
-		expect(catalog[0]?.description).toMatch(/swap/);
-		expect(catalog[0]?.inputSchema).toMatchObject({ type: "object", required: ["owner", "repo", "issue_number"] });
-	});
-
-	it("warns on issue_write that labels replaces the set, pointing at issue_labels when it is allowlisted", async () => {
-		const upstreamTool = { name: "issue_write", description: "Create or update an issue.", inputSchema: { type: "object", properties: { labels: {} } } };
-		upstream.listToolsFor.mockResolvedValue([upstreamTool]);
-		const withVerb = await buildCatalog(
-			makeConfig([{ name: "issue_write", mode: "write" }, { name: "issue_labels", mode: "write", custom: true }]),
-			secrets as any,
-			upstream as any
-		);
-		const iw = withVerb.find((t) => t.name === "issue_write")!;
-		expect(iw.description).toMatch(/^Create or update an issue\. WARNING \(gh-broker\): "labels" REPLACES the issue's whole label set/);
-		expect(iw.description).toMatch(/use issue_labels instead/);
-		expect(iw.inputSchema).toBe(upstreamTool.inputSchema);
-		expect(upstreamTool.description).toBe("Create or update an issue."); // the fetched tool is not mutated
-
-		const without = await buildCatalog(makeConfig([{ name: "issue_write", mode: "write" }]), secrets as any, upstream as any);
-		expect(without[0]?.description).toMatch(/REPLACES/);
-		expect(without[0]?.description).not.toMatch(/issue_labels/);
-		expect(without[0]?.description).toMatch(/pass the full set/);
-	});
-
-	it("still warns on issue_write when the upstream fetch fails (minimal schema)", async () => {
-		upstream.listToolsFor.mockRejectedValue(new Error("down"));
-		const catalog = await buildCatalog(makeConfig([{ name: "issue_write", mode: "write" }]), secrets as any, upstream as any);
-		expect(catalog[0]?.description).toMatch(/^\(write\) proxied to the GitHub MCP WARNING/);
-	});
-
-	it("advertises report_ci_status with its local schema", async () => {
-		upstream.listToolsFor.mockResolvedValue([]);
-		const config = makeConfig([{ name: "report_ci_status", mode: "read", custom: true }]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(catalog).toHaveLength(1);
-		expect(catalog[0]).toMatchObject({ name: "report_ci_status" });
-		expect(catalog[0]?.inputSchema).toMatchObject({ type: "object", required: ["owner", "repo"] });
-	});
-
-	it("layers ciVerbosity/logLines onto pull_request_read's real upstream schema without dropping its own params", async () => {
-		const upstreamTool = {
-			name: "pull_request_read",
-			description: "Get information on a specific pull request.",
-			inputSchema: { type: "object", required: ["owner", "repo", "pullNumber", "method"], properties: { method: { type: "string" }, pullNumber: { type: "number" } } }
-		};
-		upstream.listToolsFor.mockResolvedValue([upstreamTool]);
-		const config = makeConfig([{ name: "pull_request_read", mode: "read", augment: true }]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(catalog).toHaveLength(1);
-		const tool = catalog[0]!;
-		expect(tool.description).toContain("gh-broker extension");
-		expect((tool.inputSchema as any).required).toEqual(["owner", "repo", "pullNumber", "method"]);
-		expect((tool.inputSchema as any).properties.pullNumber).toEqual({ type: "number" });
-		expect((tool.inputSchema as any).properties.ciVerbosity).toMatchObject({ type: "number", enum: [0, 1, 2, 3] });
-		expect((tool.inputSchema as any).properties.logLines).toMatchObject({ type: "number" });
-	});
-
-	it("still adds ciVerbosity/logLines to pull_request_read when the upstream fetch fails entirely", async () => {
-		upstream.listToolsFor.mockRejectedValue(new Error("network down"));
-		const config = makeConfig([{ name: "pull_request_read", mode: "read", augment: true }]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(catalog).toHaveLength(1);
-		expect((catalog[0]!.inputSchema as any).properties).toEqual({
-			ciVerbosity: { type: "number", enum: [0, 1, 2, 3], description: expect.any(String) },
-			logLines: { type: "number", description: expect.any(String) }
-		});
-	});
-
-	it("falls back to minimal schemas when the upstream fetch fails", async () => {
-		upstream.listToolsFor.mockRejectedValue(new Error("401 bad token"));
-		const config = makeConfig([
-			{ name: "get_me", mode: "read" },
-			{ name: "resolve_review_thread", mode: "write", custom: true }
-		]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-
-		const getMe = catalog.find((t) => t.name === "get_me");
-		expect(getMe).toEqual({ name: "get_me", description: "(read) proxied to the GitHub MCP", inputSchema: { type: "object" } });
-		expect(catalog.map((t) => t.name)).toContain("resolve_review_thread");
-		expect(errSpy).toHaveBeenCalledWith(expect.stringMatching(/could not fetch upstream tool schemas/));
-	});
-
-	it("skips the upstream fetch entirely when there are no owners", async () => {
-		const config = makeConfig([{ name: "get_me", mode: "read" }], {});
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(upstream.listToolsFor).not.toHaveBeenCalled();
-		expect(catalog).toEqual([{ name: "get_me", description: "(read) proxied to the GitHub MCP", inputSchema: { type: "object" } }]);
-	});
-
-	it("times out a slow upstream and advertises minimal schemas", async () => {
-		process.env.GH_BROKER_CATALOG_TIMEOUT_MS = "15";
-		upstream.listToolsFor.mockReturnValue(new Promise(() => {})); // never resolves
-		const config = makeConfig([{ name: "get_me", mode: "read" }]);
-		const catalog = await buildCatalog(config, secrets as any, upstream as any);
-		expect(catalog.map((t) => t.name)).toEqual(["get_me"]);
-		expect(errSpy).toHaveBeenCalledWith(expect.stringMatching(/timed out after 15ms/));
-	});
-});