@theholocron/holocron-plugin-github 5.0.0-alpha.43 → 5.0.0-alpha.430

package/dist/index.mjs

@@ -1,48 +1,74 @@
 import { createRequire } from "node:module";
+import { AuthError, MissingTokenError, ProviderApiError, connectionProbe, createFeatureResolver, pickByCreation, readKeysLimited, reportProgress } from "@theholocron/cli";
 import { createGitHubClient, createGitHubClient as createGitHubClient$1 } from "@theholocron/github-client";
-import { AuthError, createFeatureResolver } from "@theholocron/cli";
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-//#region src/auth.ts
+import { findRootSync } from "@theholocron/fs-utils";
+import { ProviderApiError as ProviderApiError$1 } from "@theholocron/http-client";
+import { errorMessage } from "@theholocron/misc-utils";
+// src/auth.ts
+/** Resolves the token for read-only GitHub access (`HOLOCRON_READ_TOKEN`, keyring key `github.read`). */
 const resolveReadToken = createFeatureResolver({
 	envName: "HOLOCRON_READ_TOKEN",
 	keyringKey: "github.read"
 });
+/** Resolves the token for issue operations (`HOLOCRON_ISSUES_TOKEN`, keyring key `github.issues`). */
 const resolveIssuesToken = createFeatureResolver({
 	envName: "HOLOCRON_ISSUES_TOKEN",
 	keyringKey: "github.issues"
 });
+/** Resolves the token for syncing repo files and settings (`HOLOCRON_SYNC_TOKEN`, keyring key `github.sync`). */
 const resolveSyncToken = createFeatureResolver({
 	envName: "HOLOCRON_SYNC_TOKEN",
 	keyringKey: "github.sync"
 });
+/** Resolves the token for release operations (`HOLOCRON_RELEASE_TOKEN`, keyring key `github.release`). */
 const resolveReleaseToken = createFeatureResolver({
 	envName: "HOLOCRON_RELEASE_TOKEN",
 	keyringKey: "github.release"
 });
+/** Resolves the repo-scoped admin token (`HOLOCRON_ADMIN_TOKEN`, keyring key `github.admin`). */
 const resolveAdminToken = createFeatureResolver({
 	envName: "HOLOCRON_ADMIN_TOKEN",
 	keyringKey: "github.admin"
 });
+/** Resolves the org-level secrets token (`HOLOCRON_SECRETS_TOKEN`, keyring key `github.secrets`). */
+const resolveSecretsToken = createFeatureResolver({
+	envName: "HOLOCRON_SECRETS_TOKEN",
+	keyringKey: "github.secrets"
+});
+/** Resolves the token for deployment operations (`HOLOCRON_DEPLOY_TOKEN`, keyring key `github.deploy`). */
 const resolveDeployToken = createFeatureResolver({
 	envName: "HOLOCRON_DEPLOY_TOKEN",
 	keyringKey: "github.deploy"
 });
+/**
+* Resolves the token for the user-sync files in the org's private config repo (`HOLOCRON_USER_SYNC_TOKEN`, keyring
+* key `github.user-sync`).
+*/
+const resolveUserSyncToken = createFeatureResolver({
+	envName: "HOLOCRON_USER_SYNC_TOKEN",
+	keyringKey: "github.user-sync"
+});
+/** Resolves the org-level token (`HOLOCRON_ORG_TOKEN`, keyring key `github.org`). */
 const resolveOrgToken = createFeatureResolver({
 	envName: "HOLOCRON_ORG_TOKEN",
 	keyringKey: "github.org"
 });
-//#endregion
-//#region src/capabilities/ci.ts
+// src/capabilities/ci.ts
+/** The GitHub implementation of the `ci` capability, backed by GitHub Actions workflow runs. */
 var GitHubCi = class {
 	client;
 	opts;
+	/** Capability key, always `"ci"`. */
 	key = "ci";
+	/** Provider name, always `"github"`. */
 	providerName = "github";
 	constructor(client, opts) {
 		this.client = client;
 		this.opts = opts;
 	}
+	/** Lists workflow runs for the repo, optionally filtered by branch, status and limit. */
 	async listRuns(filter) {
 		return (await this.client.workflows.listRuns(this.opts.repo, {
 			branch: filter?.branch,
@@ -50,6 +76,7 @@ var GitHubCi = class {
 			status: filter?.status
 		})).map((r) => this.mapRun(r));
 	}
+	/** Fetches one workflow run by id. */
 	async getRun(id) {
 		const raw = await this.client.workflows.getRun(this.opts.repo, id);
 		return this.mapRun(raw);
@@ -77,17 +104,20 @@ var GitHubCi = class {
 		}
 	}
 };
-//#endregion
-//#region src/capabilities/environments.ts
+// src/capabilities/environments.ts
+/** The GitHub implementation of the `environments` capability, managing a repo's deployment environments. */
 var GitHubEnvironments = class {
 	client;
 	opts;
+	/** Capability key, always `"environments"`. */
 	key = "environments";
+	/** Provider name, always `"github"`. */
 	providerName = "github";
 	constructor(client, opts) {
 		this.client = client;
 		this.opts = opts;
 	}
+	/** Lists the repo's environments with their wait timer, self-review rule and required reviewers. */
 	async listEnvironments() {
 		return (await this.client.environments.listEnvironments(this.opts.repo)).map((e) => ({
 			name: e.name,
@@ -96,6 +126,7 @@ var GitHubEnvironments = class {
 			reviewers: this.flattenReviewers(e.protection_rules)
 		}));
 	}
+	/** Creates or updates an environment, sending only the settings the given environment defines. */
 	async upsertEnvironment(env) {
 		const body = {};
 		if (env.waitTimer !== void 0) body.wait_timer = env.waitTimer;
@@ -106,6 +137,7 @@ var GitHubEnvironments = class {
 		}));
 		await this.client.environments.upsertEnvironment(this.opts.repo, env.name, body);
 	}
+	/** Deletes the named environment. */
 	async deleteEnvironment(name) {
 		await this.client.environments.deleteEnvironment(this.opts.repo, name);
 	}
@@ -119,11 +151,348 @@ var GitHubEnvironments = class {
 		}));
 	}
 };
