@theholocron/holocron-plugin-github 5.0.0-alpha.277 → 5.0.0-alpha.279

package/dist/index.d.mts

@@ -1,24 +1,41 @@
 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, SourceRepoInfo, SourceRulesetDetail, SourceSecurity, SourceTeamMember, TeamEntry, TeamEntry as TeamEntry$1, TeamPermission, TeamPermission as TeamPermission$1, TrackerDoctorReport, TrackerUser, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, createFeatureResolver } from "@theholocron/cli";
 import { GitHubClient, GitHubClientOptions, createGitHubClient } from "@theholocron/github-client";
+/** Resolves the token for read-only GitHub access (`HOLOCRON_READ_TOKEN`, keyring key `github.read`). */
 export declare const resolveReadToken: import("@theholocron/cli").FeatureResolver;
+/** Resolves the token for issue operations (`HOLOCRON_ISSUES_TOKEN`, keyring key `github.issues`). */
 export declare const resolveIssuesToken: import("@theholocron/cli").FeatureResolver;
+/** Resolves the token for syncing repo files and settings (`HOLOCRON_SYNC_TOKEN`, keyring key `github.sync`). */
 export declare const resolveSyncToken: import("@theholocron/cli").FeatureResolver;
+/** Resolves the token for release operations (`HOLOCRON_RELEASE_TOKEN`, keyring key `github.release`). */
 export declare const resolveReleaseToken: import("@theholocron/cli").FeatureResolver;
+/** Resolves the repo-scoped admin token (`HOLOCRON_ADMIN_TOKEN`, keyring key `github.admin`). */
 export declare const resolveAdminToken: import("@theholocron/cli").FeatureResolver;
+/** Resolves the org-level secrets token (`HOLOCRON_SECRETS_TOKEN`, keyring key `github.secrets`). */
 export declare const resolveSecretsToken: import("@theholocron/cli").FeatureResolver;
+/** Resolves the token for deployment operations (`HOLOCRON_DEPLOY_TOKEN`, keyring key `github.deploy`). */
 export declare const resolveDeployToken: import("@theholocron/cli").FeatureResolver;
+/**
+ * Resolves the token for the user-sync files in the org's private config repo (`HOLOCRON_USER_SYNC_TOKEN`, keyring
+ * key `github.user-sync`).
+ */
 export declare const resolveUserSyncToken: import("@theholocron/cli").FeatureResolver;
+/** Resolves the org-level token (`HOLOCRON_ORG_TOKEN`, keyring key `github.org`). */
 export declare const resolveOrgToken: import("@theholocron/cli").FeatureResolver;
 interface CiOptions {
   repo: string;
 }
