@theholocron/holocron-plugin-github 5.0.0-alpha.34 → 5.0.0-alpha.340

package/dist/index.mjs

@@ -1,48 +1,74 @@
 import { createRequire } from "node:module";
+import { AuthError, MissingTokenError, ProviderApiError, connectionProbe, createFeatureResolver } 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,13 @@ var GitHubEnvironments = class {
 		}));
 	}
 };
-//#endregion
-//#region src/capabilities/issues.ts
+// src/capabilities/issues.ts
+/** 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,6 +179,7 @@ var GitHubIssues = class {
 			...raw.email ? { emailAddress: raw.email } : {}
 		};
 	}
+	/** Searches the repo's issues, newest update first, leaving out pull requests. */
 	async search(filter) {
 		const params = {
 			state: filter.openOnly ? "open" : "all",
@@ -164,11 +199,13 @@ var GitHubIssues = class {
 			assignee: params.assignee
 		})).filter((i) => !i.pull_request).map((i) => this.mapIssue(i));
 	}
+	/** 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 +253,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);
@@ -337,8 +376,504 @@ 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 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;
+			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))
+			};
+		});
+	}
+	/** 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;
+	}
+	/** 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 +904,46 @@ 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;
+	}
+	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 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);
+		await client.secrets.putSecret(this.opts.repo, ghScope, name, body);
 	}
+	/** 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 +953,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 auth set 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 +1030,179 @@ 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 repo setup again`);
+}
+// src/capabilities/rejected-properties.ts
+/** The values `repo 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
+// src/capabilities/read-repo.ts
+/** The settings `repo 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 `repo 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 +1210,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 +1223,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 +1356,7 @@ var GitHubSource = class {
 	repoRoot;
 	workflowDir;
 	orgClient;
+	userSyncClient;
 	baseUrl;
 	fetchImpl;
 	constructor(client, opts) {
@@ -496,15 +1365,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 +1387,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 +1427,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 +1440,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 +1449,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 +1472,77 @@ 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 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 auth set 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 auth set 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 +1552,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 +1611,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 +1620,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 +1682,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,14 +1728,34 @@ 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))
 		}
 	};
 }
@@ -746,5 +1764,16 @@ function createPlugin(options) {
 * 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 };
+/** Every token this plugin takes, for `holocron doctor tokens`. */
+const tokens = [
+	resolveReadToken,
+	resolveIssuesToken,
+	resolveSyncToken,
+	resolveReleaseToken,
+	resolveAdminToken,
+	resolveSecretsToken,
+	resolveDeployToken,
+	resolveUserSyncToken,
+	resolveOrgToken
+].map((resolver) => resolver.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 };