-//#endregion
-//#region src/capabilities/issues.ts
+// src/capabilities/issues-migration.ts
+/**
+* Export and import of GitHub issues for `holocron migrate`.
+*
+* GitHub holds less than a planning tool, so what does not fit is named in each result's `dropped` list rather than
+* lost quietly:
+*  - priority is a label (`priority: high`), because on GitHub it lives in a project field, not on the issue;
+*  - an import cannot backdate an issue or a comment, and cannot post as someone else, so the original date and
+*    author go in the text;
+*  - an import does not set parent or blocked-by links (they need GraphQL node ids of issues made in the same run);
+*  - an assignee is not mapped (a Linear user is not a GitHub login).
+* A migrated issue ends with `<!-- holocron:migrated-from <url> -->`, which is how a second run finds it.
+*/
+const MARKER = /<!-- holocron:migrated-from (\S+) -->/;
+const PRIORITY_LABEL = /^priority\s*[:/-]\s*(urgent|high|medium|low)$/i;
+const LINK_QUERY = `query($owner: String!, $name: String!, $number: Int!) { repository(owner: $owner, name: $name) {
+	issue(number: $number) { parent { number } blockedBy(first: 50) { nodes { number } } } } }`;
+/** Splits `priority: high` labels from the rest. */
+function splitLabels(names) {
+	let priority;
+	const labels = [];
+	for (const name of names) {
+		const match = PRIORITY_LABEL.exec(name);
+		if (match) priority = match[1].toLowerCase();
+		else labels.push(name);
+	}
+	return {
+		labels,
+		...priority ? { priority } : {}
+	};
+}
+function categoryOf(issue) {
+	if (issue.state === "closed") return "done";
+	const names = issue.labels.map((l) => l.name.toLowerCase());
+	if (names.some((n) => n === "status:in-review" || n === "status: in review")) return "in-review";
+	if (names.some((n) => n === "status:in-progress" || n === "status: in progress")) return "in-progress";
+	return "open";
+}
+/** How many issues an export fetches at once. GitHub's secondary rate limit punishes bursts of requests, not volume. */
+const EXPORT_CONCURRENCY = 4;
+/** Runs `fn` over `items`, at most `limit` at a time, and returns the results in the order of `items`. */
+async function mapLimit(items, limit, fn) {
+	const results = new Array(items.length);
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const at = next++;
+			results[at] = await fn(items[at]);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	return results;
+}
+/** GitHub's own answer to a burst of requests (403 or 429 naming the secondary limit) becomes a message that says what to do. */
+function explainSecondaryLimit(err) {
+	if (err instanceof ProviderApiError && (err.status === 403 || err.status === 429) && String(err.details).includes("secondary rate limit")) return /* @__PURE__ */ new Error("GitHub's secondary rate limit stopped the export. It limits bursts of requests, not the hourly quota, and nothing has been written. Wait a couple of minutes and run the command again.");
+	return err;
+}
+/**
+* Reads the issues `selector` names, with their comments, priority label, parent and blockers.
+*
+* With `limit`, only that many survivors of the other filters are read, from the `order` end of the creation order. A
+* list of keys is sorted by issue number (which rises with creation in one repository) before anything is fetched, then
+* fetched a few at a time until enough are kept; a listing already carries `created_at`, so it is cut before the
+* per-issue comment and link requests. `info.matched` receives how many the selection matched before the cut.
+*/
+async function exportIssues(client, repo, selector, info = {}) {
+	return readIssues(client, repo, selector, info).catch((err) => {
+		throw explainSecondaryLimit(err);
+	});
+}
+async function readIssues(client, repo, selector, info) {
+	const [owner = "", name = ""] = repo.split("/", 2);
+	const since = selector.since ? Date.parse(selector.since) : void 0;
+	const survives = (i) => !i.pull_request && !(selector.openOnly && i.state === "closed") && (since === void 0 || Date.parse(i.updated_at) >= since);
+	const { limit, order = "oldest" } = selector;
+	let issues;
+	if (selector.keys) {
+		const fetch = (k) => client.issues.getIssue(repo, parseNumber(k));
+		info.matched = selector.keys.length;
+		issues = limit === void 0 ? (await mapLimit(selector.keys, EXPORT_CONCURRENCY, fetch)).filter(survives) : await readKeysLimited({
+			keys: selector.keys,
+			order,
+			limit,
+			concurrency: EXPORT_CONCURRENCY,
+			fetch,
+			keep: survives
+		});
+	} else {
+		let raw;
+		if (selector.milestone) {
+			const milestone = await findMilestone(client, repo, selector.milestone);
+			if (!milestone) throw new Error(`Milestone "${selector.milestone}" not found in ${repo}.`);
+			raw = await listAll(client, repo, { milestone: String(milestone.number) });
+		} else if (selector.all) raw = await listAll(client, repo, {});
+		else throw new Error("export needs keys, a milestone or all");
+		issues = raw.filter(survives);
+		info.matched = issues.length;
+		if (limit !== void 0) issues = pickByCreation(issues, (i) => i.created_at ?? i.updated_at, order, limit);
+	}
+	const records = [];
+	for (const issue of issues) {
+		reportProgress(info.onProgress, records.length, issues.length);
+		const comments = await client.issues.listComments(repo, issue.number);
+		const links = (await client.graphql.query(LINK_QUERY, {
+			owner,
+			name,
+			number: issue.number
+		}).catch(() => void 0))?.repository.issue;
+		const { labels, priority } = splitLabels(issue.labels.map((l) => l.name));
+		const body = issue.body?.replace(MARKER, "").trimEnd();
+		const migratedFrom = issue.body ? MARKER.exec(issue.body)?.[1] : void 0;
+		records.push({
+			key: `#${issue.number}`,
+			url: issue.html_url,
+			title: issue.title,
+			...body ? { body } : {},
+			statusCategory: categoryOf(issue),
+			closed: issue.state === "closed",
+			...priority ? { priority } : {},
+			labels: labels.filter((l) => !l.toLowerCase().startsWith("status:")),
+			...issue.assignee ? { assignee: {
+				id: issue.assignee.login,
+				displayName: issue.assignee.name ?? issue.assignee.login,
+				...issue.assignee.email ? { emailAddress: issue.assignee.email } : {}
+			} } : {},
+			...issue.milestone ? { milestone: issue.milestone.title } : {},
+			...links?.parent ? { parent: `#${links.parent.number}` } : {},
+			blockedBy: (links?.blockedBy.nodes ?? []).map((n) => `#${n.number}`),
+			comments: comments.map((c) => ({
+				...c.user ? { author: c.user.login } : {},
+				body: c.body,
+				createdAt: c.created_at
+			})),
+			createdAt: issue.created_at ?? issue.updated_at,
+			updatedAt: issue.updated_at,
+			...migratedFrom ? { migratedFrom } : {}
+		});
+	}
+	reportProgress(info.onProgress, records.length, issues.length);
+	return records;
+}
+/** Makes the records as issues, skipping any whose source address an earlier run already recorded. */
+async function importIssues(client, repo, records, options = {}) {
+	const existing = /* @__PURE__ */ new Map();
+	for (const issue of await listAll(client, repo, {})) {
+		const url = issue.body ? MARKER.exec(issue.body)?.[1] : void 0;
+		if (url) existing.set(url, issue.number);
+	}
+	const results = [];
+	const tick = () => reportProgress(options.onProgress, results.length, records.length);
+	for (const record of records) {
+		const found = existing.get(record.url);
+		if (found !== void 0) {
+			results.push({
+				source: record.key,
+				key: `#${found}`,
+				created: false,
+				dropped: []
+			});
+			tick();
+			continue;
+		}
+		const dropped = droppedFor(record);
+		if (options.dryRun) {
+			results.push({
+				source: record.key,
+				created: true,
+				dropped
+			});
+			tick();
+			continue;
+		}
+		const number = await createFromRecord(client, repo, record, options);
+		results.push({
+			source: record.key,
+			key: `#${number}`,
+			created: true,
+			dropped
+		});
+		tick();
+	}
+	return results;
+}
+/** What GitHub cannot hold of this record, for the report. */
+function droppedFor(record) {
+	const dropped = ["createdAt (GitHub sets it; the original date is in the text)"];
+	if (record.assignee) dropped.push("assignee (not mapped)");
+	if (record.parent) dropped.push("parent (not set on GitHub)");
+	if (record.blockedBy.length > 0) dropped.push("blockedBy (not set on GitHub)");
+	return dropped;
+}
+/** The labels a record becomes on GitHub: its own, plus `priority: <level>` (GitHub's priority is a label). */
+function labelsFor(record) {
+	return [...record.labels, ...record.priority && record.priority !== "none" ? [`priority: ${record.priority}`] : []];
+}
+/** The text a comment gets when it is copied: GitHub cannot post as another author or backdate. */
+function renderComment(comment) {
+	return `${comment.author ? `**${comment.author}**` : "Someone"} commented on ${comment.createdAt}:\n\n${comment.body}`;
+}
+/** Makes one issue from a record, with its comments, and closes it when the record is closed; returns its number. */
+async function createFromRecord(client, repo, record, options) {
+	const milestoneName = options.milestone ?? record.milestone;
+	const milestone = milestoneName ? await ensureMilestone(client, repo, milestoneName) : void 0;
+	const labels = labelsFor(record);
+	const created = await client.issues.createIssue(repo, {
+		title: record.title,
+		body: withProvenance(record),
+		...labels.length > 0 ? { labels } : {},
+		...milestone !== void 0 ? { milestone } : {}
+	});
+	for (const comment of record.comments) await client.issues.createComment(repo, created.number, renderComment(comment));
+	if (record.closed) await client.issues.updateIssue(repo, created.number, {
+		state: "closed",
+		state_reason: "completed"
+	});
+	return created.number;
+}
+/** The text of a migrated issue: the record's body, then where it came from and the marker a second run looks for. */
+function withProvenance(record) {
+	return `${record.body ? `${record.body}\n\n` : ""}---\n_Migrated from [${record.key}](${record.url}); created ${record.createdAt}._\n<!-- holocron:migrated-from ${record.url} -->`;
+}
+function parseNumber(key) {
+	const n = key.trim().replace(/^.*#/, "");
+	if (!/^\d+$/.test(n)) throw new Error(`Invalid GitHub issue key "${key}" — expected #N or N.`);
+	return parseInt(n, 10);
+}
+async function listAll(client, repo, extra) {
+	const all = [];
+	for (let page = 1;; page++) {
+		const batch = await client.issues.listIssues(repo, {
+			state: "all",
+			per_page: 100,
+			page,
+			...extra
+		});
+		all.push(...batch);
+		if (batch.length < 100) return all;
+	}
+}
+async function findMilestone(client, repo, ref) {
+	return (await client.issues.listMilestones(repo, { state: "all" })).find((m) => String(m.number) === ref || m.title.toLowerCase() === ref.toLowerCase());
+}
+async function ensureMilestone(client, repo, title) {
+	return (await findMilestone(client, repo, title))?.number ?? (await client.issues.createMilestone(repo, title)).number;
+}
+// src/capabilities/issues-sync.ts
+const COMMENT_HEADER = /^(?:\*\*.*?\*\*|Someone) commented on (\S+?):\n/;
+/** Whether GitHub is asking to be left alone: a 429, or a 403 that says it is a rate limit. */
+function isRateLimited(err) {
+	return err instanceof ProviderApiError && (err.status === 429 || err.status === 403 && /rate limit/i.test(`${err.message} ${String(err.details)}`));
+}
+const normalize = (text) => text.replace(/\r\n/g, "\n").trim();
+const sorted = (names) => names.map((n) => n.toLowerCase()).sort().join("\n");
+/** Makes the records missing from the repo and updates the ones an earlier run made. See the file comment. */
+async function syncIssues(client, repo, records, options = {}) {
+	const existing = /* @__PURE__ */ new Map();
+	for (const issue of await listAll(client, repo, {})) {
+		const url = issue.body ? MARKER.exec(issue.body)?.[1] : void 0;
+		if (url) existing.set(url, issue);
+	}
+	const results = [];
+	for (const record of records) try {
+		const found = existing.get(record.url);
+		results.push(found ? await update(client, repo, found, record, options) : await create(client, repo, record, options));
+		reportProgress(options.onProgress, results.length, records.length);
+	} catch (err) {
+		if (isRateLimited(err)) return results;
+		throw err;
+	}
+	return results;
+}
+async function create(client, repo, record, options) {
+	const dropped = droppedFor(record);
+	if (options.dryRun) return {
+		source: record.key,
+		created: true,
+		updated: false,
+		changes: [],
+		dropped
+	};
+	const number = await createFromRecord(client, repo, record, options);
+	return {
+		source: record.key,
+		key: `#${number}`,
+		created: true,
+		updated: false,
+		changes: [],
+		dropped
+	};
+}
+async function update(client, repo, issue, record, options) {
+	const patch = {};
+	const changes = [];
+	if (issue.title !== record.title) {
+		patch.title = record.title;
+		changes.push("title");
+	}
+	const body = withProvenance(record);
+	if (normalize(issue.body) !== normalize(body)) {
+		patch.body = body;
+		changes.push("description");
+	}
+	if (issue.state === "closed" !== record.closed) {
+		patch.state = record.closed ? "closed" : "open";
+		if (record.closed) patch.state_reason = "completed";
+		changes.push("state");
+	}
+	const current = issue.labels.map((l) => l.name);
+	const finalLabels = [...labelsFor(record), ...current.filter((n) => n.toLowerCase().startsWith("status:"))];
+	if (sorted(finalLabels) !== sorted(current)) {
+		patch.labels = finalLabels;
+		changes.push("labels");
+	}
+	const comments = await client.issues.listComments(repo, issue.number);
+	const seen = new Set(comments.map((c) => COMMENT_HEADER.exec(c.body)?.[1]));
+	const missing = record.comments.filter((c) => !seen.has(c.createdAt));
+	if (missing.length > 0) changes.push("comments");
+	if (!options.dryRun) {
+		if (Object.keys(patch).length > 0) await client.issues.updateIssue(repo, issue.number, patch);
+		for (const comment of missing) await client.issues.createComment(repo, issue.number, renderComment(comment));
+	}
+	return {
+		source: record.key,
+		key: `#${issue.number}`,
+		created: false,
+		updated: changes.length > 0,
+		changes,
+		dropped: droppedFor(record)
+	};
+}
+// src/capabilities/issues.ts
+/** Issues read per request when `search` has a `text`; GitHub's largest page. */
+const TEXT_PAGE_SIZE = 100;
+/** Pages `search` reads for a `text` before it stops (the 2000 most recently updated issues). */
+const TEXT_MAX_PAGES = 20;
+/** The GitHub implementation of the `issues` capability, backed by GitHub Issues and status labels. */
 var GitHubIssues = class {
 	client;
+	/** Capability key, always `"issues"`. */
 	key = "issues";
+	/** Provider name, always `"github"`. */
 	providerName = "github";
 	owner;
 	repoName;
@@ -145,7 +514,18 @@ var GitHubIssues = class {
 			...raw.email ? { emailAddress: raw.email } : {}
 		};
 	}
+	/**
+	* Searches the repo's issues, newest update first, leaving out pull requests.
+	*
+	* With `filter.text`, the issues are paged (newest update first, 100 a page, at most 20 pages) and compared
+	* client-side, without regard to case, until `limit` matches are found or the issues run out. GitHub's issue
+	* search (`GET /search/issues`) is deliberately not used: it indexes the words of a body, so punctuation and an
+	* HTML comment such as `<!-- holocron:idea notes/a.md -->` cannot be relied on to match, it is limited to 30
+	* requests a minute and it is eventually consistent (an issue made a moment ago may be missing). Paging has none
+	* of those limits, at the cost of reading up to 20 pages of a very large repository.
+	*/
 	async search(filter) {
+		if (filter.text) return this.searchText(filter, filter.text);
 		const params = {
 			state: filter.openOnly ? "open" : "all",
 			sort: "updated",
@@ -164,11 +544,39 @@ var GitHubIssues = class {
 			assignee: params.assignee
 		})).filter((i) => !i.pull_request).map((i) => this.mapIssue(i));
 	}
