@theholocron/cli 2.0.0-alpha.20 → 2.0.0-alpha.22

package/README.md

@@ -1,3 +1,5 @@
+<!-- editorconfig-checker-disable-file -->
+
 # `@theholocron/cli`
 
 The Holocron CLI — a pluggable, capability-based orchestrator for
@@ -16,29 +18,31 @@ Holocron reads `holocron.config.{json,js,ts}` from the project root
 (priority: json → js → ts).
 
 **JSON** (simplest):
+
 ```jsonc
 // holocron.config.json
 {
-  "project": { "name": "my-app" },
-  "providers": {
-    "vault": ["1password", { "vault": "my-app" }],
-    "source": "github"
-  }
+	"project": { "name": "my-app" },
+	"providers": {
+		"vault": ["1password", { "vault": "my-app" }],
+		"source": "github",
+	},
 }
 ```
 
 **JS/TS** — use `defineConfig` for autocomplete and type-checking:
+
 ```ts
 // holocron.config.ts
-import { defineConfig } from '@theholocron/cli'
+import { defineConfig } from "@theholocron/cli";
 
 export default defineConfig({
-  project: { name: 'my-app' },
-  providers: {
-    vault: ['1password', { vault: 'my-app' }],
-    source: 'github',
-  },
-})
+	project: { name: "my-app" },
+	providers: {
+		vault: ["1password", { vault: "my-app" }],
+		source: "github",
+	},
+});
 ```
 
 ### Shareable configs
@@ -50,18 +54,19 @@ top (project wins):
 
 ```ts
 providers: {
-  vault: '@acme/holocron-vault',                     // preset only
-  source: ['@acme/holocron-github', { repo: 'x' }], // preset + override
+	vault: '@acme/holocron-vault',                     // preset only
+	source: ['@acme/holocron-github', { repo: 'x' }], // preset + override
 }
 ```
 
 A capability config package exports a `CapabilityConfigPackage` default:
+
 ```ts
-import type { CapabilityConfigPackage } from '@theholocron/cli'
+import type { CapabilityConfigPackage } from "@theholocron/cli";
 export default {
-  provider: '1password',
-  options: { vault: 'acme-app' },
-} satisfies CapabilityConfigPackage
+	provider: "1password",
+	options: { vault: "acme-app" },
+} satisfies CapabilityConfigPackage;
 ```
 
 **Level 2 — whole-config presets.** Because the config file can be
@@ -69,23 +74,23 @@ JS/TS, a shared base is just an import:
 
 ```ts
 // holocron.config.ts
-import { acmeConfig } from '@acme/holocron-config'
-export default acmeConfig
+import { acmeConfig } from "@acme/holocron-config";
+export default acmeConfig;
 ```
 
 ## What's in here
 
 - `src/capabilities/` — the 14 capability interfaces that providers
-	implement
+  implement
 - `src/config.ts` — config schema, `defineConfig`, `resolveConfig`,
-	`CapabilityConfigPackage`
+  `CapabilityConfigPackage`
 - `src/load-config.ts` — `loadConfig` — reads JSON/JS/TS config files
 - `src/define-config.ts` — `defineConfig` typed pass-through
 - `src/loader.ts` — `PluginLoader` — dynamic-imports plugins, resolves
-	capability config packages, builds the capability registry
+  capability config packages, builds the capability registry
 - `src/cli.ts` — yargs entry, dispatches subcommands
 - `src/commands/` — `setup`, `doctor`, `deploy`, `secret set`,
-	`secrets sync`, `npm publish-initial`
+  `secrets sync`, `npm publish-initial`
 
 ## Status
 

package/dist/capabilities/index.d.mts

