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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# `@theholocron/holocron-plugin-github`
+
+GitHub plugin for [Holocron](../cli). Implements five capabilities
+against the GitHub REST API:
+
+| 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)          |
+
+## Auth
+
+The plugin requires a GitHub token resolved in this order:
+
+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)
+
+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.
+
+## Config
+
+```jsonc
+// holocron.config.json
+{
+  "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`.

package/dist/index.d.mts

@@ -0,0 +1,228 @@
+import { Auth, Ci, CiRun, CiRunFilter, Environment, Environments, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, RepoRef, RepoSettings, Ruleset, SecretScope, Secrets, Source, TrackerDoctorReport, TrackerUser } from "@theholocron/cli";
+
+//#region src/auth.d.ts
+/**
+ * Token resolution for the GitHub plugin. See README §Auth.
+ *
+ * Resolution order:
+ *   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)
+ *
+ * No `gh auth token` fallback by design — it usually has narrower
+ * scopes than admin commands need.
+ */
+declare class AuthError extends Error {
+  name: string;
+}
+interface ResolveTokenInput {
+  /** From `--token` CLI flag. */
+  cliToken?: string;
+  /** Env vars; passed in for testability. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+}
+declare function resolveToken(input?: ResolveTokenInput): string;
+//#endregion
+//#region src/rest.d.ts
+/**
+ * Thin REST wrapper around api.github.com.
+ *
+ * Adapted from rando-id/rando.id `packages/cli/src/adapters/gh-rest.ts`
+ * `request<T>` method into a standalone class so each capability can
+ * hold a reference and share the same auth/error handling.
+ *
+ * Errors throw `ProviderApiError` from `@theholocron/cli`, which the
+ * orchestrator catches to soft-skip rather than abort the whole pipeline.
+ */
+interface RestClientOptions {
+  token: string;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+  body?: unknown;
+  /** Skip JSON parse when true (204 No Content endpoints). */
+  expectNoContent?: boolean;
+}
+declare class GitHubRestClient {
+  private readonly token;
+  private readonly fetchImpl;
+  readonly baseUrl: string;
+  constructor(opts: RestClientOptions);
+  request<T>(path: string, opts?: RequestOptions): Promise<T>;
+}
+//#endregion
+//#region src/sodium.d.ts
+/**
+ * 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/capabilities/source.d.ts
+interface SourceOptions {
+  repo: string;
+  /** Absolute path to the repo root. Workflow file ops are scoped here. */
+  repoRoot: string;
+}
+declare class GitHubSource implements Source {
+  private readonly rest;
+  readonly key: "source";
+  readonly providerName = "github";
+  private readonly owner;
+  private readonly name;
+  private readonly repoPath;
+  private readonly workflowDir;
+  constructor(rest: GitHubRestClient, opts: SourceOptions);
+  whoami(): Promise<{
+    login: string;
+  }>;
+  getRepo(): Promise<RepoRef>;
+  listRulesets(): Promise<Ruleset[]>;
+  createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
+  updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
+  updateRepoSettings(settings: RepoSettings): Promise<void>;
+  enableVulnerabilityAlerts(): Promise<void>;
+  enableAutomatedSecurityFixes(): Promise<void>;
+  enableSecretScanning(): 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>;
+}
+//#endregion
+//#region src/capabilities/secrets.d.ts
+interface SecretsOptions {
+  repo: string;
+}
+declare class GitHubSecrets implements Secrets {
+  private readonly rest;
+  readonly key: "secrets";
+  readonly providerName = "github";
+  private readonly repoBase;
+  constructor(rest: GitHubRestClient, opts: SecretsOptions);
+  listSecrets(scope: SecretScope): Promise<string[]>;
+  setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
+  deleteSecret(scope: SecretScope, name: string): Promise<void>;
+  /** Endpoint root for the given scope. */
+  private scopeBase;
+}
+//#endregion
+//#region src/capabilities/environments.d.ts
+interface EnvironmentsOptions {
+  repo: string;
+}
+declare class GitHubEnvironments implements Environments {
+  private readonly rest;
+  readonly key: "environments";
+  readonly providerName = "github";
+  private readonly base;
+  constructor(rest: GitHubRestClient, opts: EnvironmentsOptions);
+  listEnvironments(): Promise<Environment[]>;
+  upsertEnvironment(env: Environment): Promise<void>;
+  deleteEnvironment(name: string): Promise<void>;
+  private flattenReviewers;
+}
+//#endregion
+//#region src/capabilities/ci.d.ts
+interface CiOptions {
+  repo: string;
+}
+declare class GitHubCi implements Ci {
+  private readonly rest;
+  readonly key: "ci";
+  readonly providerName = "github";
+  private readonly base;
+  constructor(rest: GitHubRestClient, opts: CiOptions);
+  listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
+  getRun(id: string | number): Promise<CiRun>;
+  /**
+   * GitHub reports run state as `status` plus `conclusion` (the latter
+   * is set once `status === 'completed'`). Holocron's `CiRunStatus`
+   * collapses these onto one axis — when complete, the conclusion is
+   * the meaningful value.
+   */
+  private mapRun;
+  private mapConclusion;
+}
+//#endregion
+//#region src/capabilities/issues.d.ts
+interface IssuesOptions {
+  repo: string;
+  /** Lifecycle slot → status label name. */
+  labels: {
+    inProgress: string;
+    inReview: string;
+  };
+}
+declare class GitHubIssues implements Issues {
+  private readonly rest;
+  readonly key: "issues";
+  readonly providerName = "github";
+  private readonly owner;
+  private readonly repoName;
+  private readonly base;
+  private readonly labels;
+  constructor(rest: GitHubRestClient, opts: IssuesOptions);
+  getMyself(): Promise<TrackerUser>;
+  search(filter: IssueSearchFilter): Promise<Issue[]>;
+  get(key: string): Promise<Issue>;
+  create(input: {
+    summary: string;
+    body?: string;
+    labels?: string[];
+    milestone?: string;
+  }): Promise<{
+    key: string;
+  }>;
+  transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
+  comment(key: string, body: string): Promise<void>;
+  doctor(): Promise<TrackerDoctorReport>;
+  private resolveMilestone;
+  private removeStatusLabels;
+  private mapIssue;
+}
+//#endregion
+//#region src/index.d.ts
+interface GitHubPluginOptions extends ResolveTokenInput {
+  /** "owner/name" — e.g., "theholocron/holocron". Required. */
+  repo: string;
+  /** Absolute path to the working repo root. Used by `source`'s
+   * workflow-file methods. Defaults to `process.cwd()`. */
+  repoRoot?: string;
+  /** Lifecycle slot → label name. Used by the `issues` capability. */
+  labels?: {
+    inProgress: string;
+    inReview: string;
+  };
+  /** Override base URL for tests. Defaults to https://api.github.com. */
+  baseUrl?: string;
+  /** Override `fetch` for tests. Defaults to global `fetch`. */
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: GitHubPluginOptions;
+  rest: GitHubRestClient;
+  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;
+declare function ci(ctx: PluginContext): Ci;
+declare function issues(ctx: PluginContext): Issues;
+declare function createPlugin(options: GitHubPluginOptions): {
+  name: string;
+  capabilities: {
+    source: () => Source;
+    ci: () => Ci;
+    secrets: () => Secrets;
+    environments: () => Environments;
+    issues: () => Issues;
+  };
+};
+//#endregion
+export { type Auth, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubPluginOptions, GitHubRestClient, GitHubSecrets, GitHubSource, PluginContext, ResolveTokenInput, ci, createContext, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source };

package/dist/index.mjs

@@ -0,0 +1,660 @@
+import { createRequire } from "node:module";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ProviderApiError } from "@theholocron/cli";
+//#region src/auth.ts
+/**
+* Token resolution for the GitHub plugin. See README §Auth.
+*
+* Resolution order:
+*   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)
+*
+* No `gh auth token` fallback by design — it usually has narrower
+* scopes than admin commands need.
+*/
+var AuthError = class extends Error {
+	name = "AuthError";
+};
+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.");
+	return token;
+}
+//#endregion
+//#region src/repo.ts
+var RepoError = class extends Error {
+	name = "RepoError";
+};
+function parseRepo(repo) {
+	if (!repo) throw new RepoError("repo is required; pass { repo: \"owner/name\" } in plugin options");
+	const [owner, name] = repo.split("/");
+	if (!owner || !name) throw new RepoError(`invalid repo "${repo}" — expected "owner/name"`);
+	return {
+		owner,
+		name
+	};
+}
+//#endregion
+//#region src/capabilities/ci.ts
+var GitHubCi = class {
+	rest;
+	key = "ci";
+	providerName = "github";
+	base;
+	constructor(rest, opts) {
+		this.rest = rest;
+		const { owner, name } = parseRepo(opts.repo);
+		this.base = `/repos/${owner}/${name}/actions/runs`;
+	}
+	async listRuns(filter) {
+		const params = new URLSearchParams();
+		if (filter?.branch) params.set("branch", filter.branch);
+		if (filter?.limit) params.set("per_page", String(filter.limit));
+		if (filter?.status) params.set("status", filter.status);
+		const qs = params.toString();
+		const path = qs ? `${this.base}?${qs}` : this.base;
+		return (await this.rest.request(path)).workflow_runs.map((r) => this.mapRun(r));
+	}
+	async getRun(id) {
+		const raw = await this.rest.request(`${this.base}/${id}`);
+		return this.mapRun(raw);
+	}
+	/**
+	* GitHub reports run state as `status` plus `conclusion` (the latter
+	* is set once `status === 'completed'`). Holocron's `CiRunStatus`
+	* collapses these onto one axis — when complete, the conclusion is
+	* the meaningful value.
+	*/
+	mapRun(raw) {
+		const status = raw.status === "completed" && raw.conclusion ? this.mapConclusion(raw.conclusion) : raw.status;
+		return {
+			id: raw.id,
+			workflowName: raw.name ?? raw.display_title,
+			branch: raw.head_branch,
+			sha: raw.head_sha,
+			status,
+			url: raw.html_url,
+			startedAt: raw.created_at,
+			...raw.status === "completed" ? { completedAt: raw.updated_at } : {}
+		};
+	}
+	mapConclusion(conclusion) {
+		switch (conclusion) {
+			case "success":
+			case "failure":
+			case "cancelled":
+			case "skipped": return conclusion;
+			default: return "completed";
+		}
+	}
+};
+//#endregion
+//#region src/capabilities/environments.ts
+var GitHubEnvironments = class {
+	rest;
+	key = "environments";
+	providerName = "github";
+	base;
+	constructor(rest, opts) {
+		this.rest = rest;
+		const { owner, name } = parseRepo(opts.repo);
+		this.base = `/repos/${owner}/${name}/environments`;
+	}
+	async listEnvironments() {
+		return (await this.rest.request(this.base)).environments.map((e) => ({
+			name: e.name,
+			waitTimer: e.wait_timer,
+			preventSelfReview: e.prevent_self_review,
+			reviewers: this.flattenReviewers(e.protection_rules)
+		}));
+	}
+	async upsertEnvironment(env) {
+		const body = {};
+		if (env.waitTimer !== void 0) body.wait_timer = env.waitTimer;
+		if (env.preventSelfReview !== void 0) body.prevent_self_review = env.preventSelfReview;
+		if (env.reviewers !== void 0) body.reviewers = env.reviewers.map((r) => ({
+			type: r.type,
+			id: r.id
+		}));
+		await this.rest.request(`${this.base}/${encodeURIComponent(env.name)}`, {
+			method: "PUT",
+			body
+		});
+	}
+	async deleteEnvironment(name) {
+		await this.rest.request(`${this.base}/${encodeURIComponent(name)}`, {
+			method: "DELETE",
+			expectNoContent: true
+		});
+	}
+	flattenReviewers(rules) {
+		if (!rules) return void 0;
+		const reviewersRule = rules.find((r) => r.type === "required_reviewers");
+		if (!reviewersRule?.reviewers) return void 0;
+		return reviewersRule.reviewers.map((r) => ({
+			type: r.type,
+			id: r.reviewer.id
+		}));
+	}
+};
+//#endregion
+//#region src/capabilities/issues.ts
+var GitHubIssues = class {
+	rest;
+	key = "issues";
+	providerName = "github";
+	owner;
+	repoName;
+	base;
+	labels;
+	constructor(rest, opts) {
+		this.rest = rest;
+		const { owner, name } = parseRepo(opts.repo);
+		this.owner = owner;
+		this.repoName = name;
+		this.base = `/repos/${owner}/${name}`;
+		this.labels = opts.labels;
+	}
+	async getMyself() {
+		return mapUser(await this.rest.request("/user"));
+	}
+	async search(filter) {
+		const params = new URLSearchParams({
+			state: filter.openOnly ? "open" : "all",
+			sort: "updated",
+			direction: "desc",
+			per_page: String(filter.limit ?? 50),
+			filter: "all"
+		});
+		if (filter.assignee === "currentUser") {
+			const me = await this.getMyself();
+			params.set("assignee", me.id);
+		} else if (filter.assignee) params.set("assignee", filter.assignee);
+		return (await this.rest.request(`${this.base}/issues?${params.toString()}`)).filter((i) => !i.pull_request).map((i) => this.mapIssue(i));
+	}
+	async get(key) {
+		const number = parseIssueNumber(key, this.owner, this.repoName);
+		const raw = await this.rest.request(`${this.base}/issues/${number}`);
+		return this.mapIssue(raw);
+	}
+	async create(input) {
+		const body = { title: input.summary };
+		if (input.body) body.body = input.body;
+		if (input.labels?.length) body.labels = input.labels;
+		if (input.milestone) body.milestone = await this.resolveMilestone(input.milestone);
+		return { key: `#${(await this.rest.request(`${this.base}/issues`, {
+			method: "POST",
+			body
+		})).number}` };
+	}
+	async transition(key, slot) {
+		const number = parseIssueNumber(key, this.owner, this.repoName);
+		const issue = await this.rest.request(`${this.base}/issues/${number}`);
+		const currentStatusLabels = issue.labels.map((l) => l.name).filter((n) => n.startsWith("status:"));
+		if (slot === "done") {
+			if (issue.state === "closed") return {
+				transitioned: false,
+				status: "closed",
+				via: "already closed"
+			};
+			await this.removeStatusLabels(number, currentStatusLabels);
+			await this.rest.request(`${this.base}/issues/${number}`, {
+				method: "PATCH",
+				body: {
+					state: "closed",
+					state_reason: "completed"
+				}
+			});
+			return {
+				transitioned: true,
+				status: "closed",
+				via: "closed (completed)"
+			};
+		}
+		const targetLabel = slot === "inProgress" ? this.labels.inProgress : this.labels.inReview;
+		const alreadyOpen = issue.state === "open";
+		const alreadyLabeled = currentStatusLabels.includes(targetLabel);
+		if (alreadyOpen && alreadyLabeled && currentStatusLabels.length === 1) return {
+			transitioned: false,
+			status: `open + ${targetLabel}`,
+			via: "already there"
+		};
+		if (!alreadyOpen) await this.rest.request(`${this.base}/issues/${number}`, {
+			method: "PATCH",
+			body: { state: "open" }
+		});
+		const toRemove = currentStatusLabels.filter((n) => n !== targetLabel);
+		if (toRemove.length) await this.removeStatusLabels(number, toRemove);
+		if (!alreadyLabeled) await this.rest.request(`${this.base}/issues/${number}/labels`, {
+			method: "POST",
+			body: { labels: [targetLabel] }
+		});
+		return {
+			transitioned: true,
+			status: `open + ${targetLabel}`,
+			via: `label set to ${targetLabel}`
+		};
+	}
+	async comment(key, body) {
+		const number = parseIssueNumber(key, this.owner, this.repoName);
+		await this.rest.request(`${this.base}/issues/${number}/comments`, {
+			method: "POST",
+			body: { body }
+		});
+	}
+	async doctor() {
+		const me = await this.getMyself();
+		const repo = await this.rest.request(this.base);
+		const allLabels = await this.rest.request(`${this.base}/labels?per_page=100`);
+		const labelNames = new Set(allLabels.map((l) => l.name));
+		const statuses = [
+			{
+				name: "open (no status label)",
+				category: "open"
+			},
+			{
+				name: `open + ${this.labels.inProgress}`,
+				category: "in-progress"
+			},
+			{
+				name: `open + ${this.labels.inReview}`,
+				category: "in-review"
+			},
+			{
+				name: "closed",
+				category: "done"
+			}
+		];
+		const lifecycle = [
+			{
+				slot: "inProgress",
+				value: this.labels.inProgress,
+				resolved: labelNames.has(this.labels.inProgress),
+				note: labelNames.has(this.labels.inProgress) ? `label exists in ${repo.full_name}` : "(label not defined yet — auto-created on first apply)"
+			},
+			{
+				slot: "inReview",
+				value: this.labels.inReview,
+				resolved: labelNames.has(this.labels.inReview),
+				note: labelNames.has(this.labels.inReview) ? `label exists in ${repo.full_name}` : "(label not defined yet — auto-created on first apply)"
+			},
+			{
+				slot: "done",
+				value: "closed (state_reason=completed)",
+				resolved: true,
+				note: "(intrinsic — GitHub close-with-reason)"
+			}
+		];
+		return {
+			authedAs: `${me.displayName} (${me.emailAddress ?? me.id})`,
+			projectLabel: `Repo: ${repo.full_name}`,
+			statuses,
+			lifecycle
+		};
+	}
+	async resolveMilestone(ref) {
+		if (/^\d+$/.test(ref)) return parseInt(ref, 10);
+		const match = (await this.rest.request(`${this.base}/milestones?state=all&per_page=100`)).find((m) => m.title.toLowerCase() === ref.toLowerCase());
+		if (!match) throw new Error(`Milestone "${ref}" not found in ${this.owner}/${this.repoName}. Use the numeric id or an exact title.`);
+		return match.number;
+	}
+	async removeStatusLabels(number, labels) {
+		for (const label of labels) await this.rest.request(`${this.base}/issues/${number}/labels/${encodeURIComponent(label)}`, { method: "DELETE" });
+	}
+	mapIssue(raw) {
+		const statusLabels = raw.labels.map((l) => l.name).filter((n) => n.startsWith("status:"));
+		let category = "open";
+		let statusName = raw.state === "closed" ? "closed" : "open";
+		if (raw.state === "closed") category = "done";
+		else if (statusLabels.includes(this.labels.inProgress)) {
+			category = "in-progress";
+			statusName = `open + ${this.labels.inProgress}`;
+		} else if (statusLabels.includes(this.labels.inReview)) {
+			category = "in-review";
+			statusName = `open + ${this.labels.inReview}`;
+		}
+		return {
+			key: `#${raw.number}`,
+			id: String(raw.id),
+			summary: raw.title,
+			...raw.body ? { body: raw.body } : {},
+			status: statusName,
+			statusCategory: category,
+			assignee: raw.assignee ? mapUser(raw.assignee) : null,
+			updated: raw.updated_at,
+			url: raw.html_url
+		};
+	}
+};
+/**
+* Accept "#42", "42", or "owner/repo#42" and return the numeric id.
+* Cross-repo refs are allowed in input but the adapter is bound to one
+* repo — we error if the owner/repo doesn't match.
+*/
+function parseIssueNumber(key, owner, repoName) {
+	const trimmed = key.trim();
+	const crossMatch = trimmed.match(/^([^/]+)\/([^#]+)#(\d+)$/);
+	if (crossMatch) {
+		if (crossMatch[1] !== owner || crossMatch[2] !== repoName) throw new Error(`Issue key "${key}" references ${crossMatch[1]}/${crossMatch[2]} but this adapter is bound to ${owner}/${repoName}.`);
+		return parseInt(crossMatch[3], 10);
+	}
+	const num = trimmed.replace(/^#/, "");
+	if (!/^\d+$/.test(num)) throw new Error(`Invalid GitHub issue key "${key}" — expected #N or N.`);
+	return parseInt(num, 10);
+}
+function mapUser(raw) {
+	return {
+		id: raw.login,
+		displayName: raw.name ?? raw.login,
+		...raw.email ? { emailAddress: raw.email } : {}
+	};
+}
+//#endregion
+//#region src/sodium.ts
+/**
+* libsodium sealed-box encryption for GitHub Actions secrets.
+*
+* GitHub stores Actions / Codespaces / Dependabot secrets encrypted
+* with a curve25519 public key (returned by the `/actions/secrets/public-key`
+* endpoint). Callers fetch that key, encrypt the plaintext value with
+* `crypto_box_seal`, then PUT the base64-encoded ciphertext + `key_id`.
+*
+* Reference: https://docs.github.com/en/rest/actions/secrets#create-or-update-a-repository-secret
+*
+* **Why createRequire?** `libsodium-wrappers@0.7.x` ships a broken
+* ESM bundle — the `dist/modules-esm/libsodium-wrappers.mjs` entry
+* imports a sibling `libsodium.mjs` that isn't included in the npm
+* tarball. Native `import` against the package therefore fails.
+* `createRequire` routes through Node's CJS resolver, which honors
+* the `"require"` condition in the package's exports map and loads
+* the self-contained CJS bundle instead. Same API, working module.
+*/
+const sodium = createRequire(import.meta.url)("libsodium-wrappers");
+/**
+* Encrypt `value` for the given GitHub-provided base64 public key.
+* Returns the base64 ciphertext to send as `encrypted_value`.
+*/
+async function encryptSecret(publicKeyBase64, value) {
+	await sodium.ready;
+	const publicKey = sodium.from_base64(publicKeyBase64, sodium.base64_variants.ORIGINAL);
+	const plaintext = sodium.from_string(value);
+	const ciphertext = sodium.crypto_box_seal(plaintext, publicKey);
+	return sodium.to_base64(ciphertext, sodium.base64_variants.ORIGINAL);
+}
+//#endregion
+//#region src/capabilities/secrets.ts
+var GitHubSecrets = class {
+	rest;
+	key = "secrets";
+	providerName = "github";
+	repoBase;
+	constructor(rest, opts) {
+		this.rest = rest;
+		const { owner, name } = parseRepo(opts.repo);
+		this.repoBase = `/repos/${owner}/${name}`;
+	}
+	async listSecrets(scope) {
+		const base = this.scopeBase(scope);
+		return (await this.rest.request(`${base}/secrets`)).secrets.map((s) => s.name);
+	}
+	async setSecret(scope, name, value) {
+		const base = this.scopeBase(scope);
+		const pk = await this.rest.request(`${base}/secrets/public-key`);
+		const body = {
+			encrypted_value: await encryptSecret(pk.key, value),
+			key_id: pk.key_id
+		};
+		if (scope.kind === "organization") body.visibility = "all";
+		await this.rest.request(`${base}/secrets/${name}`, {
+			method: "PUT",
+			body,
+			expectNoContent: true
+		});
+	}
+	async deleteSecret(scope, name) {
+		const base = this.scopeBase(scope);
+		await this.rest.request(`${base}/secrets/${name}`, {
+			method: "DELETE",
+			expectNoContent: true
+		});
+	}
+	/** Endpoint root for the given scope. */
+	scopeBase(scope) {
+		switch (scope.kind) {
+			case "repo": return `${this.repoBase}/actions`;
+			case "environment": return `${this.repoBase}/environments/${scope.name}`;
+			case "organization": return `/orgs/${scope.name}/actions`;
+		}
+	}
+};
+//#endregion
+//#region src/capabilities/source.ts
+/**
+* `source` capability for GitHub.
+*
+* Ported from rando-id/rando.id `packages/cli/src/adapters/gh-rest.ts`
+* with two changes for v2:
+*
+*  - Repo coords are bound at construction time (not passed per call)
+*  - Workflow files are local-fs operations (not GH API) — they live
+*    in the consumer's `.github/workflows/` directory
+*/
+var GitHubSource = class {
+	rest;
+	key = "source";
+	providerName = "github";
+	owner;
+	name;
+	repoPath;
+	workflowDir;
+	constructor(rest, opts) {
+		this.rest = rest;
+		const { owner, name } = parseRepo(opts.repo);
+		this.owner = owner;
+		this.name = name;
+		this.repoPath = `/repos/${owner}/${name}`;
+		this.workflowDir = join(opts.repoRoot, ".github", "workflows");
+	}
+	async whoami() {
+		return { login: (await this.rest.request("/user")).login };
+	}
+	async getRepo() {
+		const data = await this.rest.request(this.repoPath);
+		return {
+			owner: this.owner,
+			name: this.name,
+			defaultBranch: data.default_branch
+		};
+	}
+	async listRulesets() {
+		return this.rest.request(`${this.repoPath}/rulesets`);
+	}
+	async createRuleset(payload) {
+		return this.rest.request(`${this.repoPath}/rulesets`, {
+			method: "POST",
+			body: payload
+		});
+	}
+	async updateRuleset(id, payload) {
+		return this.rest.request(`${this.repoPath}/rulesets/${id}`, {
+			method: "PUT",
+			body: payload
+		});
+	}
+	async updateRepoSettings(settings) {
+		await this.rest.request(this.repoPath, {
+			method: "PATCH",
+			body: settings
+		});
+	}
+	async enableVulnerabilityAlerts() {
+		await this.rest.request(`${this.repoPath}/vulnerability-alerts`, {
+			method: "PUT",
+			expectNoContent: true
+		});
+	}
+	async enableAutomatedSecurityFixes() {
+		await this.rest.request(`${this.repoPath}/automated-security-fixes`, {
+			method: "PUT",
+			expectNoContent: true
+		});
+	}
+	async enableSecretScanning() {
+		await this.rest.request(this.repoPath, {
+			method: "PATCH",
+			body: { security_and_analysis: {
+				secret_scanning: { status: "enabled" },
+				secret_scanning_push_protection: { status: "enabled" }
+			} }
+		});
+	}
+	async enablePrivateVulnerabilityReporting() {
+		await this.rest.request(`${this.repoPath}/private-vulnerability-reporting`, {
+			method: "PUT",
+			expectNoContent: true
+		});
+	}
+	async listWorkflowFiles() {
+		try {
+			return (await readdir(this.workflowDir)).filter((e) => e.endsWith(".yml") || e.endsWith(".yaml")).sort();
+		} catch (err) {
+			if (isENOENT(err)) return [];
+			throw err;
+		}
+	}
+	async readWorkflowFile(name) {
+		try {
+			return await readFile(join(this.workflowDir, name), "utf8");
+		} catch (err) {
+			if (isENOENT(err)) return null;
+			throw err;
+		}
+	}
+	async writeWorkflowFile(name, contents) {
+		await ensureDir(this.workflowDir);
+		await writeFile(join(this.workflowDir, name), contents, "utf8");
+	}
+	async removeWorkflowFile(name) {
+		try {
+			await rm(join(this.workflowDir, name));
+		} catch (err) {
+			if (isENOENT(err)) return;
+			throw err;
+		}
+	}
+};
+function isENOENT(err) {
+	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+async function ensureDir(path) {
+	try {
+		if (!(await stat(path)).isDirectory()) throw new Error(`${path} exists but is not a directory`);
+	} catch (err) {
+		if (isENOENT(err)) {
+			await mkdir(path, { recursive: true });
+			return;
+		}
+		throw err;
+	}
+}
+//#endregion
+//#region src/rest.ts
+/**
+* Thin REST wrapper around api.github.com.
+*
+* Adapted from rando-id/rando.id `packages/cli/src/adapters/gh-rest.ts`
+* `request<T>` method into a standalone class so each capability can
+* hold a reference and share the same auth/error handling.
+*
+* Errors throw `ProviderApiError` from `@theholocron/cli`, which the
+* orchestrator catches to soft-skip rather than abort the whole pipeline.
+*/
+var GitHubRestClient = class {
+	token;
+	fetchImpl;
+	baseUrl;
+	constructor(opts) {
+		this.token = opts.token;
+		this.fetchImpl = opts.fetch ?? globalThis.fetch;
+		this.baseUrl = (opts.baseUrl ?? "https://api.github.com").replace(/\/+$/, "");
+	}
+	async request(path, opts = {}) {
+		const url = `${this.baseUrl}${path}`;
+		const headers = {
+			accept: "application/vnd.github+json",
+			authorization: `Bearer ${this.token}`,
+			"x-github-api-version": "2022-11-28"
+		};
+		const init = {
+			method: opts.method ?? "GET",
+			headers
+		};
+		if (opts.body !== void 0) {
+			headers["content-type"] = "application/json";
+			init.body = JSON.stringify(opts.body);
+		}
+		const res = await this.fetchImpl(url, init);
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			throw new ProviderApiError(`GitHub ${init.method} ${path} → ${res.status}`, res.status, body);
+		}
+		if (opts.expectNoContent || res.status === 204) return;
+		const text = await res.text();
+		if (!text) return void 0;
+		return JSON.parse(text);
+	}
+};
+//#endregion
+//#region src/index.ts
+function createContext(options) {
+	return {
+		options,
+		rest: new GitHubRestClient({
+			token: resolveToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		}),
+		repo: options.repo,
+		repoRoot: options.repoRoot ?? process.cwd()
+	};
+}
+function source(ctx) {
+	return new GitHubSource(ctx.rest, {
+		repo: ctx.repo,
+		repoRoot: ctx.repoRoot
+	});
+}
+function secrets(ctx) {
+	return new GitHubSecrets(ctx.rest, { repo: ctx.repo });
+}
+function environments(ctx) {
+	return new GitHubEnvironments(ctx.rest, { repo: ctx.repo });
+}
+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
+	});
+}
+function createPlugin(options) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-github",
+		capabilities: {
+			source: () => source(ctx),
+			ci: () => ci(ctx),
+			secrets: () => secrets(ctx),
+			environments: () => environments(ctx),
+			issues: () => issues(ctx)
+		}
+	};
+}
+//#endregion
+export { AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubRestClient, GitHubSecrets, GitHubSource, ci, createContext, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@theholocron/holocron-plugin-github",
+  "version": "2.0.0-alpha.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-github"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "2.0.0-alpha.0"
+  },
+  "dependencies": {
+    "libsodium-wrappers": "^0.7.15"
+  },
+  "devDependencies": {
+    "@theholocron/eslint-config": "^4.1.0",
+    "@theholocron/tsconfig": "^4.1.0",
+    "@tsconfig/node-lts": "^24.0.0",
+    "@types/libsodium-wrappers": "^0.7.14",
+    "@vitest/coverage-v8": "^3.2.6",
+    "eslint": "^9.36.0",
+    "globals": "^16.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6",
+    "tsdown": "^0.22.3",
+    "@theholocron/cli": "2.0.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "types": "./dist/index.d.mts"
+}