@theholocron/holocron-plugin-github 2.2.3 → 3.0.0

package/README.md

@@ -21,17 +21,31 @@ pnpm add -D @theholocron/holocron-plugin-github@alpha
 
 ## Auth
 
-The plugin requires a GitHub token resolved in this order:
+Each capability resolves its own fine-grained token so a compromised credential can only affect that feature. The resolution chain per capability is:
 
-1. `--token <PAT>` flag on the `holocron` invocation
-2. `HOLOCRON_GH_TOKEN` env var
-3. `GITHUB_TOKEN` env var (auto-injected in GitHub Actions runners)
+```
+--token flag → HOLOCRON_<FEATURE>_TOKEN → keyring("github.<feature>")
+```
+
+| Env var                  | Keyring key      | Capabilities                        |
+| ------------------------ | ---------------- | ----------------------------------- |
+| `HOLOCRON_READ_TOKEN`    | `github.read`    | `clone`, `ci`                       |
+| `HOLOCRON_ISSUES_TOKEN`  | `github.issues`  | `issues`                            |
+| `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` |
+
+Store tokens once via the keyring so they are picked up automatically:
+
+```sh
+holocron auth set github.read     ghp_xxx  # clone + CI run listing
+holocron auth set github.issues   ghp_xxx  # issue management
+holocron auth set github.sync     ghp_xxx  # sync-github workflow templates
+holocron auth set github.release  ghp_xxx  # semantic-release
+holocron auth set github.admin    ghp_xxx  # setup, secrets, environments
+```
 
-If none are set, the plugin throws a clear error pointing at the
-options above. There is **no** `gh auth token` fallback because the
-scopes that local `gh` auth has are usually narrower than what
-admin-level holocron commands need (rulesets, repo settings, security
-toggles, etc.) — silent fallback would surface as mysterious 403s.
+See [docs/tokens.md](../../docs/tokens.md) for full scope requirements and CI setup.
 
 ## Config
 

package/dist/index.d.mts

@@ -1,7 +1,11 @@
-import { GitHubClient, createGitHubClient } from "@theholocron/github-client";
-import { Auth, AuthError, Ci, CiRun, CiRunFilter, Environment, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, RepoRef, RepoSettings, ResolveTokenInput, Ruleset, SecretScope, Secrets, Source, TeamEntry, TeamEntry as TeamEntry$1, TeamPermission, TrackerDoctorReport, TrackerUser } 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, 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 resolveToken: (input?: import("@theholocron/http-client").ResolveTokenInput) => string;
+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;
 //#endregion
 //#region src/sodium.d.ts
 /**
@@ -215,7 +219,6 @@ interface PluginContext {
   repo: string;
   repoRoot: string;
 }
-declare function createContext(options: GitHubPluginOptions): PluginContext;
 declare function source(ctx: PluginContext): Source;
 declare function secrets(ctx: PluginContext): Secrets;
 declare function environments(ctx: PluginContext): Environments;
@@ -233,10 +236,8 @@ 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. Generate a PAT at
- * https://github.com/settings/tokens with `repo` + `admin:repo_hook`
- * scopes (add `admin:org` for org-level operations).
+ * is supplied or the supplied token is rejected.
  */
 declare const AUTH_HINT: string;
 //#endregion
-export { AUTH_HINT, type Auth, AuthError, type CanonicalLabel, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubPluginOptions, GitHubSecrets, GitHubSource, type NormalizedTeamEntry, PluginContext, type ResolveTokenInput, type TeamEntry, type TeamPermission, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, ci, createContext, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, resolveToken, 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, resolveIssuesToken, resolveReadToken, resolveReleaseToken, resolveSyncToken, secrets, source, syncLabels, syncTeams, verifyToken };

package/dist/index.mjs

@@ -1,14 +1,28 @@
 import { createRequire } from "node:module";
 import { createGitHubClient, createGitHubClient as createGitHubClient$1 } from "@theholocron/github-client";
