@theholocron/holocron-plugin-github 5.0.0-alpha.27 → 5.0.0-alpha.271

package/README.md

@@ -45,7 +45,7 @@ holocron auth set github.release  ghp_xxx  # semantic-release
 holocron auth set github.admin    ghp_xxx  # setup, secrets, environments
 ```
 
-See [docs/tokens.md](../../docs/tokens.md) for full scope requirements and CI setup.
+See the [token reference](https://docs.theholocron.dev/holocron/tokens/) for full scope requirements and CI setup.
 
 ## Config
 

package/dist/index.d.mts

@@ -1,19 +1,18 @@
+import { Auth, AuthError, Ci, CiRun, CiRunFilter, Environment, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, PagesConfig, PluginToken, PullRequest, RepoRef, RepoSettings, ResolveTokenInput, Ruleset, SecretScope, Secrets, Source, SourceBranch, SourceFile, SourceTeamMember, TeamEntry, TeamEntry as TeamEntry$1, TeamPermission, TrackerDoctorReport, TrackerUser, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, createFeatureResolver } from "@theholocron/cli";
 import { GitHubClient, GitHubClientOptions, createGitHubClient } from "@theholocron/github-client";
-import { Auth, AuthError, Ci, CiRun, CiRunFilter, Environment, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, PagesConfig, PullRequest, RepoRef, RepoSettings, ResolveTokenInput, Ruleset, SecretScope, Secrets, Source, TeamEntry, TeamEntry as TeamEntry$1, TeamPermission, TrackerDoctorReport, TrackerUser, createFeatureResolver } from "@theholocron/cli";
-//#region src/auth.d.ts
-declare const resolveReadToken: (input?: ResolveTokenInput) => string;
-declare const resolveIssuesToken: (input?: ResolveTokenInput) => string;
-declare const resolveSyncToken: (input?: ResolveTokenInput) => string;
-declare const resolveReleaseToken: (input?: ResolveTokenInput) => string;
-declare const resolveAdminToken: (input?: ResolveTokenInput) => string;
-declare const resolveDeployToken: (input?: ResolveTokenInput) => string;
-declare const resolveOrgToken: (input?: ResolveTokenInput) => string;
-//#endregion
-//#region src/capabilities/ci.d.ts
+export declare const resolveReadToken: import("@theholocron/cli").FeatureResolver;
+export declare const resolveIssuesToken: import("@theholocron/cli").FeatureResolver;
+export declare const resolveSyncToken: import("@theholocron/cli").FeatureResolver;
+export declare const resolveReleaseToken: import("@theholocron/cli").FeatureResolver;
+export declare const resolveAdminToken: import("@theholocron/cli").FeatureResolver;
+export declare const resolveSecretsToken: import("@theholocron/cli").FeatureResolver;
+export declare const resolveDeployToken: import("@theholocron/cli").FeatureResolver;
+export declare const resolveUserSyncToken: import("@theholocron/cli").FeatureResolver;
+export declare const resolveOrgToken: import("@theholocron/cli").FeatureResolver;
 interface CiOptions {
   repo: string;
 }
-declare class GitHubCi implements Ci {
+export declare class GitHubCi implements Ci {
   private readonly client;
   private readonly opts;
   readonly key: "ci";
@@ -24,12 +23,10 @@ declare class GitHubCi implements Ci {
   private mapRun;
   private mapConclusion;
 }
-//#endregion
-//#region src/capabilities/environments.d.ts
 interface EnvironmentsOptions {
   repo: string;
 }
-declare class GitHubEnvironments implements Environments {
+export declare class GitHubEnvironments implements Environments {
   private readonly client;
   private readonly opts;
   readonly key: "environments";
@@ -40,8 +37,6 @@ declare class GitHubEnvironments implements Environments {
   deleteEnvironment(name: string): Promise<void>;
   private flattenReviewers;
 }
-//#endregion
-//#region src/capabilities/issues.d.ts
 interface IssuesOptions {
   repo: string;
   /**
@@ -55,7 +50,7 @@ interface IssuesOptions {
     inReview: string;
   };
 }
-declare class GitHubIssues implements Issues {
+export declare class GitHubIssues implements Issues {
   private readonly client;
   readonly key: "issues";
   readonly providerName = "github";
@@ -82,8 +77,6 @@ declare class GitHubIssues implements Issues {
   private removeStatusLabels;
   private mapIssue;
 }
-//#endregion
-//#region src/capabilities/labels.d.ts
 interface CanonicalLabel {
   readonly name: string;
   readonly color: string;
@@ -97,34 +90,39 @@ interface CanonicalLabel {
  * - DELETEs labels listed in `stale`.
  * - Leaves unrecognised labels that aren't in `stale` untouched.
  */
-declare function syncLabels(client: GitHubClient, repo: string, canonical: ReadonlyArray<CanonicalLabel>, stale: ReadonlyArray<string>): Promise<string>;
-//#endregion
-//#region src/capabilities/secrets.d.ts
+export declare function syncLabels(client: GitHubClient, repo: string, canonical: ReadonlyArray<CanonicalLabel>, stale: ReadonlyArray<string>): Promise<string>;
 interface SecretsOptions {
   repo: string;
 }
-declare class GitHubSecrets implements Secrets {
+export declare class GitHubSecrets implements Secrets {
   private readonly client;
   private readonly opts;
+  private readonly orgClient?;
   readonly key: "secrets";
   readonly providerName = "github";
-  constructor(client: GitHubClient, opts: SecretsOptions);
+  /**
+   * `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: GitHubClient, opts: SecretsOptions, orgClient?: GitHubClient | undefined);
+  private clientFor;
   listSecrets(scope: SecretScope): Promise<string[]>;
   setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
   deleteSecret(scope: SecretScope, name: string): Promise<void>;
 }
