@theholocron/holocron-plugin-github 5.0.0-alpha.33 → 5.0.0-alpha.331

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,47 +1,65 @@
+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";
-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
+/** 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;
 }
-declare class GitHubCi implements Ci {
+/** 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;
 }
-//#endregion
-//#region src/capabilities/environments.d.ts
 interface EnvironmentsOptions {
   repo: string;
 }
-declare class GitHubEnvironments implements Environments {
+/** 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;
 }
-//#endregion
-//#region src/capabilities/issues.d.ts
 interface IssuesOptions {
   repo: string;
   /**
@@ -55,9 +73,12 @@ interface IssuesOptions {
     inReview: string;
   };
 }
-declare class GitHubIssues implements Issues {
+/** 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;
@@ -65,8 +86,11 @@ 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;
@@ -76,17 +100,21 @@ 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;
 }
-//#endregion
-//#region src/capabilities/labels.d.ts
+/** 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;
 }
 /**
@@ -97,36 +125,51 @@ 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 {
+/** 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";
-  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>;
+  /** Deletes the named secret in the given scope. */
   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 {
+/**
+ * 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;
@@ -134,83 +177,117 @@ 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);
   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>;
   syncProperties(values: Record<string, string | string[]>): Promise<string>;
+  checkPropertyValues(values: Record<string, string | string[]>): Promise<string[] | undefined>;
   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";
+  }>>;
+  getRepoInfo(): Promise<SourceRepoInfo>;
+  getProperties(): Promise<Record<string, string | string[]>>;
+  listLabels(): Promise<LabelDef[]>;
+  listTeamAccess(): Promise<Array<{
+    slug: string;
+    permission: TeamPermission$1;
+  }>>;
+  getRulesetDetail(id: number): Promise<SourceRulesetDetail>;
+  getSecurity(): Promise<SourceSecurity>;
   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
+/** 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;
 }
-declare function normalizeTeamEntry(entry: TeamEntry): NormalizedTeamEntry;
-declare function syncTeams(client: GitHubClient, repo: string, teams: TeamEntry[]): Promise<string>;
-//#endregion
-//#region src/sodium.d.ts
+/** 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`.
  */
-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>;
+/** Options for `verifyToken`. */
 interface VerifyTokenOptions {
+  /** Overrides the API base URL, for tests. */
   baseUrl?: string;
+  /** Overrides `fetch`, for tests. */
   fetch?: typeof fetch;
 }
-declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
-//#endregion
-//#region src/index.d.ts
-interface GitHubPluginOptions extends ResolveTokenInput {
+/** 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;
   /** Absolute path to the working repo root. Used by `source`'s
@@ -218,7 +295,9 @@ 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. */
@@ -226,19 +305,33 @@ interface GitHubPluginOptions extends ResolveTokenInput {
   /** Override `fetch` for tests. Defaults to global `fetch`. */
   fetch?: typeof fetch;
 }
-interface PluginContext {
+/** 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;
 }
-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): {
+/** 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: {
+    connection: import("@theholocron/cli").Probe;
+  };
   capabilities: {
     source: () => Source;
     ci: () => Ci;
@@ -251,6 +344,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 };