@theholocron/holocron-plugin-github 2.0.0-alpha.0 → 2.0.0-alpha.5

package/README.md

@@ -3,13 +3,19 @@
 GitHub plugin for [Holocron](../cli). Implements five capabilities
 against the GitHub REST API:
 
-| Capability     | What this plugin does                                     |
-| -------------- | --------------------------------------------------------- |
+| Capability     | What this plugin does                                            |
+| -------------- | ---------------------------------------------------------------- |
 | `source`       | Repos, rulesets, repo settings, security toggles, workflow files |
-| `ci`           | Workflow run history + status                              |
-| `secrets`      | GH Actions secrets (repo + environment + organization)     |
-| `environments` | Named deployment environments (reviewers, wait timers)     |
-| `issues`       | GitHub Issues as a tracker (with lifecycle slots)          |
+| `ci`           | Workflow run history + status                                    |
+| `secrets`      | GH Actions secrets (repo + environment + organization)           |
+| `environments` | Named deployment environments (reviewers, wait timers)           |
+| `issues`       | GitHub Issues as a tracker (with lifecycle slots)                |
+
+## Install
+
+```bash
+pnpm add -D @theholocron/holocron-plugin-github@alpha
+```
 
 ## Auth
 
@@ -30,19 +36,19 @@ toggles, etc.) — silent fallback would surface as mysterious 403s.
 ```jsonc
 // holocron.config.json
 {
-  "providers": {
-    "source":       "github",
-    "ci":           "github",
-    "secrets":      "github",
-    "environments": "github",
-    "issues":       ["github", { "labels": { "inProgress": "status:in-progress", "inReview": "status:in-review" } }]
-  }
+	"providers": {
+		"source": "github",
+		"ci": "github",
+		"secrets": "github",
+		"environments": "github",
+		"issues": ["github", { "labels": { "inProgress": "status:in-progress", "inReview": "status:in-review" } }],
+	},
 }
 ```
 
 ## Status
 