-//#endregion
-//#region src/capabilities/source.d.ts
 interface SourceOptions {
   repo: string;
   repoRoot: string;
   /** Secondary client authenticated with HOLOCRON_ORG_TOKEN for org-scoped operations (teams, custom properties). */
   orgClient?: GitHubClient;
+  /** Client for the files that link GitHub accounts to other services (HOLOCRON_USER_SYNC_TOKEN); falls back to the org client. */
+  userSyncClient?: GitHubClient;
   /** Forwarded to a secondary client created for Pages calls (HOLOCRON_DEPLOY_TOKEN). */
   baseUrl?: string;
   fetch?: typeof fetch;
 }
-declare class GitHubSource implements Source {
+export declare class GitHubSource implements Source {
   private readonly client;
   readonly key: "source";
   readonly providerName = "github";
@@ -134,6 +132,7 @@ declare class GitHubSource implements Source {
   private readonly repoRoot;
   private readonly workflowDir;
   private readonly orgClient?;
+  private readonly userSyncClient?;
   private readonly baseUrl?;
   private readonly fetchImpl?;
   constructor(client: GitHubClient, opts: SourceOptions);
@@ -161,56 +160,56 @@ declare class GitHubSource implements Source {
   syncLabels(canonical: ReadonlyArray<LabelDef>, stale: ReadonlyArray<string>): Promise<string>;
   syncProperties(values: Record<string, string | string[]>): Promise<string>;
   syncTeams(teams: TeamEntry$1[]): Promise<string>;
+  teamMembers(teamSlug: string, org?: string): Promise<SourceTeamMember[]>;
+  readFile(path: string, repo?: string): Promise<SourceFile | null>;
+  writeFile(path: string, content: string, opts: {
+    message: string;
+    version?: string;
+    repo?: string;
+  }): Promise<void>;
   syncTopics(topics: string[]): Promise<string>;
+  syncVariables(variables: Record<string, string>, opts?: {
+    prune?: boolean;
+    dryRun?: boolean;
+  }): Promise<string>;
+  syncOrgVariables(org: string, variables: Record<string, {
+    value: string;
+    visibility: "all" | "private";
+  }>, opts?: {
+    prune?: boolean;
+    dryRun?: boolean;
+  }): Promise<string>;
+  listVariables(): Promise<Record<string, string>>;
+  listOrgVariables(org: string): Promise<Record<string, {
+    value: string;
+    visibility: "all" | "private" | "selected";
+  }>>;
   syncDescription(description: string): Promise<string>;
   syncHomepage(homepage: string): Promise<string>;
   getPullRequest(number: number, repo?: string): Promise<PullRequest>;
+  listPullRequests(state: "open" | "closed", repo?: string): Promise<PullRequest[]>;
+  listBranches(repo?: string): Promise<SourceBranch[]>;
+  deleteBranch(name: string, repo?: string): Promise<void>;
+  listPullRequestCommits(number: number, repo?: string): Promise<string[]>;
   configurePages(config: PagesConfig, token: string): Promise<void>;
 }
-//#endregion
-//#region src/capabilities/teams.d.ts
 interface NormalizedTeamEntry {
   slug: string;
   permission: TeamPermission;
 }
-declare function normalizeTeamEntry(entry: TeamEntry): NormalizedTeamEntry;
-declare function syncTeams(client: GitHubClient, repo: string, teams: TeamEntry[]): Promise<string>;
-//#endregion
-//#region src/sodium.d.ts
+export declare function normalizeTeamEntry(entry: TeamEntry): NormalizedTeamEntry;
+export declare function syncTeams(client: GitHubClient, repo: string, teams: TeamEntry[]): Promise<string>;
 /**
  * Encrypt `value` for the given GitHub-provided base64 public key.
  * Returns the base64 ciphertext to send as `encrypted_value`.
  */
-declare function encryptSecret(publicKeyBase64: string, value: string): Promise<string>;
-//#endregion
-//#region src/verify-token.d.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.
- */
-interface VerifyTokenSuccess {
-  ok: true;
-  subject: string;
-}
-interface VerifyTokenFailure {
-  ok: false;
-  message: string;
-}
-type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+export declare function encryptSecret(publicKeyBase64: string, value: string): Promise<string>;
 interface VerifyTokenOptions {
   baseUrl?: string;
   fetch?: typeof fetch;
 }
-declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
-//#endregion
-//#region src/index.d.ts
-interface GitHubPluginOptions extends ResolveTokenInput {
+export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
+export interface GitHubPluginOptions extends ResolveTokenInput {
   /** "owner/name" — e.g., "theholocron/holocron". Required. */
   repo: string;
   /** Absolute path to the working repo root. Used by `source`'s
@@ -226,19 +225,22 @@ interface GitHubPluginOptions extends ResolveTokenInput {
   /** Override `fetch` for tests. Defaults to global `fetch`. */
   fetch?: typeof fetch;
 }
-interface PluginContext {
+export interface PluginContext {
   options: GitHubPluginOptions;
   client: GitHubClient;
   repo: string;
   repoRoot: string;
 }
-declare function source(ctx: PluginContext, orgClient?: GitHubClient): Source;
-declare function secrets(ctx: PluginContext): Secrets;
-declare function environments(ctx: PluginContext): Environments;
-declare function ci(ctx: PluginContext): Ci;
-declare function issues(ctx: PluginContext): Issues;
-declare function createPlugin(options: GitHubPluginOptions): {
+export declare function source(ctx: PluginContext, orgClient?: GitHubClient, userSyncClient?: GitHubClient): Source;
+export declare function secrets(ctx: PluginContext, orgClient?: GitHubClient): Secrets;
+export declare function environments(ctx: PluginContext): Environments;
+export declare function ci(ctx: PluginContext): Ci;
+export declare function issues(ctx: PluginContext): Issues;
+export declare function createPlugin(options: GitHubPluginOptions): {
   name: string;
+  probes: {
+    connection: import("@theholocron/cli").Probe;
+  };
   capabilities: {
     source: () => Source;
     ci: () => Ci;
@@ -251,6 +253,7 @@ declare function createPlugin(options: GitHubPluginOptions): {
  * One-line hint printed by `holocron auth set github` when no token
  * is supplied or the supplied token is rejected.
  */
-declare const AUTH_HINT: string;
-//#endregion
-export { AUTH_HINT, type Auth, AuthError, type CanonicalLabel, GitHubCi, type GitHubClientOptions, GitHubEnvironments, GitHubIssues, GitHubPluginOptions, GitHubSecrets, GitHubSource, type NormalizedTeamEntry, PluginContext, type ResolveTokenInput, type TeamEntry, type TeamPermission, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, ci, createFeatureResolver, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, resolveAdminToken, resolveDeployToken, resolveIssuesToken, resolveOrgToken, resolveReadToken, resolveReleaseToken, resolveSyncToken, secrets, source, syncLabels, syncTeams, verifyToken };
+export declare const AUTH_HINT: string;
+/** Every token this plugin takes, for `holocron doctor tokens`. */
+export declare const tokens: PluginToken[];
+export { type Auth, AuthError, type CanonicalLabel, type GitHubClientOptions, type NormalizedTeamEntry, type ResolveTokenInput, type TeamEntry, type TeamPermission, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createFeatureResolver, createGitHubClient };

package/dist/index.mjs

@@ -1,9 +1,12 @@
 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
 const resolveReadToken = createFeatureResolver({
 	envName: "HOLOCRON_READ_TOKEN",
 	keyringKey: "github.read"
@@ -24,16 +27,23 @@ const resolveAdminToken = createFeatureResolver({
 	envName: "HOLOCRON_ADMIN_TOKEN",
 	keyringKey: "github.admin"
 });
+const resolveSecretsToken = createFeatureResolver({
+	envName: "HOLOCRON_SECRETS_TOKEN",
+	keyringKey: "github.secrets"
+});
 const resolveDeployToken = createFeatureResolver({
 	envName: "HOLOCRON_DEPLOY_TOKEN",
 	keyringKey: "github.deploy"
 });
+const resolveUserSyncToken = createFeatureResolver({
+	envName: "HOLOCRON_USER_SYNC_TOKEN",
+	keyringKey: "github.user-sync"
+});
 const resolveOrgToken = createFeatureResolver({
 	envName: "HOLOCRON_ORG_TOKEN",
 	keyringKey: "github.org"
 });
-//#endregion
-//#region src/capabilities/ci.ts
+// src/capabilities/ci.ts
 var GitHubCi = class {
 	client;
 	opts;
@@ -77,8 +87,7 @@ var GitHubCi = class {
 		}
 	}
 };
-//#endregion
-//#region src/capabilities/environments.ts
+// src/capabilities/environments.ts
 var GitHubEnvironments = class {
 	client;
 	opts;
@@ -119,8 +128,7 @@ var GitHubEnvironments = class {
 		}));
 	}
 };
-//#endregion
-//#region src/capabilities/issues.ts
+// src/capabilities/issues.ts
 var GitHubIssues = class {
 	client;
 	key = "issues";
@@ -337,8 +345,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 +376,42 @@ 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
 var GitHubSecrets = class {
 	client;
 	opts;
+	orgClient;
 	key = "secrets";
 	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);
 	}
 	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 +421,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 +498,74 @@ 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/teams.ts
 function normalizeTeamEntry(entry) {
 	if (typeof entry === "string") return {
 		slug: entry,
@@ -470,14 +585,123 @@ 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
+	};
+}
 var GitHubSource = class {
 	client;
 	key = "source";
@@ -488,6 +712,7 @@ var GitHubSource = class {
 	repoRoot;
 	workflowDir;
 	orgClient;
+	userSyncClient;
 	baseUrl;
 	fetchImpl;
 	constructor(client, opts) {
@@ -496,9 +721,13 @@ 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;
 	}
@@ -591,9 +820,43 @@ 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 syncDescription(description) {
 		await this.client.repos.updateRepo(this.repo, { description });
 		return "description updated";
@@ -603,15 +866,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 +925,7 @@ 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
 async function verifyToken(token, opts = {}) {
 	const client = createGitHubClient({
 		token,
@@ -669,31 +933,32 @@ 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
+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 });
+function secrets(ctx, orgClient) {
+	return new GitHubSecrets(ctx.client, { repo: ctx.repo }, orgClient);
 }
 function environments(ctx) {
 	return new GitHubEnvironments(ctx.client, { repo: ctx.repo });
@@ -708,10 +973,11 @@ function issues(ctx) {
 }
 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 +985,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 +1031,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 +1066,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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "5.0.0-alpha.27",
+  "version": "5.0.0-alpha.271",
   "description": "Holocron plugin for GitHub. Implements source, ci, secrets, environments, and issues capabilities against the GitHub REST API.",
   "keywords": [
     "ci",
@@ -9,12 +9,12 @@
     "plugin",
     "source"
   ],
-  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-github#readme",
+  "homepage": "https://docs.theholocron.dev/holocron/plugins/github/",
   "bugs": "https://github.com/theholocron/holocron/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/theholocron/holocron.git",
-    "directory": "packages/holocron-plugin-github"
+    "directory": "plugins/holocron-plugin-github"
   },
   "license": "MIT",
   "author": "Newton Koumantzelis",
@@ -34,27 +34,31 @@
     "libsodium-wrappers": "^0.8.4"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.0.0",
-    "@theholocron/github-client": "^1.23.0",
-    "@theholocron/http-client": "^1.23.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/tsdown-config": "^8.0.0",
-    "@theholocron/vitest-config": "^8.0.0",
     "@types/node": "^26",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^5.0.5",
     "@vitest/eslint-plugin": "^1.6.27",
     "eslint": "^10.8.1",
     "eslint-plugin-n": "^18.3.0",
     "globals": "^17.11.0",
-    "tsdown": "^0.22.14",
-    "tsx": "4.23.12",
+    "tsdown": "^0.23.3",
+    "tsx": "4.23.15",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.27"
+    "vitest": "^5.0.5",
+    "@theholocron/cli": "5.0.0-alpha.271",
+    "@theholocron/eslint-config": "^8.9.0-alpha.3",
+    "@theholocron/fs-utils": "^1.16.1-alpha.1",
+    "@theholocron/http-client": "^1.58.0-alpha.2",
+    "@theholocron/misc-utils": "^1.16.1-alpha.1",
+    "@theholocron/tsconfig": "^8.9.0-alpha.3",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
+    "@theholocron/github-client": "^1.58.0-alpha.2",
+    "@theholocron/vitest-config": "^8.9.0-alpha.3"
   },
   "peerDependencies": {
-    "@theholocron/github-client": "^1.23.0",
-    "@theholocron/cli": "5.0.0-alpha.27"
+    "@theholocron/fs-utils": "^1.16.0",
+    "@theholocron/github-client": "^1.58.0",
+    "@theholocron/misc-utils": "^1.16.0",
+    "@theholocron/cli": "5.0.0-alpha.271"
   },
   "engines": {
     "node": ">=22"
@@ -64,10 +68,10 @@
   },
   "scripts": {
     "delivery.build": "tsdown",
-    "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
+    "sourceQuality.staticAnalysis": "eslint .",
     "test:watch": "vitest",
     "validate": "tsx scripts/validate.mjs",
-    "verification.typeSafety": "holocron run verification.typeSafety --",
-    "verification.unitTests": "holocron run verification.unitTests --"
+    "verification.typeSafety": "tsc --noEmit",
+    "verification.unitTests": "vitest run"
   }
 }