@cldmv/gh-broker 0.8.0 → 0.10.0

package/src/verbs/ghcr_push.ts

@@ -1,264 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/ghcr_push.ts
- *	@Date: 2026-10-31T11:02:57-07:00 (1793469777)
- *	@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-31T13:14:41-07:00 (1793477681)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-/**
- * Custom verbs: ghcr_push, ghcr_push_status, ghcr_tags — push container images to GHCR
- * (ghcr.io/<owner>/<image>) without the agent ever holding a registry credential.
- *
- * The agent writes a `docker save` archive into the drop directory and calls `ghcr_push`.
- * The broker checks the call against `config.ghcr` (owner configured, image on the owner's
- * allowlist, tag well-formed, archive really inside the drop directory, release tag not
- * already taken), exchanges the owner's classic PAT for a registry token, and pushes in a
- * background job. `ghcr_push_status` reports that job; `ghcr_tags` lists an allowlisted
- * image's tags so a push can be verified.
- *
- * What the verbs can't do, by construction: talk to any registry but ghcr.io, push outside
- * `ghcr.io/<owner>/<allowlisted image>`, delete anything, change visibility, or read a
- * file outside the drop directory. No result, error, audit line or log line carries the
- * PAT or the registry token (registry.ts `clean()`).
- *
- * The handlers are the real contract: the MCP server doesn't validate against the
- * advertised schemas, so every key and type is checked here before any network call.
- */
-
-import type { SecretStore } from "../types.ts";
-import { audit } from "../audit.ts";
-import { imageAllowed, type GhcrConfig, type GhcrOwnerConfig } from "./ghcr/config.ts";
-import { openArchive, planImage } from "./ghcr/archive.ts";
-import { Registry, GHCR_BASE } from "./ghcr/registry.ts";
-import { pushImage, RELEASE_TAG } from "./ghcr/push.ts";
-import { JobQueue, type Job } from "./ghcr/jobs.ts";
-
-/** OCI repository path component; `/` separates components. */
-const IMAGE = /^[a-z0-9]+(?:(?:\.|_|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:\.|_|__|-+)[a-z0-9]+)*)*$/;
-/** OCI tag grammar. */
-const TAG = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
-const JOB_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-
-const PUSH_KEYS = new Set(["owner", "image", "tag", "archive"]);
-const STATUS_KEYS = new Set(["owner", "job"]);
-const TAGS_KEYS = new Set(["owner", "image"]);
-
-export interface GhcrPushInput {
-	owner: string;
-	image: string;
-	tag: string;
-	archive: string;
-}
-export interface GhcrPushStatusInput {
-	owner: string;
-	job?: string;
-}
-export interface GhcrTagsInput {
-	owner: string;
-	image: string;
-}
-
-function strictArgs(verb: string, input: unknown, keys: Set<string>): Record<string, unknown> {
-	if (typeof input !== "object" || input === null || Array.isArray(input)) throw new Error(`${verb}: arguments must be an object`);
-	const a = input as Record<string, unknown>;
-	const unknown = Object.keys(a).filter((k) => !keys.has(k));
-	if (unknown.length) throw new Error(`${verb}: unknown argument(s): ${unknown.join(", ")} — expected ${[...keys].join(", ")}`);
-	if (typeof a.owner !== "string" || !a.owner.trim()) throw new Error(`${verb}: "owner" must be a non-empty string`);
-	return a;
-}
-
-export interface GhcrServiceOptions {
-	/** Registry origin — tests only; production is always https://ghcr.io. */
-	base?: string;
-	queue?: JobQueue;
-}
-
-export class GhcrService {
-	private readonly cfg?: GhcrConfig;
-	private readonly secrets: SecretStore;
-	private readonly base: string;
-	readonly queue: JobQueue;
-
-	constructor(cfg: GhcrConfig | undefined, secrets: SecretStore, opts: GhcrServiceOptions = {}) {
-		this.cfg = cfg;
-		this.secrets = secrets;
-		this.base = opts.base ?? GHCR_BASE;
-		this.queue = opts.queue ?? new JobQueue();
-	}
-
-	private config(verb: string): GhcrConfig {
-		if (!this.cfg) throw new Error(`${verb}: GHCR is not configured — add a "ghcr" block to the config (see docs/TOOLS.md#ghcr_push)`);
-		return this.cfg;
-	}
-
-	private ownerConfig(verb: string, owner: string): GhcrOwnerConfig {
-		const o = this.config(verb).owners[owner.toLowerCase()];
-		if (!o) throw new Error(`${verb}: owner "${owner}" has no GHCR configuration (config.ghcr.owners)`);
-		if (!this.secrets.has(o.credential)) throw new Error(`${verb}: owner "${owner}"'s GHCR credential "${o.credential.replace(/^cred:/, "")}" is not stored (re-run the installer to add it)`);
-		return o;
-	}
-
-	private image(verb: string, owner: string, oc: GhcrOwnerConfig, raw: unknown): string {
-		if (typeof raw !== "string" || !raw) throw new Error(`${verb}: "image" must be a non-empty string`);
-		const lower = raw.toLowerCase();
-		if (lower.startsWith("ghcr.io/") || lower.startsWith(`${owner}/`)) {
-			throw new Error(`${verb}: "image" is the name under ghcr.io/${owner}/ — pass e.g. "hoot", not "${raw}"`);
-		}
-		if (!IMAGE.test(raw) || raw.length + owner.length + 1 > 255) throw new Error(`${verb}: "image" "${raw}" is not a valid image name (lowercase [a-z0-9], separators . _ __ -, "/" between segments)`);
-		if (!imageAllowed(oc, raw)) throw new Error(`${verb}: ghcr.io/${owner}/${raw} is not on the allowlist (config.ghcr.owners.${owner}.images: ${oc.images.join(", ")})`);
-		return raw;
-	}
-
-	private registry(owner: string, oc: GhcrOwnerConfig, image: string): Registry {
-		return new Registry({ base: this.base, username: oc.username, password: this.secrets.resolve(oc.credential), repository: `${owner}/${image}` });
-	}
-
-	async push(input: unknown): Promise<Omit<Job, "progress" | "result">> {
-		const verb = "ghcr_push";
-		const a = strictArgs(verb, input, PUSH_KEYS);
-		const owner = (a.owner as string).toLowerCase();
-		const cfg = this.config(verb);
-		const oc = this.ownerConfig(verb, owner);
-		const image = this.image(verb, owner, oc, a.image);
-		if (typeof a.tag !== "string" || !TAG.test(a.tag)) throw new Error(`${verb}: "tag" must be a valid tag ([A-Za-z0-9_][A-Za-z0-9._-]{0,127})`);
-		const tag = a.tag;
-
-		const archive = openArchive(a.archive, cfg.dropDir, cfg.maxArchiveBytes);
-		let handedOff = false;
-		let registry: Registry | undefined;
-		try {
-			const plan = planImage(archive.fd, archive.size);
-			registry = this.registry(owner, oc, image);
-			const ref = `${registry.host}/${owner}/${image}`;
-			// First network calls: proves the credential can push here, and refuses a taken release tag
-			// before the job is queued (push.ts re-checks right before the manifest PUT).
-			await registry.login("push,pull");
-			if (cfg.protectReleaseTags && RELEASE_TAG.test(tag) && (await registry.manifestExists(tag))) {
-				throw new Error(`${verb}: tag ${tag} already exists on ${ref} and release tags are protected — push a new version instead`);
-			}
-
-			const reg = registry;
-			const job = this.queue.submit(
-				{ owner, image: ref, tag, archive: archive.path, archiveBytes: archive.size, format: plan.format },
-				{
-					run: (progress) => pushImage(reg, archive.fd, plan, tag, { protectReleaseTags: cfg.protectReleaseTags, onProgress: progress }),
-					describeError: (err) => reg.clean((err as Error)?.message ?? String(err)),
-					finally: (done) => {
-						archive.close();
-						audit({
-							tool: verb,
-							owner,
-							mode: "write",
-							repo: ref,
-							decision: "custom",
-							ok: done.state === "succeeded",
-							detail:
-								done.state === "succeeded"
-									? `job=${done.job} tag=${tag} digest=${done.result?.digest} size=${done.result?.size} uploaded=${done.result?.blobsUploaded} skipped=${done.result?.blobsSkipped} archive=${archive.path}`
-									: `job=${done.job} tag=${tag} archive=${archive.path} error=${done.error}`
-						});
-					}
-				}
-			);
-			handedOff = true;
-			audit({ tool: verb, owner, mode: "write", repo: ref, decision: "custom", ok: true, detail: `job=${job.job} queued tag=${tag} archive=${archive.path} bytes=${archive.size} format=${plan.format} layers=${plan.layers.length}` });
-			return { ...job };
-		} catch (err) {
-			// Anything thrown before hand-off may come from the registry: scrub it like a job error.
-			if (!registry) throw err; // archive/plan errors carry no secret
-			throw new Error(registry.clean((err as Error)?.message ?? String(err)));
-		} finally {
-			if (!handedOff) archive.close();
-		}
-	}
-
-	status(input: unknown): Job | { jobs: Job[] } {
-		const verb = "ghcr_push_status";
-		const a = strictArgs(verb, input, STATUS_KEYS);
-		const owner = (a.owner as string).toLowerCase();
-		this.ownerConfig(verb, owner);
-		if (a.job === undefined) return { jobs: this.queue.list(owner) };
-		if (typeof a.job !== "string" || !JOB_ID.test(a.job)) throw new Error(`${verb}: "job" must be a job id returned by ghcr_push`);
-		const job = this.queue.get(a.job);
-		// A job of another owner reads as unknown: status never crosses owners.
-		if (!job || job.owner !== owner) throw new Error(`${verb}: no job ${a.job} for owner ${owner} (jobs are kept in memory; a broker restart forgets them)`);
-		return job;
-	}
-
-	async tags(input: unknown): Promise<{ image: string; exists: boolean; tags: string[] }> {
-		const verb = "ghcr_tags";
-		const a = strictArgs(verb, input, TAGS_KEYS);
-		const owner = (a.owner as string).toLowerCase();
-		const oc = this.ownerConfig(verb, owner);
-		const image = this.image(verb, owner, oc, a.image);
-		const registry = this.registry(owner, oc, image);
-		try {
-			await registry.login("pull");
-			const tags = await registry.listTags();
-			return { image: `${registry.host}/${owner}/${image}`, exists: tags !== undefined, tags: tags ?? [] };
-		} catch (err) {
-			throw new Error(registry.clean((err as Error)?.message ?? String(err)));
-		}
-	}
-}
-
-const owner = { type: "string", description: "registry owner (org/user login) — must be configured in config.ghcr.owners" };
-const image = { type: "string", description: 'image name under ghcr.io/<owner>/, e.g. "hoot" — must match config.ghcr.owners.<owner>.images' };
-
-export const GHCR_PUSH_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "image", "tag", "archive"],
-	additionalProperties: false,
-	properties: {
-		owner,
-		image,
-		tag: { type: "string", pattern: "^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$", description: "tag to push, e.g. \"1.4.0\" or \"latest\"" },
-		archive: {
-			type: "string",
-			description: "a `docker save` archive (docker-archive or OCI layout) inside the configured drop directory — absolute, or relative to it. Must be a regular, group-readable file; symlinks and hard links are refused."
-		}
-	}
-};
-
-export const GHCR_PUSH_STATUS_SCHEMA = {
-	type: "object" as const,
-	required: ["owner"],
-	additionalProperties: false,
-	properties: {
-		owner,
-		job: { type: "string", description: "job id returned by ghcr_push; omit to list this owner's recent jobs" }
-	}
-};
-
-export const GHCR_TAGS_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "image"],
-	additionalProperties: false,
-	properties: { owner, image }
-};
-
-/** Advertised description + schema per GHCR verb, keyed by tool name (catalog.ts). */
-export const GHCR_CATALOG: Record<string, { description: string; inputSchema: { type: "object"; [k: string]: unknown } }> = {
-	ghcr_push: {
-		description:
-			"Push a container image to ghcr.io/<owner>/<image>:<tag> from a `docker save` archive in the broker's drop directory, without holding a registry token. The image must be on config.ghcr's allowlist; an existing release tag (1.2.3 / v1.2.3) is never overwritten while protectReleaseTags is on. Starts a background job and returns its id at once — poll ghcr_push_status. Runs on the owner's GHCR credential (classic PAT, write:packages).",
-		inputSchema: GHCR_PUSH_SCHEMA
-	},
-	ghcr_push_status: {
-		description:
-			"Progress of a ghcr_push job (phase, blobs uploaded/skipped, bytes sent), then its final manifest digest or error. Omit job to list this owner's recent jobs. Jobs are kept in memory; a broker restart forgets them.",
-		inputSchema: GHCR_PUSH_STATUS_SCHEMA
-	},
-	ghcr_tags: {
-		description: "List the tags of an allowlisted image on ghcr.io/<owner>/<image>, e.g. to verify a push landed. Runs on the owner's GHCR credential (pull scope).",
-		inputSchema: GHCR_TAGS_SCHEMA
-	}
-};