-**v0.0.0 — scaffolded.** Implementations are being ported from
-[`rando-id/rando.id`](https://github.com/rando-id/rando.id)'s
-`packages/cli/src/adapters/` per the migration plan in
-`.notes/tech-architecture.spec.md`.
+**`v2.0.0-alpha.0`** — published on npm under the `alpha` dist-tag.
+[Release notes](https://github.com/theholocron/holocron/releases/tag/v2.0.0-alpha.0).
+All five capabilities are implemented; APIs may still shift before
+stable v2.0.0.

package/dist/index.d.mts

@@ -4,10 +4,13 @@ import { Auth, Ci, CiRun, CiRunFilter, Environment, Environments, Issue, IssueSe
 /**
  * Token resolution for the GitHub plugin. See README §Auth.
  *
- * Resolution order:
+ * Resolution order (matches the standard 4-step precedence set by
+ * `.notes/tech-auth-bootstrap.spec.md`):
  *   1. explicit `token` argument (from `--token` flag)
  *   2. HOLOCRON_GH_TOKEN env var (preferred over GITHUB_TOKEN — clearer intent)
  *   3. GITHUB_TOKEN env var (auto-injected in GH Actions)
+ *   4. keyring (com.theholocron.cli / "github")
+ *   5. AuthError naming all four options + the bootstrap hint
  *
  * No `gh auth token` fallback by design — it usually has narrower
  * scopes than admin commands need.
@@ -20,6 +23,8 @@ interface ResolveTokenInput {
   cliToken?: string;
   /** Env vars; passed in for testability. Defaults to `process.env`. */
   env?: NodeJS.ProcessEnv;
+  /** Keyring lookup fn; passed in for testability. Defaults to `getToken(provider)`. */
+  keyring?: (provider: string) => string | null;
 }
 declare function resolveToken(input?: ResolveTokenInput): string;
 //#endregion
@@ -40,7 +45,7 @@ interface RestClientOptions {
   baseUrl?: string;
 }
 interface RequestOptions {
-  method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
   body?: unknown;
   /** Skip JSON parse when true (204 No Content endpoints). */
   expectNoContent?: boolean;
@@ -73,6 +78,7 @@ declare class GitHubSource implements Source {
   private readonly owner;
   private readonly name;
   private readonly repoPath;
+  private readonly repoRoot;
   private readonly workflowDir;
   constructor(rest: GitHubRestClient, opts: SourceOptions);
   whoami(): Promise<{
@@ -83,14 +89,18 @@ declare class GitHubSource implements Source {
   createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
   updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
   updateRepoSettings(settings: RepoSettings): Promise<void>;
+  protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
   enableVulnerabilityAlerts(): Promise<void>;
   enableAutomatedSecurityFixes(): Promise<void>;
   enableSecretScanning(): Promise<void>;
+  enableCodeScanning(): Promise<string>;
+  enableDependencyGraph(): Promise<void>;
   enablePrivateVulnerabilityReporting(): Promise<void>;
   listWorkflowFiles(): Promise<string[]>;
   readWorkflowFile(name: string): Promise<string | null>;
   writeWorkflowFile(name: string, contents: string): Promise<void>;
   removeWorkflowFile(name: string): Promise<void>;
+  writeRepoFile(path: string, contents: string): Promise<void>;
 }
 //#endregion
 //#region src/capabilities/secrets.d.ts
@@ -151,8 +161,15 @@ declare class GitHubCi implements Ci {
 //#region src/capabilities/issues.d.ts
 interface IssuesOptions {
   repo: string;
-  /** Lifecycle slot → status label name. */
-  labels: {
+  /**
+   * Lifecycle slot → status label name. Optional at construction; if
+   * omitted, capability methods that need labels (`transition`,
+   * `doctor`) degrade gracefully — `transition` throws a clear error,
+   * `doctor` reports the two label-backed slots as unresolved. This
+   * lets the plugin load in configs where the operator hasn't picked
+   * labels yet without failing the whole runtime.
+   */
+  labels?: {
     inProgress: string;
     inReview: string;
   };
@@ -185,6 +202,32 @@ declare class GitHubIssues implements Issues {
   private mapIssue;
 }
 //#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;
+interface VerifyTokenOptions {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
 //#region src/index.d.ts
 interface GitHubPluginOptions extends ResolveTokenInput {
   /** "owner/name" — e.g., "theholocron/holocron". Required. */
@@ -224,5 +267,12 @@ declare function createPlugin(options: GitHubPluginOptions): {
     issues: () => Issues;
   };
 };
+/**
+ * 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).
+ */
+declare const AUTH_HINT: string;
 //#endregion
-export { type Auth, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubPluginOptions, GitHubRestClient, GitHubSecrets, GitHubSource, PluginContext, ResolveTokenInput, ci, createContext, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source };
+export { AUTH_HINT, type Auth, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubPluginOptions, GitHubRestClient, GitHubSecrets, GitHubSource, PluginContext, ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, ci, createContext, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source, verifyToken };

package/dist/index.mjs

@@ -1,15 +1,18 @@
 import { createRequire } from "node:module";
+import { ProviderApiError, getToken } from "@theholocron/cli";
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { ProviderApiError } from "@theholocron/cli";
+import { dirname, join } from "node:path";
 //#region src/auth.ts
 /**
 * Token resolution for the GitHub plugin. See README §Auth.
 *
-* Resolution order:
+* Resolution order (matches the standard 4-step precedence set by
+* `.notes/tech-auth-bootstrap.spec.md`):
 *   1. explicit `token` argument (from `--token` flag)
 *   2. HOLOCRON_GH_TOKEN env var (preferred over GITHUB_TOKEN — clearer intent)
 *   3. GITHUB_TOKEN env var (auto-injected in GH Actions)
+*   4. keyring (com.theholocron.cli / "github")
+*   5. AuthError naming all four options + the bootstrap hint
 *
 * No `gh auth token` fallback by design — it usually has narrower
 * scopes than admin commands need.
@@ -19,8 +22,9 @@ var AuthError = class extends Error {
 };
 function resolveToken(input = {}) {
 	const env = input.env ?? process.env;
-	const token = input.cliToken || env.HOLOCRON_GH_TOKEN || env.GITHUB_TOKEN;
-	if (!token) throw new AuthError("no GitHub token found. Pass --token <PAT>, or set HOLOCRON_GH_TOKEN / GITHUB_TOKEN.");
+	const keyring = input.keyring ?? getToken;
+	const token = input.cliToken || env.HOLOCRON_GH_TOKEN || env.GITHUB_TOKEN || keyring("github");
+	if (!token) throw new AuthError("no GitHub token found. Pass --token <PAT>, set HOLOCRON_GH_TOKEN / GITHUB_TOKEN, or run: holocron auth set github <PAT>");
 	return token;
 }
 //#endregion
@@ -214,6 +218,7 @@ var GitHubIssues = class {
 				via: "closed (completed)"
 			};
 		}
+		if (!this.labels) throw new Error(`transition to \`${slot}\` requires \`labels\` in plugin options: { inProgress: '<label>', inReview: '<label>' }`);
 		const targetLabel = slot === "inProgress" ? this.labels.inProgress : this.labels.inReview;
 		const alreadyOpen = issue.state === "open";
 		const alreadyLabeled = currentStatusLabels.includes(targetLabel);
@@ -255,20 +260,19 @@ var GitHubIssues = class {
 				name: "open (no status label)",
 				category: "open"
 			},
-			{
+			...this.labels ? [{
 				name: `open + ${this.labels.inProgress}`,
 				category: "in-progress"
-			},
-			{
+			}, {
 				name: `open + ${this.labels.inReview}`,
 				category: "in-review"
-			},
+			}] : [],
 			{
 				name: "closed",
 				category: "done"
 			}
 		];
-		const lifecycle = [
+		const lifecycle = this.labels ? [
 			{
 				slot: "inProgress",
 				value: this.labels.inProgress,
@@ -287,6 +291,25 @@ var GitHubIssues = class {
 				resolved: true,
 				note: "(intrinsic — GitHub close-with-reason)"
 			}
+		] : [
+			{
+				slot: "inProgress",
+				value: null,
+				resolved: false,
+				note: "no `labels` configured in plugin options — transitions to `inProgress` will error"
+			},
+			{
+				slot: "inReview",
+				value: null,
+				resolved: false,
+				note: "no `labels` configured in plugin options — transitions to `inReview` will error"
+			},
+			{
+				slot: "done",
+				value: "closed (state_reason=completed)",
+				resolved: true,
+				note: "(intrinsic — GitHub close-with-reason)"
+			}
 		];
 		return {
 			authedAs: `${me.displayName} (${me.emailAddress ?? me.id})`,
@@ -309,10 +332,10 @@ var GitHubIssues = class {
 		let category = "open";
 		let statusName = raw.state === "closed" ? "closed" : "open";
 		if (raw.state === "closed") category = "done";
-		else if (statusLabels.includes(this.labels.inProgress)) {
+		else if (this.labels && statusLabels.includes(this.labels.inProgress)) {
 			category = "in-progress";
 			statusName = `open + ${this.labels.inProgress}`;
-		} else if (statusLabels.includes(this.labels.inReview)) {
+		} else if (this.labels && statusLabels.includes(this.labels.inReview)) {
 			category = "in-review";
 			statusName = `open + ${this.labels.inReview}`;
 		}
@@ -449,6 +472,7 @@ var GitHubSource = class {
 	owner;
 	name;
 	repoPath;
+	repoRoot;
 	workflowDir;
 	constructor(rest, opts) {
 		this.rest = rest;
@@ -456,6 +480,7 @@ var GitHubSource = class {
 		this.owner = owner;
 		this.name = name;
 		this.repoPath = `/repos/${owner}/${name}`;
+		this.repoRoot = opts.repoRoot;
 		this.workflowDir = join(opts.repoRoot, ".github", "workflows");
 	}
 	async whoami() {
@@ -490,6 +515,12 @@ var GitHubSource = class {
 			body: settings
 		});
 	}
+	async protectBranch(branch, payload) {
+		await this.rest.request(`${this.repoPath}/branches/${encodeURIComponent(branch)}/protection`, {
+			method: "PUT",
+			body: payload
+		});
+	}
 	async enableVulnerabilityAlerts() {
 		await this.rest.request(`${this.repoPath}/vulnerability-alerts`, {
 			method: "PUT",
@@ -507,7 +538,28 @@ var GitHubSource = class {
 			method: "PATCH",
 			body: { security_and_analysis: {
 				secret_scanning: { status: "enabled" },
-				secret_scanning_push_protection: { status: "enabled" }
+				secret_scanning_push_protection: { status: "enabled" },
+				secret_scanning_validity_checks: { status: "enabled" },
+				secret_scanning_non_provider_patterns: { status: "enabled" }
+			} }
+		});
+	}
+	async enableCodeScanning() {
+		return `run ${(await this.rest.request(`${this.repoPath}/code-scanning/default-setup`, {
+			method: "PATCH",
+			body: {
+				state: "configured",
+				query_suite: "extended",
+				threat_model: "remote_and_local"
+			}
+		})).run_id}`;
+	}
+	async enableDependencyGraph() {
+		await this.rest.request(this.repoPath, {
+			method: "PATCH",
+			body: { security_and_analysis: {
+				dependency_graph: { status: "enabled" },
+				dependency_graph_autosubmit_action: { status: "enabled" }
 			} }
 		});
 	}
@@ -545,6 +597,11 @@ var GitHubSource = class {
 			throw err;
 		}
 	}
+	async writeRepoFile(path, contents) {
+		const full = join(this.repoRoot, path);
+		await ensureDir(dirname(full));
+		await writeFile(full, contents, "utf8");
+	}
 };
 function isENOENT(err) {
 	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
@@ -579,7 +636,9 @@ var GitHubRestClient = class {
 	constructor(opts) {
 		this.token = opts.token;
 		this.fetchImpl = opts.fetch ?? globalThis.fetch;
-		this.baseUrl = (opts.baseUrl ?? "https://api.github.com").replace(/\/+$/, "");
+		let url = opts.baseUrl ?? "https://api.github.com";
+		while (url.endsWith("/")) url = url.slice(0, -1);
+		this.baseUrl = url;
 	}
 	async request(path, opts = {}) {
 		const url = `${this.baseUrl}${path}`;
@@ -608,6 +667,36 @@ var GitHubRestClient = class {
 	}
 };
 //#endregion
+//#region src/verify-token.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.
+*/
+async function verifyToken(token, opts = {}) {
+	const restOpts = { token };
+	if (opts.baseUrl !== void 0) restOpts.baseUrl = opts.baseUrl;
+	if (opts.fetch !== void 0) restOpts.fetch = opts.fetch;
+	const rest = new GitHubRestClient(restOpts);
+	try {
+		const me = await rest.request("/user");
+		return {
+			ok: true,
+			subject: `user @ ${me.login ?? me.email ?? "unknown"}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
 //#region src/index.ts
 function createContext(options) {
 	return {
@@ -637,11 +726,9 @@ function ci(ctx) {
 	return new GitHubCi(ctx.rest, { repo: ctx.repo });
 }
 function issues(ctx) {
-	if (!ctx.options.labels) throw new Error("issues capability requires `labels` in plugin options: { inProgress, inReview }");
-	return new GitHubIssues(ctx.rest, {
-		repo: ctx.repo,
-		labels: ctx.options.labels
-	});
+	const opts = { repo: ctx.repo };
+	if (ctx.options.labels !== void 0) opts.labels = ctx.options.labels;
+	return new GitHubIssues(ctx.rest, opts);
 }
 function createPlugin(options) {
 	const ctx = createContext(options);
@@ -656,5 +743,12 @@ function createPlugin(options) {
 		}
 	};
 }
+/**
+* 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).
+*/
+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>";
 //#endregion
-export { AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubRestClient, GitHubSecrets, GitHubSource, ci, createContext, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source };
+export { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubRestClient, GitHubSecrets, GitHubSource, ci, createContext, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0-alpha.5",
   "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",
@@ -21,7 +21,7 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "2.0.0-alpha.0"
+    "@theholocron/cli": "2.0.0-alpha.5"
   },
   "dependencies": {
     "libsodium-wrappers": "^0.7.15"
@@ -37,7 +37,8 @@
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
     "tsdown": "^0.22.3",
-    "@theholocron/cli": "2.0.0-alpha.0"
+    "tsx": "^4.22.4",
+    "@theholocron/cli": "2.0.0-alpha.5"
   },
   "publishConfig": {
     "access": "public"
@@ -52,7 +53,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
   },
   "types": "./dist/index.d.mts"
 }