+	async searchText(filter, text) {
+		const needle = text.toLowerCase();
+		const limit = filter.limit ?? 50;
+		const assignee = filter.assignee === "currentUser" ? (await this.getMyself()).id : filter.assignee || void 0;
+		const found = [];
+		for (let page = 1; page <= TEXT_MAX_PAGES; page++) {
+			const raw = await this.client.issues.listIssues(this.repo, {
+				state: filter.openOnly ? "open" : "all",
+				sort: "updated",
+				direction: "desc",
+				per_page: TEXT_PAGE_SIZE,
+				page,
+				filter: "all",
+				...assignee ? { assignee } : {}
+			});
+			for (const issue of raw) {
+				if (issue.pull_request) continue;
+				if (`${issue.title}\n${issue.body ?? ""}`.toLowerCase().includes(needle)) {
+					found.push(this.mapIssue(issue));
+					if (found.length >= limit) return found;
+				}
+			}
+			if (raw.length < TEXT_PAGE_SIZE) break;
+		}
+		return found;
+	}
+	/** Fetches one issue by its key. */
 	async get(key) {
 		const number = parseIssueNumber(key, this.owner, this.repoName);
 		const raw = await this.client.issues.getIssue(this.repo, number);
 		return this.mapIssue(raw);
 	}
+	/** Creates an issue and returns its key as `#<number>`; the milestone is resolved from its title. */
 	async create(input) {
 		const body = { title: input.summary };
 		if (input.body) body.body = input.body;
@@ -216,10 +624,12 @@ var GitHubIssues = class {
 			via: `label set to ${targetLabel}`
 		};
 	}
+	/** Adds a comment to the issue with the given key. */
 	async comment(key, body) {
 		const number = parseIssueNumber(key, this.owner, this.repoName);
 		await this.client.issues.createComment(this.repo, number, body);
 	}
+	/** Checks the authenticated user, the repo and the label-backed lifecycle slots, and reports what resolves. */
 	async doctor() {
 		const me = await this.getMyself();
 		const repo = await this.client.repos.getRepo(this.repo);
@@ -288,6 +698,18 @@ var GitHubIssues = class {
 			lifecycle
 		};
 	}
