@theholocron/holocron-plugin-github 5.0.0-alpha.199 → 5.0.0-alpha.200

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 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, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, createFeatureResolver } from "@theholocron/cli";
+import { Auth, AuthError, Ci, CiRun, CiRunFilter, Environment, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, PagesConfig, PullRequest, RepoRef, RepoSettings, ResolveTokenInput, Ruleset, SecretScope, Secrets, Source, SourceFile, SourceTeamMember, TeamEntry, TeamEntry as TeamEntry$1, TeamPermission, TrackerDoctorReport, TrackerUser, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, createFeatureResolver } from "@theholocron/cli";
 //#region src/auth.d.ts
 declare const resolveReadToken: (input?: ResolveTokenInput) => string;
 declare const resolveIssuesToken: (input?: ResolveTokenInput) => string;
@@ -8,6 +8,7 @@ declare const resolveReleaseToken: (input?: ResolveTokenInput) => string;
 declare const resolveAdminToken: (input?: ResolveTokenInput) => string;
 declare const resolveSecretsToken: (input?: ResolveTokenInput) => string;
 declare const resolveDeployToken: (input?: ResolveTokenInput) => string;
+declare const resolveUserSyncToken: (input?: ResolveTokenInput) => string;
 declare const resolveOrgToken: (input?: ResolveTokenInput) => string;
 //#endregion
 //#region src/capabilities/ci.d.ts
@@ -128,6 +129,8 @@ interface SourceOptions {
   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;
@@ -142,6 +145,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);
@@ -169,6 +173,13 @@ 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>;
   syncDescription(description: string): Promise<string>;
   syncHomepage(homepage: string): Promise<string>;
@@ -221,7 +232,7 @@ interface PluginContext {
   repo: string;
   repoRoot: string;
 }
-declare function source(ctx: PluginContext, orgClient?: GitHubClient): Source;
+declare function source(ctx: PluginContext, orgClient?: GitHubClient, userSyncClient?: GitHubClient): Source;
 declare function secrets(ctx: PluginContext, orgClient?: GitHubClient): Secrets;
 declare function environments(ctx: PluginContext): Environments;
 declare function ci(ctx: PluginContext): Ci;
@@ -242,4 +253,4 @@ declare function createPlugin(options: GitHubPluginOptions): {
  */
 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, resolveSecretsToken, resolveSyncToken, secrets, source, syncLabels, syncTeams, verifyToken };
+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, resolveSecretsToken, resolveSyncToken, resolveUserSyncToken, secrets, source, syncLabels, syncTeams, verifyToken };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { createGitHubClient, createGitHubClient as createGitHubClient$1 } from "@theholocron/github-client";
-import { AuthError, createFeatureResolver } from "@theholocron/cli";
+import { AuthError, ProviderApiError, createFeatureResolver } from "@theholocron/cli";
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { findRootSync } from "@theholocron/fs-utils";
@@ -34,6 +34,10 @@ 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"
@@ -422,6 +426,46 @@ function toGHScope(scope) {
 	return scope;
 }
 //#endregion
+//#region 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;
+	}
+}
+//#endregion
 //#region src/capabilities/labels.ts
 /**
 * Idempotently synchronise a repo's labels to the canonical set.
@@ -505,6 +549,7 @@ var GitHubSource = class {
 	repoRoot;
 	workflowDir;
 	orgClient;
+	userSyncClient;
 	baseUrl;
 	fetchImpl;
 	constructor(client, opts) {
@@ -519,6 +564,7 @@ var GitHubSource = class {
 		});
 		this.workflowDir = join(this.repoRoot, ".github", "workflows");
 		this.orgClient = opts.orgClient;
+		this.userSyncClient = opts.userSyncClient;
 		this.baseUrl = opts.baseUrl;
 		this.fetchImpl = opts.fetch;
 	}
@@ -611,6 +657,18 @@ 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);
 	}
@@ -693,11 +751,12 @@ async function verifyToken(token, opts = {}) {
 }
 //#endregion
 //#region src/index.ts
-function source(ctx, orgClient) {
+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
 	});
@@ -776,10 +835,19 @@ 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",
 		capabilities: {
-			source: () => source(makeCtx(resolveAdminToken), makeOrgClient()),
+			source: () => source(makeCtx(resolveAdminToken), makeOrgClient(), makeUserSyncClient()),
 			ci: () => ci(makeCtx(resolveReadToken)),
 			secrets: () => makeSecrets(),
 			environments: () => environments(makeCtx(resolveAdminToken)),
@@ -793,4 +861,4 @@ function createPlugin(options) {
 */
 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, resolveSecretsToken, resolveSyncToken, secrets, source, syncLabels, syncTeams, verifyToken };
+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, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "5.0.0-alpha.199",
+  "version": "5.0.0-alpha.200",
   "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.43.1",
+    "@theholocron/github-client": "^1.47.1",
     "@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.199"
+    "@theholocron/cli": "5.0.0-alpha.200"
   },
   "peerDependencies": {
     "@theholocron/fs-utils": "^1.16.0",
-    "@theholocron/github-client": "^1.43.1",
+    "@theholocron/github-client": "^1.47.1",
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/cli": "5.0.0-alpha.199"
+    "@theholocron/cli": "5.0.0-alpha.200"
   },
   "engines": {
     "node": ">=22"