@@ -1,3 +1,5 @@
+import { ProviderApiError } from "@theholocron/http-client";
+
 //#region src/capabilities/index.d.ts
 /**
  * Capability interfaces — the contracts that providers implement.
@@ -39,18 +41,6 @@ interface ProviderIdentity {
   readonly key: CapabilityKey;
   readonly providerName: string;
 }
-/**
- * Surfaced from every capability call that hits a vendor API. Wraps
- * the underlying error with `status` (HTTP) and `details` so
- * orchestrators (`holocron setup`, `doctor`) can soft-skip rather
- * than abort.
- */
-declare class ProviderApiError extends Error {
-  readonly status: number | undefined;
-  readonly details?: unknown | undefined;
-  name: string;
-  constructor(message: string, status: number | undefined, details?: unknown | undefined);
-}
 interface Ruleset {
   id: number;
   name: string;

package/dist/capabilities/index.mjs

@@ -1,3 +1,4 @@
+import { ProviderApiError } from "@theholocron/http-client";
 //#region src/capabilities/index.ts
 const CARDINALITY = {
 	source: "single",
@@ -21,22 +22,6 @@ const CARDINALITY = {
 * own requirements at call time.
 */
 const REQUIRED_CAPABILITIES = [];
-/**
-* Surfaced from every capability call that hits a vendor API. Wraps
-* the underlying error with `status` (HTTP) and `details` so
-* orchestrators (`holocron setup`, `doctor`) can soft-skip rather
-* than abort.
-*/
-var ProviderApiError = class extends Error {
-	status;
-	details;
-	name = "ProviderApiError";
-	constructor(message, status, details) {
-		super(message);
-		this.status = status;
-		this.details = details;
-	}
-};
 var WebhookVerificationError = class extends Error {
 	name = "WebhookVerificationError";
 };

package/dist/cli.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import path, { basename, dirname, join } from "node:path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
+import { ProviderApiError } from "@theholocron/http-client";
 import { Entry, findCredentials } from "@napi-rs/keyring";
-import path, { dirname, join } from "node:path";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { readFile, stat } from "node:fs/promises";
@@ -31,22 +32,6 @@ const CARDINALITY = {
 * own requirements at call time.
 */
 const REQUIRED_CAPABILITIES = [];
-/**
-* Surfaced from every capability call that hits a vendor API. Wraps
-* the underlying error with `status` (HTTP) and `details` so
-* orchestrators (`holocron setup`, `doctor`) can soft-skip rather
-* than abort.
-*/
-var ProviderApiError = class extends Error {
-	status;
-	details;
-	name = "ProviderApiError";
-	constructor(message, status, details) {
-		super(message);
-		this.status = status;
-		this.details = details;
-	}
-};
 //#endregion
 //#region src/config.ts
 /**
@@ -687,6 +672,161 @@ async function runNpmBumpVersions(input) {
 	};
 }
 //#endregion
+//#region src/commands/upgrade-node.ts
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	"coverage",
+	"build",
+	".turbo",
+	".next",
+	"out"
+]);
+function patchPackageJson(content, from, to) {
+	let pkg;
+	try {
+		pkg = JSON.parse(content);
+	} catch {
+		return null;
+	}
+	let changed = false;
+	const engines = pkg.engines;
+	if (engines?.node === `>=${from}.0.0`) {
+		engines.node = `>=${to}.0.0`;
+		changed = true;
+	}
+	for (const field of ["devDependencies", "dependencies"]) {
+		const deps = pkg[field];
+		if (!deps?.["@types/node"]) continue;
+		if (deps["@types/node"] === `^${from}.0.0`) {
+			deps["@types/node"] = `^${to}.0.0`;
+			changed = true;
+		}
+	}
+	return changed ? JSON.stringify(pkg, null, 2) + "\n" : null;
+}
+function patchYaml(content, from, to) {
+	const updated = content.replace(/node-version:\s+['"]?(\d+)['"]?/g, (match, ver) => ver === String(from) ? match.replace(String(from), String(to)) : match);
+	return updated !== content ? updated : null;
+}
+function patchPinFile(content, from, to) {
+	const trimmed = content.trim();
+	if (trimmed === String(from) || trimmed.startsWith(`${from}.`)) return `${to}\n`;
+	return null;
+}
+function patchDockerfile(content, from, to) {
+	const updated = content.replace(/^(FROM\s+node:)(\d+)/gm, (match, prefix, ver) => ver === String(from) ? `${prefix}${to}` : match);
+	return updated !== content ? updated : null;
+}
+function patchToolVersions(content, from, to) {
+	const updated = content.replace(/^(nodejs\s+)(\d+)/gm, (match, prefix, ver) => ver === String(from) ? `${prefix}${to}` : match);
+	return updated !== content ? updated : null;
+}
+const PATTERNS = [
+	{
+		matches: (n) => n === "package.json",
+		patch: patchPackageJson
+	},
+	{
+		matches: (n) => n.endsWith(".yml") || n.endsWith(".yaml"),
+		patch: patchYaml
+	},
+	{
+		matches: (n) => n === ".nvmrc" || n === ".node-version",
+		patch: patchPinFile
+	},
+	{
+		matches: (n) => n === "Dockerfile" || n.startsWith("Dockerfile."),
+		patch: patchDockerfile
+	},
+	{
+		matches: (n) => n === ".tool-versions",
+		patch: patchToolVersions
+	}
+];
+function detectFrom(cwd, _readFile) {
+	for (const name of [".nvmrc", ".node-version"]) try {
+		const major = parseInt(_readFile(join(cwd, name)).trim(), 10);
+		if (!isNaN(major)) return major;
+	} catch {}
+	try {
+		const node = JSON.parse(_readFile(join(cwd, "package.json"))).engines?.node;
+		if (node) {
+			const m = node.match(/(\d+)/);
+			if (m) return parseInt(m[1], 10);
+		}
+	} catch {}
+	return null;
+}
+function defaultWalkFiles(dir) {
+	const results = [];
+	function walk(current) {
+		let entries;
+		try {
+			entries = readdirSync(current);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (SKIP_DIRS.has(entry)) continue;
+			const abs = join(current, entry);
+			try {
+				if (statSync(abs).isDirectory()) walk(abs);
+				else results.push(abs);
+			} catch {}
+		}
+	}
+	walk(dir);
+	return results;
+}
+async function runUpgradeNode(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const cwd = input.cwd ?? process.cwd();
+	const { to, dryRun = false, extra = [] } = input;
+	const _readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const _writeFile = input.writeFile ?? ((p, c) => writeFileSync(p, c));
+	const _walkFiles = input.walkFiles ?? defaultWalkFiles;
+	const from = input.from ?? detectFrom(cwd, _readFile);
+	if (from === null) return {
+		status: "fail",
+		updated: [],
+		message: "could not detect current Node version — pass --from <major>"
+	};
+	if (from === to) {
+		print(`Already at Node.js ${to} — nothing to do.`);
+		return {
+			status: "ok",
+			updated: []
+		};
+	}
+	print(`Upgrading Node.js ${from} → ${to}${dryRun ? " (dry-run)" : ""}…`);
+	const updated = [];
+	const scanned = [..._walkFiles(cwd), ...extra.map((p) => join(cwd, p))];
+	for (const abs of scanned) {
+		const name = basename(abs);
+		const pattern = PATTERNS.find((p) => p.matches(name));
+		if (!pattern) continue;
+		let content;
+		try {
+			content = _readFile(abs);
+		} catch {
+			continue;
+		}
+		const patched = pattern.patch(content, from, to);
+		if (patched === null) continue;
+		const rel = abs.startsWith(cwd + "/") ? abs.slice(cwd.length + 1) : abs;
+		if (!dryRun) _writeFile(abs, patched);
+		print(`  ${dryRun ? "~" : "✓"} ${rel}`);
+		updated.push(rel);
+	}
+	if (updated.length === 0) print(`  · no files contained Node.js ${from} pins`);
+	return {
+		status: dryRun ? "dry-run" : "ok",
+		updated
+	};
+}
+//#endregion
 //#region src/templates/index.ts
 /**
 * All reusable workflow and composite action content bundled as string
@@ -1027,6 +1167,7 @@ jobs:
         name: Run Super Linter
         env:
           GITHUB_TOKEN: \${{ github.token }}
+          DEFAULT_BRANCH: \${{ github.event.pull_request.base.ref || github.event.repository.default_branch }}
           ANNOTATE_ONLY: true
           DISABLE_COMMENTS: false
           IGNORE_GITIGNORED_FILES: true
@@ -2253,48 +2394,19 @@ function deriveDefaults(input) {
 //#endregion
 //#region src/commands/plugin-create/templates/auth.ts
 function render$17(inputs) {
-	return `/**
- * Token resolution for the ${inputs.vendorName} plugin.
- *
- * Resolution order (matches the standard 4-step precedence set by
- * \`.notes/tech-auth-bootstrap.spec.md\`):
- *   1. explicit \`cliToken\` argument (from \`--token\` flag)
- *   2. ${inputs.tokenEnv} env var (preferred — explicit intent)
- *   3. ${inputs.vendorEnv} env var (vendor-native)
- *   4. keyring (com.theholocron.cli / "${inputs.slug}")
- *   5. AuthError naming all four options + the bootstrap hint
- */
-
-import { getToken as getKeyringToken } from "@theholocron/cli";
-
-export class AuthError extends Error {
-	override name = "AuthError";
-}
-
-export 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;
-}
-
-export function resolveToken(input: ResolveTokenInput = {}): string {
-	const env = input.env ?? process.env;
-	const keyring = input.keyring ?? getKeyringToken;
-	// Bracket access so numeric-prefixed slugs (e.g., env.HOLOCRON_1PASSWORD_TOKEN
-	// which is invalid JS) still produce syntactically valid code.
-	const token =
-		input.cliToken || env["${inputs.tokenEnv}"] || env["${inputs.vendorEnv}"] || keyring("${inputs.slug}");
-	if (!token) {
-		throw new AuthError(
-			"no ${inputs.vendorName} token found. Pass --token <TOKEN>, set ${inputs.tokenEnv} / ${inputs.vendorEnv}, " +
-				"or run: holocron auth set ${inputs.slug} <TOKEN>"
-		);
-	}
-	return token;
-}
+	return `import { AuthError, createResolveToken, type ResolveTokenInput } from "@theholocron/cli";
+
+export { AuthError };
+export type { ResolveTokenInput };
+
+export const resolveToken = createResolveToken({
+\tenvName: "${inputs.tokenEnv}",
+\tvendorEnvName: "${inputs.vendorEnv}",
+\tkeyringService: "${inputs.slug}",
+\terrorMessage:
+\t\t"no ${inputs.vendorName} token found. Pass --token <TOKEN>, set ${inputs.tokenEnv} / ${inputs.vendorEnv}, " +
+\t\t"or run: holocron auth set ${inputs.slug} <TOKEN>",
+});
 `;
 }
 //#endregion
@@ -2720,148 +2832,79 @@ Not yet published; capability methods are stubs.
 //#endregion
 //#region src/commands/plugin-create/templates/rest.ts
 function render$7(inputs) {
-	const clientClass = `${inputs.vendorName}RestClient`;
-	return `/**
- * Thin REST wrapper around ${inputs.baseUrl}.
- *
- * Bearer auth, JSON-only bodies, transport-failure wrapping with
- * \`status: 0\` so orchestrator soft-skip paths see a clear message
- * instead of a generic \`TypeError: fetch failed\`.
- */
-
-import { ProviderApiError } from "@theholocron/cli";
-
-export interface RestClientOptions {
-	token: string;
-	fetch?: typeof fetch;
-	baseUrl?: string;
-}
-
-export interface RequestOptions {
-	method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
-	body?: unknown;
-	query?: Record<string, string>;
-	/** Treat this response as void even if 200 is returned. */
-	expectNoContent?: boolean;
-}
-
-export class ${clientClass} {
-	private readonly token: string;
-	private readonly fetchImpl: typeof fetch;
-	readonly baseUrl: string;
-
-	constructor(opts: RestClientOptions) {
-		this.token = opts.token;
-		this.fetchImpl = opts.fetch ?? globalThis.fetch;
-		// Manual trailing-slash trim — CodeQL flags regex on library
-		// input as polynomial ReDoS. O(n) loop, no backtracking risk.
-		let url = opts.baseUrl ?? "${inputs.baseUrl}";
-		while (url.endsWith("/")) url = url.slice(0, -1);
-		this.baseUrl = url;
-	}
-
-	async request<T>(path: string, opts: RequestOptions = {}): Promise<T> {
-		const url = new URL(\`\${this.baseUrl}\${path.startsWith("/") ? path : "/" + path}\`);
-		for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
-		const fullUrl = url.toString();
-
-		const headers: Record<string, string> = {
-			authorization: \`Bearer \${this.token}\`,
-			accept: "application/json",
-		};
-		const init: RequestInit = {
-			method: opts.method ?? "GET",
-			headers,
-		};
-		if (opts.body !== undefined) {
-			headers["content-type"] = "application/json";
-			init.body = JSON.stringify(opts.body);
-		}
-
-		let res: Response;
-		try {
-			res = await this.fetchImpl(fullUrl, init);
-		} catch (err) {
-			const detail = err instanceof Error ? \`\${err.name}: \${err.message}\` : String(err);
-			throw new ProviderApiError(\`${inputs.vendorName} \${init.method} \${path} failed: \${detail}\`, 0, undefined);
-		}
-		if (!res.ok) {
-			const body = await res.text().catch(() => "");
-			throw new ProviderApiError(\`${inputs.vendorName} \${init.method} \${path} → \${res.status}\`, res.status, body);
-		}
-		if (opts.expectNoContent || res.status === 204) return undefined as T;
-		const text = await res.text();
-		if (!text) return undefined as T;
-		return JSON.parse(text) as T;
-	}
+	return `import { createRestClient, type RequestOptions, type RestClient } from "@theholocron/cli";
+
+export type { RequestOptions, RestClient };
+
+export function ${`create${inputs.vendorName}RestClient`}(opts: {
+\ttoken: string;
+\tbaseUrl?: string;
+\tfetch?: typeof fetch;
+}): RestClient {
+\treturn createRestClient({
+\t\tbaseUrl: opts.baseUrl ?? "${inputs.baseUrl}",
+\t\ttoken: opts.token,
+\t\tvendor: "${inputs.vendorName}",
+\t\tfetch: opts.fetch,
+\t});
 }
 `;
 }
 //#endregion
 //#region src/commands/plugin-create/templates/rest-test.ts
 function render$6(inputs) {
-	const clientClass = `${inputs.vendorName}RestClient`;
+	const factoryName = `create${inputs.vendorName}RestClient`;
 	return `import { ProviderApiError } from "@theholocron/cli";
 import { describe, expect, it } from "vitest";
 
-import { ${clientClass} } from "../rest.js";
+import { ${factoryName} } from "../rest.js";
 import { stubFetch } from "./helpers.js";
 
-describe("${clientClass}", () => {
-	it("sends bearer + accept headers and returns the parsed body", async () => {
-		const stub = stubFetch([{ status: 200, body: { ok: true } }]);
-		const client = new ${clientClass}({ token: "t", fetch: stub.fetch });
-		const res = await client.request<{ ok: boolean }>("/me");
-		expect(res.ok).toBe(true);
-		expect(stub.calls[0]?.headers["authorization"]).toBe("Bearer t");
-		expect(stub.calls[0]?.headers["accept"]).toBe("application/json");
-	});
-
-	it("serializes body as JSON and sets content-type when present", async () => {
-		const stub = stubFetch([{ status: 200, body: {} }]);
-		const client = new ${clientClass}({ token: "t", fetch: stub.fetch });
-		await client.request<unknown>("/resource", { method: "POST", body: { name: "demo" } });
-		expect(stub.calls[0]?.method).toBe("POST");
-		expect(stub.calls[0]?.headers["content-type"]).toBe("application/json");
-		expect(stub.calls[0]?.body).toEqual({ name: "demo" });
-	});
-
-	it("returns undefined on 204", async () => {
-		const stub = stubFetch([{ status: 204 }]);
-		const client = new ${clientClass}({ token: "t", fetch: stub.fetch });
-		expect(await client.request<unknown>("/whatever")).toBeUndefined();
-	});
-
-	it("throws ProviderApiError with the HTTP status on non-2xx", async () => {
-		const stub = stubFetch([{ status: 401, body: { messages: ["invalid"] } }]);
-		const client = new ${clientClass}({ token: "bad", fetch: stub.fetch });
-		try {
-			await client.request<unknown>("/me");
-			throw new Error("should have thrown");
-		} catch (err) {
-			expect(err).toBeInstanceOf(ProviderApiError);
-			expect((err as ProviderApiError).status).toBe(401);
-		}
-	});
-
-	it("wraps transport-level failures with status 0", async () => {
-		const throwing: typeof fetch = async () => {
-			throw new TypeError("fetch failed");
-		};
-		const client = new ${clientClass}({ token: "t", fetch: throwing });
-		try {
-			await client.request<unknown>("/me");
-			throw new Error("should have thrown");
-		} catch (err) {
-			expect(err).toBeInstanceOf(ProviderApiError);
-			expect((err as ProviderApiError).status).toBe(0);
-		}
-	});
-
-	it("trims trailing slashes from the base URL", () => {
-		const client = new ${clientClass}({ token: "t", baseUrl: "${inputs.baseUrl}//" });
-		expect(client.baseUrl).toBe("${inputs.baseUrl}");
-	});
+describe("${factoryName}", () => {
+\tit("sends bearer + accept headers and returns the parsed body", async () => {
+\t\tconst stub = stubFetch([{ status: 200, body: { ok: true } }]);
+\t\tconst client = ${factoryName}({ token: "t", fetch: stub.fetch });
+\t\tconst res = await client.request<{ ok: boolean }>("/me");
+\t\texpect(res.ok).toBe(true);
+\t\texpect(stub.calls[0]?.headers["authorization"]).toBe("Bearer t");
+\t\texpect(stub.calls[0]?.headers["accept"]).toBe("application/json");
+\t});
+
+\tit("serializes body as JSON and sets content-type when present", async () => {
+\t\tconst stub = stubFetch([{ status: 200, body: {} }]);
+\t\tconst client = ${factoryName}({ token: "t", fetch: stub.fetch });
+\t\tawait client.request<unknown>("/resource", { method: "POST", body: { name: "demo" } });
+\t\texpect(stub.calls[0]?.method).toBe("POST");
+\t\texpect(stub.calls[0]?.headers["content-type"]).toBe("application/json");
+\t\texpect(stub.calls[0]?.body).toEqual({ name: "demo" });
+\t});
+
+\tit("returns undefined on 204", async () => {
+\t\tconst stub = stubFetch([{ status: 204 }]);
+\t\tconst client = ${factoryName}({ token: "t", fetch: stub.fetch });
+\t\texpect(await client.request<unknown>("/whatever")).toBeUndefined();
+\t});
+
+\tit("throws ProviderApiError with the HTTP status on non-2xx", async () => {
+\t\tconst stub = stubFetch([{ status: 401, body: { messages: ["invalid"] } }]);
+\t\tconst client = ${factoryName}({ token: "bad", fetch: stub.fetch });
+\t\tconst err = await client.request<unknown>("/me").catch((e: unknown) => e);
+\t\texpect(err).toBeInstanceOf(ProviderApiError);
+\t\texpect((err as ProviderApiError).status).toBe(401);
+\t});
+
+\tit("wraps transport-level failures with status 0", async () => {
+\t\tconst throwing: typeof fetch = async () => { throw new TypeError("fetch failed"); };
+\t\tconst client = ${factoryName}({ token: "t", fetch: throwing });
+\t\tconst err = await client.request<unknown>("/me").catch((e: unknown) => e);
+\t\texpect(err).toBeInstanceOf(ProviderApiError);
+\t\texpect((err as ProviderApiError).status).toBe(0);
+\t});
+
+\tit("trims trailing slashes from the base URL", () => {
+\t\tconst client = ${factoryName}({ token: "t", baseUrl: "${inputs.baseUrl}//" });
+\t\texpect(client.baseUrl).toBe("${inputs.baseUrl}");
+\t});
 });
 `;
 }
@@ -3523,6 +3566,15 @@ function vaultProviderName(loader) {
 }
 //#endregion
 //#region src/commands/setup.ts
+const ALEX_CONFIG = JSON.stringify({ allow: [
+	"dead",
+	"failure",
+	"failures",
+	"hook",
+	"hooks",
+	"husky",
+	"period"
+] }, null, 2) + "\n";
 const DEPENDABOT_CONFIG = `\
 # AUTO-GENERATED by holocron — run \`holocron setup\` to regenerate.
 version: 2
@@ -3746,6 +3798,13 @@ async function runSetup(input) {
 		}));
 		print(formatStep(steps[steps.length - 1]));
 	}
+	if (loader.has("source")) {
+		const source = loader.get("source");
+		steps.push(await runStep("source", "write .alexrc.json", dryRun, async () => {
+			await source.writeRepoFile(".alexrc.json", ALEX_CONFIG);
+		}));
+		print(formatStep(steps[steps.length - 1]));
+	}
 	if (loader.has("environments")) {
 		const envs = loader.get("environments");
 		print("  → environments");
@@ -4183,7 +4242,32 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 		}
 		throw err;
 	}
-}).command("auth <subcommand>", "Manage bootstrap credentials in the OS keyring", (y) => y.command("set <provider> [token]", "Verify + store a bootstrap token for a provider", (yy) => yy.positional("provider", {
+}).command("upgrade", "Upgrade toolchain version pins across the repo", (y) => y.command("node <to>", "Scan the repo and update every Node.js version pin to a new major", (yy) => yy.positional("to", {
+	type: "number",
+	demandOption: true,
+	describe: "Target Node.js major version (e.g., 22)"
+}).option("from", {
+	type: "number",
+	describe: "Current major version to replace. Auto-detected from .nvmrc / engines.node when omitted."
+}), async (argv) => {
+	let extra = [];
+	try {
+		const raw = readFileSync(join(argv.cwd, "holocron.config.json"), "utf8");
+		const upgradeNode = JSON.parse(raw).upgrade?.node;
+		if (Array.isArray(upgradeNode?.extra)) extra = upgradeNode.extra;
+	} catch {}
+	const report = await runUpgradeNode({
+		to: argv.to,
+		...argv.from != null ? { from: argv.from } : {},
+		cwd: argv.cwd,
+		dryRun: argv.dryRun,
+		extra
+	});
+	if (report.status === "fail") {
+		if (report.message) console.error(`upgrade node: ${report.message}`);
+		process.exitCode = 1;
+	}
+}).demandCommand(1, "Run `holocron upgrade --help` to see available upgrade subcommands."), () => {}).command("auth <subcommand>", "Manage bootstrap credentials in the OS keyring", (y) => y.command("set <provider> [token]", "Verify + store a bootstrap token for a provider", (yy) => yy.positional("provider", {
 	type: "string",
 	demandOption: true
 }).positional("token", { type: "string" }), async (argv) => {

package/dist/index.d.mts

@@ -1,5 +1,12 @@
 import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, isMulti } from "./capabilities/index.mjs";
+import { AuthError, RequestOptions, ResolveTokenConfig as ResolveTokenConfig$1, ResolveTokenInput, RestClient, RestClientConfig, createRestClient } from "@theholocron/http-client";
 
+//#region src/auth-resolver.d.ts
+type ResolveTokenConfig = Omit<ResolveTokenConfig$1, "getKeyringToken">;
+/** Wraps `createResolveToken` from `@theholocron/http` and injects the
+ *  system keyring so plugins stay at a one-liner call site. */
+declare function createResolveToken(config: ResolveTokenConfig): (input?: import("@theholocron/http-client").ResolveTokenInput) => string;
+//#endregion
 //#region src/config.d.ts
 type ProviderOptions = Record<string, unknown>;
 /**
@@ -183,4 +190,4 @@ interface LoadedConfig {
  */
 declare function loadConfig(cwd: string): Promise<LoadedConfig>;
 //#endregion
-export { Analytics, AppConfig, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DoctorConfig, EnsureResult, Environment, EnvironmentReviewer, Environments, HolocronConfig, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, LoadedConfig, MultiEntry, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoPolicyConfig, RepoRef, RepoSettings, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+export { Analytics, AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DoctorConfig, EnsureResult, Environment, EnvironmentReviewer, Environments, HolocronConfig, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, LoadedConfig, MultiEntry, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoPolicyConfig, RepoRef, RepoSettings, type RequestOptions, ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, createResolveToken, createRestClient, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/dist/index.mjs

@@ -1,8 +1,89 @@
 import { CARDINALITY, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti } from "./capabilities/index.mjs";
+import { AuthError, createResolveToken as createResolveToken$1, createRestClient } from "@theholocron/http-client";
 import { Entry, findCredentials } from "@napi-rs/keyring";
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+//#region src/keyring.ts
+/**
+* Keyring-backed bootstrap credential store.
+*
+* Every holocron plugin's bootstrap token (the one it needs before it
+* can talk to its vendor's API) can be stored in the OS keyring under
+* a single reverse-DNS service scope. Managed via `holocron auth`
+* subcommands; consulted at position 4 in every plugin's auth
+* precedence chain (after --token / HOLOCRON_<X>_TOKEN / <native>_TOKEN).
+*
+* See `.notes/tech-auth-bootstrap.spec.md` for the design rationale.
+*
+* Failure model: keyring access is best-effort. Platforms without a
+* supported credential store (some Linux CI images, sandboxed
+* environments) will throw from the underlying library. Every export
+* here catches and returns a null/empty result rather than propagating
+* — the plugin's precedence chain then falls through to
+* env-var-only paths, which is exactly how CI is meant to work.
+*/
+const SERVICE = "com.theholocron.cli";
+/**
+* Store or overwrite a bootstrap token for a provider. Returns true on
+* success, false when the underlying keyring is unsupported or errored.
+*/
+function setToken(provider, token) {
+	try {
+		new Entry(SERVICE, provider).setPassword(token);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Read the bootstrap token for a provider. Returns `null` for both
+* "not stored" and "keyring unavailable" — callers can treat them the
+* same way (fall through to env-var precedence).
+*/
+function getToken(provider) {
+	try {
+		return new Entry(SERVICE, provider).getPassword();
+	} catch {
+		return null;
+	}
+}
+/**
+* Delete a stored token. Returns true when a token was removed, false
+* when there was nothing to delete or the keyring is unavailable.
+* Distinguishing the two cases isn't worth the surface area — the
+* command output makes the situation clear either way.
+*/
+function deleteToken(provider) {
+	try {
+		return new Entry(SERVICE, provider).deletePassword();
+	} catch {
+		return false;
+	}
+}
+/**
+* List provider slugs with a stored token in this service scope.
+* Uses the library's `findCredentials(service)` — supported on all
+* platforms the underlying credential store supports.
+*/
+function listStoredProviders() {
+	try {
+		return findCredentials(SERVICE).map((c) => c.account);
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/auth-resolver.ts
+/** Wraps `createResolveToken` from `@theholocron/http` and injects the
+*  system keyring so plugins stay at a one-liner call site. */
+function createResolveToken(config) {
+	return createResolveToken$1({
+		...config,
+		getKeyringToken: getToken
+	});
+}
+//#endregion
 //#region src/config.ts
 /**
 * `holocron.config.json` schema, parser, and provider resolution.
@@ -119,76 +200,6 @@ function defineConfig(config) {
 	return config;
 }
 //#endregion
-//#region src/keyring.ts
-/**
-* Keyring-backed bootstrap credential store.
-*
-* Every holocron plugin's bootstrap token (the one it needs before it
-* can talk to its vendor's API) can be stored in the OS keyring under
-* a single reverse-DNS service scope. Managed via `holocron auth`
-* subcommands; consulted at position 4 in every plugin's auth
-* precedence chain (after --token / HOLOCRON_<X>_TOKEN / <native>_TOKEN).
-*
-* See `.notes/tech-auth-bootstrap.spec.md` for the design rationale.
-*
-* Failure model: keyring access is best-effort. Platforms without a
-* supported credential store (some Linux CI images, sandboxed
-* environments) will throw from the underlying library. Every export
-* here catches and returns a null/empty result rather than propagating
-* — the plugin's precedence chain then falls through to
-* env-var-only paths, which is exactly how CI is meant to work.
-*/
-const SERVICE = "com.theholocron.cli";
-/**
-* Store or overwrite a bootstrap token for a provider. Returns true on
-* success, false when the underlying keyring is unsupported or errored.
-*/
-function setToken(provider, token) {
-	try {
-		new Entry(SERVICE, provider).setPassword(token);
-		return true;
-	} catch {
-		return false;
-	}
-}
-/**
-* Read the bootstrap token for a provider. Returns `null` for both
-* "not stored" and "keyring unavailable" — callers can treat them the
-* same way (fall through to env-var precedence).
-*/
-function getToken(provider) {
-	try {
-		return new Entry(SERVICE, provider).getPassword();
-	} catch {
-		return null;
-	}
-}
-/**
-* Delete a stored token. Returns true when a token was removed, false
-* when there was nothing to delete or the keyring is unavailable.
-* Distinguishing the two cases isn't worth the surface area — the
-* command output makes the situation clear either way.
-*/
-function deleteToken(provider) {
-	try {
-		return new Entry(SERVICE, provider).deletePassword();
-	} catch {
-		return false;
-	}
-}
-/**
-* List provider slugs with a stored token in this service scope.
-* Uses the library's `findCredentials(service)` — supported on all
-* platforms the underlying credential store supports.
-*/
-function listStoredProviders() {
-	try {
-		return findCredentials(SERVICE).map((c) => c.account);
-	} catch {
-		return [];
-	}
-}
-//#endregion
 //#region src/load-config.ts
 /**
 * `holocron.config.{json,js,ts}` file loader.
@@ -265,4 +276,4 @@ async function fileExists(path) {
 	}
 }
 //#endregion
-export { CARDINALITY, ConfigError, ConfigFileError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, createResolveToken, createRestClient, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "2.0.0-alpha.20",
+  "version": "2.0.0-alpha.22",
   "description": "The Holocron CLI — a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/cli#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -34,22 +34,23 @@
   ],
   "dependencies": {
     "@napi-rs/keyring": "^1.3.0",
+    "@theholocron/http-client": "^0.1.0",
     "tsx": "^4.22.4",
     "yargs": "^18.0.0"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^5.1.2",
-    "@theholocron/tsconfig": "^5.1.2",
-    "@tsconfig/node-lts": "^24.0.0",
+    "@theholocron/eslint-config": "^5.2.0",
+    "@theholocron/tsconfig": "^6.0.0",
+    "@theholocron/vitest-config": "^5.2.0",
+    "@types/node": "^26",
     "@types/yargs": "^17.0.35",
-    "@vitest/coverage-v8": "^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",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.6",
+    "vitest": "^4.1.10",
     "@theholocron/cli-utils": "0.0.0"
   },
   "publishConfig": {