@theholocron/cli 5.0.0-alpha.199 → 5.0.0-alpha.200

package/dist/cli.mjs

@@ -26,6 +26,7 @@ import ora from "ora";
 import { findRootSync, isWorkspaceRoot, walkFilesSync } from "@theholocron/fs-utils";
 import { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { createServer } from "node:http";
 import { stringifyJson } from "@theholocron/json-utils";
 import { generateReadme } from "@theholocron/components-doc/markdown";
 import { getClients, getConfigs, getDocs, getPlugins, getSkills, getThemes, getUtils } from "@theholocron/registry-doc";
@@ -409,6 +410,8 @@ const COMMAND_CONTEXTS = {
 	"secrets sync": "workspace",
 	"notifications channel add": "workspace",
 	"notifications setup": "workspace",
+	"notifications link": "workspace",
+	"notifications sync-roles": "workspace",
 	"doctor notifications": "workspace",
 	deploy: "workspace",
 	"deploy cleanup-preview": "workspace",
@@ -2945,6 +2948,570 @@ async function runNotificationsChannelAdd(input) {
 		};
 	}
 }
+const localRedirectUri = (port) => `http://localhost:${port}/callback`;
+/**
+* The hosted service answers `GET <hostedUrl>/api/link` with `{ "service": "link" }`. Anything else (a 402 for
+* an exhausted plan, a 404 before the route exists, a timeout) means it cannot serve sign-in now.
+*/
+async function resolveCallback(input) {
+	const port = input.port ?? 53682;
+	const local = (reason) => ({
+		kind: "local",
+		redirectUri: localRedirectUri(port),
+		reason
+	});
+	if (!input.hostedUrl) return local("no hosted URL is configured (`layout.links.hostedUrl`)");
+	let base = input.hostedUrl;
+	while (base.endsWith("/")) base = base.slice(0, -1);
+	try {
+		const res = await (input.fetch ?? fetch)(`${base}/api/link`, {
+			headers: { accept: "application/json" },
+			signal: AbortSignal.timeout(input.timeoutMs ?? 5e3)
+		});
+		if (res.status === 402) return local(`${base} answered 402 (the plan's quota is used up)`);
+		if (!res.ok) return local(`${base}/api/link answered ${res.status}`);
+		if ((await res.json().catch(() => ({}))).service !== "link") return local(`${base}/api/link is not the link service`);
+		return {
+			kind: "hosted",
+			redirectUri: `${base}/api/link/callback`,
+			reason: `${base} serves sign-in`
+		};
+	} catch {
+		return local(`${base} did not answer`);
+	}
+}
+/** The portal step, worded for whichever redirect is wanted, for `link` and the doctor to show. */
+function redirectInstruction(redirectUri) {
+	return `add ${redirectUri} under OAuth2 → Redirects in the Discord developer portal (the API does not allow setting it)`;
+}
+//#endregion
+//#region src/commands/notifications-link/listener.ts
+const PAGE = (title, body) => `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font:16px system-ui;margin:3rem auto;max-width:32rem"><h1>${title}</h1><p>${body}</p>`;
+/**
+* Listens once on this machine for the browser coming back from the provider, and resolves with the `code` it
+* carries. It accepts nothing but a `/callback` whose `state` is the one that was handed out, answers every
+* other request with 404, stops after the first good answer, and gives up after `timeoutMs`.
+* Bound to the loopback address only, so nothing else on the network can reach it.
+*/
+function waitForCode(input) {
+	return new Promise((resolve, reject) => {
+		let done = false;
+		const finish = (fn) => {
+			/* v8 ignore next -- a second event after the first has settled; the guard keeps it harmless */
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			server.close();
+			server.closeAllConnections();
+			fn();
+		};
+		const server = createServer((req, res) => {
+			/* v8 ignore next -- a server request always has a url */
+			const url = new URL(req.url ?? "/", "http://localhost");
+			if (req.method !== "GET" || url.pathname !== "/callback") {
+				res.writeHead(404).end();
+				return;
+			}
+			const reply = (status, title, body) => {
+				res.writeHead(status, { "content-type": "text/html; charset=utf-8" }).end(PAGE(title, body));
+			};
+			if (url.searchParams.get("state") !== input.state) {
+				reply(400, "Wrong sign-in", "This link does not belong to the running command. Start it again.");
+				return;
+			}
+			const error = url.searchParams.get("error");
+			const code = url.searchParams.get("code");
+			if (error || !code) {
+				reply(400, "Sign-in was not approved", "You can close this window.");
+				finish(() => reject(/* @__PURE__ */ new Error(`the sign-in was not approved (${error ?? "no code returned"})`)));
+				return;
+			}
+			reply(200, "You are signed in", "You can close this window and go back to the terminal.");
+			finish(() => resolve(code));
+		});
+		const timer = setTimeout(() => finish(() => reject(/* @__PURE__ */ new Error("timed out waiting for the sign-in to come back"))), input.timeoutMs ?? 3e5);
+		server.once("error", (err) => finish(() => reject(err.code === "EADDRINUSE" ? /* @__PURE__ */ new Error(`port ${input.port} is already in use; stop what is using it or set \`layout.links.localPort\``) : /* v8 ignore start -- an error other than the port being taken cannot be provoked in a test */ err)));
+		server.listen(input.port, "127.0.0.1", () => {
+			const address = server.address();
+			/* v8 ignore next -- a bound TCP server always reports an address object */
+			input.onListening?.(typeof address === "object" && address ? address.port : input.port);
+		});
+	});
+}
+//#endregion
+//#region src/commands/notifications-sync-roles/links.ts
+const EMPTY_LINKS = {
+	version: 1,
+	links: []
+};
+const DIGITS = /^\d{1,20}$/;
+/** Reads the file's text. Throws with a plain reason on anything that is not a links file, so a damaged one is never treated as empty. */
+function parseLinks(text) {
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		throw new Error("the links file is not valid JSON");
+	}
+	const file = raw;
+	if (file.version !== 1) throw new Error(`the links file has version ${JSON.stringify(file.version)}; expected 1`);
+	if (!Array.isArray(file.links)) throw new Error("the links file has no `links` list");
+	const links = file.links.map((entry, i) => {
+		const e = entry;
+		if (typeof e.github !== "string" || !DIGITS.test(e.github)) throw new Error(`links[${i}]: \`github\` must be a numeric user id string`);
+		if (typeof e.member !== "string" || !DIGITS.test(e.member)) throw new Error(`links[${i}]: \`member\` must be a numeric id string`);
+		if (typeof e.login !== "string") throw new Error(`links[${i}]: \`login\` must be a string`);
+		return {
+			github: e.github,
+			login: e.login,
+			member: e.member
+		};
+	});
+	for (const key of ["github", "member"]) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const [i, link] of links.entries()) {
+			if (seen.has(link[key])) throw new Error(`links[${i}]: \`${key}\` ${link[key]} appears more than once`);
+			seen.add(link[key]);
+		}
+	}
+	return {
+		version: 1,
+		links
+	};
+}
+/** Stable text: sorted by GitHub id, two-space JSON, one trailing newline, so a change is a clean diff. */
+function serializeLinks(file) {
+	const links = [...file.links].sort((a, b) => BigInt(a.github) < BigInt(b.github) ? -1 : 1);
+	return `${JSON.stringify({
+		version: 1,
+		links
+	}, null, 2)}\n`;
+}
+/**
+* Records that `link.github` and `link.member` are the same person. A GitHub account has one member and a
+* member one GitHub account, so any earlier entry for either is replaced. `changed` is false when the file
+* already said exactly this.
+*/
+function upsertLink(file, link) {
+	const next = {
+		version: 1,
+		links: [...file.links.filter((l) => l.github !== link.github && l.member !== link.member), link]
+	};
+	return {
+		file: next,
+		changed: serializeLinks(next) !== serializeLinks(file)
+	};
+}
+/** Where the links file is: the layout's `links`, else `<org>/.github-private` and `notifications/<provider>-links.json`. */
+function linksLocation(layout, org, provider) {
+	const repo = layout.links?.repo ?? (org ? `${org}/.github-private` : void 0);
+	if (!repo) throw new Error("no org to find the links file under — set `layout.links.repo` or `org` in holocron.config.ts");
+	return {
+		repo,
+		path: layout.links?.path ?? `notifications/${provider.toLowerCase()}-links.json`
+	};
+}
+//#endregion
+//#region src/commands/notifications-sync-roles/plan.ts
+/**
+* What it takes to make a role's holders equal a team, given who is linked to whom. Pure: it decides, the
+* caller acts. A holder is removed only when a link says they are a person who left the team; a holder
+* nobody has linked is reported, never removed, so an empty or missing links file cannot strip the role from
+* everyone.
+*/
+function planRoleSync(input) {
+	const byGithub = new Map(input.links.map((l) => [l.github, l]));
+	const byMember = new Map(input.links.map((l) => [l.member, l]));
+	const onTeam = new Set(input.team.map((m) => m.id));
+	const holding = new Set(input.holders.map((h) => h.id));
+	const plan = {
+		add: [],
+		remove: [],
+		unlinked: [],
+		unknownHolders: [],
+		inSync: 0
+	};
+	for (const person of input.team) {
+		const link = byGithub.get(person.id);
+		if (!link) plan.unlinked.push(person);
+		else if (holding.has(link.member)) plan.inSync++;
+		else plan.add.push({
+			member: link.member,
+			login: person.login
+		});
+	}
+	for (const holder of input.holders) {
+		const link = byMember.get(holder.id);
+		if (!link) plan.unknownHolders.push({
+			member: holder.id,
+			...holder.name ? { name: holder.name } : {}
+		});
+		else if (!onTeam.has(link.github)) plan.remove.push({
+			member: holder.id,
+			login: link.login
+		});
+	}
+	return plan;
+}
+/**
+* The first role the layout declares for two different teams, or undefined. Names compare ignoring case, as
+* the server does; the role would be synced against one team and then the other, so the last would win.
+*/
+function roleTeamProblem(layout) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const role of layout.roles ?? []) {
+		if (!role.team) continue;
+		const key = role.name.toLowerCase();
+		const earlier = seen.get(key);
+		if (earlier !== void 0 && earlier.toLowerCase() !== role.team.toLowerCase()) return `role \`${role.name}\` is declared for two teams (\`${earlier}\` and \`${role.team}\`); a role follows one team`;
+		seen.set(key, role.team);
+	}
+}
+//#endregion
+//#region src/commands/notifications-sync-roles/notifications-sync-roles.ts
+/**
+* `holocron notifications sync-roles` — make who holds a server role match a team.
+*
+* A role that declares `team` in the layout is kept equal to that team of the `source` provider (for GitHub,
+* a team in the org). A team member is matched to a server member through the links file, so only people who
+* have linked their account can be given the role; the rest are listed. The role is taken from a linked
+* person who has left the team, but never from someone nobody has linked: an empty or missing links file
+* cannot strip the role from everyone.
+*
+* Idempotent and safe to re-run. `--dry-run` previews it.
+*/
+/** The provider that can list and change who holds a role. */
+function pickRoleManager(providers, wanted, keep = false) {
+	return pickProvider(providers, wanted, (p) => typeof p.roleMembers === "function" && typeof p.addRoleMember === "function" && (keep || typeof p.removeRoleMember === "function"), {
+		infinitive: "manage role members",
+		gerund: "managing role members"
+	});
+}
+/** What a source provider needs to be able to do to feed a role sync, or the reason it cannot. */
+function sourceProblem(source) {
+	if (!source) return "no `source` provider is available to read the team and the links file";
+	if (!source.teamMembers) return `the \`${source.providerName}\` provider cannot list team members`;
+	if (!source.readFile) return `the \`${source.providerName}\` provider cannot read the links file`;
+}
+/** Reads the links file; a file that does not exist yet is an empty one, a damaged one throws. */
+async function readLinks(source, layout, org, provider) {
+	const { repo, path } = linksLocation(layout, org, provider);
+	const file = await source.readFile(path, repo);
+	if (!file) return EMPTY_LINKS;
+	try {
+		return parseLinks(file.content);
+	} catch (err) {
+		throw new Error(`${repo}/${path}: ${errorMessage(err)}`, { cause: err });
+	}
+}
+/** Reads the team, the links and the role's holders, and works out what has to change. */
+async function planForRole(args) {
+	const [team, holders] = await Promise.all([args.source.teamMembers(args.team, args.org), args.notifications.roleMembers(args.role)]);
+	return planRoleSync({
+		team,
+		links: args.links.links,
+		holders
+	});
+}
+async function runNotificationsSyncRoles(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "notifications sync-roles");
+	const dryRun = input.context.dryRun ?? false;
+	const report = {
+		status: "ok",
+		roles: [],
+		failures: []
+	};
+	const refuse = (message, reason = message) => {
+		print(`  ${style.fail(message)}`);
+		print("");
+		print(style.header("0 ok, 1 fail, 0 skipped"));
+		logger.warn({ reason }, "notifications sync-roles");
+		return {
+			...report,
+			status: "fail",
+			message
+		};
+	};
+	let notifications;
+	try {
+		notifications = pickRoleManager(notificationProviders(loader), input.provider, input.keep);
+	} catch (err) {
+		return refuse(errorMessage(err));
+	}
+	const layout = notifications.layout;
+	const roles = (layout?.roles ?? []).filter((r) => r.team);
+	if (!layout || roles.length === 0) return refuse(`no role in the \`${notifications.providerName}\` layout declares a \`team\` — add \`team: "<slug>"\` to a role in holocron.config.ts`);
+	const conflict = roleTeamProblem(layout);
+	if (conflict) return refuse(conflict);
+	const source = loader.has("source") ? loader.get("source") : void 0;
+	const problem = sourceProblem(source);
+	if (problem) return refuse(loader.has("source") ? problem : whyMissing(loader, "source", problem));
+	let links;
+	try {
+		links = await readLinks(source, layout, input.context.org, notifications.providerName);
+	} catch (err) {
+		return refuse(describeProviderError(err), logReason(err));
+	}
+	if (links.links.length === 0) print(`  ${style.skip("no links yet: nobody can be given a role until they link their account")}`);
+	const tally = {
+		ok: 0,
+		skip: 0
+	};
+	for (const role of roles) {
+		print(`\n${style.header(`${role.name} ← team ${role.team}`)}`);
+		const step = `role ${role.name}`;
+		let plan;
+		try {
+			plan = await planForRole({
+				notifications,
+				source,
+				role: role.name,
+				team: role.team,
+				...input.context.org ? { org: input.context.org } : {},
+				links
+			});
+		} catch (err) {
+			const message = describeProviderError(err);
+			print(`  ${style.fail(`${step}: ${message}`)}`);
+			report.failures.push({
+				step,
+				message
+			});
+			continue;
+		}
+		const outcome = {
+			role: role.name,
+			team: role.team,
+			plan,
+			added: [],
+			removed: []
+		};
+		report.roles.push(outcome);
+		tally.skip += plan.inSync;
+		if (plan.inSync > 0) print(`  ${style.skip(`${plan.inSync} already have it`)}`);
+		const act = async (verb, who) => {
+			const label = `${verb === "add" ? "gave" : "took"} ${role.name} ${verb === "add" ? "to" : "from"} ${who.login} (${who.member})`;
+			if (dryRun || verb === "remove" && input.keep) {
+				print(`  ${style.skip(`would ${verb === "add" ? "give" : "take"} ${role.name} ${verb === "add" ? "to" : "from"} ${who.login} (${who.member})${input.keep && verb === "remove" ? " (kept: --keep)" : ""}`)}`);
+				tally.skip++;
+				return;
+			}
+			try {
+				if (verb === "add") await notifications.addRoleMember(role.name, who.member);
+				else await notifications.removeRoleMember(role.name, who.member);
+				(verb === "add" ? outcome.added : outcome.removed).push(who.member);
+				print(`  ${style.success(label)}`);
+				tally.ok++;
+			} catch (err) {
+				const message = describeProviderError(err);
+				print(`  ${style.fail(`${step}: ${verb} ${who.login}: ${message}`)}`);
+				report.failures.push({
+					step: `${step} ${verb} ${who.login}`,
+					message
+				});
+			}
+		};
+		for (const who of plan.add) await act("add", who);
+		for (const who of plan.remove) await act("remove", who);
+		for (const person of plan.unlinked) {
+			print(`  ${style.skip(`${person.login} is on the team but has not linked their account`)}`);
+			tally.skip++;
+		}
+		for (const holder of plan.unknownHolders) {
+			print(`  ${style.skip(`${holder.name ?? holder.member} holds ${role.name} but is not linked to anyone: left alone`)}`);
+			tally.skip++;
+		}
+	}
+	if (report.failures.length > 0) report.status = "fail";
+	else if (dryRun) report.status = "dry-run";
+	print("");
+	print(style.header(`${tally.ok} ok, ${report.failures.length} fail, ${tally.skip} skipped`));
+	logger.info({
+		provider: notifications.providerName,
+		roles: report.roles.length,
+		failures: report.failures.length,
+		status: report.status
+	}, "notifications sync-roles");
+	return report;
+}
+//#endregion
+//#region src/commands/notifications-link/notifications-link.ts
+/**
+* `holocron notifications link` — record which server member is which GitHub account, by having the member
+* sign in with the provider. The provider reports the GitHub account it has verified they own, so a link
+* cannot be claimed for someone else's account. Writes the links file `sync-roles` reads.
+*
+* Signs in on this machine (a one-shot listener on localhost) unless the hosted service (Sentinel) answers
+* its health route, in which case it points you there. Nothing but the two public ids is stored; the token
+* the provider hands over is discarded as soon as it has been read.
+*/
+/* v8 ignore start -- hands a URL to the operating system's browser, which a test must not do */
+/** Opens a URL in the system browser; resolves once it has been handed over. */
+async function openInBrowser(url) {
+	const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]] : ["xdg-open", [url]];
+	await new Promise((resolve, reject) => {
+		const child = spawn(cmd, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.once("error", reject);
+		child.once("spawn", () => {
+			child.unref();
+			resolve();
+		});
+	});
+}
+/* v8 ignore stop */
+async function runNotificationsLink(input) {
+	/* v8 ignore start -- the real console and logger are only used outside tests, which inject both */
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	/* v8 ignore stop */
+	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "notifications link");
+	const dryRun = input.context.dryRun ?? false;
+	const refuse = (message, reason = message) => {
+		print(`  ${style.fail(message)}`);
+		print("");
+		print(style.header("0 ok, 1 fail, 0 skipped"));
+		logger.warn({ reason }, "notifications link");
+		return {
+			status: "fail",
+			message
+		};
+	};
+	let notifications;
+	try {
+		notifications = pickProvider(notificationProviders(loader), input.provider, (p) => typeof p.signIn === "function", {
+			infinitive: "sign members in",
+			gerund: "signing members in"
+		});
+	} catch (err) {
+		return refuse(errorMessage(err));
+	}
+	const layout = notifications.layout ?? {};
+	const source = loader.has("source") ? loader.get("source") : void 0;
+	if (!source?.readFile || !source.writeFile) return refuse(whyMissing(loader, "source", "no `source` provider that can read and write files is available for the links file"));
+	let location;
+	try {
+		location = linksLocation(layout, input.context.org, notifications.providerName);
+	} catch (err) {
+		return refuse(errorMessage(err));
+	}
+	const port = layout.links?.localPort ?? 53682;
+	const choice = await resolveCallback({
+		...layout.links?.hostedUrl ? { hostedUrl: layout.links.hostedUrl } : {},
+		port,
+		/* v8 ignore next -- the real fetch is only used outside tests, which inject one */
+		...input.fetch ? { fetch: input.fetch } : {}
+	});
+	print(`  ${style.skip(`sign-in ${choice.kind === "hosted" ? "is hosted" : "runs on this machine"}: ${choice.reason}`)}`);
+	if (choice.kind === "hosted") {
+		print(`  open ${`${choice.redirectUri.replace(/\/callback$/, "")}/start`} in a browser to link your account`);
+		print("");
+		print(style.header("0 ok, 0 fail, 1 skipped"));
+		return {
+			status: "ok",
+			via: "hosted"
+		};
+	}
+	if (dryRun) {
+		print(`  ${style.skip(`would sign in on ${choice.redirectUri} and write the link to ${location.repo}/${location.path}`)}`);
+		print(`  ${style.skip(`first, ${redirectInstruction(choice.redirectUri)}`)}`);
+		print("");
+		print(style.header("0 ok, 0 fail, 1 skipped"));
+		return {
+			status: "dry-run",
+			via: "local"
+		};
+	}
+	const signIn = notifications.signIn();
+	/* v8 ignore next -- tests inject a fixed state */
+	const state = (input.newState ?? (() => randomBytes(16).toString("hex")))();
+	try {
+		/* v8 ignore next 3 -- the real listener and browser are only used outside tests, which inject both */
+		const wait = input.waitForCode ?? ((i) => waitForCode({
+			port: i.port,
+			state: i.state,
+			onListening: i.onListening
+		}));
+		/* v8 ignore next -- see above */
+		const open = input.openBrowser ?? openInBrowser;
+		const url = await signIn.authorizeUrl({
+			redirectUri: choice.redirectUri,
+			state
+		});
+		print(`  if your browser does not open, go to: ${url}`);
+		print(`  (it must be allowed to come back to ${choice.redirectUri}: ${redirectInstruction(choice.redirectUri)})`);
+		const code = await wait({
+			port,
+			state,
+			onListening: () => void open(url).catch(() => print(`  ${style.skip("could not open a browser; use the link above")}`))
+		});
+		const who = await signIn.complete({
+			redirectUri: choice.redirectUri,
+			code
+		});
+		if (!who.github) return refuse(`${who.name ?? who.member} has no verified GitHub account on ${notifications.providerName}: connect GitHub under User Settings → Connections, then run this again`);
+		let outcome = { changed: false };
+		for (let attempt = 0; attempt < 2; attempt++) {
+			const file = await source.readFile(location.path, location.repo);
+			const next = upsertLink(file ? await readLinks(source, layout, input.context.org, notifications.providerName) : {
+				version: 1,
+				links: []
+			}, {
+				github: who.github.id,
+				login: who.github.login,
+				member: who.member
+			});
+			outcome = { changed: next.changed };
+			if (!next.changed) break;
+			try {
+				await source.writeFile(location.path, serializeLinks(next.file), {
+					message: `chore(notifications): link ${who.github.login} to ${notifications.providerName} member ${who.member}`,
+					...file ? { version: file.version } : {},
+					repo: location.repo
+				});
+				break;
+			} catch (err) {
+				const status = err.status;
+				if (attempt === 0 && (status === 409 || status === 422)) continue;
+				throw err;
+			}
+		}
+		print(`  ${style.success(`${outcome.changed ? "linked" : "already linked"} ${who.github.login} (github ${who.github.id}) to ${who.name ?? who.member} (${who.member})`)}`);
+		print("");
+		print(style.header(`${outcome.changed ? 1 : 0} ok, 0 fail, ${outcome.changed ? 0 : 1} skipped`));
+		logger.info({
+			provider: notifications.providerName,
+			changed: outcome.changed
+		}, "notifications link");
+		return {
+			status: "ok",
+			via: "local",
+			linked: {
+				github: who.github.id,
+				login: who.github.login,
+				member: who.member,
+				changed: outcome.changed
+			}
+		};
+	} catch (err) {
+		return refuse(describeProviderError(err), logReason(err));
+	}
+}
 //#endregion
 //#region src/commands/doctor-notifications/doctor-notifications.ts
 /**
@@ -2959,23 +3526,15 @@ async function runNotificationsChannelAdd(input) {
 * is {@link PLANNED_CHECKS}; the numbers match the table in holocron#1098.
 */
 /** Features not built yet, in the order of the table in holocron#1098. Move an entry into a real check when it lands. */
