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

package/README.md

@@ -13,8 +13,10 @@ against the GitHub REST API:
 
 ## Install
 
+<!-- prettier-ignore -->
 ```bash
 pnpm add -D @theholocron/holocron-plugin-github@alpha
+
 ```
 
 ## Auth
@@ -33,17 +35,19 @@ toggles, etc.) — silent fallback would surface as mysterious 403s.
 
 ## Config
 
+<!-- prettier-ignore -->
 ```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

package/dist/index.d.mts

@@ -1,62 +1,8 @@
-import { Auth, Ci, CiRun, CiRunFilter, Environment, Environments, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, RepoRef, RepoSettings, Ruleset, SecretScope, Secrets, Source, TrackerDoctorReport, TrackerUser } from "@theholocron/cli";
+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, TrackerDoctorReport, TrackerUser } from "@theholocron/cli";
 
 //#region src/auth.d.ts
-/**
- * Token resolution for the GitHub plugin. See README §Auth.
- *
- * 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.
- */
-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;
-  /** Keyring lookup fn; passed in for testability. Defaults to `getToken(provider)`. */
-  keyring?: (provider: string) => string | null;
-}
-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>;
-}
+declare const resolveToken: (input?: import("@theholocron/http-client").ResolveTokenInput) => string;
 //#endregion
 //#region src/sodium.d.ts
 /**
@@ -68,19 +14,18 @@ declare function encryptSecret(publicKeyBase64: string, value: string): Promise<
 //#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;
+  private readonly client;
   readonly key: "source";
   readonly providerName = "github";
   private readonly owner;
   private readonly name;
-  private readonly repoPath;
+  private readonly repo;
   private readonly repoRoot;
   private readonly workflowDir;
-  constructor(rest: GitHubRestClient, opts: SourceOptions);
+  constructor(client: GitHubClient, opts: SourceOptions);
   whoami(): Promise<{
     login: string;
   }>;
@@ -94,6 +39,7 @@ declare class GitHubSource implements Source {
   enableAutomatedSecurityFixes(): Promise<void>;
   enableSecretScanning(): Promise<void>;
   enableCodeScanning(): Promise<string>;
+  disableDefaultCodeScanning(): Promise<void>;
   enableDependencyGraph(): Promise<void>;
   enablePrivateVulnerabilityReporting(): Promise<void>;
   listWorkflowFiles(): Promise<string[]>;
@@ -101,6 +47,9 @@ declare class GitHubSource implements Source {
   writeWorkflowFile(name: string, contents: string): Promise<void>;
   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>): Promise<string>;
+  syncTopics(topics: string[]): Promise<string>;
 }
 //#endregion
 //#region src/capabilities/secrets.d.ts
@@ -108,16 +57,14 @@ interface SecretsOptions {
   repo: string;
 }
 declare class GitHubSecrets implements Secrets {
-  private readonly rest;
+  private readonly client;
+  private readonly opts;
   readonly key: "secrets";
   readonly providerName = "github";
-  private readonly repoBase;
-  constructor(rest: GitHubRestClient, opts: SecretsOptions);
+  constructor(client: GitHubClient, 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
@@ -125,11 +72,11 @@ interface EnvironmentsOptions {
   repo: string;
 }
 declare class GitHubEnvironments implements Environments {
-  private readonly rest;
+  private readonly client;
+  private readonly opts;
   readonly key: "environments";
   readonly providerName = "github";
-  private readonly base;
-  constructor(rest: GitHubRestClient, opts: EnvironmentsOptions);
+  constructor(client: GitHubClient, opts: EnvironmentsOptions);
   listEnvironments(): Promise<Environment[]>;
   upsertEnvironment(env: Environment): Promise<void>;
   deleteEnvironment(name: string): Promise<void>;
@@ -141,19 +88,13 @@ interface CiOptions {
   repo: string;
 }
 declare class GitHubCi implements Ci {
-  private readonly rest;
+  private readonly client;
+  private readonly opts;
   readonly key: "ci";
   readonly providerName = "github";
-  private readonly base;
-  constructor(rest: GitHubRestClient, opts: CiOptions);
+  constructor(client: GitHubClient, 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;
 }
@@ -165,9 +106,7 @@ interface IssuesOptions {
    * 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.
+   * `doctor` reports the two label-backed slots as unresolved.
    */
   labels?: {
     inProgress: string;
@@ -175,14 +114,14 @@ interface IssuesOptions {
   };
 }
 declare class GitHubIssues implements Issues {
-  private readonly rest;
+  private readonly client;
   readonly key: "issues";
   readonly providerName = "github";
   private readonly owner;
   private readonly repoName;
-  private readonly base;
+  private readonly repo;
   private readonly labels;
-  constructor(rest: GitHubRestClient, opts: IssuesOptions);
+  constructor(client: GitHubClient, opts: IssuesOptions);
   getMyself(): Promise<TrackerUser>;
   search(filter: IssueSearchFilter): Promise<Issue[]>;
   get(key: string): Promise<Issue>;
@@ -202,6 +141,22 @@ declare class GitHubIssues implements Issues {
   private mapIssue;
 }
 //#endregion
+//#region src/capabilities/labels.d.ts
+interface CanonicalLabel {
+  readonly name: string;
+  readonly color: string;
+  readonly description: string;
+}
+/**
+ * Idempotently synchronise a repo's labels to the canonical set.
+ *
+ * - Creates labels that are missing.
+ * - PATCHes labels whose color or description has drifted.
+ * - 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/verify-token.d.ts
 /**
  * `verifyToken` — plugin-level export used by `holocron auth set` +
@@ -247,7 +202,7 @@ interface GitHubPluginOptions extends ResolveTokenInput {
 }
 interface PluginContext {
   options: GitHubPluginOptions;
-  rest: GitHubRestClient;
+  client: GitHubClient;
   repo: string;
   repoRoot: string;
 }
@@ -275,4 +230,4 @@ declare function createPlugin(options: GitHubPluginOptions): {
  */
 declare const AUTH_HINT: string;
 //#endregion
-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 };
+export { AUTH_HINT, type Auth, AuthError, type CanonicalLabel, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubPluginOptions, GitHubSecrets, GitHubSource, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, ci, createContext, createGitHubClient, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source, syncLabels, verifyToken };

package/dist/index.mjs

@@ -1,77 +1,37 @@
 import { createRequire } from "node:module";
-import { ProviderApiError, getToken } from "@theholocron/cli";
+import { createGitHubClient, createGitHubClient as createGitHubClient$1 } from "@theholocron/github-client";
+import { AuthError, createResolveToken } from "@theholocron/cli";
 import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 //#region src/auth.ts
-/**
-* Token resolution for the GitHub plugin. See README §Auth.
-*
-* 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.
-*/
-var AuthError = class extends Error {
-	name = "AuthError";
-};
-function resolveToken(input = {}) {
-	const env = input.env ?? process.env;
-	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
-//#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
-	};
-}
+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>"
+});
 //#endregion
 //#region src/capabilities/ci.ts
 var GitHubCi = class {
-	rest;
+	client;
+	opts;
 	key = "ci";
 	providerName = "github";
-	base;
-	constructor(rest, opts) {
-		this.rest = rest;
-		const { owner, name } = parseRepo(opts.repo);
-		this.base = `/repos/${owner}/${name}/actions/runs`;
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
 	}
 	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));
+		return (await this.client.workflows.listRuns(this.opts.repo, {
+			branch: filter?.branch,
+			limit: filter?.limit,
+			status: filter?.status
+		})).map((r) => this.mapRun(r));
 	}
 	async getRun(id) {
-		const raw = await this.rest.request(`${this.base}/${id}`);
+		const raw = await this.client.workflows.getRun(this.opts.repo, 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 {
@@ -98,17 +58,16 @@ var GitHubCi = class {
 //#endregion
 //#region src/capabilities/environments.ts
 var GitHubEnvironments = class {
-	rest;
+	client;
+	opts;
 	key = "environments";
 	providerName = "github";
-	base;
-	constructor(rest, opts) {
-		this.rest = rest;
-		const { owner, name } = parseRepo(opts.repo);
-		this.base = `/repos/${owner}/${name}/environments`;
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
 	}
 	async listEnvironments() {
-		return (await this.rest.request(this.base)).environments.map((e) => ({
+		return (await this.client.environments.listEnvironments(this.opts.repo)).map((e) => ({
 			name: e.name,
 			waitTimer: e.wait_timer,
 			preventSelfReview: e.prevent_self_review,
@@ -123,16 +82,10 @@ var GitHubEnvironments = class {
 			type: r.type,
 			id: r.id
 		}));
-		await this.rest.request(`${this.base}/${encodeURIComponent(env.name)}`, {
-			method: "PUT",
-			body
-		});
+		await this.client.environments.upsertEnvironment(this.opts.repo, env.name, body);
 	}
 	async deleteEnvironment(name) {
-		await this.rest.request(`${this.base}/${encodeURIComponent(name)}`, {
-			method: "DELETE",
-			expectNoContent: true
-		});
+		await this.client.environments.deleteEnvironment(this.opts.repo, name);
 	}
 	flattenReviewers(rules) {
 		if (!rules) return void 0;
@@ -147,41 +100,51 @@ var GitHubEnvironments = class {
 //#endregion
 //#region src/capabilities/issues.ts
 var GitHubIssues = class {
-	rest;
+	client;
 	key = "issues";
 	providerName = "github";
 	owner;
 	repoName;
-	base;
+	repo;
 	labels;
-	constructor(rest, opts) {
-		this.rest = rest;
-		const { owner, name } = parseRepo(opts.repo);
+	constructor(client, opts) {
+		this.client = client;
+		const [owner = "", repoName = ""] = opts.repo.split("/", 2);
 		this.owner = owner;
-		this.repoName = name;
-		this.base = `/repos/${owner}/${name}`;
+		this.repoName = repoName;
+		this.repo = opts.repo;
 		this.labels = opts.labels;
 	}
 	async getMyself() {
-		return mapUser(await this.rest.request("/user"));
+		const raw = await this.client.user.getCurrentUser();
+		return {
+			id: raw.login,
+			displayName: raw.name ?? raw.login,
+			...raw.email ? { emailAddress: raw.email } : {}
+		};
 	}
 	async search(filter) {
-		const params = new URLSearchParams({
+		const params = {
 			state: filter.openOnly ? "open" : "all",
 			sort: "updated",
 			direction: "desc",
-			per_page: String(filter.limit ?? 50),
+			per_page: 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));
+		};
+		if (filter.assignee === "currentUser") params.assignee = (await this.getMyself()).id;
+		else if (filter.assignee) params.assignee = filter.assignee;
+		return (await this.client.issues.listIssues(this.repo, {
+			state: params.state,
+			sort: params.sort,
+			direction: params.direction,
+			per_page: Number(params.per_page),
+			filter: params.filter,
+			assignee: params.assignee
+		})).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}`);
+		const raw = await this.client.issues.getIssue(this.repo, number);
 		return this.mapIssue(raw);
 	}
 	async create(input) {
@@ -189,14 +152,11 @@ var GitHubIssues = class {
 		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}` };
+		return { key: `#${(await this.client.issues.createIssue(this.repo, 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 issue = await this.client.issues.getIssue(this.repo, number);
 		const currentStatusLabels = issue.labels.map((l) => l.name).filter((n) => n.startsWith("status:"));
 		if (slot === "done") {
 			if (issue.state === "closed") return {
@@ -205,12 +165,9 @@ var GitHubIssues = class {
 				via: "already closed"
 			};
 			await this.removeStatusLabels(number, currentStatusLabels);
-			await this.rest.request(`${this.base}/issues/${number}`, {
-				method: "PATCH",
-				body: {
-					state: "closed",
-					state_reason: "completed"
-				}
+			await this.client.issues.updateIssue(this.repo, number, {
+				state: "closed",
+				state_reason: "completed"
 			});
 			return {
 				transitioned: true,
@@ -227,16 +184,10 @@ var GitHubIssues = class {
 			status: `open + ${targetLabel}`,
 			via: "already there"
 		};
-		if (!alreadyOpen) await this.rest.request(`${this.base}/issues/${number}`, {
-			method: "PATCH",
-			body: { state: "open" }
-		});
+		if (!alreadyOpen) await this.client.issues.updateIssue(this.repo, number, { 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] }
-		});
+		if (!alreadyLabeled) await this.client.issues.addLabels(this.repo, number, [targetLabel]);
 		return {
 			transitioned: true,
 			status: `open + ${targetLabel}`,
@@ -245,15 +196,12 @@ var GitHubIssues = class {
 	}
 	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 }
-		});
+		await this.client.issues.createComment(this.repo, number, 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 repo = await this.client.repos.getRepo(this.repo);
+		const allLabels = await this.client.labels.listLabels(this.repo);
 		const labelNames = new Set(allLabels.map((l) => l.name));
 		const statuses = [
 			{
@@ -320,12 +268,12 @@ var GitHubIssues = class {
 	}
 	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());
+		const match = (await this.client.issues.listMilestones(this.repo, { state: "all" })).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" });
+		for (const label of labels) await this.client.issues.removeLabel(this.repo, number, label);
 	}
 	mapIssue(raw) {
 		const statusLabels = raw.labels.map((l) => l.name).filter((n) => n.startsWith("status:"));
@@ -346,17 +294,16 @@ var GitHubIssues = class {
 			...raw.body ? { body: raw.body } : {},
 			status: statusName,
 			statusCategory: category,
-			assignee: raw.assignee ? mapUser(raw.assignee) : null,
+			assignee: raw.assignee ? {
+				id: raw.assignee.login,
+				displayName: raw.assignee.name ?? raw.assignee.login,
+				...raw.assignee.email ? { emailAddress: raw.assignee.email } : {}
+			} : 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+)$/);
@@ -368,13 +315,6 @@ function parseIssueNumber(key, owner, repoName) {
 	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
 /**
@@ -410,84 +350,114 @@ async function encryptSecret(publicKeyBase64, value) {
 //#endregion
 //#region src/capabilities/secrets.ts
 var GitHubSecrets = class {
-	rest;
+	client;
+	opts;
 	key = "secrets";
 	providerName = "github";
-	repoBase;
-	constructor(rest, opts) {
-		this.rest = rest;
-		const { owner, name } = parseRepo(opts.repo);
-		this.repoBase = `/repos/${owner}/${name}`;
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
 	}
 	async listSecrets(scope) {
-		const base = this.scopeBase(scope);
-		return (await this.rest.request(`${base}/secrets`)).secrets.map((s) => s.name);
+		return this.client.secrets.listSecrets(this.opts.repo, toGHScope(scope));
 	}
 	async setSecret(scope, name, value) {
-		const base = this.scopeBase(scope);
-		const pk = await this.rest.request(`${base}/secrets/public-key`);
+		const ghScope = toGHScope(scope);
+		const pk = await this.client.secrets.getPublicKey(this.opts.repo, ghScope);
 		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
-		});
+		await this.client.secrets.putSecret(this.opts.repo, ghScope, name, body);
 	}
 	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`;
-		}
+		await this.client.secrets.deleteSecret(this.opts.repo, toGHScope(scope), name);
 	}
 };
+function toGHScope(scope) {
+	if (scope.kind === "organization") return {
+		kind: "organization",
+		org: scope.name
+	};
+	return scope;
+}
 //#endregion
-//#region src/capabilities/source.ts
+//#region src/capabilities/labels.ts
 /**
-* `source` capability for GitHub.
-*
-* Ported from rando-id/rando.id `packages/cli/src/adapters/gh-rest.ts`
-* with two changes for v2:
+* Idempotently synchronise a repo's labels to the canonical set.
 *
-*  - 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
+* - Creates labels that are missing.
+* - PATCHes labels whose color or description has drifted.
+* - DELETEs labels listed in `stale`.
+* - Leaves unrecognised labels that aren't in `stale` untouched.
 */
+async function syncLabels(client, repo, canonical, stale) {
+	const existing = await client.labels.listLabels(repo);
+	const existingMap = new Map(existing.map((l) => [l.name.toLowerCase(), l]));
+	let created = 0;
+	let updated = 0;
+	let deleted = 0;
+	for (const label of canonical) {
+		const current = existingMap.get(label.name);
+		if (!current) {
+			await client.labels.createLabel(repo, {
+				name: label.name,
+				color: label.color,
+				description: label.description
+			});
+			created++;
+		} else if (current.color !== label.color || (current.description ?? "") !== label.description) {
+			await client.labels.updateLabel(repo, label.name, {
+				color: label.color,
+				description: label.description
+			});
+			updated++;
+		}
+	}
+	for (const staleName of stale) if (existingMap.has(staleName)) {
+		await client.labels.deleteLabel(repo, staleName);
+		deleted++;
+	}
+	return `${created} created, ${updated} updated, ${deleted} deleted`;
+}
+//#endregion
+//#region src/capabilities/properties.ts
+async function syncProperties(client, repo, values) {
+	await client.properties.setProperties(repo, values);
+	return `${Object.keys(values).length} properties set`;
+}
+//#endregion
+//#region src/capabilities/topics.ts
+async function syncTopics(client, repo, topics) {
+	await client.topics.setTopics(repo, topics);
+	return `${topics.length} topics set`;
+}
+//#endregion
+//#region src/capabilities/source.ts
 var GitHubSource = class {
-	rest;
+	client;
 	key = "source";
 	providerName = "github";
 	owner;
 	name;
-	repoPath;
+	repo;
 	repoRoot;
 	workflowDir;
-	constructor(rest, opts) {
-		this.rest = rest;
-		const { owner, name } = parseRepo(opts.repo);
+	constructor(client, opts) {
+		this.client = client;
+		const [owner = "", name = ""] = opts.repo.split("/", 2);
 		this.owner = owner;
 		this.name = name;
-		this.repoPath = `/repos/${owner}/${name}`;
+		this.repo = opts.repo;
 		this.repoRoot = opts.repoRoot;
 		this.workflowDir = join(opts.repoRoot, ".github", "workflows");
 	}
 	async whoami() {
-		return { login: (await this.rest.request("/user")).login };
+		return { login: (await this.client.user.getCurrentUser()).login };
 	}
 	async getRepo() {
-		const data = await this.rest.request(this.repoPath);
+		const data = await this.client.repos.getRepo(this.repo);
 		return {
 			owner: this.owner,
 			name: this.name,
@@ -495,79 +465,40 @@ var GitHubSource = class {
 		};
 	}
 	async listRulesets() {
-		return this.rest.request(`${this.repoPath}/rulesets`);
+		return this.client.rulesets.listRulesets(this.repo);
 	}
 	async createRuleset(payload) {
-		return this.rest.request(`${this.repoPath}/rulesets`, {
-			method: "POST",
-			body: payload
-		});
+		return this.client.rulesets.createRuleset(this.repo, payload);
 	}
 	async updateRuleset(id, payload) {
-		return this.rest.request(`${this.repoPath}/rulesets/${id}`, {
-			method: "PUT",
-			body: payload
-		});
+		return this.client.rulesets.updateRuleset(this.repo, id, payload);
 	}
 	async updateRepoSettings(settings) {
-		await this.rest.request(this.repoPath, {
-			method: "PATCH",
-			body: settings
-		});
+		await this.client.repos.updateRepo(this.repo, settings);
 	}
 	async protectBranch(branch, payload) {
-		await this.rest.request(`${this.repoPath}/branches/${encodeURIComponent(branch)}/protection`, {
-			method: "PUT",
-			body: payload
-		});
+		await this.client.branches.protectBranch(this.repo, branch, payload);
 	}
 	async enableVulnerabilityAlerts() {
-		await this.rest.request(`${this.repoPath}/vulnerability-alerts`, {
-			method: "PUT",
-			expectNoContent: true
-		});
+		await this.client.security.enableVulnerabilityAlerts(this.repo);
 	}
 	async enableAutomatedSecurityFixes() {
-		await this.rest.request(`${this.repoPath}/automated-security-fixes`, {
-			method: "PUT",
-			expectNoContent: true
-		});
+		await this.client.security.enableAutomatedSecurityFixes(this.repo);
 	}
 	async enableSecretScanning() {
-		await this.rest.request(this.repoPath, {
-			method: "PATCH",
-			body: { security_and_analysis: {
-				secret_scanning: { status: "enabled" },
-				secret_scanning_push_protection: { status: "enabled" },
-				secret_scanning_validity_checks: { status: "enabled" },
-				secret_scanning_non_provider_patterns: { status: "enabled" }
-			} }
-		});
+		await this.client.security.enableSecretScanning(this.repo);
 	}
 	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}`;
+		return `run ${(await this.client.security.enableCodeScanning(this.repo)).run_id}`;
+	}
+	async disableDefaultCodeScanning() {
+		await this.client.security.disableDefaultCodeScanning(this.repo);
 	}
 	async enableDependencyGraph() {
-		await this.rest.request(this.repoPath, {
-			method: "PATCH",
-			body: { security_and_analysis: {
-				dependency_graph: { status: "enabled" },
-				dependency_graph_autosubmit_action: { status: "enabled" }
-			} }
-		});
+		await this.client.security.enableDependencyGraph(this.repo);
 	}
 	async enablePrivateVulnerabilityReporting() {
-		await this.rest.request(`${this.repoPath}/private-vulnerability-reporting`, {
-			method: "PUT",
-			expectNoContent: true
-		});
+		await this.client.security.enablePrivateVulnerabilityReporting(this.repo);
 	}
 	async listWorkflowFiles() {
 		try {
@@ -602,6 +533,15 @@ var GitHubSource = class {
 		await ensureDir(dirname(full));
 		await writeFile(full, contents, "utf8");
 	}
+	async syncLabels(canonical, stale) {
+		return syncLabels(this.client, this.repo, canonical, stale);
+	}
+	async syncProperties(values) {
+		return syncProperties(this.client, this.repo, values);
+	}
+	async syncTopics(topics) {
+		return syncTopics(this.client, this.repo, topics);
+	}
 };
 function isENOENT(err) {
 	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
@@ -618,55 +558,6 @@ async function ensureDir(path) {
 	}
 }
 //#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;
-		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}`;
-		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/verify-token.ts
 /**
 * `verifyToken` — plugin-level export used by `holocron auth set` +
@@ -679,12 +570,13 @@ var GitHubRestClient = class {
 * 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);
+	const client = createGitHubClient({
+		token,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
 	try {
-		const me = await rest.request("/user");
+		const me = await client.user.getCurrentUser();
 		return {
 			ok: true,
 			subject: `user @ ${me.login ?? me.email ?? "unknown"}`
@@ -701,7 +593,7 @@ async function verifyToken(token, opts = {}) {
 function createContext(options) {
 	return {
 		options,
-		rest: new GitHubRestClient({
+		client: createGitHubClient$1({
 			token: resolveToken(options),
 			baseUrl: options.baseUrl,
 			fetch: options.fetch
@@ -711,24 +603,24 @@ function createContext(options) {
 	};
 }
 function source(ctx) {
-	return new GitHubSource(ctx.rest, {
+	return new GitHubSource(ctx.client, {
 		repo: ctx.repo,
 		repoRoot: ctx.repoRoot
 	});
 }
 function secrets(ctx) {
-	return new GitHubSecrets(ctx.rest, { repo: ctx.repo });
+	return new GitHubSecrets(ctx.client, { repo: ctx.repo });
 }
 function environments(ctx) {
-	return new GitHubEnvironments(ctx.rest, { repo: ctx.repo });
+	return new GitHubEnvironments(ctx.client, { repo: ctx.repo });
 }
 function ci(ctx) {
-	return new GitHubCi(ctx.rest, { repo: ctx.repo });
+	return new GitHubCi(ctx.client, { repo: ctx.repo });
 }
 function issues(ctx) {
 	const opts = { repo: ctx.repo };
 	if (ctx.options.labels !== void 0) opts.labels = ctx.options.labels;
-	return new GitHubIssues(ctx.rest, opts);
+	return new GitHubIssues(ctx.client, opts);
 }
 function createPlugin(options) {
 	const ctx = createContext(options);
@@ -751,4 +643,4 @@ function createPlugin(options) {
 */
 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 { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubRestClient, GitHubSecrets, GitHubSource, ci, createContext, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source, verifyToken };
+export { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubSecrets, GitHubSource, ci, createContext, createGitHubClient, createPlugin, encryptSecret, environments, issues, resolveToken, secrets, source, syncLabels, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-alpha.50",
   "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,24 +21,29 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "2.0.0-alpha.5"
+    "@theholocron/github-client": "^0.7.0",
+    "@theholocron/cli": "2.0.0-alpha.50"
   },
   "dependencies": {
     "libsodium-wrappers": "^0.7.15"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^4.1.0",
-    "@theholocron/tsconfig": "^4.1.0",
-    "@tsconfig/node-lts": "^24.0.0",
+    "@theholocron/github-client": "^0.7.0",
+    "@types/node": "^26",
+    "@theholocron/eslint-config": "^5.2.0",
+    "@theholocron/tsconfig": "^6.0.0",
+    "@theholocron/tsdown-config": "^5.1.2",
+    "@theholocron/vitest-config": "^5.2.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",
+    "@vitest/eslint-plugin": "^1.6.23",
+    "eslint": "^10.7.0",
+    "eslint-plugin-n": "^18.2.2",
+    "globals": "^17.7.0",
     "tsdown": "^0.22.3",
     "tsx": "^4.22.4",
-    "@theholocron/cli": "2.0.0-alpha.5"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@theholocron/cli": "2.0.0-alpha.50"
   },
   "publishConfig": {
     "access": "public"