-import { AuthError, createResolveToken } from "@theholocron/cli";
+import { AuthError, createFeatureResolver } from "@theholocron/cli";
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 //#region src/auth.ts
-const resolveToken = createResolveToken({
-	envName: "HOLOCRON_GH_TOKEN",
-	vendorEnvName: "GITHUB_TOKEN",
-	keyringService: "github",
-	errorMessage: "no GitHub token found. Pass --token <PAT>, set HOLOCRON_GH_TOKEN / GITHUB_TOKEN, or run: holocron auth set github <PAT>"
+const resolveReadToken = createFeatureResolver({
+	envName: "HOLOCRON_READ_TOKEN",
+	keyringKey: "github.read"
+});
+const resolveIssuesToken = createFeatureResolver({
+	envName: "HOLOCRON_ISSUES_TOKEN",
+	keyringKey: "github.issues"
+});
+const resolveSyncToken = createFeatureResolver({
+	envName: "HOLOCRON_SYNC_TOKEN",
+	keyringKey: "github.sync"
+});
+const resolveReleaseToken = createFeatureResolver({
+	envName: "HOLOCRON_RELEASE_TOKEN",
+	keyringKey: "github.release"
+});
+const resolveAdminToken = createFeatureResolver({
+	envName: "HOLOCRON_ADMIN_TOKEN",
+	keyringKey: "github.admin"
 });
 //#endregion
 //#region src/capabilities/ci.ts
@@ -618,18 +632,6 @@ async function verifyToken(token, opts = {}) {
 }
 //#endregion
 //#region src/index.ts
-function createContext(options) {
-	return {
-		options,
-		client: createGitHubClient$1({
-			token: resolveToken(options),
-			baseUrl: options.baseUrl,
-			fetch: options.fetch
-		}),
-		repo: options.repo,
-		repoRoot: options.repoRoot ?? process.cwd()
-	};
-}
 function source(ctx) {
 	return new GitHubSource(ctx.client, {
 		repo: ctx.repo,
@@ -651,24 +653,33 @@ function issues(ctx) {
 	return new GitHubIssues(ctx.client, opts);
 }
 function createPlugin(options) {
-	const ctx = createContext(options);
+	function makeCtx(resolver) {
+		return {
+			options,
+			client: createGitHubClient$1({
+				token: resolver(options),
+				baseUrl: options.baseUrl,
+				fetch: options.fetch
+			}),
+			repo: options.repo,
+			repoRoot: options.repoRoot ?? process.cwd()
+		};
+	}
 	return {
 		name: "@theholocron/holocron-plugin-github",
 		capabilities: {
-			source: () => source(ctx),
-			ci: () => ci(ctx),
-			secrets: () => secrets(ctx),
-			environments: () => environments(ctx),
-			issues: () => issues(ctx)
+			source: () => source(makeCtx(resolveAdminToken)),
+			ci: () => ci(makeCtx(resolveReadToken)),
+			secrets: () => secrets(makeCtx(resolveAdminToken)),
+			environments: () => environments(makeCtx(resolveAdminToken)),
+			issues: () => issues(makeCtx(resolveIssuesToken))
 		}
 	};
 }
 /**
 * One-line hint printed by `holocron auth set github` when no token
-* is supplied or the supplied token is rejected. Generate a PAT at
-* https://github.com/settings/tokens with `repo` + `admin:repo_hook`
-* scopes (add `admin:org` for org-level operations).
+* is supplied or the supplied token is rejected.
 */
-const AUTH_HINT = "generate a Personal Access Token at https://github.com/settings/tokens (scopes: repo, admin:repo_hook — plus admin:org for org-level ops), then run: holocron auth set github <PAT>";
+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, createContext, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, resolveToken, secrets, source, syncLabels, syncTeams, verifyToken };
+export { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubSecrets, GitHubSource, ci, createFeatureResolver, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, resolveAdminToken, resolveIssuesToken, resolveReadToken, resolveReleaseToken, resolveSyncToken, secrets, source, syncLabels, syncTeams, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "2.2.3",
+  "version": "3.0.0",
   "description": "Holocron plugin for GitHub. Implements source, ci, secrets, environments, and issues capabilities against the GitHub REST API.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-github#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -13,6 +13,7 @@
   "author": "Newton Koumantzelis",
   "type": "module",
   "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -21,18 +22,18 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/github-client": "^1.3.0",
-    "@theholocron/cli": "2.2.3"
+    "@theholocron/github-client": "^1.3.3",
+    "@theholocron/cli": "3.0.0"
   },
   "dependencies": {
     "libsodium-wrappers": "^0.8.4"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^7.4.1",
-    "@theholocron/github-client": "^1.3.0",
-    "@theholocron/tsconfig": "^7.4.1",
-    "@theholocron/tsdown-config": "^7.4.1",
-    "@theholocron/vitest-config": "^7.4.1",
+    "@theholocron/eslint-config": "^7.5.0",
+    "@theholocron/github-client": "^1.3.3",
+    "@theholocron/tsconfig": "^7.5.0",
+    "@theholocron/tsdown-config": "^7.5.0",
+    "@theholocron/vitest-config": "^7.5.0",
     "@types/node": "^26",
     "@vitest/coverage-v8": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.23",
@@ -40,10 +41,10 @@
     "eslint-plugin-n": "^18.2.2",
     "globals": "^17.7.0",
     "tsdown": "^0.22.13",
-    "tsx": "4.22.4",
+    "tsx": "4.23.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@theholocron/cli": "2.2.3"
+    "@theholocron/cli": "3.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -60,6 +61,5 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "validate": "tsx scripts/validate.mjs"
-  },
-  "types": "./dist/index.d.mts"
+  }
 }