@theholocron/holocron-plugin-github 5.0.0-alpha.28 → 5.0.0-alpha.280

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,7 @@ 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/sodium.ts
 /**
 * libsodium sealed-box encryption for GitHub Actions secrets.
 *
@@ -369,32 +407,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 +456,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 +533,149 @@ async function syncLabels(client, repo, canonical, stale) {
 	}
 	return `${created} created, ${updated} updated, ${deleted} deleted`;
 }
-//#endregion
-//#region src/capabilities/properties.ts
+// 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;
+	}
+}
+/**
+* Sets the repo's custom properties. When GitHub answers 422 the error says which value it refused: the values
+* are compared with the organization's property definitions (read-only), and GitHub's own message is added.
+* One refused value fails the whole request, so none of the properties is set.
+*/
 async function syncProperties(client, repo, values) {
-	await client.properties.setProperties(repo, values);
+	try {
+		await client.properties.setProperties(repo, values);
+	} catch (err) {
+		if (!(err instanceof ProviderApiError$1) || err.status !== 422) throw err;
+		const schema = await orgSchema(client, repo);
+		const problems = schema ? rejectedProperties(values, schema) : [];
+		const said = githubMessage(err.details);
+		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}`, { 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 +683,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 +696,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 +829,7 @@ var GitHubSource = class {
 	repoRoot;
 	workflowDir;
 	orgClient;
+	userSyncClient;
 	baseUrl;
 	fetchImpl;
 	constructor(client, opts) {
@@ -496,15 +838,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 +860,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 +900,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 +913,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 +922,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));
@@ -591,9 +950,69 @@ var GitHubSource = class {
 	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 +1022,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 +1081,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 +1090,57 @@ 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);
 }
+/** 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 +1148,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,12 +1194,31 @@ 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))
 		}
@@ -746,5 +1229,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, GitHubSecrets, GitHubSource, ci, createFeatureResolver, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, resolveAdminToken, resolveDeployToken, resolveIssuesToken, resolveOrgToken, resolveReadToken, resolveReleaseToken, resolveSecretsToken, resolveSyncToken, resolveUserSyncToken, secrets, source, syncLabels, syncTeams, tokens, verifyToken };