+/** The GitHub implementation of the `ci` capability, backed by GitHub Actions workflow runs. */
 export declare class GitHubCi implements Ci {
   private readonly client;
   private readonly opts;
+  /** Capability key, always `"ci"`. */
   readonly key: "ci";
+  /** Provider name, always `"github"`. */
   readonly providerName = "github";
   constructor(client: GitHubClient, opts: CiOptions);
+  /** Lists workflow runs for the repo, optionally filtered by branch, status and limit. */
   listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
+  /** Fetches one workflow run by id. */
   getRun(id: string | number): Promise<CiRun>;
   private mapRun;
   private mapConclusion;
@@ -26,14 +43,20 @@ export declare class GitHubCi implements Ci {
 interface EnvironmentsOptions {
   repo: string;
 }
+/** The GitHub implementation of the `environments` capability, managing a repo's deployment environments. */
 export declare class GitHubEnvironments implements Environments {
   private readonly client;
   private readonly opts;
+  /** Capability key, always `"environments"`. */
   readonly key: "environments";
+  /** Provider name, always `"github"`. */
   readonly providerName = "github";
   constructor(client: GitHubClient, opts: EnvironmentsOptions);
+  /** Lists the repo's environments with their wait timer, self-review rule and required reviewers. */
   listEnvironments(): Promise<Environment[]>;
+  /** Creates or updates an environment, sending only the settings the given environment defines. */
   upsertEnvironment(env: Environment): Promise<void>;
+  /** Deletes the named environment. */
   deleteEnvironment(name: string): Promise<void>;
   private flattenReviewers;
 }
@@ -50,9 +73,12 @@ interface IssuesOptions {
     inReview: string;
   };
 }
+/** The GitHub implementation of the `issues` capability, backed by GitHub Issues and status labels. */
 export declare class GitHubIssues implements Issues {
   private readonly client;
+  /** Capability key, always `"issues"`. */
   readonly key: "issues";
+  /** Provider name, always `"github"`. */
   readonly providerName = "github";
   private readonly owner;
   private readonly repoName;
@@ -60,8 +86,11 @@ export declare class GitHubIssues implements Issues {
   private readonly labels;
   constructor(client: GitHubClient, opts: IssuesOptions);
   getMyself(): Promise<TrackerUser>;
+  /** Searches the repo's issues, newest update first, leaving out pull requests. */
   search(filter: IssueSearchFilter): Promise<Issue[]>;
+  /** Fetches one issue by its key. */
   get(key: string): Promise<Issue>;
+  /** Creates an issue and returns its key as `#<number>`; the milestone is resolved from its title. */
   create(input: {
     summary: string;
     body?: string;
@@ -71,15 +100,21 @@ export declare class GitHubIssues implements Issues {
     key: string;
   }>;
   transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
+  /** Adds a comment to the issue with the given key. */
   comment(key: string, body: string): Promise<void>;
+  /** Checks the authenticated user, the repo and the label-backed lifecycle slots, and reports what resolves. */
   doctor(): Promise<TrackerDoctorReport>;
   private resolveMilestone;
   private removeStatusLabels;
   private mapIssue;
 }
+/** A label the repo is expected to have. */
 interface CanonicalLabel {
+  /** The label's name. */
   readonly name: string;
+  /** The label's color, as a hex string. */
   readonly color: string;
+  /** The label's description. */
   readonly description: string;
 }
 /**
@@ -94,11 +129,14 @@ export declare function syncLabels(client: GitHubClient, repo: string, canonical
 interface SecretsOptions {
   repo: string;
 }
+/** The GitHub implementation of the `secrets` capability, covering repository, environment and organization secrets. */
 export declare class GitHubSecrets implements Secrets {
   private readonly client;
   private readonly opts;
   private readonly orgClient?;
+  /** Capability key, always `"secrets"`. */
   readonly key: "secrets";
+  /** Provider name, always `"github"`. */
   readonly providerName = "github";
   /**
    * `client` handles repo and environment scopes; `orgClient`, when given, handles
@@ -109,6 +147,7 @@ export declare class GitHubSecrets implements Secrets {
   private clientFor;
   listSecrets(scope: SecretScope): Promise<string[]>;
   setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
+  /** Deletes the named secret in the given scope. */
   deleteSecret(scope: SecretScope, name: string): Promise<void>;
 }
 interface SourceOptions {
@@ -122,9 +161,15 @@ interface SourceOptions {
   baseUrl?: string;
   fetch?: typeof fetch;
 }
+/**
+ * The GitHub implementation of the `source` capability: repo settings, rulesets, branch protection, security
+ * features and local workflow files.
+ */
 export declare class GitHubSource implements Source {
   private readonly client;
+  /** Capability key, always `"source"`. */
   readonly key: "source";
+  /** Provider name, always `"github"`. */
   readonly providerName = "github";
   private readonly owner;
   private readonly name;
@@ -139,22 +184,35 @@ export declare class GitHubSource implements Source {
   whoami(): Promise<{
     login: string;
   }>;
+  /** Returns the repo's owner, name and default branch. */
   getRepo(): Promise<RepoRef>;
+  /** Lists the repo's rulesets. */
   listRulesets(): Promise<Ruleset[]>;
+  /** Creates a ruleset from the given payload. */
   createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
+  /** Updates the ruleset with the given id from the payload. */
   updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
+  /** Updates the repo's settings. */
   updateRepoSettings(settings: RepoSettings): Promise<void>;
   protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
+  /** Enables Dependabot vulnerability alerts. */
   enableVulnerabilityAlerts(): Promise<void>;
+  /** Enables Dependabot automated security fixes. */
   enableAutomatedSecurityFixes(): Promise<void>;
+  /** Enables secret scanning. */
   enableSecretScanning(): Promise<void>;
   enableCodeScanning(): Promise<string>;
   disableDefaultCodeScanning(): Promise<void>;
   enableDependencyGraph(): Promise<void>;
+  /** Enables private vulnerability reporting. */
   enablePrivateVulnerabilityReporting(): Promise<void>;
+  /** Lists the `.yml` and `.yaml` files in `.github/workflows`, sorted by name; empty when the folder is missing. */
   listWorkflowFiles(): Promise<string[]>;
+  /** Reads a workflow file's text, or `null` when it does not exist. */
   readWorkflowFile(name: string): Promise<string | null>;
+  /** Writes a workflow file, creating `.github/workflows` first when needed. */
   writeWorkflowFile(name: string, contents: string): Promise<void>;
+  /** Removes a workflow file; a file that is already gone is not an error. */
   removeWorkflowFile(name: string): Promise<void>;
   writeRepoFile(path: string, contents: string): Promise<void>;
   syncLabels(canonical: ReadonlyArray<LabelDef>, stale: ReadonlyArray<string>): Promise<string>;
@@ -202,22 +260,32 @@ export declare class GitHubSource implements Source {
   listPullRequestCommits(number: number, repo?: string): Promise<string[]>;
   configurePages(config: PagesConfig, token: string): Promise<void>;
 }
+/** A team entry with the permission spelled out. */
 interface NormalizedTeamEntry {
+  /** The team's slug. */
   slug: string;
+  /** The permission the team gets on the repo. */
   permission: TeamPermission;
 }
+/** Turns a team entry into slug and permission form; a bare slug gets `push`. */
 export declare function normalizeTeamEntry(entry: TeamEntry): NormalizedTeamEntry;
+/** Grants each team access to the repo and reports the outcome; throws when every team fails. */
 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`.
  */
 export declare function encryptSecret(publicKeyBase64: string, value: string): Promise<string>;
+/** Options for `verifyToken`. */
 interface VerifyTokenOptions {
+  /** Overrides the API base URL, for tests. */
   baseUrl?: string;
+  /** Overrides `fetch`, for tests. */
   fetch?: typeof fetch;
 }
+/** Checks a token against `GET /user` and returns who it belongs to, or why it failed. */
 export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
+/** Options for the GitHub plugin. */
 export interface GitHubPluginOptions extends ResolveTokenInput {
   /** "owner/name" — e.g., "theholocron/holocron". Required. */
   repo: string;
@@ -226,7 +294,9 @@ export interface GitHubPluginOptions extends ResolveTokenInput {
   repoRoot?: string;
   /** Lifecycle slot → label name. Used by the `issues` capability. */
   labels?: {
+    /** Label that marks an issue as in progress. */
     inProgress: string;
+    /** Label that marks an issue as in review. */
     inReview: string;
   };
   /** Override base URL for tests. Defaults to https://api.github.com. */
@@ -234,17 +304,28 @@ export interface GitHubPluginOptions extends ResolveTokenInput {
   /** Override `fetch` for tests. Defaults to global `fetch`. */
   fetch?: typeof fetch;
 }
+/** What the capability factories receive: the plugin options, a client, the repo and its root. */
 export interface PluginContext {
+  /** The plugin options. */
   options: GitHubPluginOptions;
+  /** The GitHub client the capability uses. */
   client: GitHubClient;
+  /** The repo as `owner/name`. */
   repo: string;
+  /** Absolute path to the working repo root. */
   repoRoot: string;
 }
+/** Builds the `source` capability; the optional clients cover org-level and user-sync access. */
 export declare function source(ctx: PluginContext, orgClient?: GitHubClient, userSyncClient?: GitHubClient): Source;
+/** Builds the `secrets` capability; the optional client handles organization secrets. */
 export declare function secrets(ctx: PluginContext, orgClient?: GitHubClient): Secrets;
+/** Builds the `environments` capability. */
 export declare function environments(ctx: PluginContext): Environments;
+/** Builds the `ci` capability. */
 export declare function ci(ctx: PluginContext): Ci;
+/** Builds the `issues` capability, passing the lifecycle labels when configured. */
 export declare function issues(ctx: PluginContext): Issues;
+/** Creates the plugin, resolving a token per capability when it is first used. */
 export declare function createPlugin(options: GitHubPluginOptions): {
   name: string;
   probes: {

package/dist/index.mjs

@@ -7,52 +7,68 @@ 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"
 });
 // 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,
@@ -60,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);
@@ -88,15 +105,19 @@ var GitHubCi = class {
 	}
 };
 // 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,
@@ -105,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;
@@ -115,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);
 	}
@@ -129,9 +152,12 @@ var GitHubEnvironments = class {
 	}
 };
 // 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;
@@ -153,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",
@@ -172,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;
@@ -224,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);
@@ -377,11 +408,14 @@ async function encryptSecret(publicKeyBase64, value) {
 	return sodium.to_base64(ciphertext, sodium.base64_variants.ORIGINAL);
 }
 // 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";
 	/**
 	* `client` handles repo and environment scopes; `orgClient`, when given, handles
@@ -410,6 +444,7 @@ var GitHubSecrets = class {
 		if (scope.kind === "organization") body.visibility = "all";
 		await client.secrets.putSecret(this.opts.repo, ghScope, name, body);
 	}
+	/** Deletes the named secret in the given scope. */
 	async deleteSecret(scope, name) {
 		await this.clientFor(scope).secrets.deleteSecret(this.opts.repo, toGHScope(scope), name);
 	}
@@ -640,6 +675,7 @@ async function readSecurity(client, repo) {
 	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,
@@ -647,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);
@@ -776,9 +813,15 @@ function toPullRequest(raw) {
 		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;
@@ -808,6 +851,7 @@ var GitHubSource = class {
 	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 {
@@ -816,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);
 	}
@@ -849,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();
@@ -860,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");
@@ -868,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));
@@ -1026,6 +1082,7 @@ async function ensureDir(path) {
 	}
 }
 // 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,
@@ -1047,6 +1104,7 @@ async function verifyToken(token, opts = {}) {
 	}
 }
 // 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,
@@ -1057,20 +1115,25 @@ function source(ctx, orgClient, userSyncClient) {
 		fetch: ctx.options.fetch
 	});
 }
+/** 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "5.0.0-alpha.277",
+  "version": "5.0.0-alpha.279",
   "description": "Holocron plugin for GitHub. Implements source, ci, secrets, environments, and issues capabilities against the GitHub REST API.",
   "keywords": [
     "ci",
@@ -44,21 +44,21 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/cli": "5.0.0-alpha.277",
-    "@theholocron/eslint-config": "^8.9.0-alpha.3",
-    "@theholocron/fs-utils": "^1.16.1-alpha.2",
+    "@theholocron/fs-utils": "^1.16.1-alpha.3",
+    "@theholocron/eslint-config": "^8.9.0-alpha.4",
+    "@theholocron/cli": "5.0.0-alpha.279",
     "@theholocron/http-client": "^1.58.0-alpha.3",
-    "@theholocron/misc-utils": "^1.16.1-alpha.2",
-    "@theholocron/vitest-config": "^8.9.0-alpha.3",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
-    "@theholocron/tsconfig": "^8.9.0-alpha.3",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.4",
+    "@theholocron/tsconfig": "^8.9.0-alpha.4",
+    "@theholocron/vitest-config": "^8.9.0-alpha.4",
+    "@theholocron/misc-utils": "^1.16.1-alpha.3",
     "@theholocron/github-client": "^1.58.0-alpha.3"
   },
   "peerDependencies": {
     "@theholocron/fs-utils": "^1.16.0",
     "@theholocron/github-client": "^1.58.0",
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/cli": "5.0.0-alpha.277"
+    "@theholocron/cli": "5.0.0-alpha.279"
   },
   "engines": {
     "node": ">=22"