@theholocron/holocron-plugin-github 5.0.0-alpha.34 → 5.0.0-alpha.340

package/README.md

@@ -1,7 +1,7 @@
 # `@theholocron/holocron-plugin-github`
 
-GitHub plugin for [Holocron](../cli). Implements five capabilities
-against the GitHub REST API:
+GitHub plugin for [Holocron](../cli). Implements six capabilities
+against the GitHub REST and GraphQL APIs:
 
 | Capability     | What this plugin does                                            |
 | -------------- | ---------------------------------------------------------------- |
@@ -10,6 +10,7 @@ against the GitHub REST API:
 | `secrets`      | GH Actions secrets (repo + environment + organization)           |
 | `environments` | Named deployment environments (reviewers, wait timers)           |
 | `issues`       | GitHub Issues as a tracker (with lifecycle slots)                |
+| `projects`     | GitHub Projects v2 boards (GraphQL)                              |
 
 ## Install
 
@@ -34,6 +35,7 @@ Each capability resolves its own fine-grained token so a compromised credential
 | `HOLOCRON_SYNC_TOKEN`    | `github.sync`    | `sync-github` command               |
 | `HOLOCRON_RELEASE_TOKEN` | `github.release` | semantic-release, GitHub releases   |
 | `HOLOCRON_ADMIN_TOKEN`   | `github.admin`   | `source`, `secrets`, `environments` |
+| `HOLOCRON_ORG_TOKEN`     | `github.org`     | `projects`                          |
 
 Store tokens once via the keyring so they are picked up automatically:
 
@@ -45,7 +47,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
 
@@ -64,6 +66,29 @@ See [docs/tokens.md](../../docs/tokens.md) for full scope requirements and CI se
 
 ```
 
+## `projects` capability
+
+GitHub Projects v2 boards over GraphQL, for `holocron project ...` (SPEC-0020, #1744). It uses the org token
+(`HOLOCRON_ORG_TOKEN`, keyring `github.org`) with the **Projects** organization permission. Items are keyed `#N` in the
+configured `repo` and `owner/repo#N` elsewhere.
+
+| Method      | What it does                                                                                                                                                               |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list`      | Every project of the organization, open and closed. `find` is the exact name among the open ones.                                                                          |
+| `create`    | Copies the board `template.source` names (fields, options, views, automation rules, no items), or creates a project and applies the template.                              |
+| `close`     | `updateProjectV2` with `closed: true`. Reversible.                                                                                                                         |
+| `read`      | Statuses, other fields, board and table views and automation rules.                                                                                                        |
+| `ensure`    | Adds what the template lists and the board lacks (options, fields, views, filters). Never deletes. Rules and view grouping the API cannot set come back as `todos`.        |
+| `items`     | Each issue or pull request with its status, category, whether it is open and its open blockers.                                                                            |
+| `setStatus` | Sets an item's status. Idempotent: `transitioned: false` when it is already there.                                                                                         |
+| `move`      | Puts open items on another board with status and priority (only where the target has none); closed and merged ones stay and are set to done when theirs is not a done one. |
+| `whoami`    | How many boards the token sees, for `holocron doctor`.                                                                                                                     |
+
+`ensure` is safe on a field that has items. `updateProjectV2Field` replaces a single select field's whole option list,
+and an option sent without its `id` blanks the field on every item, so `ensure` reads the field first, sends every
+existing option with its `id` in the template's order (new ones without), and stops when the field cannot be read. It
+also keeps the item values in memory and, if a re-read shows any gone, writes them back by option name and fails.
+
 ## Status
 
 **`v2.0.0-alpha.0`** — published on npm under the `alpha` dist-tag.

package/dist/index.d.mts

@@ -1,47 +1,65 @@
-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
+import { Auth, AuthError, BoardItem, BoardState, BoardSummary, BoardTemplate, Ci, CiRun, CiRunFilter, EnsureReport, Environment, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, MoveReport, PagesConfig, PluginToken, Projects, 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, GraphQLClient, 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;
 }
-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,113 @@ 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>;
+/** Options of the GitHub `projects` capability. */
+interface ProjectsOptions {
+  /** The repository the provider is configured for, as `owner/name`; its items get the short key `#N`. */
+  repo: string;
+}
+/** The GitHub implementation of the `projects` capability, backed by Projects v2. */
+export declare class GitHubProjects implements Projects {
+  private readonly graphql;
+  /** Capability key, always `"projects"`. */
+  readonly key: "projects";
+  /** Provider name, always `"github"`. */
+  readonly providerName = "github";
+  private readonly repo;
+  constructor(graphql: GraphQLClient, opts: ProjectsOptions);
+  /** Every board of the organization, open and closed. */
+  list(owner: string): Promise<BoardSummary[]>;
+  /** The open board with exactly this name. */
+  find(owner: string, name: string): Promise<BoardSummary | undefined>;
+  /**
+   * Makes a board. With `template.source` naming an open board it is copied (fields, options, views and automation
+   * rules, no items); otherwise the board is created and brought in line with the template.
+   */
+  create(owner: string, name: string, template: BoardTemplate): Promise<BoardSummary>;
+  /** Closes the board; `updateProjectV2` with `closed: true` is the only way, and reversible. */
+  close(_owner: string, board: BoardSummary): Promise<void>;
+  /** The live board: statuses, other fields, views and automation rules. */
+  read(_owner: string, board: BoardSummary): Promise<BoardState>;
+  /**
+   * Brings the board in line with the template. Never deletes a field, option or view, and never sends an option
+   * list without ids. Stops (throws) when the status field cannot be read.
+   */
+  ensure(_owner: string, board: BoardSummary, template: BoardTemplate): Promise<EnsureReport>;
+  /**
+   * Makes a single select field hold the wanted options in order, every existing one sent with its id. Options the
+   * template does not mention stay, after the wanted ones. Returns what changed (`Blocked added`, `order set`).
+   */
+  private ensureOptions;
+  private createField;
+  private createView;
+  private updateView;
+  /** The board's issues and pull requests with their status, whether they are open and their open blockers. */
+  items(_owner: string, board: BoardSummary, template: BoardTemplate): Promise<BoardItem[]>;
+  /** Puts an item in a status; `transitioned` is false when it already is there. */
+  setStatus(_owner: string, board: BoardSummary, key: string, status: string): Promise<LifecycleResult>;
+  /**
+   * Puts the open items of `from` on `to` with their status and priority, only where the target has no value;
+   * closed and merged ones stay, and are set to the template's done status when theirs is not a done one.
+   */
+  move(_owner: string, from: BoardSummary, to: BoardSummary, template: BoardTemplate): Promise<MoveReport>;
+  /** A `holocron doctor` smoke check: how many boards the token sees in the configured repository's organization. */
+  whoami(): Promise<{
+    ok: boolean;
+    boards: number;
+  }>;
+  /** Sets a single select value by option name; a field or option the board lacks is skipped. */
+  private setOption;
+  private ownerId;
+  private readRaw;
+  private fetchItems;
+  private keyOf;
+  private parseKey;
+}
 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 +239,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 +357,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,31 +367,49 @@ 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;
+/** Builds the `projects` capability: GitHub Projects v2 over GraphQL, with items keyed relative to the configured repo. */
+export declare function projects(ctx: PluginContext): Projects;
+/** 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;
     secrets: () => Secrets;
     environments: () => Environments;
     issues: () => Issues;
+    projects: () => Projects;
   };
 };
 /**
  * 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 ProjectsOptions, type ResolveTokenInput, type TeamEntry, type TeamPermission, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createFeatureResolver, createGitHubClient };