package/src/verbs/issue_labels.ts

@@ -1,329 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/issue_labels.ts
- *	@Date: 2026-10-16T17:14:34-07:00 (1792196074)
- *	@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-16T17:25:33-07:00 (1792196733)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-import type { Octokit } from "@octokit/core";
-
-/**
- * Custom verb: issue_labels — edit the labels on one issue or PR without replacing the
- * whole set.
- *
- * Why a custom verb: the hosted MCP's only label write path is `issue_write`, whose
- * `labels` argument REPLACES every label on the issue. Changing one status label that way
- * silently drops the rest (CLDMV/gh-broker#117), and reading the set then writing the
- * merged set back loses any label someone else adds in between. GitHub's REST API has
- * per-label endpoints that touch only the labels named, so this verb drives those:
- *
- *  - `add`    → POST   /repos/{o}/{r}/issues/{n}/labels         (server-side append)
- *  - `remove` → DELETE /repos/{o}/{r}/issues/{n}/labels/{name}  (one call per label)
- *  - `swap`   → a POST of `to`, then a DELETE for every current label starting with `prefix`
- *  - `set`    → PUT    /repos/{o}/{r}/issues/{n}/labels         (explicit full replace, never empty)
- *
- * Writes run create → add → remove, so a call that fails part-way never leaves the issue
- * with fewer labels than it should have (a swap whose add is rate-limited keeps its old
- * status label). The error then names exactly what was applied and what was not.
- *
- * Issues and PRs share these endpoints, so a PR number works the same way.
- *
- * Label names to ADD (via `add`, `swap.to` or `set`) must already exist in the repo —
- * a typo would otherwise create a stray label silently. `create_missing: true` creates
- * them instead. Every add-side name is checked before any write, so a refused call
- * changes nothing.
- *
- * GitHub label names are case-insensitive; all matching here (existence, swap prefix,
- * add/remove overlap) is too, and the repo's own spelling is what gets written.
- */
-
-export interface IssueLabelsSwap {
-	/** Every current label starting with this (e.g. "status: ") is removed. */
-	prefix: string;
-	/** Then these are added. One label or several. */
-	to: string | string[];
-}
-
-export interface IssueLabelsInput {
-	owner: string;
-	repo: string;
-	/** Issue or pull-request number. */
-	issue_number: number;
-	add?: string | string[];
-	remove?: string | string[];
-	swap?: IssueLabelsSwap;
-	/** Replace the whole set. Cannot be combined with add/remove/swap. */
-	set?: string | string[];
-	/** Create add-side labels that don't exist in the repo instead of refusing. */
-	create_missing?: boolean;
-	/** Hex color (no #) for labels created via create_missing. */
-	color?: string;
-}
-
-export interface IssueLabelsResult {
-	issue: string;
-	/** The issue's label set after the call. */
-	labels: string[];
-	added: string[];
-	removed: string[];
-	created: string[];
-}
-
-const DEFAULT_COLOR = "ededed";
-/** GitHub's own per-issue label limit; also bounds the requests one call can make. */
-export const MAX_LABELS = 100;
-const INPUT_KEYS = new Set(["owner", "repo", "issue_number", "add", "remove", "swap", "set", "create_missing", "color"]);
-const SWAP_KEYS = new Set(["prefix", "to"]);
-
-const fail = (msg: string): never => {
-	throw new Error(`issue_labels: ${msg}`);
-};
-
-function toList(v: unknown, field: string): string[] {
-	if (v === undefined) return [];
-	const arr = Array.isArray(v) ? v : [v];
-	if (arr.length === 0) fail(`"${field}" is empty — pass at least one label name`);
-	for (const x of arr) {
-		if (typeof x !== "string" || !x.trim()) fail(`"${field}" must be a label name or a list of label names`);
-	}
-	const list = dedupe((arr as string[]).map((x) => x.trim()));
-	if (list.length > MAX_LABELS) fail(`"${field}" has ${list.length} labels — at most ${MAX_LABELS} per call`);
-	return list;
-}
-
-const key = (s: string): string => s.toLowerCase();
-
-function dedupe(list: string[]): string[] {
-	const seen = new Set<string>();
-	return list.filter((x) => (seen.has(key(x)) ? false : (seen.add(key(x)), true)));
-}
-
-function statusOf(err: unknown): number | undefined {
-	return (err as { status?: number })?.status;
-}
-
-const fmt = (list: string[]): string => `[${list.join(", ")}]`;
-
-type Label = { name: string };
-const names = (data: unknown): string[] => (Array.isArray(data) ? (data as Label[]).map((l) => l.name) : []);
-
-/**
- * The handler is the real contract: the MCP server does not validate against the
- * advertised inputSchema, so every key and type is checked here, before any request.
- */
-function validate(input: unknown) {
-	if (typeof input !== "object" || input === null || Array.isArray(input)) fail("arguments must be an object");
-	const a = input as Record<string, unknown>;
-	const unknown = Object.keys(a).filter((k) => !INPUT_KEYS.has(k));
-	if (unknown.length) fail(`unknown argument(s): ${unknown.join(", ")} — expected ${[...INPUT_KEYS].join(", ")}`);
-	if (typeof a.owner !== "string" || !a.owner.trim()) fail('"owner" must be a non-empty string');
-	if (typeof a.repo !== "string" || !a.repo.trim()) fail('"repo" must be a non-empty string');
-	if (typeof a.issue_number !== "number" || !Number.isInteger(a.issue_number) || a.issue_number <= 0) fail('"issue_number" must be a positive integer');
-	if (a.create_missing !== undefined && typeof a.create_missing !== "boolean") fail('"create_missing" must be a boolean');
-	if (a.color !== undefined && (typeof a.color !== "string" || !/^#?[0-9a-f]{6}$/i.test(a.color))) fail('"color" must be a 6-digit hex color, e.g. "ededed"');
-
-	const add = toList(a.add, "add");
-	const remove = toList(a.remove, "remove");
-	const set = a.set === undefined ? undefined : toList(a.set, "set");
-	let swapTo: string[] = [];
-	let swapPrefix: string | undefined;
-	if (a.swap !== undefined) {
-		const sw = a.swap as Record<string, unknown>;
-		if (typeof sw !== "object" || sw === null || Array.isArray(sw)) fail('"swap" must be an object { prefix, to }');
-		const extra = Object.keys(sw).filter((k) => !SWAP_KEYS.has(k));
-		if (extra.length) fail(`unknown "swap" key(s): ${extra.join(", ")} — expected prefix, to`);
-		if (typeof sw.prefix !== "string" || !sw.prefix) fail('"swap.prefix" is required');
-		if (sw.to === undefined) fail('"swap.to" needs at least one label');
-		swapPrefix = sw.prefix as string;
-		swapTo = toList(sw.to, "swap.to");
-	}
-
-	if (set !== undefined && (add.length || remove.length || swapPrefix !== undefined)) {
-		fail('"set" replaces the whole label set and cannot be combined with add/remove/swap');
-	}
-	if (set === undefined && !add.length && !remove.length && swapPrefix === undefined) fail("nothing to do — pass add, remove, swap or set");
-	const addSide = dedupe([...add, ...swapTo]);
-	if (addSide.length > MAX_LABELS) fail(`${addSide.length} labels to add — at most ${MAX_LABELS} per call`);
-	const removeKeys = new Set(remove.map(key));
-	const clash = addSide.filter((l) => removeKeys.has(key(l)));
-	if (clash.length) fail(`label(s) both added and removed: ${clash.join(", ")}`);
-
-	return {
-		owner: a.owner as string,
-		repo: a.repo as string,
-		issue_number: a.issue_number as number,
-		remove,
-		set,
-		swapPrefix,
-		addSide,
-		createMissing: a.create_missing === true,
-		color: ((a.color as string | undefined) ?? DEFAULT_COLOR).replace(/^#/, "")
-	};
-}
-
-export async function issueLabels(octokit: Octokit, input: IssueLabelsInput): Promise<IssueLabelsResult> {
-	const { owner, repo, issue_number, remove, set, swapPrefix, addSide, createMissing, color } = validate(input);
-	const issue = `${owner}/${repo}#${issue_number}`;
-	const base = { owner, repo, issue_number };
-	const readLabels = async (): Promise<string[]> =>
-		names((await octokit.request("GET /repos/{owner}/{repo}/issues/{issue_number}/labels", { ...base, per_page: MAX_LABELS })).data);
-
-	// 0. The current set: needed for swap's prefix matches, for the spelling of removals and
-	//    for reporting what changed. It also fails a wrong issue number (404) before anything
-	//    is written or created.
-	const before = await readLabels();
-	const beforeKeys = new Set(before.map(key));
-	const onIssue = (n: string): string | undefined => before.find((l) => key(l) === key(n));
-
-	// 1. Resolve every add-side label against the repo before writing anything.
-	const toResolve = set ?? addSide;
-	const resolved: string[] = [];
-	const missing: string[] = [];
-	for (const name of toResolve) {
-		try {
-			const res = await octokit.request("GET /repos/{owner}/{repo}/labels/{name}", { owner, repo, name });
-			resolved.push((res.data as Label).name);
-		} catch (err) {
-			if (statusOf(err) !== 404) throw err;
-			missing.push(name);
-		}
-	}
-	if (missing.length && !createMissing) {
-		fail(`label(s) not found in ${owner}/${repo}: ${missing.join(", ")} — nothing was changed. Check the spelling (list_label), or pass create_missing: true to create them.`);
-	}
-
-	// 2. Plan the removals: only labels actually on the issue, in the issue's own spelling.
-	//    swap removes every prefix match except a label this call also adds — that one stays
-	//    put instead of being deleted and re-added.
-	const removals: string[] = [];
-	if (set === undefined) {
-		for (const n of remove) {
-			const hit = onIssue(n);
-			if (hit) removals.push(hit);
-		}
-		if (swapPrefix !== undefined) {
-			const keep = new Set(addSide.map(key));
-			const p = key(swapPrefix);
-			for (const l of before) if (key(l).startsWith(p) && !keep.has(key(l))) removals.push(l);
-		}
-	}
-	const plannedRemovals = dedupe(removals);
-
-	// 3. Writes. Order is chosen so a failure part-way never leaves the issue with LESS than
-	//    it started with plus what was asked: create, then add (POST), and removals last.
-	//    Any failure is rethrown with exactly what was applied and what was not.
-	const created: string[] = [];
-	let addedDone = false;
-	const removed: string[] = [];
-	let latest: string[] | undefined;
-	const canonical = (): string[] => [...resolved, ...created];
-	const canon = (n: string): string => canonical().find((c) => key(c) === key(n)) ?? n;
-	try {
-		for (const name of missing) {
-			const res = await octokit.request("POST /repos/{owner}/{repo}/labels", { owner, repo, name, color });
-			created.push((res.data as Label).name);
-		}
-
-		if (set !== undefined) {
-			const res = await octokit.request("PUT /repos/{owner}/{repo}/issues/{issue_number}/labels", { ...base, labels: set.map(canon) });
-			latest = names(res.data);
-			addedDone = true;
-			return result(latest, before);
-		}
-
-		if (addSide.length) {
-			const res = await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/labels", { ...base, labels: addSide.map(canon) });
-			latest = names(res.data);
-			addedDone = true;
-		}
-
-		for (const name of plannedRemovals) {
-			try {
-				const res = await octokit.request("DELETE /repos/{owner}/{repo}/issues/{issue_number}/labels/{name}", { ...base, name });
-				latest = names(res.data);
-				removed.push(name);
-			} catch (err) {
-				// Someone removed it since the read above: already the state asked for.
-				if (statusOf(err) !== 404) throw err;
-			}
-		}
-	} catch (err) {
-		const applied: string[] = [];
-		const notApplied: string[] = [];
-		const part = (label: string, done: string[], all: string[]) => {
-			const doneKeys = new Set(done.map(key));
-			if (done.length) applied.push(`${label} ${fmt(done)}`);
-			const rest = all.filter((l) => !doneKeys.has(key(l)));
-			if (rest.length) notApplied.push(`${label} ${fmt(rest)}`);
-		};
-		part("created", created, missing);
-		if (set !== undefined) part("set", addedDone ? set : [], set);
-		else part("added", addedDone ? addSide.map(canon) : [], addSide.map(canon));
-		part("removed", removed, plannedRemovals);
-		const e = new Error(
-			`issue_labels: failed part-way on ${issue}: ${(err as Error).message}. Applied: ${applied.join("; ") || "nothing"}. Not applied: ${notApplied.join("; ") || "nothing"}.`,
-			{ cause: err }
-		);
-		(e as Error & { status?: number }).status = statusOf(err);
-		throw e;
-	}
-
-	return result(latest ?? (await readLabels()), removed);
-
-	function result(labels: string[], removedFrom: string[]): IssueLabelsResult {
-		const afterKeys = new Set(labels.map(key));
-		// Only what this call asked for — a label someone else added meanwhile isn't ours to report.
-		const requested = new Set(toResolve.map(key));
-		return {
-			issue,
-			labels,
-			added: labels.filter((l) => requested.has(key(l)) && !beforeKeys.has(key(l))),
-			removed: removedFrom.filter((l) => !afterKeys.has(key(l))),
-			created
-		};
-	}
-}
-
-const labelList = (description: string) => ({
-	description,
-	oneOf: [{ type: "string" }, { type: "array", items: { type: "string" }, minItems: 1, maxItems: MAX_LABELS }]
-});
-
-/** JSON Schema advertised to the agent for issue_labels. */
-export const ISSUE_LABELS_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "repo", "issue_number"],
-	additionalProperties: false,
-	properties: {
-		owner: { type: "string", description: "repository owner (org/user login) — selects the write credential" },
-		repo: { type: "string", description: "repository name" },
-		issue_number: { type: "number", description: "issue or pull-request number" },
-		add: labelList("label(s) to add; ones already on the issue are a no-op"),
-		remove: labelList("label(s) to remove; ones the issue doesn't have are a no-op"),
-		swap: {
-			type: "object",
-			additionalProperties: false,
-			required: ["prefix", "to"],
-			description: 'remove every current label starting with prefix, then add to — e.g. { "prefix": "status: ", "to": "status: verified" }',
-			properties: {
-				prefix: { type: "string", description: 'label-name prefix, e.g. "status: "' },
-				to: labelList("label(s) to add after the prefix matches are removed")
-			}
-		},
-		set: labelList("replace the WHOLE label set with these (at least one); cannot be combined with add/remove/swap"),
-		create_missing: {
-			type: "boolean",
-			default: false,
-			description: "create add-side labels that don't exist in the repo; without it an unknown name refuses the call and nothing changes"
-		},
-		color: { type: "string", pattern: "^#?[0-9a-fA-F]{6}$", description: `6-digit hex color (with or without #) for labels created via create_missing; default ${DEFAULT_COLOR}` }
-	}
-};

package/src/verbs/link_issue.ts

@@ -1,84 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/link_issue.ts
- *	@Date: 2026-07-07T00:24:51-07:00 (1783409091)
- *	@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 verb: link_issue — create an EXPLICIT PR→issue closing reference via the
- * `addClosingIssueReference` GraphQL mutation.
- *
- * Why a custom verb and why an App token:
- *  - The hosted GitHub MCP has no tool for PR→issue closing links (verified), so
- *    it can't be proxied — it's a direct GitHub API call.
- *  - `addClosingIssueReference` is NOT in the fine-grained-PAT GraphQL schema
- *    (GitHub returns "Field doesn't exist", distinct from a permission error). It
- *    is available to GitHub **App** tokens — exactly what CLDMV's own
- *    `sync-closing-issues` action uses. So this runs on an App-authed Octokit.
- *  - We deliberately do NOT depend on commit-message keywords for linkage.
- *
- * Uses Octokit (`octokit.graphql`) — GitHub's official SDK — not a hand-rolled fetch.
- */
-
-export interface LinkIssueInput {
-	owner: string;
-	repo: string;
-	/** pull request number */
-	pull: number;
-	/** issue number to link as a closing reference */
-	issue: number;
-}
-
-const RESOLVE_IDS = `
-	query($owner: String!, $repo: String!, $pr: Int!, $issue: Int!) {
-		repository(owner: $owner, name: $repo) {
-			pullRequest(number: $pr) { id }
-			issue(number: $issue) { id }
-		}
-	}`;
-
-const ADD_CLOSING_REF = `
-	mutation($prId: ID!, $issueId: ID!) {
-		addClosingIssueReference(input: { pullRequestId: $prId, issueId: $issueId }) {
-			pullRequest { id }
-		}
-	}`;
-
-/** Resolve node IDs, then create the closing reference. Returns the linked node IDs. */
-export async function linkIssue(octokit: Octokit, input: LinkIssueInput): Promise<{ pullRequestId: string; issueId: string }> {
-	const ids = await octokit.graphql<{
-		repository: { pullRequest: { id: string } | null; issue: { id: string } | null };
-	}>(RESOLVE_IDS, { owner: input.owner, repo: input.repo, pr: input.pull, issue: input.issue });
-
-	const pullRequestId = ids.repository.pullRequest?.id;
-	const issueId = ids.repository.issue?.id;
-	if (!pullRequestId) throw new Error(`link_issue: PR #${input.pull} not found in ${input.owner}/${input.repo}`);
-	if (!issueId) throw new Error(`link_issue: issue #${input.issue} not found in ${input.owner}/${input.repo}`);
-
-	await octokit.graphql(ADD_CLOSING_REF, { prId: pullRequestId, issueId });
-	return { pullRequestId, issueId };
-}
-
-/** JSON Schema advertised to the agent for this custom verb. */
-export const LINK_ISSUE_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "repo", "pull", "issue"],
-	additionalProperties: false,
-	properties: {
-		owner: { type: "string", description: "repository owner (org/user login)" },
-		repo: { type: "string", description: "repository name" },
-		pull: { type: "integer", description: "pull request number" },
-		issue: { type: "integer", description: "issue number to close when the PR merges to the default branch" }
-	}
-};