+	/** Reads issues with their comments, priority label, parent and blockers, for `holocron migrate`. */
+	export(selector, info) {
+		return exportIssues(this.client, this.repo, selector, info);
+	}
+	/** Makes the records as issues; one already made by an earlier run is skipped. */
+	import(records, options) {
+		return importIssues(this.client, this.repo, records, options);
+	}
+	/** Like `import`, and it also updates what an earlier import or sync made, for `holocron sync issues`. */
+	sync(records, options) {
+		return syncIssues(this.client, this.repo, records, options);
+	}
 	async resolveMilestone(ref) {
 		if (/^\d+$/.test(ref)) return parseInt(ref, 10);
 		const match = (await this.client.issues.listMilestones(this.repo, { state: "all" })).find((m) => m.title.toLowerCase() === ref.toLowerCase());
@@ -337,8 +759,584 @@ function parseIssueNumber(key, owner, repoName) {
 	if (!/^\d+$/.test(num)) throw new Error(`Invalid GitHub issue key "${key}" — expected #N or N.`);
 	return parseInt(num, 10);
 }
-//#endregion
-//#region src/sodium.ts
+// src/capabilities/projects.ts
+/** The name of the single select field that holds an item's status. */
+const STATUS_FIELD = "Status";
+/** The name of the field `move` carries over besides the status. */
+const PRIORITY_FIELD = "Priority";
+const P_LEVELS = {
+	p0: "urgent",
+	p1: "high",
+	p2: "medium",
+	p3: "low"
+};
+/** The neutral priority a `Priority` option stands for, by its name; undefined for a name that is not one of them. */
+function priorityOf(value) {
+	const name = value?.trim().toLowerCase();
+	if (name === "urgent" || name === "high" || name === "medium" || name === "low") return name;
+	return name ? P_LEVELS[name] : void 0;
+}
+const PROJECT_FIELDS = "id number title closed url";
+const BOARD_QUERY = `query($id: ID!) { node(id: $id) { ... on ProjectV2 {
+	${PROJECT_FIELDS}
+	fields(first: 100) { nodes {
+		... on ProjectV2FieldCommon { id name dataType }
+		... on ProjectV2SingleSelectField { options { id name color description } }
+	} }
+	views(first: 50) { nodes { id name layout filter groupByFields(first: 5) { nodes { ... on ProjectV2FieldCommon { name } } } } }
+	workflows(first: 50) { nodes { id name enabled } }
+} } }`;
+const ITEMS_QUERY = `query($id: ID!, $after: String) { node(id: $id) { ... on ProjectV2 {
+	items(first: 100, after: $after) {
+		pageInfo { hasNextPage endCursor }
+		nodes {
+			id
+			fieldValues(first: 30) { nodes { ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2FieldCommon { name } } } } }
+			content {
+				__typename
+				... on Issue { id number title state repository { nameWithOwner } blockedBy(first: 50) { nodes { number state repository { nameWithOwner } } } }
+				... on PullRequest { id number title state repository { nameWithOwner } }
+			}
+		}
+	}
+} } }`;
+const LIST_QUERY = `query($owner: String!, $after: String) { organization(login: $owner) { id projectsV2(first: 100, after: $after) {
+	pageInfo { hasNextPage endCursor }
+	nodes { ${PROJECT_FIELDS} }
+} } }`;
+const OWNER_QUERY = "query($owner: String!) { organization(login: $owner) { id } }";
+const SET_VALUE = `mutation($project: ID!, $item: ID!, $field: ID!, $option: String!) {
+	updateProjectV2ItemFieldValue(input: { projectId: $project, itemId: $item, fieldId: $field, value: { singleSelectOptionId: $option } }) { projectV2Item { id } }
+}`;
+const UPDATE_OPTIONS = `mutation($field: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]!) {
+	updateProjectV2Field(input: { fieldId: $field, singleSelectOptions: $options }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+}`;
+const DATA_TYPES = {
+	single_select: "SINGLE_SELECT",
+	text: "TEXT",
+	number: "NUMBER",
+	date: "DATE",
+	iteration: "ITERATION"
+};
+function fieldTypeOf(dataType) {
+	return Object.keys(DATA_TYPES).find((t) => DATA_TYPES[t] === dataType);
+}
+function toSummary(n) {
+	return {
+		id: n.id,
+		number: n.number,
+		name: n.title,
+		url: n.url,
+		closed: n.closed
+	};
+}
+function toOptionInput(o) {
+	return {
+		...o.id ? { id: o.id } : {},
+		name: o.name,
+		color: (o.color ?? "GRAY").toUpperCase(),
+		description: o.description ?? ""
+	};
+}
+/** The GitHub implementation of the `projects` capability, backed by Projects v2. */
+var GitHubProjects = class {
+	graphql;
+	/** Capability key, always `"projects"`. */
+	key = "projects";
+	/** Provider name, always `"github"`. */
+	providerName = "github";
+	repo;
+	constructor(graphql, opts) {
+		this.graphql = graphql;
+		this.repo = opts.repo;
+	}
+	/** Every board of the organization, open and closed. */
+	async list(owner) {
+		const boards = [];
+		let after = null;
+		for (;;) {
+			const page = (await this.graphql.query(LIST_QUERY, {
+				owner,
+				after
+			})).organization.projectsV2;
+			boards.push(...page.nodes.map(toSummary));
+			if (!page.pageInfo.hasNextPage) return boards;
+			after = page.pageInfo.endCursor;
+		}
+	}
+	/** The open board with exactly this name. */
+	async find(owner, name) {
+		return (await this.list(owner)).find((b) => !b.closed && b.name === name);
+	}
+	/**
+	* Makes a board. With `template.source` naming an open board it is copied (fields, options, views and automation
+	* rules, no items); otherwise the board is created and brought in line with the template.
+	*/
+	async create(owner, name, template) {
+		const ownerId = await this.ownerId(owner);
+		const source = template.source ? await this.find(owner, template.source) : void 0;
+		if (source) return toSummary((await this.graphql.query(`mutation($project: ID!, $owner: ID!, $title: String!) {
+	copyProjectV2(input: { projectId: $project, ownerId: $owner, title: $title, includeDraftIssues: false }) { projectV2 { ${PROJECT_FIELDS} } }
+}`, {
+			project: source.id,
+			owner: ownerId,
+			title: name
+		})).copyProjectV2.projectV2);
+		const board = toSummary((await this.graphql.query(`mutation($owner: ID!, $title: String!) {
+	createProjectV2(input: { ownerId: $owner, title: $title }) { projectV2 { ${PROJECT_FIELDS} } }
+}`, {
+			owner: ownerId,
+			title: name
+		})).createProjectV2.projectV2);
+		await this.ensure(owner, board, template);
+		return board;
+	}
+	/** Closes the board; `updateProjectV2` with `closed: true` is the only way, and reversible. */
+	async close(_owner, board) {
+		await this.graphql.query(`mutation($project: ID!) { updateProjectV2(input: { projectId: $project, closed: true }) { projectV2 { id } } }`, { project: board.id });
+	}
+	/** The live board: statuses, other fields, views and automation rules. */
+	async read(_owner, board) {
+		const raw = await this.readRaw(board.id);
+		const status = raw.fields.find((f) => f.name === STATUS_FIELD);
+		const fields = [];
+		for (const f of raw.fields) {
+			const type = fieldTypeOf(f.dataType);
+			if (!type || f.name === STATUS_FIELD) continue;
+			fields.push({
+				name: f.name,
+				type,
+				...f.options ? { options: f.options.map((o) => o.name) } : {}
+			});
+		}
+		const views = [];
+		for (const v of raw.views) {
+			const layout = v.layout === "BOARD_LAYOUT" ? "board" : v.layout === "TABLE_LAYOUT" ? "table" : void 0;
+			if (!layout) continue;
+			views.push({
+				name: v.name,
+				layout,
+				...v.filter ? { filter: v.filter } : {},
+				...v.groupBy[0] ? { groupBy: v.groupBy[0] } : {}
+			});
+		}
+		return {
+			board: raw.summary,
+			statuses: (status?.options ?? []).map((o) => o.name),
+			fields,
+			views,
+			rules: raw.rules.map(({ name, enabled }) => ({
+				name,
+				enabled
+			}))
+		};
+	}
+	/**
+	* Brings the board in line with the template. Never deletes a field, option or view, and never sends an option
+	* list without ids. Stops (throws) when the status field cannot be read.
+	*/
+	async ensure(_owner, board, template) {
+		const raw = await this.readRaw(board.id);
+		const status = raw.fields.find((f) => f.name === STATUS_FIELD && f.options);
+		if (!status) throw new Error(`cannot read the "${STATUS_FIELD}" field of board "${board.name}"; stopped before any write so no item loses its status`);
+		const changes = [];
+		const todos = [];
+		const statusChanges = await this.ensureOptions(board, status, template.statuses.map((s) => ({
+			name: s.name,
+			color: s.color,
+			description: s.description
+		})));
+		changes.push(...statusChanges.map((c) => `status ${c}`));
+		for (const want of template.fields) {
+			const have = raw.fields.find((f) => f.name === want.name);
+			if (!have) {
+				await this.createField(board.id, want);
+				changes.push(`field ${want.name} created`);
+				continue;
+			}
+			if (fieldTypeOf(have.dataType) !== want.type) {
+				todos.push(`field "${want.name}" is ${have.dataType} but the template says ${want.type}; change it by hand`);
+				continue;
+			}
+			if (want.type === "single_select" && have.options && want.options) {
+				const diff = await this.ensureOptions(board, have, want.options.map((name) => ({ name })));
+				changes.push(...diff.map((c) => `field ${want.name} option ${c}`));
+			}
+		}
+		for (const want of template.views) {
+			const have = raw.views.find((v) => v.name === want.name);
+			const layout = want.layout === "board" ? "BOARD_LAYOUT" : "TABLE_LAYOUT";
+			let viewId = have?.id;
+			if (!viewId) {
+				viewId = await this.createView(board.id, want.name, layout);
+				changes.push(`view ${want.name} created`);
+			} else if (have && have.layout !== layout) {
+				await this.updateView(viewId, { layout });
+				changes.push(`view ${want.name} layout set to ${want.layout}`);
+			}
+			if (want.filter !== void 0 && want.filter !== (have?.filter ?? "")) {
+				await this.updateView(viewId, { filter: want.filter });
+				changes.push(`view ${want.name} filter set`);
+			}
+			if (want.groupBy && have?.groupBy[0] !== want.groupBy) todos.push(`group view "${want.name}" by ${want.groupBy}; the API cannot set a view's grouping`);
+		}
+		for (const rule of template.rules ?? []) {
+			const have = raw.rules.find((r) => r.name === rule);
+			if (!have) todos.push(`create the automation rule "${rule}"; the API cannot create one`);
+			else if (!have.enabled) todos.push(`turn on the automation rule "${rule}"; the API cannot switch one`);
+		}
+		return {
+			created: false,
+			changes,
+			todos
+		};
+	}
+	/**
+	* Makes a single select field hold the wanted options in order, every existing one sent with its id. Options the
+	* template does not mention stay, after the wanted ones. Returns what changed (`Blocked added`, `order set`).
+	*/
+	async ensureOptions(board, field, wanted) {
+		/* v8 ignore next -- every caller passes a field it found with options; the fallback only satisfies the type */
+		const existing = field.options ?? [];
+		const next = [];
+		const changes = [];
+		for (const w of wanted) {
+			const have = existing.find((o) => o.name === w.name);
+			if (have) {
+				next.push({
+					id: have.id,
+					name: have.name,
+					color: (w.color ?? have.color).toUpperCase(),
+					description: w.description ?? have.description
+				});
+				if (next[next.length - 1].color !== have.color || next[next.length - 1].description !== have.description) changes.push(`${have.name} updated`);
+			} else {
+				next.push({
+					name: w.name,
+					color: (w.color ?? "GRAY").toUpperCase(),
+					description: w.description ?? ""
+				});
+				changes.push(`${w.name} added`);
+			}
+		}
+		for (const have of existing) if (!next.some((n) => n.id === have.id)) next.push({ ...have });
+		const sameOrder = next.length === existing.length && next.every((n, i) => n.id === existing[i]?.id);
+		if (changes.length === 0 && sameOrder) return [];
+		if (sameOrder === false && !changes.some((c) => c.endsWith("added"))) changes.push("order set");
+		const before = await this.fetchItems(board.id);
+		const snapshot = /* @__PURE__ */ new Map();
+		for (const item of before) {
+			const value = item.values[field.name];
+			if (value) snapshot.set(item.id, value);
+		}
+		await this.graphql.query(UPDATE_OPTIONS, {
+			field: field.id,
+			options: next.map(toOptionInput)
+		});
+		const afterField = (await this.readRaw(board.id)).fields.find((f) => f.id === field.id);
+		const afterItems = await this.fetchItems(board.id);
+		const afterValues = new Map(afterItems.map((i) => [i.id, i.values[field.name]]));
+		const lost = [...snapshot].filter(([itemId]) => !afterValues.get(itemId));
+		if (lost.length > 0) {
+			let restored = 0;
+			for (const [itemId, name] of lost) {
+				const option = afterField?.options?.find((o) => o.name === name);
+				if (!option) continue;
+				await this.graphql.query(SET_VALUE, {
+					project: board.id,
+					item: itemId,
+					field: field.id,
+					option: option.id
+				});
+				restored++;
+			}
+			throw new Error(`updating "${field.name}" on board "${board.name}" blanked ${lost.length} item value(s); wrote ${restored} back by option name`);
+		}
+		return changes;
+	}
+	async createField(projectId, want) {
+		await this.graphql.query(`mutation($project: ID!, $name: String!, $type: ProjectV2CustomFieldType!, $options: [ProjectV2SingleSelectFieldOptionInput!]) {
+	createProjectV2Field(input: { projectId: $project, name: $name, dataType: $type, singleSelectOptions: $options }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+}`, {
+			project: projectId,
+			name: want.name,
+			type: DATA_TYPES[want.type],
+			options: want.type === "single_select" ? (want.options ?? []).map((name) => toOptionInput({ name })) : void 0
+		});
+	}
+	async createView(projectId, name, layout) {
+		return (await this.graphql.query(`mutation($project: ID!, $name: String!, $layout: ProjectV2ViewLayout!) {
+	createProjectV2View(input: { projectId: $project, name: $name, layout: $layout }) { projectV2View { id } }
+}`, {
+			project: projectId,
+			name,
+			layout
+		})).createProjectV2View.projectV2View.id;
+	}
+	async updateView(viewId, change) {
+		await this.graphql.query(`mutation($view: ID!, $layout: ProjectV2ViewLayout, $filter: String) {
+	updateProjectV2View(input: { viewId: $view, layout: $layout, filter: $filter }) { projectV2View { id } }
+}`, {
+			view: viewId,
+			layout: change.layout,
+			filter: change.filter
+		});
+	}
+	/** The board's issues and pull requests with their status, whether they are open and their open blockers. */
+	async items(_owner, board, template) {
+		const categories = new Map(template.statuses.map((s) => [s.name, s.category]));
+		return (await this.fetchItems(board.id)).map((i) => {
+			const status = i.values[STATUS_FIELD];
+			const category = status ? categories.get(status) : void 0;
+			const priority = priorityOf(i.values[PRIORITY_FIELD]);
+			return {
+				key: this.keyOf(i.repo, i.number),
+				title: i.title,
+				open: i.open,
+				...status ? { status } : {},
+				...category ? { category } : {},
+				blockedBy: i.blockers.map((b) => this.keyOf(b.repo, b.number)),
+				...priority ? { priority } : {}
+			};
+		});
+	}
+	/** Puts an item in a status; `transitioned` is false when it already is there. */
+	async setStatus(_owner, board, key, status) {
+		const ref = this.parseKey(key);
+		const field = (await this.readRaw(board.id)).fields.find((f) => f.name === STATUS_FIELD && f.options);
+		const option = field?.options?.find((o) => o.name === status);
+		if (!field || !option) throw new Error(`board "${board.name}" has no status "${status}"`);
+		const item = (await this.fetchItems(board.id)).find((i) => i.repo === ref.repo && i.number === ref.number);
+		if (!item) throw new Error(`${key} is not on board "${board.name}"`);
+		if (item.values[STATUS_FIELD] === status) return {
+			transitioned: false,
+			status
+		};
+		await this.graphql.query(SET_VALUE, {
+			project: board.id,
+			item: item.id,
+			field: field.id,
+			option: option.id
+		});
+		return {
+			transitioned: true,
+			status,
+			via: "project field set"
+		};
+	}
+	/**
+	* Puts the open items of `from` on `to` with their status and priority, only where the target has no value;
+	* closed and merged ones stay, and are set to the template's done status when theirs is not a done one.
+	*/
+	async move(_owner, from, to, template) {
+		const report = {
+			moved: [],
+			kept: [],
+			left: []
+		};
+		const [source, target, fromRaw, toRaw] = await Promise.all([
+			this.fetchItems(from.id),
+			this.fetchItems(to.id),
+			this.readRaw(from.id),
+			this.readRaw(to.id)
+		]);
+		const done = template.statuses.find((s) => s.category === "done")?.name;
+		const doneNames = new Set(template.statuses.filter((s) => s.category === "done").map((s) => s.name));
+		const carried = [STATUS_FIELD, PRIORITY_FIELD];
+		for (const item of source) {
+			const key = this.keyOf(item.repo, item.number);
+			if (!item.open) {
+				const current = item.values[STATUS_FIELD];
+				if (done && (!current || !doneNames.has(current))) await this.setOption(from.id, fromRaw, item.id, STATUS_FIELD, done);
+				report.left.push(key);
+				continue;
+			}
+			let targetItem = target.find((t) => t.contentId === item.contentId);
+			if (targetItem) report.kept.push(key);
+			else {
+				const data = await this.graphql.query(`mutation($project: ID!, $content: ID!) { addProjectV2ItemById(input: { projectId: $project, contentId: $content }) { item { id } } }`, {
+					project: to.id,
+					content: item.contentId
+				});
+				targetItem = {
+					...item,
+					id: data.addProjectV2ItemById.item.id,
+					values: {}
+				};
+				report.moved.push(key);
+			}
+			for (const name of carried) {
+				const value = item.values[name];
+				if (value && !targetItem.values[name]) await this.setOption(to.id, toRaw, targetItem.id, name, value);
+			}
+		}
+		return report;
+	}
+	/**
+	* Puts issues on the board (`addProjectV2ItemById`, the content id the issue's node id) and sets Status and Priority
+	* through the single select update, only where the item has no value yet. A status or priority with no option on
+	* the board is reported in `dropped`; no option is ever created, so no value is cleared.
+	*/
+	async addItems(_owner, board, items, template) {
+		const raw = await this.readRaw(board.id);
+		const onBoard = await this.fetchItems(board.id);
+		const statusField = raw.fields.find((f) => f.name === STATUS_FIELD && f.options);
+		const priorityField = raw.fields.find((f) => f.name === PRIORITY_FIELD && f.options);
+		const results = [];
+		for (const input of items) {
+			const ref = this.parseKey(input.key);
+			let current = onBoard.find((i) => i.repo === ref.repo && i.number === ref.number);
+			const added = !current;
+			if (!current) current = {
+				id: (await this.graphql.query(`mutation($project: ID!, $content: ID!) { addProjectV2ItemById(input: { projectId: $project, contentId: $content }) { item { id } } }`, {
+					project: board.id,
+					content: await this.nodeId(ref)
+				})).addProjectV2ItemById.item.id,
+				contentId: "",
+				repo: ref.repo,
+				number: ref.number,
+				title: "",
+				open: true,
+				values: {},
+				blockers: []
+			};
+			const dropped = [];
+			if (input.status !== void 0 || input.category !== void 0) {
+				const name = this.statusFor(input, template, statusField?.options);
+				if (!name) dropped.push(`status ${input.status ?? input.category} (no matching option on the board)`);
+				else if (!current.values[STATUS_FIELD]) await this.setOption(board.id, raw, current.id, STATUS_FIELD, name);
+			}
+			if (input.priority !== void 0 && input.priority !== "none") {
+				const option = priorityField?.options?.find((o) => priorityOf(o.name) === input.priority);
+				if (!option) dropped.push(`priority ${input.priority} (no matching option on the board)`);
+				else if (!current.values[PRIORITY_FIELD]) await this.setOption(board.id, raw, current.id, PRIORITY_FIELD, option.name);
+			}
+			results.push({
+				key: input.key,
+				added,
+				dropped
+			});
+		}
+		return results;
+	}
+	/** The board's own status for an input: the option named like its status, else the template's status of its category. */
+	statusFor(input, template, options) {
+		const has = (name) => options?.find((o) => o.name.toLowerCase() === name.toLowerCase())?.name;
+		const named = input.status === void 0 ? void 0 : has(input.status);
+		if (named) return named;
+		const byCategory = template.statuses.find((s) => s.category === input.category);
+		return byCategory ? has(byCategory.name) : void 0;
+	}
+	/** The node id of an issue, which `addProjectV2ItemById` takes as the content id. */
+	async nodeId(ref) {
+		const [owner, name] = ref.repo.split("/");
+		const id = (await this.graphql.query(`query($owner: String!, $name: String!, $number: Int!) { repository(owner: $owner, name: $name) { issue(number: $number) { id } } }`, {
+			owner,
+			name,
+			number: ref.number
+		})).repository?.issue?.id;
+		if (!id) throw new Error(`issue ${ref.repo}#${ref.number} not found`);
+		return id;
+	}
+	/** A `holocron doctor` smoke check: how many boards the token sees in the configured repository's organization. */
+	async whoami() {
+		try {
+			return {
+				ok: true,
+				boards: (await this.list(this.repo.split("/")[0] ?? "")).length
+			};
+		} catch {
+			return {
+				ok: false,
+				boards: 0
+			};
+		}
+	}
+	/** Sets a single select value by option name; a field or option the board lacks is skipped. */
+	async setOption(projectId, raw, itemId, fieldName, optionName) {
+		const field = raw.fields.find((f) => f.name === fieldName && f.options);
+		const option = field?.options?.find((o) => o.name === optionName);
+		if (!field || !option) return;
+		await this.graphql.query(SET_VALUE, {
+			project: projectId,
+			item: itemId,
+			field: field.id,
+			option: option.id
+		});
+	}
+	async ownerId(owner) {
+		return (await this.graphql.query(OWNER_QUERY, { owner })).organization.id;
+	}
+	async readRaw(id) {
+		const n = (await this.graphql.query(BOARD_QUERY, { id })).node;
+		if (!n) throw new Error(`board ${id} not found`);
+		return {
+			summary: toSummary(n),
+			fields: n.fields.nodes.filter((f) => f.id).map((f) => ({
+				id: f.id,
+				name: f.name,
+				dataType: f.dataType,
+				...f.options ? { options: f.options } : {}
+			})),
+			views: n.views.nodes.map((v) => ({
+				id: v.id,
+				name: v.name,
+				layout: v.layout,
+				filter: v.filter,
+				groupBy: (v.groupByFields?.nodes ?? []).map((g) => g.name)
+			})),
+			rules: n.workflows.nodes.map((w) => ({
+				id: w.id,
+				name: w.name,
+				enabled: w.enabled
+			}))
+		};
+	}
+	async fetchItems(id) {
+		const items = [];
+		let after = null;
+		for (;;) {
+			const page = (await this.graphql.query(ITEMS_QUERY, {
+				id,
+				after
+			})).node.items;
+			for (const n of page.nodes) {
+				const c = n.content;
+				if (!c || !c.repository) continue;
+				const values = {};
+				for (const v of n.fieldValues.nodes) if (v.name && v.field?.name) values[v.field.name] = v.name;
+				items.push({
+					id: n.id,
+					contentId: c.id,
+					repo: c.repository.nameWithOwner,
+					number: c.number,
+					title: c.title,
+					open: c.state === "OPEN",
+					values,
+					blockers: (c.blockedBy?.nodes ?? []).filter((b) => b.state === "OPEN").map((b) => ({
+						repo: b.repository.nameWithOwner,
+						number: b.number
+					}))
+				});
+			}
+			if (!page.pageInfo.hasNextPage) return items;
+			after = page.pageInfo.endCursor;
+		}
+	}
+	keyOf(repo, number) {
+		return repo === this.repo ? `#${number}` : `${repo}#${number}`;
+	}
+	parseKey(key) {
+		const m = /^(?:([^#\s]+))?#?(\d+)$/.exec(key.trim());
+		const hasRepo = key.includes("#") && m?.[1];
+		if (!m) throw new Error(`not an issue key: ${key}`);
+		return {
+			repo: hasRepo ? m[1] : this.repo,
+			number: Number(m[2])
+		};
+	}
+};
+// src/sodium.ts
 /**
 * libsodium sealed-box encryption for GitHub Actions secrets.
 *
@@ -369,32 +1367,86 @@ async function encryptSecret(publicKeyBase64, value) {
 	const ciphertext = sodium.crypto_box_seal(plaintext, publicKey);
 	return sodium.to_base64(ciphertext, sodium.base64_variants.ORIGINAL);
 }
-//#endregion
-//#region src/capabilities/secrets.ts
+// src/capabilities/secrets.ts
+/** The GitHub implementation of the `secrets` capability, covering repository, environment and organization secrets. */
 var GitHubSecrets = class {
 	client;
 	opts;
+	orgClient;
+	/** Capability key, always `"secrets"`. */
 	key = "secrets";
+	/** Provider name, always `"github"`. */
 	providerName = "github";
-	constructor(client, opts) {
+	/**
+	* `client` handles repo and environment scopes; `orgClient`, when given, handles
+	* the organization scope. They differ when a dedicated org-only token exists:
+	* it can write org secrets but not repo ones, and `github.admin` is the reverse.
+	*/
+	constructor(client, opts, orgClient) {
 		this.client = client;
 		this.opts = opts;
+		this.orgClient = orgClient;
+	}
+	/** Repository name to numeric id, so one run asks GitHub once per repository however many secrets name it. */
+	repoIds = /* @__PURE__ */ new Map();
+	clientFor(scope) {
+		return scope.kind === "organization" ? this.orgClient ?? this.client : this.client;
 	}
 	async listSecrets(scope) {
-		return this.client.secrets.listSecrets(this.opts.repo, toGHScope(scope));
+		return this.clientFor(scope).secrets.listSecrets(this.opts.repo, toGHScope(scope));
 	}
 	async setSecret(scope, name, value) {
 		const ghScope = toGHScope(scope);
-		const pk = await this.client.secrets.getPublicKey(this.opts.repo, ghScope);
+		const client = this.clientFor(scope);
+		const readers = scope.kind === "organization" ? await this.readers(scope) : {};
+		const pk = await client.secrets.getPublicKey(this.opts.repo, ghScope);
 		const body = {
 			encrypted_value: await encryptSecret(pk.key, value),
 			key_id: pk.key_id
 		};
-		if (scope.kind === "organization") body.visibility = "all";
-		await this.client.secrets.putSecret(this.opts.repo, ghScope, name, body);
+		Object.assign(body, readers);
+		await client.secrets.putSecret(this.opts.repo, ghScope, name, body);
+	}
+	/**
+	* Who can read each organization secret, by name (never a value): `selected` ones come with the names of their
+	* repositories. Any other scope has no visibility and gives `{}`.
+	*/
+	async listSecretAccess(scope) {
+		if (scope.kind !== "organization") return {};
+		const client = this.clientFor(scope);
+		const found = {};
+		for (const info of await client.secrets.listOrgSecretInfo(scope.name)) found[info.name] = info.visibility === "selected" ? {
+			visibility: "selected",
+			repos: await client.secrets.listSelectedRepositories(scope.name, info.name)
+		} : { visibility: info.visibility };
+		return found;
+	}
+	/** The `visibility` (and repository ids) of an organization write. No `visibility` keeps the older default, `all`. */
+	async readers(scope) {
+		const visibility = scope.visibility ?? "all";
+		if (visibility !== "selected") return { visibility };
+		if (!scope.repos?.length) throw new Error(`organization secret with visibility "selected" needs a non-empty repos list`);
+		const ids = [];
+		for (const name of scope.repos) ids.push(await this.repoId(scope.name, name));
+		return {
+			visibility,
+			selected_repository_ids: ids
+		};
+	}
+	repoId(org, name) {
+		const full = `${org}/${name}`;
+		let id = this.repoIds.get(full);
+		if (!id) {
+			id = this.client.repos.getRepo(full).then((repo) => repo.id, (err) => {
+				throw new Error(`could not resolve repository ${full}: ${err instanceof Error ? err.message : String(err)}`);
+			});
+			this.repoIds.set(full, id);
+		}
+		return id;
 	}
+	/** Deletes the named secret in the given scope. */
 	async deleteSecret(scope, name) {
-		await this.client.secrets.deleteSecret(this.opts.repo, toGHScope(scope), name);
+		await this.clientFor(scope).secrets.deleteSecret(this.opts.repo, toGHScope(scope), name);
 	}
 };
 function toGHScope(scope) {
@@ -404,8 +1456,46 @@ function toGHScope(scope) {
 	};
 	return scope;
 }
-//#endregion
-//#region src/capabilities/labels.ts
+// src/capabilities/files.ts
+/** Reads one file; `null` when it does not exist. `version` is the blob sha `writeFile` needs to replace exactly this one. */
+/** A fine-grained token only reaches the repositories and permissions it was given; say which one is missing. */
+function noAccess(repo, action, cause) {
+	return new Error(`the token cannot ${action} files in ${repo} (403): give the user-sync token (HOLOCRON_USER_SYNC_TOKEN, or holocron new token github.user-sync) access to that repository with Contents: ${action === "read" ? "read" : "read and write"}`, { cause });
+}
+async function readRepoFile(client, repo, path) {
+	try {
+		const file = await client.git.getContents(repo, path);
+		if (file.encoding !== "base64") throw new Error(`${repo}/${path}: unexpected encoding \`${file.encoding}\``);
+		return {
+			content: Buffer.from(file.content, "base64").toString("utf-8"),
+			version: file.sha
+		};
+	} catch (err) {
+		if (err instanceof ProviderApiError && err.status === 403) throw noAccess(repo, "read", err);
+		if (!(err instanceof ProviderApiError && err.status === 404)) throw err;
+	}
+	try {
+		await client.repos.getRepo(repo);
+	} catch (err) {
+		if (err instanceof ProviderApiError && err.status === 404) throw new Error(`${repo} was not found: it does not exist, or the token cannot see it`, { cause: err });
+		throw err;
+	}
+	return null;
+}
+/** Creates or replaces one file in a commit; GitHub refuses (409) a `version` that has since changed. */
+async function writeRepoFile(client, repo, path, content, opts) {
+	try {
+		await client.git.putContents(repo, path, {
+			message: opts.message,
+			content,
+			...opts.version ? { sha: opts.version } : {}
+		});
+	} catch (err) {
+		if (err instanceof ProviderApiError && err.status === 403) throw noAccess(repo, "write", err);
+		throw err;
+	}
+}
+// src/capabilities/labels.ts
 /**
 * Idempotently synchronise a repo's labels to the canonical set.
 *
@@ -443,14 +1533,202 @@ async function syncLabels(client, repo, canonical, stale) {
 	}
 	return `${created} created, ${updated} updated, ${deleted} deleted`;
 }
-//#endregion
-//#region src/capabilities/properties.ts
-async function syncProperties(client, repo, values) {
-	await client.properties.setProperties(repo, values);
+// src/capabilities/property-fix-hints.ts
+/** GitHub's wording when a custom property value is not one the organization's definition allows. */
+const NOT_ALLOWED = /Value '([^']+)' is not allowed for property '([^']+)'/g;
+/**
+* What to do about each value GitHub says an organization custom property does not allow, one sentence per property,
+* read from GitHub's own message so it works even when the organization's definitions cannot be read. The values
+* belong to the organization's definition, not to the repository, so the fix is to add them there: a repository cannot
+* make its own value allowed. Empty when GitHub's message names no such value.
+*/
+function propertyFixHints(githubMessage) {
+	const byProperty = /* @__PURE__ */ new Map();
+	for (const [, value, property] of githubMessage.matchAll(NOT_ALLOWED)) {
+		const values = byProperty.get(property) ?? [];
+		if (!values.includes(value)) values.push(value);
+		byProperty.set(property, values);
+	}
+	return [...byProperty].map(([property, values]) => `add ${values.map((v) => `"${v}"`).join(", ")} to the allowed values of the organization custom property ${property} (the organization's Settings, Custom properties), then run setup again`);
+}
+// src/capabilities/rejected-properties.ts
+/** The values `setup` sends for `true_false` properties; anything else is rejected. */
+const BOOLEANS = /* @__PURE__ */ new Set(["true", "false"]);
+/**
+* What is wrong with `values` when compared with the organization's property definitions, one sentence per
+* problem, in the order the properties are given: a property the organization does not define, a value a
+* `single_select` or `multi_select` property does not allow, or a `true_false` property that is not `true` or
+* `false`. A `string` or `url` property has nothing to check here. Empty when every value fits its definition.
+*/
+function rejectedProperties(values, schema) {
+	const byName = new Map(schema.map((property) => [property.property_name, property]));
+	const problems = [];
+	for (const [name, value] of Object.entries(values)) {
+		const definition = byName.get(name);
+		if (!definition) {
+			problems.push(`${name} is not a custom property of the organization`);
+			continue;
+		}
+		const sent = Array.isArray(value) ? value : [value];
+		if (definition.value_type === "true_false") {
+			for (const item of sent.filter((item) => !BOOLEANS.has(item))) problems.push(`${name} is "${item}", but it takes only true or false`);
+			continue;
+		}
+		const allowed = definition.allowed_values ?? [];
+		if (definition.value_type !== "single_select" && definition.value_type !== "multi_select") continue;
+		for (const item of sent.filter((item) => !allowed.includes(item))) problems.push(`${name} has "${item}", which is not one of its allowed values (${allowed.join(", ")})`);
+	}
+	return problems;
+}
+// src/capabilities/properties.ts
+/** GitHub's own message from a 422 body (`{"message": ..., "errors": [...]}`), or the start of the body when it is not JSON. */
+function githubMessage(details) {
+	const raw = String(details ?? "").trim();
+	try {
+		const body = JSON.parse(raw);
+		const errors = Array.isArray(body.errors) ? body.errors.map((e) => JSON.stringify(e)).join(", ") : "";
+		const message = typeof body.message === "string" ? body.message : raw;
+		return errors ? `${message}: ${errors}` : message;
+	} catch {
+		return raw.slice(0, 300);
+	}
+}
+/** The organization's property definitions, or `undefined` when they cannot be read (permission, an older client). */
+async function orgSchema(client, repo) {
+	try {
+		return await client.properties.orgSchema(repo.split("/")[0]);
+	} catch {
+		return;
+	}
+}
+/**
+* The values `values` holds that the organization's property definitions do not allow, one sentence each, or
+* `undefined` when the definitions cannot be read (the token lacks the organization's custom properties permission, or
+* the organization defines none). `client` should be the organization-scoped one when there is one, since reading the
+* definitions is an organization permission a repository token often lacks. Read-only.
+*/
+async function checkPropertyValues(client, repo, values) {
+	const schema = await orgSchema(client, repo);
+	return schema ? rejectedProperties(values, schema) : void 0;
+}
+/**
+* Sets the repo's custom properties. When GitHub answers 422 the error says which value it refused and what to do
+* about it: the values are compared with the organization's property definitions (read-only, with `schemaClient`, the
+* organization-scoped client when there is one), GitHub's own message is added, and each value GitHub says a property
+* does not allow gets the fix, which does not need the definitions to be readable. One refused value fails the whole
+* request, so none of the properties is set.
+*/
+async function syncProperties(client, repo, values, schemaClient = client) {
+	try {
+		await client.properties.setProperties(repo, values);
+	} catch (err) {
+		if (!(err instanceof ProviderApiError$1) || err.status !== 422) throw err;
+		const problems = await checkPropertyValues(schemaClient, repo, values) ?? [];
+		const said = githubMessage(err.details);
+		const fixes = propertyFixHints(said);
+		throw new Error(`GitHub refused the custom properties (422), so none was set: ${problems.length > 0 ? problems.join("; ") : "no value differs from the organization's definitions, or they could not be read"}. GitHub said: ${said}${fixes.length > 0 ? `. To fix it: ${fixes.join("; ")}` : ""}`, { cause: err });
+	}
 	return `${Object.keys(values).length} properties set`;
 }
-//#endregion
-//#region src/capabilities/teams.ts
+/** The values the organization's property `name` allows; `undefined` when it cannot be read, is not defined or takes any value. */
+async function getOrgPropertyValues(client, repo, name) {
+	return ((await orgSchema(client, repo))?.find((p) => p.property_name === name))?.allowed_values ?? void 0;
+}
+/**
+* Adds the missing `values` to the organization's property `name` and returns them. GitHub replaces the whole
+* definition on a write, so the current one is read and sent back with the allowed values extended, in their order,
+* and nothing removed. A write is made only when something is missing.
+*/
+async function addOrgPropertyValues(client, repo, name, values) {
+	const org = repo.split("/")[0];
+	const current = (await client.properties.orgSchema(org)).find((p) => p.property_name === name);
+	if (!current) throw new Error(`the organization ${org} has no custom property "${name}"; create it first`);
+	if (!current.allowed_values) throw new Error(`the custom property "${name}" takes any value; it has nothing to extend`);
+	const have = new Set(current.allowed_values);
+	const added = [...new Set(values)].filter((v) => !have.has(v));
+	if (added.length === 0) return [];
+	await client.properties.setOrgProperty(org, {
+		...current,
+		allowed_values: [...current.allowed_values, ...added]
+	});
+	return added;
+}
+// src/capabilities/read-repo.ts
+/** The settings `setup` writes, which `GET /repos/{repo}` reports under the same names. */
+const SETTING_KEYS = [
+	"allow_squash_merge",
+	"allow_merge_commit",
+	"allow_rebase_merge",
+	"allow_auto_merge",
+	"allow_update_branch",
+	"delete_branch_on_merge",
+	"has_issues",
+	"has_discussions",
+	"has_projects",
+	"has_wiki"
+];
+/** The repository's description, homepage, default branch, topics and settings, from one read. */
+async function readRepoInfo(client, repo) {
+	const data = await client.repos.getRepo(repo);
+	const settings = { default_branch: data.default_branch };
+	for (const key of SETTING_KEYS) {
+		const value = data[key];
+		if (value !== void 0) settings[key] = value;
+	}
+	return {
+		description: data.description ?? null,
+		homepage: data.homepage ?? null,
+		defaultBranch: data.default_branch,
+		topics: data.topics ?? [],
+		settings
+	};
+}
+/** A ruleset reduced to what `setup` writes: its enforcement, rule types and required status checks. */
+function toRulesetDetail(data) {
+	const rules = data.rules ?? [];
+	const checks = rules.find((r) => r.type === "required_status_checks")?.parameters?.required_status_checks;
+	return {
+		name: data.name,
+		enforcement: data.enforcement,
+		ruleTypes: rules.map((r) => r.type),
+		requiredChecks: Array.isArray(checks) ? checks.map((c) => String(c.context)) : []
+	};
+}
+/** The value, or `undefined` when GitHub refuses the read (permission, plan, feature absent). Other errors still throw. */
+async function readable(read) {
+	try {
+		return await read();
+	} catch (err) {
+		if (err instanceof ProviderApiError$1) return void 0;
+		throw err;
+	}
+}
+/** Which security features are on. One GitHub refuses to report is left out, not reported as off. */
+async function readSecurity(client, repo) {
+	const [data, alerts, fixes, reporting, codeScanning] = await Promise.all([
+		readable(() => client.repos.getRepo(repo)),
+		readable(() => client.security.vulnerabilityAlertsEnabled(repo)),
+		readable(() => client.security.automatedSecurityFixesEnabled(repo)),
+		readable(() => client.security.privateVulnerabilityReportingEnabled(repo)),
+		readable(() => client.security.codeScanningDefaultSetupState(repo))
+	]);
+	const analysis = data?.security_and_analysis;
+	const on = (feature) => {
+		const status = analysis?.[feature]?.status;
+		return status === void 0 ? void 0 : status === "enabled";
+	};
+	const found = {
+		vulnerabilityAlerts: alerts,
+		automatedSecurityFixes: fixes,
+		secretScanning: on("secret_scanning"),
+		secretScanningPushProtection: on("secret_scanning_push_protection"),
+		privateVulnerabilityReporting: reporting,
+		codeScanningDefaultSetup: codeScanning === void 0 ? void 0 : codeScanning === "configured"
+	};
+	return Object.fromEntries(Object.entries(found).filter(([, v]) => v !== void 0));
+}
+// src/capabilities/teams.ts
+/** Turns a team entry into slug and permission form; a bare slug gets `push`. */
 function normalizeTeamEntry(entry) {
 	if (typeof entry === "string") return {
 		slug: entry,
@@ -458,6 +1736,7 @@ function normalizeTeamEntry(entry) {
 	};
 	return entry;
 }
+/** Grants each team access to the repo and reports the outcome; throws when every team fails. */
 async function syncTeams(client, repo, teams) {
 	const [org = "", name = ""] = repo.split("/", 2);
 	const normalized = teams.map(normalizeTeamEntry);
@@ -470,17 +1749,132 @@ async function syncTeams(client, repo, teams) {
 	}
 	return `${succeeded} team${succeeded === 1 ? "" : "s"} synced`;
 }
-//#endregion
-//#region src/capabilities/topics.ts
+// src/capabilities/topics.ts
 async function syncTopics(client, repo, topics) {
 	await client.topics.setTopics(repo, topics);
 	return `${topics.length} topics set`;
 }
-//#endregion
-//#region src/capabilities/source.ts
+// src/capabilities/variables.ts
+/** GitHub's rule for a variable name: letters, digits and underscores, not starting with a digit or `GITHUB_`. */
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Longest name GitHub accepts. */
+const MAX_NAME = 256;
+function assertNames(names) {
+	for (const name of names) if (!NAME.test(name) || name.length > MAX_NAME || name.toUpperCase().startsWith("GITHUB_")) throw new Error(`invalid variable name ${JSON.stringify(name)}: use letters, digits and underscores (at most ${MAX_NAME}), not starting with a digit or GITHUB_`);
+}
+/** GitHub treats variable names as case-insensitive, so every comparison goes through this. */
+const key = (name) => name.toUpperCase();
+/**
+* Bring one scope's variables in line with the declaration: create what is missing, update what differs, leave what
+* already matches. Variables that exist but are not declared are left alone, or deleted with `prune`, except an
+* organization variable limited to selected repositories, which this client cannot manage and so is never deleted.
+* Returns a one-line summary, naming the ones left so drift is visible. In a dry run it only describes the changes.
+*/
+async function reconcile(client, repo, scope, wanted, opts) {
+	assertNames(wanted.map((w) => w.name));
+	const existing = new Map((await client.variables.listVariables(repo, scope)).map((v) => [key(v.name), v]));
+	const counts = {
+		created: 0,
+		updated: 0,
+		unchanged: 0,
+		deleted: 0
+	};
+	for (const want of wanted) {
+		const have = existing.get(key(want.name));
+		const body = {
+			name: want.name,
+			value: want.value
+		};
+		if (want.visibility) body["visibility"] = want.visibility;
+		if (!have) {
+			if (opts.dryRun) {
+				counts.created++;
+				continue;
+			}
+			try {
+				await client.variables.createVariable(repo, scope, body);
+				counts.created++;
+				continue;
+			} catch (err) {
+				if (!(err instanceof ProviderApiError && (err.status === 409 || err.status === 422))) throw err;
+			}
+		} else if (have.value === want.value && (!want.visibility || have.visibility === want.visibility)) {
+			counts.unchanged++;
+			continue;
+		}
+		if (!opts.dryRun) await client.variables.updateVariable(repo, scope, have?.name ?? want.name, body);
+		counts.updated++;
+	}
+	const declared = new Set(wanted.map((w) => key(w.name)));
+	const undeclared = [...existing.entries()].filter(([k]) => !declared.has(k)).map(([, v]) => v);
+	const unmanaged = undeclared.filter((v) => v.visibility === "selected");
+	if (opts.prune) for (const v of undeclared.filter((u) => u.visibility !== "selected")) {
+		if (!opts.dryRun) await client.variables.deleteVariable(repo, scope, v.name);
+		counts.deleted++;
+	}
+	const parts = opts.dryRun ? [
+		`would create ${counts.created}`,
+		`would update ${counts.updated}`,
+		`${counts.unchanged} unchanged`
+	] : [
+		`${counts.created} created`,
+		`${counts.updated} updated`,
+		`${counts.unchanged} unchanged`
+	];
+	if (counts.deleted > 0) parts.push(`${counts.deleted} ${opts.dryRun ? "would be deleted" : "deleted"}`);
+	const left = opts.prune ? unmanaged : undeclared;
+	if (left.length > 0) {
+		const why = opts.prune ? "limited to selected repositories, not managed" : "not declared, left alone";
+		parts.push(`${left.length} ${why}: ${left.map((v) => v.name).join(", ")}`);
+	}
+	return parts.join(", ");
+}
+/** Reconcile a repository's Actions variables. */
+function syncVariables(client, repo, variables, opts = {}) {
+	return reconcile(client, repo, { kind: "repo" }, Object.entries(variables).map(([name, value]) => ({
+		name,
+		value
+	})), {
+		prune: opts.prune === true,
+		dryRun: opts.dryRun === true
+	});
+}
+/** Reconcile an organization's Actions variables. `repo` is only the coordinate the client is bound to. */
+function syncOrgVariables(client, repo, org, variables, opts = {}) {
+	const wanted = Object.entries(variables).map(([name, v]) => ({
+		name,
+		value: v.value,
+		visibility: v.visibility
+	}));
+	return reconcile(client, repo, {
+		kind: "organization",
+		org
+	}, wanted, {
+		prune: opts.prune === true,
+		dryRun: opts.dryRun === true
+	});
+}
+// src/capabilities/source.ts
+function toPullRequest(raw) {
+	return {
+		number: raw.number,
+		title: raw.title,
+		state: raw.state,
+		merged: raw.merged_at !== null,
+		branch: raw.head.ref,
+		headSha: raw.head.sha,
+		url: raw.html_url
+	};
+}
+/**
+* The GitHub implementation of the `source` capability: repo settings, rulesets, branch protection, security
+* features and local workflow files.
+*/
 var GitHubSource = class {
 	client;
+	/** Capability key, always `"source"`. */
 	key = "source";
+	/** Provider name, always `"github"`. */
 	providerName = "github";
 	owner;
 	name;
@@ -488,6 +1882,7 @@ var GitHubSource = class {
 	repoRoot;
 	workflowDir;
 	orgClient;
+	userSyncClient;
 	baseUrl;
 	fetchImpl;
 	constructor(client, opts) {
@@ -496,15 +1891,20 @@ var GitHubSource = class {
 		this.owner = owner;
 		this.name = name;
 		this.repo = opts.repo;
-		this.repoRoot = opts.repoRoot;
-		this.workflowDir = join(opts.repoRoot, ".github", "workflows");
+		this.repoRoot = findRootSync(opts.repoRoot, ".git", {
+			fallback: "start",
+			realpath: true
+		});
+		this.workflowDir = join(this.repoRoot, ".github", "workflows");
 		this.orgClient = opts.orgClient;
+		this.userSyncClient = opts.userSyncClient;
 		this.baseUrl = opts.baseUrl;
 		this.fetchImpl = opts.fetch;
 	}
 	async whoami() {
 		return { login: (await this.client.user.getCurrentUser()).login };
 	}
+	/** Returns the repo's owner, name and default branch. */
 	async getRepo() {
 		const data = await this.client.repos.getRepo(this.repo);
 		return {
@@ -513,27 +1913,34 @@ var GitHubSource = class {
 			defaultBranch: data.default_branch
 		};
 	}
+	/** Lists the repo's rulesets. */
 	async listRulesets() {
 		return this.client.rulesets.listRulesets(this.repo);
 	}
+	/** Creates a ruleset from the given payload. */
 	async createRuleset(payload) {
 		return this.client.rulesets.createRuleset(this.repo, payload);
 	}
+	/** Updates the ruleset with the given id from the payload. */
 	async updateRuleset(id, payload) {
 		return this.client.rulesets.updateRuleset(this.repo, id, payload);
 	}
+	/** Updates the repo's settings. */
 	async updateRepoSettings(settings) {
 		await this.client.repos.updateRepo(this.repo, settings);
 	}
 	async protectBranch(branch, payload) {
 		await this.client.branches.protectBranch(this.repo, branch, payload);
 	}
+	/** Enables Dependabot vulnerability alerts. */
 	async enableVulnerabilityAlerts() {
 		await this.client.security.enableVulnerabilityAlerts(this.repo);
 	}
+	/** Enables Dependabot automated security fixes. */
 	async enableAutomatedSecurityFixes() {
 		await this.client.security.enableAutomatedSecurityFixes(this.repo);
 	}
+	/** Enables secret scanning. */
 	async enableSecretScanning() {
 		await this.client.security.enableSecretScanning(this.repo);
 	}
@@ -546,9 +1953,11 @@ var GitHubSource = class {
 	async enableDependencyGraph() {
 		await this.client.security.enableDependencyGraph(this.repo);
 	}
+	/** Enables private vulnerability reporting. */
 	async enablePrivateVulnerabilityReporting() {
 		await this.client.security.enablePrivateVulnerabilityReporting(this.repo);
 	}
+	/** Lists the `.yml` and `.yaml` files in `.github/workflows`, sorted by name; empty when the folder is missing. */
 	async listWorkflowFiles() {
 		try {
 			return (await readdir(this.workflowDir)).filter((e) => e.endsWith(".yml") || e.endsWith(".yaml")).sort();
@@ -557,6 +1966,7 @@ var GitHubSource = class {
 			throw err;
 		}
 	}
+	/** Reads a workflow file's text, or `null` when it does not exist. */
 	async readWorkflowFile(name) {
 		try {
 			return await readFile(join(this.workflowDir, name), "utf8");
@@ -565,10 +1975,12 @@ var GitHubSource = class {
 			throw err;
 		}
 	}
+	/** Writes a workflow file, creating `.github/workflows` first when needed. */
 	async writeWorkflowFile(name, contents) {
 		await ensureDir(this.workflowDir);
 		await writeFile(join(this.workflowDir, name), contents, "utf8");
 	}
+	/** Removes a workflow file; a file that is already gone is not an error. */
 	async removeWorkflowFile(name) {
 		try {
 			await rm(join(this.workflowDir, name));
@@ -586,14 +1998,83 @@ var GitHubSource = class {
 		return syncLabels(this.client, this.repo, canonical, stale);
 	}
 	async syncProperties(values) {
-		return syncProperties(this.client, this.repo, values);
+		return syncProperties(this.client, this.repo, values, this.orgClient ?? this.client);
+	}
+	async getOrgPropertyValues(name) {
+		return getOrgPropertyValues(this.orgClient ?? this.client, this.repo, name);
+	}
+	async addOrgPropertyValues(name, values) {
+		return addOrgPropertyValues(this.orgClient ?? this.client, this.repo, name, values);
+	}
+	async checkPropertyValues(values) {
+		return checkPropertyValues(this.orgClient ?? this.client, this.repo, values);
 	}
 	async syncTeams(teams) {
 		return syncTeams(this.orgClient ?? this.client, this.repo, teams);
 	}
+	async teamMembers(teamSlug, org = this.owner) {
+		return (await (this.orgClient ?? this.client).teams.members(org, teamSlug)).map((m) => ({
+			id: String(m.id),
+			login: m.login
+		}));
+	}
+	async readFile(path, repo = this.repo) {
+		return readRepoFile(this.userSyncClient ?? this.orgClient ?? this.client, repo, path);
+	}
+	async writeFile(path, content, opts) {
+		return writeRepoFile(this.userSyncClient ?? this.orgClient ?? this.client, opts.repo ?? this.repo, path, content, opts);
+	}
 	async syncTopics(topics) {
 		return syncTopics(this.client, this.repo, topics);
 	}
+	async syncVariables(variables, opts) {
+		return syncVariables(this.client, this.repo, variables, opts);
+	}
+	async syncOrgVariables(org, variables, opts) {
+		if (!this.orgClient) throw new Error("organization variables need the org token: set HOLOCRON_ORG_TOKEN or run `holocron new token github.org <token>`");
+		return syncOrgVariables(this.orgClient, this.repo, org, variables, opts);
+	}
+	async listVariables() {
+		const found = await this.client.variables.listVariables(this.repo, { kind: "repo" });
+		return Object.fromEntries(found.map((v) => [v.name, v.value]));
+	}
+	async listOrgVariables(org) {
+		if (!this.orgClient) throw new MissingTokenError("organization variables need the org token: set HOLOCRON_ORG_TOKEN or run `holocron new token github.org <token>`");
+		const found = await this.orgClient.variables.listVariables(this.repo, {
+			kind: "organization",
+			org
+		});
+		return Object.fromEntries(found.map((v) => [v.name, {
+			value: v.value,
+			visibility: v.visibility ?? "all"
+		}]));
+	}
+	async getRepoInfo() {
+		return readRepoInfo(this.client, this.repo);
+	}
+	async getProperties() {
+		const found = await this.client.properties.getValues(this.repo);
+		return Object.fromEntries(found.flatMap((p) => p.value === null ? [] : [[p.property_name, p.value]]));
+	}
+	async listLabels() {
+		return (await this.client.labels.listLabels(this.repo)).map((l) => ({
+			name: l.name,
+			color: l.color,
+			description: l.description ?? ""
+		}));
+	}
+	async listTeamAccess() {
+		return (await (this.orgClient ?? this.client).teams.listForRepo(this.repo)).map((t) => ({
+			slug: t.slug,
+			permission: t.permission
+		}));
+	}
+	async getRulesetDetail(id) {
+		return toRulesetDetail(await this.client.rulesets.getRuleset(this.repo, id));
+	}
+	async getSecurity() {
+		return readSecurity(this.client, this.repo);
+	}
 	async syncDescription(description) {
 		await this.client.repos.updateRepo(this.repo, { description });
 		return "description updated";
@@ -603,15 +2084,27 @@ var GitHubSource = class {
 		return "homepage updated";
 	}
 	async getPullRequest(number, repo) {
-		const raw = await this.client.pulls.getPullRequest(repo ?? this.repo, number);
-		return {
-			number: raw.number,
-			title: raw.title,
-			state: raw.state,
-			merged: raw.merged_at !== null,
-			branch: raw.head.ref,
-			url: raw.html_url
-		};
+		return toPullRequest(await this.client.pulls.getPullRequest(repo ?? this.repo, number));
+	}
+	async listPullRequests(state, repo) {
+		return (await this.client.pulls.listPullRequests(repo ?? this.repo, state)).map(toPullRequest);
+	}
+	async listBranches(repo) {
+		return (await this.client.branches.listBranches(repo ?? this.repo)).map((b) => ({
+			name: b.name,
+			sha: b.commit.sha
+		}));
+	}
+	async deleteBranch(name, repo) {
+		try {
+			await this.client.branches.removeBranch(repo ?? this.repo, name);
+		} catch (err) {
+			if (err instanceof ProviderApiError && err.status === 422 && String(err.details).includes("does not exist")) return;
+			throw err;
+		}
+	}
+	async listPullRequestCommits(number, repo) {
+		return (await this.client.pulls.listCommits(repo ?? this.repo, number)).map((commit) => commit.sha);
 	}
 	async configurePages(config, token) {
 		const pagesClient = createGitHubClient$1({
@@ -650,18 +2143,8 @@ async function ensureDir(path) {
 		throw err;
 	}
 }
-//#endregion
-//#region src/verify-token.ts
-/**
-* `verifyToken` — plugin-level export used by `holocron auth set` +
-* `holocron auth check`. Hits `GET /user` and translates the response
-* into the normalized `VerifyTokenResult` shape.
-*
-* Kept as a standalone function (not a capability method) so the auth
-* command can call it without initializing the full plugin — plugin
-* construction requires an already-resolved token, which is exactly
-* what we don't have yet at bootstrap time.
-*/
+// src/verify-token.ts
+/** Checks a token against `GET /user` and returns who it belongs to, or why it failed. */
 async function verifyToken(token, opts = {}) {
 	const client = createGitHubClient({
 		token,
@@ -669,49 +2152,61 @@ async function verifyToken(token, opts = {}) {
 		fetch: opts.fetch
 	});
 	try {
-		const me = await client.user.getCurrentUser();
+		const { user: me, expiresAt } = await client.user.getCurrentUserWithExpiry();
 		return {
 			ok: true,
-			subject: `user @ ${me.login ?? me.email ?? "unknown"}`
+			subject: `user @ ${me.login ?? me.email ?? "unknown"}`,
+			...expiresAt ? { expiresAt } : {}
 		};
 	} catch (err) {
 		return {
 			ok: false,
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
-//#endregion
-//#region src/index.ts
-function source(ctx, orgClient) {
+// src/index.ts
+/** Builds the `source` capability; the optional clients cover org-level and user-sync access. */
+function source(ctx, orgClient, userSyncClient) {
 	return new GitHubSource(ctx.client, {
 		repo: ctx.repo,
 		repoRoot: ctx.repoRoot,
 		orgClient,
+		userSyncClient,
 		baseUrl: ctx.options.baseUrl,
 		fetch: ctx.options.fetch
 	});
 }
-function secrets(ctx) {
-	return new GitHubSecrets(ctx.client, { repo: ctx.repo });
+/** Builds the `secrets` capability; the optional client handles organization secrets. */
+function secrets(ctx, orgClient) {
+	return new GitHubSecrets(ctx.client, { repo: ctx.repo }, orgClient);
 }
+/** Builds the `environments` capability. */
 function environments(ctx) {
 	return new GitHubEnvironments(ctx.client, { repo: ctx.repo });
 }
+/** Builds the `ci` capability. */
 function ci(ctx) {
 	return new GitHubCi(ctx.client, { repo: ctx.repo });
 }
+/** Builds the `issues` capability, passing the lifecycle labels when configured. */
 function issues(ctx) {
 	const opts = { repo: ctx.repo };
 	if (ctx.options.labels !== void 0) opts.labels = ctx.options.labels;
 	return new GitHubIssues(ctx.client, opts);
 }
+/** Builds the `projects` capability: GitHub Projects v2 over GraphQL, with items keyed relative to the configured repo. */
+function projects(ctx) {
+	return new GitHubProjects(ctx.client.graphql, { repo: ctx.repo });
+}
+/** Creates the plugin, resolving a token per capability when it is first used. */
 function createPlugin(options) {
 	function makeCtx(resolver) {
+		const token = resolver(options);
 		return {
 			options,
 			client: createGitHubClient$1({
-				token: resolver(options),
+				token,
 				baseUrl: options.baseUrl,
 				fetch: options.fetch
 			}),
@@ -719,10 +2214,45 @@ function createPlugin(options) {
 			repoRoot: options.repoRoot ?? process.cwd()
 		};
 	}
+	/** A token, or undefined when that feature token is simply not configured. */
+	function tryResolve(resolver) {
+		try {
+			return resolver(options);
+		} catch (err) {
+			if (err instanceof AuthError) return void 0;
+			throw err;
+		}
+	}
+	/**
+	* Organization secrets need an org-resource-owner token (`github.secrets`);
+	* repo and environment secrets need `github.admin`. Each scope prefers its own
+	* token and falls back to the other, so a setup with only one of them keeps
+	* working, and an explicit `--token` serves both. With neither configured this
+	* fails exactly as the admin-token capabilities do.
+	*/
+	function makeSecrets() {
+		const secretsToken = tryResolve(resolveSecretsToken);
+		const adminToken = tryResolve(resolveAdminToken);
+		if (!secretsToken && !adminToken) resolveAdminToken(options);
+		const clientFor = (token) => createGitHubClient$1({
+			token,
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		});
+		const repoClient = clientFor(adminToken ?? secretsToken);
+		const orgClient = clientFor(secretsToken ?? adminToken);
+		return secrets({
+			options,
+			client: repoClient,
+			repo: options.repo,
+			repoRoot: options.repoRoot ?? process.cwd()
+		}, orgClient);
+	}
 	function makeOrgClient() {
 		try {
+			const token = resolveOrgToken(options);
 			return createGitHubClient$1({
-				token: resolveOrgToken(options),
+				token,
 				baseUrl: options.baseUrl,
 				fetch: options.fetch
 			});
@@ -730,21 +2260,58 @@ function createPlugin(options) {
 			return;
 		}
 	}
+	/** The token for the user-sync files; undefined when it is not configured, and the org token is used instead. */
+	function makeUserSyncClient() {
+		const token = tryResolve(resolveUserSyncToken);
+		return token ? createGitHubClient$1({
+			token,
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		}) : void 0;
+	}
 	return {
 		name: "@theholocron/holocron-plugin-github",
+		probes: { connection: connectionProbe({
+			provider: "GitHub",
+			url: options.baseUrl ?? "https://api.github.com",
+			fetch: options.fetch,
+			token: () => resolveReadToken(options),
+			verify: (token) => verifyToken(token, {
+				baseUrl: options.baseUrl,
+				fetch: options.fetch
+			})
+		}) },
 		capabilities: {
-			source: () => source(makeCtx(resolveAdminToken), makeOrgClient()),
+			source: () => source(makeCtx(resolveAdminToken), makeOrgClient(), makeUserSyncClient()),
 			ci: () => ci(makeCtx(resolveReadToken)),
-			secrets: () => secrets(makeCtx(resolveAdminToken)),
+			secrets: () => makeSecrets(),
 			environments: () => environments(makeCtx(resolveAdminToken)),
-			issues: () => issues(makeCtx(resolveIssuesToken))
+			issues: () => issues(makeCtx(resolveIssuesToken)),
+			projects: () => projects(makeCtx(resolveOrgToken))
 		}
 	};
 }
 /**
-* One-line hint printed by `holocron auth set github` when no token
+* One-line hint printed by `holocron new token github` when no token
 * is supplied or the supplied token is rejected.
 */
-const AUTH_HINT = "generate fine-grained Personal Access Tokens at https://github.com/settings/tokens (one per feature — see docs/tokens.md for required scopes per operation), then run: holocron auth set github.<feature> <PAT>";
-//#endregion
-export { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubSecrets, GitHubSource, ci, createFeatureResolver, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, resolveAdminToken, resolveDeployToken, resolveIssuesToken, resolveOrgToken, resolveReadToken, resolveReleaseToken, resolveSyncToken, secrets, source, syncLabels, syncTeams, verifyToken };
+const AUTH_HINT = "generate fine-grained Personal Access Tokens at https://github.com/settings/tokens (one per feature — see docs/tokens.md for required scopes per operation), then run: holocron new token github.<feature> <PAT>";
+/**
+* Every token this plugin takes, for `holocron doctor secrets --verify`. The release token is `optional`: only CI's release
+* workflow reads it (from the org secret), so a development environment has no reason to hold it.
+*/
+const tokens = [
+	resolveReadToken.token,
+	resolveIssuesToken.token,
+	resolveSyncToken.token,
+	{
+		...resolveReleaseToken.token,
+		optional: true
+	},
+	resolveAdminToken.token,
+	resolveSecretsToken.token,
+	resolveDeployToken.token,
+	resolveUserSyncToken.token,
+	resolveOrgToken.token
+];
+export { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubProjects, GitHubSecrets, GitHubSource, ci, createFeatureResolver, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, projects, resolveAdminToken, resolveDeployToken, resolveIssuesToken, resolveOrgToken, resolveReadToken, resolveReleaseToken, resolveSecretsToken, resolveSyncToken, resolveUserSyncToken, secrets, source, syncLabels, syncTeams, tokens, verifyToken };