@theholocron/holocron-plugin-github 5.0.0-alpha.209 → 5.0.0-alpha.210

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

@@ -181,6 +181,17 @@ declare class GitHubSource implements Source {
     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>;
   syncDescription(description: string): Promise<string>;
   syncHomepage(homepage: string): Promise<string>;
   getPullRequest(number: number, repo?: string): Promise<PullRequest>;

package/dist/index.mjs

@@ -538,6 +538,107 @@ async function syncTopics(client, repo, topics) {
 	return `${topics.length} topics set`;
 }
 //#endregion
+//#region 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
+	});
+}
+//#endregion
 //#region src/capabilities/source.ts
 var GitHubSource = class {
 	client;
@@ -672,6 +773,13 @@ var GitHubSource = class {
 	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 syncDescription(description) {
 		await this.client.repos.updateRepo(this.repo, { description });
 		return "description updated";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "5.0.0-alpha.209",
+  "version": "5.0.0-alpha.210",
   "description": "Holocron plugin for GitHub. Implements source, ci, secrets, environments, and issues capabilities against the GitHub REST API.",
   "keywords": [
     "ci",
@@ -36,7 +36,7 @@
   "devDependencies": {
     "@theholocron/eslint-config": "^8.8.2",
     "@theholocron/fs-utils": "^1.16.0",
-    "@theholocron/github-client": "^1.47.1",
+    "@theholocron/github-client": "^1.51.0",
     "@theholocron/http-client": "^1.43.1",
     "@theholocron/misc-utils": "^1.16.0",
     "@theholocron/tsconfig": "^8.8.2",
@@ -52,13 +52,13 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.209"
+    "@theholocron/cli": "5.0.0-alpha.210"
   },
   "peerDependencies": {
     "@theholocron/fs-utils": "^1.16.0",
-    "@theholocron/github-client": "^1.47.1",
+    "@theholocron/github-client": "^1.51.0",
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/cli": "5.0.0-alpha.209"
+    "@theholocron/cli": "5.0.0-alpha.210"
   },
   "engines": {
     "node": ">=22"