-const PLANNED_CHECKS = [
-	{
-		step: 14,
-		id: "role-assignment",
-		title: "role assigned to team members"
-	},
-	{
-		step: 15,
-		id: "post-works",
-		title: "test post reached every channel (platform.notifyCheck)"
-	},
-	{
-		step: 16,
-		id: "server-creation",
-		title: "server created from config"
-	}
-];
+const PLANNED_CHECKS = [{
+	step: 15,
+	id: "post-works",
+	title: "test post reached every channel (platform.notifyCheck)"
+}, {
+	step: 16,
+	id: "server-creation",
+	title: "server created from config"
+}];
 const same = (a, b) => a.toLowerCase() === b.toLowerCase();
 /** `everyone`, or the roles sorted and lower-cased, so order and case do not matter when comparing. */
 const accessKey = (v) => v === "everyone" ? "everyone" : JSON.stringify([...new Set(v.map((r) => r.toLowerCase()))].sort());
@@ -2999,6 +3558,7 @@ const AVATAR_TITLE = "webhook names and avatars set";
 const SERVER_TITLE = "server verification, notifications and community set";
 const ACCESS_TITLE = "channel and category access set";
 const ROLE_APPEARANCE_TITLE = "role colour, hoist and permissions set";
+const ROLE_MEMBERS_TITLE = "role assigned to team members";
 const SECRETS_TITLE = "webhook URLs and role id stored as secrets";
 async function runDoctorNotifications(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -3337,6 +3897,14 @@ async function runDoctorNotifications(input) {
 				const exact = (list) => JSON.stringify([...new Set(list)].sort());
 				if (wantApp.description !== void 0 && (have.description ?? "") !== wantApp.description) appProblems.push("description differs from the layout");
 				if (wantApp.tags !== void 0 && set(have.tags ?? []) !== set(wantApp.tags)) appProblems.push(`tags are ${(have.tags ?? []).map(shown).join(", ") || "none"} but the layout says ${wantApp.tags.map(shown).join(", ") || "none"}`);
+				if (wantApp.intents?.members !== void 0 && (have.intents?.members ?? false) !== wantApp.intents.members) appProblems.push(`the Server Members Intent is ${have.intents?.members ? "on" : "off"} but the layout says ${wantApp.intents.members ? "on" : "off"} (\`holocron notifications setup\` changes it)`);
+				const needsLink = (layout.roles ?? []).some((r) => r.team);
+				const wantRedirects = wantApp.redirectUris ?? (needsLink ? [(await resolveCallback({
+					...layout.links?.hostedUrl ? { hostedUrl: layout.links.hostedUrl } : {},
+					...layout.links?.localPort ? { port: layout.links.localPort } : {},
+					...input.fetch ? { fetch: input.fetch } : {}
+				})).redirectUri] : []);
+				for (const uri of wantRedirects) if (!(have.redirectUris ?? []).includes(uri)) appProblems.push(shown(redirectInstruction(uri)));
 				if (wantApp.install !== void 0) {
 					if (!have.install) appProblems.push("no install link is set");
 					else {
@@ -3380,6 +3948,41 @@ async function runDoctorNotifications(input) {
 			failed("secrets", SECRETS_TITLE, describeProviderError(err));
 		}
 	}
+	const teamRoles = (layout.roles ?? []).filter((r) => r.team);
+	const blankTeams = (layout.roles ?? []).filter((r) => r.team !== void 0 && r.team.trim() === "");
+	if (blankTeams.length > 0) failed("role-members", ROLE_MEMBERS_TITLE, shown(`${blankTeams.map((r) => r.name).join(", ")}: declares an empty \`team\`; name a team or remove the field`));
+	else if (teamRoles.length === 0) checks.push({
+		id: "role-members",
+		title: ROLE_MEMBERS_TITLE,
+		status: "pass",
+		detail: "none declared",
+		problems: []
+	});
+	else {
+		const source = loader.has("source") ? loader.get("source") : void 0;
+		const problem = !notifications.roleMembers ? `the \`${notifications.providerName}\` provider cannot list who holds a role` : sourceProblem(source);
+		if (problem) failed("role-members", ROLE_MEMBERS_TITLE, shown(loader.has("source") ? problem : whyMissing(loader, "source", problem)));
+		else try {
+			const links = await readLinks(source, layout, input.context.org, notifications.providerName);
+			const problems = [];
+			for (const role of teamRoles) {
+				const plan = await planForRole({
+					notifications,
+					source,
+					role: role.name,
+					team: role.team,
+					...input.context.org ? { org: input.context.org } : {},
+					links
+				});
+				for (const who of plan.add) problems.push(`${shown(who.login)}: on team ${shown(role.team)} but lacks ${shown(role.name)}`);
+				for (const who of plan.remove) problems.push(`${shown(who.login)}: holds ${shown(role.name)} but left team ${shown(role.team)}`);
+				for (const who of plan.unlinked) problems.push(`${shown(who.login)}: on team ${shown(role.team)} but has not linked their account`);
+			}
+			add("role-members", ROLE_MEMBERS_TITLE, problems, `${teamRoles.length} of ${teamRoles.length} in sync`);
+		} catch (err) {
+			failed("role-members", ROLE_MEMBERS_TITLE, shown(describeProviderError(err)));
+		}
+	}
 	if (!input.builtOnly) for (const planned of PLANNED_CHECKS) checks.push({
 		id: planned.id,
 		title: planned.title,
@@ -4071,6 +4674,10 @@ function serverLayoutProblem(layout) {
 		if (count === 0) return `${where} names the channel \`${name}\`, which is not in the layout's channels`;
 		if (count > 1) return `${where} names \`${name}\`, but more than one channel in the layout has that name`;
 	};
+	const roleTeams = roleTeamProblem(layout);
+	if (roleTeams) return roleTeams;
+	const emptyTeam = (layout.roles ?? []).find((r) => r.team !== void 0 && r.team.trim() === "");
+	if (emptyTeam) return `role \`${emptyTeam.name}\` has an empty \`team\``;
 	const everyone = layout.everyone;
 	const both = (everyone?.allow ?? []).find((p) => (everyone?.deny ?? []).some((d) => d.toLowerCase() === p.toLowerCase()));
 	if (both !== void 0) return `everyone: \`${both}\` is in both \`allow\` and \`deny\``;
@@ -4308,6 +4915,13 @@ async function runNotificationsSetup(input) {
 				const changed = result.updated.length > 0;
 				print(`  ${(changed ? style.success : style.skip)(`${changed ? "updated" : "exists "} ${label}${changed ? `: ${result.updated.join(", ")}` : ""}`)}`);
 				made(changed);
+				for (const todo of result.todo ?? []) {
+					print(`  ${style.fail(`${label}: ${todo}`)}`);
+					report.failures.push({
+						step: label,
+						message: todo
+					});
+				}
 			});
 		};
 		await apply("@everyone permissions", !!layout.everyone, () => notifications.ensureEveryone(layout.everyone));
@@ -10478,6 +11092,36 @@ const COMMAND_REGISTRY = [
 		positionals: [],
 		supportsDryRun: true
 	},
+	{
+		name: "notifications link",
+		description: "Link your server account to your GitHub account by signing in with the provider",
+		positionals: [],
+		options: [{
+			key: "provider",
+			flag: "--provider",
+			type: "input",
+			message: "Which notifications provider (blank = the only one that can sign members in):"
+		}],
+		supportsDryRun: true
+	},
+	{
+		name: "notifications sync-roles",
+		description: "Make who holds a server role match a team, through the links file",
+		positionals: [],
+		options: [{
+			key: "provider",
+			flag: "--provider",
+			type: "input",
+			message: "Which notifications provider (blank = the only one that can manage roles):"
+		}, {
+			key: "keep",
+			flag: "--keep",
+			type: "confirm",
+			default: false,
+			message: "Keep the role on linked people who left the team (only add, never remove)?"
+		}],
+		supportsDryRun: true
+	},
 	{
 		name: "deploy",
 		description: "Trigger a deployment via the configured `deployment` capability",
@@ -12056,6 +12700,47 @@ try {
 			...argv.scope ? { scope: parseScope(argv.scope) } : {},
 			...argv.provider ? { provider: argv.provider } : {}
 		})).status === "fail") process.exitCode = 1;
+	}).command("link", "Link your server account to your GitHub account by signing in with the provider", (y) => y.option("provider", {
+		type: "string",
+		describe: "Which notifications provider, when several can sign members in"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runNotificationsLink({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			...argv.provider ? { provider: argv.provider } : {}
+		})).status === "fail") process.exitCode = 1;
+	}).command("sync-roles", "Make who holds a server role match a team, through the links file", (y) => y.option("provider", {
+		type: "string",
+		describe: "Which notifications provider, when several can manage roles"
+	}).option("keep", {
+		type: "boolean",
+		default: false,
+		describe: "Give the role to new team members but do not take it from people who left"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runNotificationsSyncRoles({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			...argv.provider ? { provider: argv.provider } : {},
+			keep: argv.keep
+		})).status === "fail") process.exitCode = 1;
 	}).command("$0", false, () => {}, async (argv) => {
 		await launchGroupMenu("notifications", argv);
 	}), () => {}).command("sync", "Sync generated files to other repos", (g) => g.command("github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {