@theholocron/cli 2.0.0-alpha.1 → 2.0.0-alpha.6

package/dist/cli.mjs

@@ -1,11 +1,183 @@
 #!/usr/bin/env -S tsx
-import { t as CARDINALITY } from "./capabilities-QjjhVlDd.mjs";
-import { n as resolveConfig, t as ConfigError } from "./config-DWlIfFZm.mjs";
+import { n as ProviderApiError, t as CARDINALITY } from "./capabilities-DapaKOlX.mjs";
+import { a as ConfigError, c as resolvePluginPackage, i as setToken, n as getToken, o as resolveConfig, r as listStoredProviders, t as deleteToken } from "./keyring-DwNEmrBc.mjs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
+import path, { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { readFile, stat } from "node:fs/promises";
-import { join } from "node:path";
+//#region src/commands/auth.ts
+/**
+* `holocron auth <subcommand>` — manage bootstrap credentials in the
+* OS keyring.
+*
+* Subcommands:
+*   auth set <provider> [token]   verify + store
+*   auth unset <provider>         remove
+*   auth check <provider>         re-verify a stored token
+*   auth list                     every provider with a stored entry
+*
+* See `.notes/tech-auth-bootstrap.spec.md`.
+*
+* Verification lives in each plugin as a top-level `verifyToken(token)`
+* export. The auth command dynamically imports
+* `@theholocron/holocron-plugin-<provider>` and calls it. Plugins that
+* don't export `verifyToken` can still store — with a warning — because
+* "no verify path" shouldn't block credential storage.
+*/
+const defaultImporter$1 = async (pkg) => await import(pkg);
+/**
+* Resolve a token from (positional → HOLOCRON_<X> → vendor-native env).
+* Keyring is NOT consulted here — `auth set` writes TO the keyring, so
+* pulling FROM it would just re-store the same value.
+*/
+function resolveAuthSetToken(input) {
+	const env = input.env ?? process.env;
+	const upper = input.provider.toUpperCase();
+	const holocronKey = `HOLOCRON_${upper}_TOKEN`;
+	return input.positional || env[holocronKey] || env[upper + "_TOKEN"] || null;
+}
+async function runAuthSet(input) {
+	const print = input.print ?? ((l) => console.log(l));
+	const importer = input.importer ?? defaultImporter$1;
+	const { provider } = input;
+	const token = resolveAuthSetToken({
+		provider,
+		positional: input.positional,
+		env: input.env
+	});
+	const packageName = resolvePluginPackage(provider);
+	if (!token) {
+		print(`no token supplied for \`${provider}\`.`);
+		print(`  pass as positional arg: holocron auth set ${provider} <token>`);
+		print(`  or via env: HOLOCRON_${provider.toUpperCase()}_TOKEN / ${provider.toUpperCase()}_TOKEN`);
+		const hint = await tryLoadHint(importer, packageName);
+		if (hint) print(`  hint: ${hint}`);
+		return {
+			status: "fail",
+			message: "no token supplied"
+		};
+	}
+	let subject;
+	try {
+		const module = await importer(packageName);
+		if (typeof module.verifyToken === "function") {
+			const verified = await module.verifyToken(token);
+			if (!verified.ok) {
+				print(`token rejected by ${provider}: ${verified.message}`);
+				if (module.AUTH_HINT) print(`  hint: ${module.AUTH_HINT}`);
+				return {
+					status: "fail",
+					message: verified.message
+				};
+			}
+			subject = verified.subject;
+		} else print(`(${provider} plugin has no verifyToken; storing without verification)`);
+	} catch (err) {
+		print(`cannot verify token — failed to load ${packageName}: ${err instanceof Error ? err.message : String(err)}`);
+		print(`  storing token anyway; run 'holocron auth check ${provider}' once the plugin is installed`);
+	}
+	if (!setToken(provider, token)) {
+		print(`keyring unavailable — token not stored. Use env vars instead.`);
+		return {
+			status: "fail",
+			message: "keyring unavailable"
+		};
+	}
+	print(`stored ${provider} token${subject ? ` (${subject})` : ""}`);
+	return {
+		status: "ok",
+		...subject ? { message: subject } : {}
+	};
+}
+function runAuthUnset(input) {
+	const print = input.print ?? ((l) => console.log(l));
+	if (deleteToken(input.provider)) {
+		print(`removed ${input.provider} token`);
+		return { status: "ok" };
+	}
+	print(`no stored token for ${input.provider}`);
+	return {
+		status: "skip",
+		message: "nothing to remove"
+	};
+}
+async function runAuthCheck(input) {
+	const print = input.print ?? ((l) => console.log(l));
+	const importer = input.importer ?? defaultImporter$1;
+	const { provider } = input;
+	const token = getToken(provider);
+	if (!token) {
+		print(`no stored token for ${provider}`);
+		return {
+			status: "skip",
+			message: "no stored token"
+		};
+	}
+	const packageName = resolvePluginPackage(provider);
+	try {
+		const module = await importer(packageName);
+		if (typeof module.verifyToken !== "function") {
+			print(`${provider}: token stored (plugin has no verifyToken; can't confirm validity)`);
+			return {
+				status: "ok",
+				message: "stored, unverified"
+			};
+		}
+		const verified = await module.verifyToken(token);
+		if (verified.ok) {
+			print(`${provider}: ok — ${verified.subject}`);
+			return {
+				status: "ok",
+				message: verified.subject
+			};
+		}
+		print(`${provider}: rejected — ${verified.message}`);
+		if (module.AUTH_HINT) print(`  hint: ${module.AUTH_HINT}`);
+		return {
+			status: "fail",
+			message: verified.message
+		};
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		print(`${provider}: cannot verify — ${msg}`);
+		return {
+			status: "fail",
+			message: msg
+		};
+	}
+}
+async function runAuthList(input = {}) {
+	const print = input.print ?? ((l) => console.log(l));
+	const importer = input.importer ?? defaultImporter$1;
+	const providers = listStoredProviders();
+	if (providers.length === 0) {
+		print("no stored tokens.");
+		print("run: holocron auth set <provider> <token>");
+		return {
+			status: "ok",
+			message: "none"
+		};
+	}
+	for (const provider of providers.sort()) {
+		const check = await runAuthCheck({
+			provider,
+			importer,
+			print: () => {}
+		});
+		print(`  ${check.status === "ok" ? "✓" : check.status === "fail" ? "✗" : "·"} ${provider}${check.message ? ` — ${check.message}` : ""}`);
+	}
+	return { status: "ok" };
+}
+async function tryLoadHint(importer, packageName) {
+	try {
+		return (await importer(packageName)).AUTH_HINT ?? null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/loader.ts
 var LoaderError = class extends Error {
 	name = "LoaderError";
@@ -58,12 +230,23 @@ var PluginLoader = class {
 		});
 		if (typeof module.createPlugin !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\``);
 		const factory = module.createPlugin({
+			...this.projectDefaults(),
 			...this.context,
 			...tuple.options
 		}).capabilities[key];
 		if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
 		return factory();
 	}
+	/**
+	* Project-level defaults that get merged into every plugin's options
+	* unless overridden by the CLI context or per-plugin tuple options.
+	* See `.notes/tech-setup-and-config.spec.md` §Design.
+	*/
+	projectDefaults() {
+		const defaults = {};
+		if (this.config.project.repo) defaults.repo = this.config.project.repo;
+		return defaults;
+	}
 };
 /** Default importer — native dynamic import. */
 const defaultImporter = async (pkg) => {
@@ -193,6 +376,76 @@ function pad(s, width) {
 	return s.length >= width ? s : s + " ".repeat(width - s.length);
 }
 //#endregion
+//#region src/commands/npm-bump-versions.ts
+async function runNpmBumpVersions(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const cwd = input.cwd ?? process.cwd();
+	const { version, dryRun = false } = input;
+	const readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const writeFile = input.writeFile ?? ((p, c) => writeFileSync(p, c));
+	const listDir = input.listDir ?? ((p) => readdirSync(p));
+	const isDir = input.isDir ?? ((p) => statSync(p).isDirectory());
+	const bumped = [];
+	const skipped = [];
+	print(`Bumping monorepo to ${version}${dryRun ? " (dry-run)" : ""}…`);
+	function bumpFile(absPath, label) {
+		let pkg;
+		try {
+			pkg = JSON.parse(readFile(absPath));
+		} catch {
+			print(`  ✗ could not parse ${label}`);
+			return;
+		}
+		const old = pkg.version;
+		if (!dryRun) {
+			pkg.version = version;
+			writeFile(absPath, JSON.stringify(pkg, null, 2) + "\n");
+		}
+		print(`  ${dryRun ? "~" : "✓"} ${label}: ${old} → ${version}`);
+		bumped.push(label);
+	}
+	bumpFile(join(cwd, "package.json"), "root");
+	const packagesDir = join(cwd, "packages");
+	let entries;
+	try {
+		entries = listDir(packagesDir);
+	} catch {
+		return {
+			status: "fail",
+			bumped,
+			skipped,
+			message: `packages/ directory not found in ${cwd}`
+		};
+	}
+	for (const entry of entries) {
+		const pkgDir = join(packagesDir, entry);
+		try {
+			if (!isDir(pkgDir)) continue;
+		} catch {
+			continue;
+		}
+		const pkgFile = join(pkgDir, "package.json");
+		let pkg;
+		try {
+			pkg = JSON.parse(readFile(pkgFile));
+		} catch {
+			print(`  ! skipping packages/${entry}: no package.json or malformed JSON`);
+			continue;
+		}
+		if (pkg.private) {
+			print(`  · skipping private package packages/${entry}`);
+			skipped.push(`packages/${entry}`);
+			continue;
+		}
+		bumpFile(pkgFile, `packages/${entry}`);
+	}
+	return {
+		status: dryRun ? "dry-run" : "ok",
+		bumped,
+		skipped
+	};
+}
+//#endregion
 //#region src/commands/npm-publish-initial.ts
 /**
 * `holocron npm publish-initial` — bottles up the chicken-and-egg
@@ -269,7 +522,7 @@ async function runNpmPublishInitial(input = {}) {
 		print("");
 		print("  … (dry-run) skipping actual publish");
 		print(`    would run: pnpm ${publishArgs.join(" ")}`);
-		printNextSteps(print, env);
+		printNextSteps$1(print, env);
 		return {
 			status: "dry-run",
 			message: "dry-run — no publish executed",
@@ -294,13 +547,13 @@ async function runNpmPublishInitial(input = {}) {
 		};
 	}
 	print("    ✓ publish complete");
-	printNextSteps(print, env);
+	printNextSteps$1(print, env);
 	return {
 		status: "ok",
 		packageNames: PUBLISHABLE_PACKAGES
 	};
 }
-function printNextSteps(print, env) {
+function printNextSteps$1(print, env) {
 	print("");
 	print("  → next: configure Trusted Publisher for each package on npm:");
 	for (const name of PUBLISHABLE_PACKAGES) print(`    https://www.npmjs.com/package/${name}/access`);
@@ -328,6 +581,1124 @@ const defaultExec = async (cmd, args, opts) => {
 	};
 };
 //#endregion
+//#region src/commands/plugin-create/template-inputs.ts
+/** Derive the standard defaults from a slug + vendor name. */
+function deriveDefaults(input) {
+	const vendorUpper = input.slug.toUpperCase().replace(/-/g, "_");
+	const capability = input.capability;
+	return {
+		vendorUpper,
+		capabilityClass: `${input.vendorName}${capability.charAt(0).toUpperCase() + capability.slice(1)}`,
+		tokenEnv: `HOLOCRON_${vendorUpper}_TOKEN`,
+		transport: "rest"
+	};
+}
+//#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;
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/auth-test.ts
+function render$16(inputs) {
+	return `import { describe, expect, it } from "vitest";
+
+import { AuthError, resolveToken } from "../auth.js";
+
+const noKeyring = () => null;
+
+describe("resolveToken", () => {
+	it("prefers --token over env vars + keyring", () => {
+		expect(
+			resolveToken({
+				cliToken: "flag",
+				env: { ${inputs.tokenEnv}: "hlc", ${inputs.vendorEnv}: "vendor" },
+				keyring: () => "kr",
+			})
+		).toBe("flag");
+	});
+
+	it("prefers ${inputs.tokenEnv} over ${inputs.vendorEnv}", () => {
+		expect(
+			resolveToken({
+				env: { ${inputs.tokenEnv}: "hlc", ${inputs.vendorEnv}: "vendor" },
+				keyring: noKeyring,
+			})
+		).toBe("hlc");
+	});
+
+	it("falls back to ${inputs.vendorEnv} when ${inputs.tokenEnv} is unset", () => {
+		expect(resolveToken({ env: { ${inputs.vendorEnv}: "vendor" }, keyring: noKeyring })).toBe("vendor");
+	});
+
+	it("falls back to keyring when env vars are unset", () => {
+		expect(resolveToken({ env: {}, keyring: (p) => (p === "${inputs.slug}" ? "kr" : null) })).toBe("kr");
+	});
+
+	it("throws AuthError with a helpful message when nothing is set", () => {
+		try {
+			resolveToken({ env: {}, keyring: noKeyring });
+			throw new Error("should have thrown");
+		} catch (err) {
+			expect(err).toBeInstanceOf(AuthError);
+			expect((err as Error).message).toMatch(/${inputs.tokenEnv}/);
+			expect((err as Error).message).toMatch(/holocron auth set ${inputs.slug}/);
+		}
+	});
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/capability.ts
+function render$15(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	const capabilityInterface = inputs.capability.charAt(0).toUpperCase() + inputs.capability.slice(1);
+	return `/**
+ * \`${inputs.capability}\` capability for ${inputs.vendorName}.
+ *
+ * Methods are STUBS — implement them against ${inputs.vendorName}'s
+ * REST API per the \`${capabilityInterface}\` interface contract in
+ * \`@theholocron/cli\`.
+ *
+ * TODO once you've stubbed the interface methods, restore the type
+ * import + \`implements\` clause:
+ *   import type { ${capabilityInterface} } from "@theholocron/cli";
+ *   export class ${inputs.capabilityClass} implements ${capabilityInterface} { ... }
+ */
+
+import type { ${clientClass} } from "../rest.js";
+
+export class ${inputs.capabilityClass} {
+	readonly key = "${inputs.capability}" as const;
+	readonly providerName = "${inputs.slug}";
+
+	constructor(private readonly rest: ${clientClass}) {}
+
+	// TODO: implement the ${capabilityInterface} interface methods
+	// (see \`packages/cli/src/capabilities/index.ts\`). Each method
+	// should hit a specific ${inputs.vendorName} REST endpoint via
+	// \`this.rest.request(...)\`. Once methods are stubbed, add
+	// \`implements ${capabilityInterface}\` to the class declaration
+	// above and remove the \`as unknown as\` cast in src/index.ts.
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/capability-test.ts
+function render$14(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	return `import { describe, it } from "vitest";
+
+import { ${inputs.capabilityClass} } from "../capabilities/${inputs.capability}.js";
+import { ${clientClass} } from "../rest.js";
+import { stubFetch } from "./helpers.js";
+
+// Stub client used by the constructor smoke test. Real capability
+// tests replace this with per-method stubs once implementations land.
+function makeCapability() {
+	const stub = stubFetch([]);
+	const rest = new ${clientClass}({ token: "t", fetch: stub.fetch });
+	return new ${inputs.capabilityClass}(rest);
+}
+
+describe("${inputs.capabilityClass}", () => {
+	it("constructs with a REST client", () => {
+		makeCapability();
+	});
+
+	// TODO: implement one test per ${inputs.capability} capability method
+	// as you fill in the class stubs. See other plugins for reference
+	// patterns:
+	//   - REST behaviors (URL / method / body / query) via \`stub.calls\`
+	//   - Error paths via \`stubFetch([{ status: 4xx, body: {...} }])\`
+	//   - Idempotency (409 handling for ensure* methods, if applicable)
+	it.todo("implement per-method tests");
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/eslint-config.ts
+function render$13(_inputs) {
+	return `import root from "../../eslint.config.js";
+
+export default [
+	...root,
+	{
+		ignores: ["dist/**", "coverage/**"],
+	},
+];
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/helpers.ts
+function render$12(_inputs) {
+	return `import { vi, type Mock } from "vitest";
+
+export interface FetchCall {
+	url: string;
+	method: string;
+	headers: Record<string, string>;
+	body: unknown;
+}
+
+export interface FetchStub {
+	fetch: typeof fetch;
+	calls: FetchCall[];
+	mock: Mock;
+}
+
+export function stubFetch(responses: Array<{ status?: number; body?: unknown; text?: string }>): FetchStub {
+	const calls: FetchCall[] = [];
+	let i = 0;
+	const mock = vi.fn(async (input: string | URL, init?: RequestInit) => {
+		const url = typeof input === "string" ? input : input.toString();
+		const body = typeof init?.body === "string" ? safeJsonParse(init.body) : (init?.body ?? null);
+		calls.push({
+			url,
+			method: (init?.method ?? "GET").toUpperCase(),
+			headers: (init?.headers as Record<string, string>) ?? {},
+			body,
+		});
+		const next = responses[i++] ?? { status: 200, body: {} };
+		const status = next.status ?? 200;
+		if (status === 204 || status === 205 || status === 304) {
+			return new Response(null, { status });
+		}
+		const text = next.text ?? (typeof next.body === "string" ? next.body : JSON.stringify(next.body ?? {}));
+		return new Response(text, { status });
+	});
+	return { fetch: mock as unknown as typeof fetch, calls, mock };
+}
+
+function safeJsonParse(s: string): unknown {
+	try {
+		return JSON.parse(s);
+	} catch {
+		return s;
+	}
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/index-test.ts
+function render$11(inputs) {
+	return `import { describe, expect, it } from "vitest";
+
+import { AUTH_HINT, createPlugin } from "../index.js";
+import { stubFetch } from "./helpers.js";
+
+describe("createPlugin", () => {
+	it("wires the ${inputs.capability} capability against the given fetch + token", () => {
+		const stub = stubFetch([]);
+		const plugin = createPlugin({
+			cliToken: "test-token",
+			fetch: stub.fetch,
+		});
+		expect(plugin.name).toBe("@theholocron/holocron-plugin-${inputs.slug}");
+		expect(typeof plugin.capabilities.${inputs.capability}).toBe("function");
+	});
+});
+
+describe("AUTH_HINT", () => {
+	it("mentions the holocron auth set command", () => {
+		expect(AUTH_HINT).toMatch(/holocron auth set ${inputs.slug}/);
+	});
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/package-json.ts
+function render$10(inputs) {
+	return `{
+  "name": "@theholocron/holocron-plugin-${inputs.slug}",
+  "version": "2.0.0-alpha.1",
+  "description": "Holocron plugin for ${inputs.vendorName}. Implements the ${inputs.capability} capability against ${inputs.vendorName}'s REST API, plus exports verifyToken + AUTH_HINT for \`holocron auth\`.",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-${inputs.slug}#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-${inputs.slug}"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "workspace:*"
+  },
+  "devDependencies": {
+    "@theholocron/cli": "workspace:*",
+    "@theholocron/tsconfig": "catalog:",
+    "@tsconfig/node-lts": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "eslint": "catalog:",
+    "globals": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "tsdown": "catalog:",
+    "tsx": "catalog:"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.mjs",
+    "types": "./dist/index.d.mts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.mts",
+        "import": "./dist/index.mjs",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/plugin-index.ts
+function render$9(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	const capabilityInterface = inputs.capability.charAt(0).toUpperCase() + inputs.capability.slice(1);
+	return `/**
+ * \`@theholocron/holocron-plugin-${inputs.slug}\` — entrypoint.
+ *
+ * Implements the \`${inputs.capability}\` capability against ${inputs.vendorName}'s
+ * REST API. Also exports \`verifyToken\` + \`AUTH_HINT\` for
+ * \`holocron auth\`. See README for auth + config docs.
+ *
+ * TODO: once you fill in the ${inputs.capabilityClass} methods and add
+ * \`implements ${capabilityInterface}\` to the class, add the type import:
+ *   import type { ${capabilityInterface} } from "@theholocron/cli";
+ * and set \`: ${capabilityInterface}\` as the factory return type below.
+ */
+
+import { resolveToken, type ResolveTokenInput } from "./auth.js";
+import { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
+import { ${clientClass} } from "./rest.js";
+
+export interface ${inputs.vendorName}PluginOptions extends ResolveTokenInput {
+	/** Override base URL for tests. */
+	baseUrl?: string;
+	/** Override \`fetch\` for tests. */
+	fetch?: typeof fetch;
+}
+
+export interface PluginContext {
+	options: ${inputs.vendorName}PluginOptions;
+	rest: ${clientClass};
+}
+
+export function createContext(options: ${inputs.vendorName}PluginOptions): PluginContext {
+	const token = resolveToken(options);
+	const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
+	if (options.baseUrl !== undefined) restOpts.baseUrl = options.baseUrl;
+	if (options.fetch !== undefined) restOpts.fetch = options.fetch;
+	return {
+		options,
+		rest: new ${clientClass}(restOpts),
+	};
+}
+
+export function ${inputs.capability}(ctx: PluginContext) {
+	// Return type inferred at scaffold time — the class doesn't yet
+	// \`implements ${capabilityInterface}\`. Add the type import + the
+	// \`: ${capabilityInterface}\` annotation once methods are stubbed.
+	return new ${inputs.capabilityClass}(ctx.rest);
+}
+
+export function createPlugin(options: ${inputs.vendorName}PluginOptions) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-${inputs.slug}",
+		capabilities: {
+			${inputs.capability}: () => ${inputs.capability}(ctx),
+		},
+	};
+}
+
+/**
+ * One-line hint printed by \`holocron auth set ${inputs.slug}\` when no
+ * token is supplied or the supplied token is rejected. Edit this to
+ * point operators at the specific ${inputs.vendorName} docs path for
+ * generating a token.
+ */
+export const AUTH_HINT =
+	"generate a ${inputs.vendorName} API token, then run: holocron auth set ${inputs.slug} <TOKEN>";
+
+// ── Public re-exports ────────────────────────────────────────────────
+
+export * from "./auth.js";
+export { ${clientClass} } from "./rest.js";
+export { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
+export { verifyToken } from "./verify-token.js";
+export type { VerifyTokenResult, VerifyTokenSuccess, VerifyTokenFailure } from "./verify-token.js";
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/readme.ts
+function render$8(inputs) {
+	return `<!-- editorconfig-checker-disable-file -->
+
+# \`@theholocron/holocron-plugin-${inputs.slug}\`
+
+${inputs.vendorName} plugin for [Holocron](../cli). Implements the
+\`${inputs.capability}\` capability against [${inputs.vendorName}'s REST API](${inputs.baseUrl}),
+plus exports \`verifyToken\` + \`AUTH_HINT\` for use by \`holocron auth\`.
+
+## Install
+
+\`\`\`bash
+pnpm add -D @theholocron/holocron-plugin-${inputs.slug}@alpha
+\`\`\`
+
+## Auth
+
+Token resolution order (matches the standard 4-step precedence set by
+\`.notes/tech-auth-bootstrap.spec.md\`):
+
+1. \`--token <TOKEN>\` flag on the holocron invocation
+2. \`${inputs.tokenEnv}\` env var (preferred — explicit intent)
+3. \`${inputs.vendorEnv}\` env var (${inputs.vendorName}-native)
+4. **Keyring** — \`com.theholocron.cli\` service, account \`${inputs.slug}\`
+5. \`AuthError\` naming all four options + the bootstrap hint
+
+## Setup
+
+\`\`\`bash
+# Generate a ${inputs.vendorName} API token (see vendor docs), then:
+holocron auth set ${inputs.slug} <TOKEN>
+holocron auth check ${inputs.slug}    # verify
+\`\`\`
+
+## Config
+
+\`\`\`jsonc
+{
+	"providers": {
+		"${inputs.capability}": "${inputs.slug}",
+	},
+}
+\`\`\`
+
+Plugin options extend \`ResolveTokenInput\` — add whatever ${inputs.vendorName}-
+specific options you need here (project id, workspace slug, etc.) via
+the tuple form:
+
+\`\`\`jsonc
+{
+	"providers": {
+		"${inputs.capability}": ["${inputs.slug}", { "baseUrl": "${inputs.baseUrl}" }],
+	},
+}
+\`\`\`
+
+## What's implemented
+
+TODO: fill in as capability methods land.
+
+## Status
+
+**\`v2.0.0-alpha.1\`** — scaffolded via \`holocron plugin create\`.
+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;
+	}
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/rest-test.ts
+function render$6(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	return `import { ProviderApiError } from "@theholocron/cli";
+import { describe, expect, it } from "vitest";
+
+import { ${clientClass} } 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}");
+	});
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/tsconfig-json.ts
+function render$5(inputs) {
+	return `{
+  "display": "Holocron Plugin: ${inputs.vendorName}",
+  "extends": "@tsconfig/node-lts/tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "outDir": "./dist",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/tsdown-config.ts
+function render$4(_inputs) {
+	return `import { defineConfig } from "tsdown";
+
+export default defineConfig({
+	entry: ["src/index.ts"],
+	format: "esm",
+	dts: true,
+	clean: true,
+	deps: { neverBundle: [/^@theholocron\\//] },
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/validate-script.ts
+/**
+* Scaffolds `scripts/validate.mjs` — a smoke-test the operator runs
+* against a live vendor account to verify the plugin's REST endpoints,
+* auth, and response parsing all work in reality (the unit tests only
+* exercise stubbed HTTP responses). READ-ONLY BY DESIGN.
+*
+* Convention: every plugin ships this script + a matching `validate`
+* entry in `package.json`'s scripts block, so operators run
+* `pnpm --filter @theholocron/holocron-plugin-<slug> validate`.
+* Capability-specific args (project id, workspace, etc.) come from
+* positional command-line arguments; the plugin author fills in the
+* exact shape per their vendor.
+*
+* Includes a `hintFor(message)` helper the operator customizes with
+* vendor-specific "here's the likely fix" guidance for common error
+* shapes (401 / 403 / 404 / network / 5xx). Points users at docs and
+* setup steps rather than leaving them staring at a raw stack trace.
+*/
+function render$3(inputs) {
+	return `#!/usr/bin/env node
+/**
+ * Read-only smoke test for @theholocron/holocron-plugin-${inputs.slug} against
+ * a live ${inputs.vendorName} account.
+ *
+ * READ-ONLY BY DESIGN. Never calls write(), or bootstrap methods
+ * (\`ensureProject\`, \`ensureEnvironment\`, etc.). Any ERROR line means
+ * the plugin needs adjusting — the \`hintFor\` helper below points at
+ * the most likely fix per error shape.
+ *
+ * Auth: reads the ${inputs.vendorName} token from holocron's keyring —
+ * you must have run \`pnpm holocron auth set ${inputs.slug} <TOKEN>\` first.
+ *
+ * Usage:
+ *   pnpm --filter @theholocron/holocron-plugin-${inputs.slug} validate <arg1> [arg2] ...
+ *
+ * TODO: replace the positional args below with whatever your
+ * capability's methods need (e.g., project id, environment slug,
+ * secret name). Adapt the test steps to your capability's method
+ * surface. Model on \`packages/holocron-plugin-infisical/scripts/validate.mjs\`.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- filled in by operator
+import { AuthError, createPlugin, resolveToken, verifyToken } from "../src/index.ts";
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+	console.error("usage: pnpm --filter @theholocron/holocron-plugin-${inputs.slug} validate <args>");
+	process.exit(2);
+}
+
+// Use the plugin's own auth resolution so the validate script honors
+// the same 4-step precedence as the plugin's runtime:
+//   --token → ${inputs.tokenEnv} → ${inputs.vendorEnv} → keyring
+// (--token isn't available here since this is a bare Node script;
+// the other three all work.)
+let token;
+try {
+	token = resolveToken();
+} catch (err) {
+	if (err instanceof AuthError) {
+		console.error(err.message);
+		console.error("  see: packages/holocron-plugin-${inputs.slug}/README.md#setup");
+		process.exit(2);
+	}
+	throw err;
+}
+
+console.log("Validating @theholocron/holocron-plugin-${inputs.slug} (READ-ONLY)");
+console.log("");
+
+// ── 1. verifyToken ─────────────────────────────────────────────────
+console.log("[1/N] verifyToken");
+const verifyResult = await verifyToken(token);
+console.log(\`      \${verifyResult.ok ? "✓" : "✗"} \${JSON.stringify(verifyResult)}\`);
+if (!verifyResult.ok) {
+	const hint = hintFor(verifyResult.message);
+	if (hint) console.log(\`         hint: \${hint}\`);
+}
+console.log("");
+
+// ── 2..N. capability method calls ──────────────────────────────────
+// TODO: implement one \`runStep\`-wrapped call per meaningful read-side
+// capability method. Model on the infisical validate.mjs. Never call
+// write / ensure* / other mutating paths.
+//
+// Example:
+//   console.log("[2/N] vault.list()");
+//   await runStep(async () => {
+//       const keys = await vault.list();
+//       console.log(\`      ✓ \${keys.length} secrets\`);
+//   });
+
+console.log("Done. Fill in capability method calls above before shipping.");
+
+// ── helpers ────────────────────────────────────────────────────────
+
+/** Wrap a capability call, print ERROR + hint on failure. */
+async function runStep(body) {
+	try {
+		await body();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.log(\`      ✗ ERROR: \${message}\`);
+		const hint = hintFor(message);
+		if (hint) console.log(\`         hint: \${hint}\`);
+	}
+}
+
+/**
+ * Point the operator at the most likely fix based on the error shape.
+ * Generic defaults below — CUSTOMIZE per your vendor's docs URLs and
+ * common permission/config gotchas.
+ */
+function hintFor(message) {
+	if (/→ 401/.test(message)) {
+		return "token invalid — regenerate per ${inputs.vendorName}'s docs (see README §Setup)";
+	}
+	if (/→ 403/.test(message)) {
+		return "token authenticates but lacks scope — check the token/identity has permissions on the resource";
+	}
+	if (/→ 404/.test(message)) {
+		return "endpoint or resource not found — verify your positional args match a real resource";
+	}
+	if (/fetch failed|status: 0|network/i.test(message)) {
+		return "network error — check the base URL (${inputs.baseUrl}) and connectivity";
+	}
+	if (/→ 5\\d\\d/.test(message)) {
+		return "server error — vendor-side. Retry, and check the vendor's status page if persistent";
+	}
+	return null;
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/verify-token.ts
+function render$2(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	return `/**
+ * \`verifyToken\` — plugin-level export used by \`holocron auth set\` +
+ * \`holocron auth check\`. Hits a lightweight whoami-style endpoint
+ * and translates the response into the normalized \`VerifyTokenResult\`
+ * shape.
+ *
+ * Kept as a standalone function (not a capability method) so the auth
+ * command can call it without initializing the full plugin — plugin
+ * construction requires an already-resolved token, which is exactly
+ * what we don't have yet at bootstrap time.
+ *
+ * TODO: replace \`/me\` with the ${inputs.vendorName} equivalent of a
+ * "check my token" endpoint. Common shapes: \`/user\`, \`/whoami\`,
+ * \`/me\`, \`/account\`.
+ */
+
+import { ${clientClass} } from "./rest.js";
+
+export interface VerifyTokenSuccess {
+	ok: true;
+	subject: string;
+}
+
+export interface VerifyTokenFailure {
+	ok: false;
+	message: string;
+}
+
+export type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+
+interface MeResponse {
+	/** Adjust to whatever ${inputs.vendorName}'s whoami endpoint returns. */
+	name?: string;
+	email?: string;
+	id?: string;
+}
+
+export interface VerifyTokenOptions {
+	baseUrl?: string;
+	fetch?: typeof fetch;
+}
+
+export async function verifyToken(token: string, opts: VerifyTokenOptions = {}): Promise<VerifyTokenResult> {
+	const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
+	if (opts.baseUrl !== undefined) restOpts.baseUrl = opts.baseUrl;
+	if (opts.fetch !== undefined) restOpts.fetch = opts.fetch;
+	const rest = new ${clientClass}(restOpts);
+	try {
+		const me = await rest.request<MeResponse>("/me");
+		// Optional chaining because \`me\` is \`undefined\` on 204 / empty body.
+		const subject = me?.email ?? me?.name ?? me?.id ?? "unknown";
+		return { ok: true, subject: \`user @ \${subject}\` };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { ok: false, message };
+	}
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/verify-token-test.ts
+function render$1(_inputs) {
+	return `import { describe, expect, it } from "vitest";
+
+import { verifyToken } from "../verify-token.js";
+import { stubFetch } from "./helpers.js";
+
+describe("verifyToken", () => {
+	it("returns ok with a subject when /me returns 200", async () => {
+		const stub = stubFetch([{ status: 200, body: { email: "user@example.com" } }]);
+		const result = await verifyToken("token", { fetch: stub.fetch });
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.subject).toMatch(/user@example.com/);
+		}
+	});
+
+	it("returns ok:false with the error message on 401", async () => {
+		const stub = stubFetch([{ status: 401, body: { messages: ["Invalid token"] } }]);
+		const result = await verifyToken("bad", { fetch: stub.fetch });
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.message).toMatch(/→ 401/);
+		}
+	});
+
+	it("returns ok:false when the network layer throws", async () => {
+		const throwing: typeof fetch = async () => {
+			throw new TypeError("network down");
+		};
+		const result = await verifyToken("t", { fetch: throwing });
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.message).toMatch(/network down/);
+		}
+	});
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/vitest-config.ts
+function render(_inputs) {
+	return `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		environment: "node",
+		globals: false,
+		coverage: {
+			provider: "v8",
+			reporter: ["text", "html", "json-summary"],
+			include: ["src/**/*.ts"],
+			exclude: ["src/**/__tests__/**", "src/**/*.test.ts", "src/index.ts"],
+			thresholds: { lines: 0, functions: 0, branches: 0, statements: 0 },
+		},
+	},
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/index.ts
+/**
+* `holocron plugin create <slug> <vendor>` — scaffold a new plugin
+* package matching the proven template.
+*
+* Design: see `.notes/tool-plugin-create.spec.md`.
+*
+* Flow:
+*   1. Preflight — verify CWD is a workspace root (pnpm-workspace.yaml
+*      + packages/ dir present).
+*   2. Slug collision — packages/holocron-plugin-<slug>/ must not exist.
+*   3. Capability sanity — must be one of the 14 known keys; warn for
+*      many-cardinality caps.
+*   4. Prompt — fill in any missing flags via cli-utils / inquirer
+*      (Phase B; Phase A takes fully-populated input).
+*   5. Generate — for each template, write to
+*      packages/holocron-plugin-<slug>/<path>.
+*   6. Verify (unless --no-verify) — Phase B; runs pnpm install +
+*      pnpm --filter <pkg> typecheck lint test.
+*   7. Print next steps.
+*/
+var PluginCreateError = class extends Error {
+	name = "PluginCreateError";
+};
+const TEMPLATES = [
+	{
+		path: "package.json",
+		render: render$10
+	},
+	{
+		path: "tsconfig.json",
+		render: render$5
+	},
+	{
+		path: "vitest.config.ts",
+		render
+	},
+	{
+		path: "eslint.config.js",
+		render: render$13
+	},
+	{
+		path: "tsdown.config.ts",
+		render: render$4
+	},
+	{
+		path: "README.md",
+		render: render$8
+	},
+	{
+		path: "src/auth.ts",
+		render: render$17
+	},
+	{
+		path: "src/rest.ts",
+		render: render$7
+	},
+	{
+		path: "src/verify-token.ts",
+		render: render$2
+	},
+	{
+		path: "src/index.ts",
+		render: render$9
+	},
+	{
+		path: "src/capabilities/{{capability}}.ts",
+		render: render$15
+	},
+	{
+		path: "src/__tests__/helpers.ts",
+		render: render$12
+	},
+	{
+		path: "src/__tests__/auth.test.ts",
+		render: render$16
+	},
+	{
+		path: "src/__tests__/rest.test.ts",
+		render: render$6
+	},
+	{
+		path: "src/__tests__/verify-token.test.ts",
+		render: render$1
+	},
+	{
+		path: "src/__tests__/{{capability}}.test.ts",
+		render: render$14
+	},
+	{
+		path: "src/__tests__/index.test.ts",
+		render: render$11
+	},
+	{
+		path: "scripts/validate.mjs",
+		render: render$3
+	}
+];
+/** Replace `{{capability}}` in a template path with the actual capability key. */
+function resolvePath(template, inputs) {
+	return template.replace(/\{\{capability\}\}/g, inputs.capability);
+}
+function runPluginCreate(input) {
+	const cwd = input.cwd ?? process.cwd();
+	const print = input.print ?? ((line) => console.log(line));
+	const write = input.writeFile ?? defaultWrite;
+	preflight(cwd);
+	validateSlug(input.slug);
+	validateVendorName(input.vendorName);
+	const packageDir = path.join(cwd, "packages", `holocron-plugin-${input.slug}`);
+	if (existsSync(packageDir)) throw new PluginCreateError(`\`${packageDir}\` already exists — edit in place or pick a different slug.`);
+	validateCapability(input.capability, print);
+	const derived = deriveDefaults({
+		slug: input.slug,
+		vendorName: input.vendorName,
+		capability: input.capability
+	});
+	const inputs = {
+		slug: input.slug,
+		vendorName: input.vendorName,
+		vendorUpper: derived.vendorUpper,
+		capability: input.capability,
+		capabilityClass: derived.capabilityClass,
+		tokenEnv: input.tokenEnv ?? derived.tokenEnv,
+		vendorEnv: input.vendorEnv,
+		baseUrl: trimTrailingSlashes(input.baseUrl),
+		transport: derived.transport
+	};
+	const filesWritten = [];
+	print(`Scaffolding @theholocron/holocron-plugin-${inputs.slug}${input.dryRun ? " (dry-run)" : ""}`);
+	print(`  → ${packageDir}`);
+	for (const template of TEMPLATES) {
+		const resolvedPath = resolvePath(template.path, inputs);
+		const filepath = path.join(packageDir, resolvedPath);
+		const content = template.render(inputs);
+		if (input.dryRun) print(`  … would write ${resolvedPath} (${content.length} bytes)`);
+		else {
+			write(filepath, content);
+			print(`  ✓ ${resolvedPath}`);
+		}
+		filesWritten.push(resolvedPath);
+	}
+	if (!input.dryRun) printNextSteps(print, inputs);
+	return {
+		status: "ok",
+		packagePath: packageDir,
+		filesWritten
+	};
+}
+function preflight(cwd) {
+	if (!existsSync(path.join(cwd, "pnpm-workspace.yaml"))) throw new PluginCreateError(`\`pnpm-workspace.yaml\` not found in \`${cwd}\`. Run \`holocron plugin create\` from the monorepo root.`);
+	if (!existsSync(path.join(cwd, "packages"))) throw new PluginCreateError(`\`packages/\` directory not found in \`${cwd}\`.`);
+}
+/**
+* npm-package-name conventions: kebab-case, starts with lowercase
+* letter. Rejecting numeric-prefixed slugs also sidesteps the
+* `env.HOLOCRON_1FOO_TOKEN` invalid-identifier trap in the auth
+* template.
+*/
+const SLUG_RE = /^[a-z][a-z0-9-]*$/;
+function validateSlug(slug) {
+	if (!SLUG_RE.test(slug)) throw new PluginCreateError(`invalid slug "${slug}" — must be kebab-case: lowercase letter followed by lowercase letters, digits, or hyphens. Examples: "clerk", "cloud-flare", "doppler".`);
+}
+/** PascalCase — starts with uppercase, alphanumeric only. */
+const VENDOR_NAME_RE = /^[A-Z][a-zA-Z0-9]*$/;
+function validateVendorName(name) {
+	if (!VENDOR_NAME_RE.test(name)) throw new PluginCreateError(`invalid vendor name "${name}" — must be PascalCase: starts with uppercase, alphanumeric only. Examples: "Clerk", "CloudFlare", "Doppler".`);
+}
+/**
+* Trim trailing slashes with a plain loop (no regex — matches the
+* rest.ts template's own trimming to stay ReDoS-safe under CodeQL).
+*/
+function trimTrailingSlashes(url) {
+	let out = url;
+	while (out.endsWith("/")) out = out.slice(0, -1);
+	return out;
+}
+function validateCapability(capability, print) {
+	if (!(capability in CARDINALITY)) throw new PluginCreateError(`\`${capability}\` is not a known capability. See \`packages/cli/src/capabilities/index.ts\`.`);
+	if (CARDINALITY[capability] === "many") print(`  ! ${capability} is a many-cardinality capability — multiple providers can be active at once. Confirm your config wiring accordingly.`);
+}
+function defaultWrite(filepath, content) {
+	mkdirSync(path.dirname(filepath), { recursive: true });
+	writeFileSync(filepath, content, "utf8");
+}
+function printNextSteps(print, inputs) {
+	print("");
+	print(`  Scaffolded @theholocron/holocron-plugin-${inputs.slug} (18 files).`);
+	print("");
+	print("  Next:");
+	print(`    1. pnpm install                                                        # picks up the workspace package`);
+	print(`    2. pnpm --filter @theholocron/holocron-plugin-${inputs.slug} typecheck   # green`);
+	print(`    3. pnpm --filter @theholocron/holocron-plugin-${inputs.slug} lint        # green`);
+	print(`    4. pnpm --filter @theholocron/holocron-plugin-${inputs.slug} test        # green (stubs pass, real tests are it.todo)`);
+	print(`    5. Implement ${inputs.capabilityClass} methods in src/capabilities/${inputs.capability}.ts`);
+	print(`    6. Replace it.todo(...) with real tests in src/__tests__/${inputs.capability}.test.ts`);
+	print("    7. Commit + push when capability is functionally complete.");
+}
+//#endregion
 //#region src/commands/secret-set.ts
 async function runSecretSet(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -494,7 +1865,389 @@ function vaultProviderName(loader) {
 	return loader.get("vault").providerName;
 }
 //#endregion
+//#region src/commands/setup-workflows.ts
+/**
+* Thin workflow wrapper templates for `holocron setup`.
+*
+* Each entry is a complete `.github/workflows/<name>.yml` that delegates
+* to the corresponding reusable `ci-<name>.yml` in `theholocron/.github`.
+* Files are overwritten on each setup run — they are generated artifacts.
+*/
+const WORKFLOW_REPO = "theholocron/.github";
+const WORKFLOW_REF = "main";
+function ref(name) {
+	return `${WORKFLOW_REPO}/.github/workflows/${name}.yml@${WORKFLOW_REF}`;
+}
+/** Header prepended when holocron setup writes a thin caller to a repo. */
+const WORKFLOW_HEADER = `\
+# AUTO-GENERATED by holocron — do not edit directly.
+# Source: theholocron/holocron · packages/cli/src/commands/setup-workflows.ts
+# Run \`holocron setup\` to regenerate.
+
+`;
+const WORKFLOW_TEMPLATES = {
+	lint: `\
+name: Lint
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: lint-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  statuses: write
+
+jobs:
+  lint:
+    name: Lint
+    uses: ${ref("lint")}
+    secrets: inherit
+    with:
+      enable-auto-commit: true
+`,
+	test: `\
+name: Test
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: test-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    uses: ${ref("test")}
+    secrets: inherit
+`,
+	typecheck: `\
+name: Typecheck
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: typecheck-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck:
+    name: Typecheck
+    uses: ${ref("typecheck")}
+    secrets: inherit
+`,
+	codeql: `\
+name: CodeQL
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "0 0 * * 1"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  codeql:
+    uses: ${ref("codeql")}
+    secrets: inherit
+`,
+	review: `\
+name: Review
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+
+concurrency:
+  group: review-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  review:
+    name: Review
+    uses: ${ref("review")}
+    secrets: inherit
+`,
+	release: `\
+name: Release
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  id-token: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    uses: ${ref("release")}
+    secrets: inherit
+`,
+	stale: `\
+name: Stale
+
+on: # yamllint disable-line rule:truthy
+  schedule:
+    - cron: "30 1 * * *"
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    uses: ${ref("stale")}
+    secrets: inherit
+`,
+	greetings: `\
+name: Greetings
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+  issues:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  greetings:
+    uses: ${ref("greetings")}
+    secrets: inherit
+`,
+	dependencies: `\
+name: Dependencies
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependencies:
+    uses: ${ref("dependencies")}
+    secrets: inherit
+`,
+	"bookkeeping-pr": `\
+name: PR Bookkeeping
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+    types:
+      - opened
+      - edited
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  bookkeeping:
+    uses: ${ref("bookkeeping-pr")}
+    secrets: inherit
+`,
+	audit: `\
+name: Audit
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    uses: ${ref("audit")}
+    secrets: inherit
+`
+};
+const KNOWN_WORKFLOWS = new Set(Object.keys(WORKFLOW_TEMPLATES));
+//#endregion
 //#region src/commands/setup.ts
+const DEPENDABOT_CONFIG = `\
+# AUTO-GENERATED by holocron — run \`holocron setup\` to regenerate.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      security-patches:
+        applies-to: security-updates
+        patterns:
+          - "*"
+      all-dependencies:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      all-actions:
+        patterns:
+          - "*"
+`;
+const RULESET_NAME = "holocron-default-branch";
+const BALANCED_REPO_SETTINGS = {
+	allow_squash_merge: true,
+	allow_merge_commit: false,
+	allow_rebase_merge: false,
+	allow_auto_merge: true,
+	allow_update_branch: true,
+	delete_branch_on_merge: true,
+	has_issues: true,
+	has_discussions: true,
+	has_projects: true,
+	has_wiki: false
+};
+function buildClassicProtectionPayload(requiredChecks = []) {
+	return {
+		required_status_checks: requiredChecks.length > 0 ? {
+			strict: false,
+			contexts: requiredChecks
+		} : null,
+		enforce_admins: false,
+		required_pull_request_reviews: {
+			required_approving_review_count: 0,
+			dismiss_stale_reviews: false,
+			require_code_owner_reviews: false
+		},
+		restrictions: null,
+		allow_force_pushes: false,
+		allow_deletions: false
+	};
+}
+function buildRulesetPayload(requiredChecks = []) {
+	const rules = [
+		{ type: "deletion" },
+		{ type: "non_fast_forward" },
+		{
+			type: "pull_request",
+			parameters: {
+				required_approving_review_count: 0,
+				dismiss_stale_reviews_on_push: false,
+				require_code_owner_review: false,
+				require_last_push_approval: false,
+				required_review_thread_resolution: false
+			}
+		}
+	];
+	if (requiredChecks.length > 0) rules.push({
+		type: "required_status_checks",
+		parameters: {
+			required_status_checks: requiredChecks.map((context) => ({ context })),
+			strict_required_status_checks_policy: false
+		}
+	});
+	return {
+		name: RULESET_NAME,
+		target: "branch",
+		enforcement: "active",
+		conditions: { ref_name: {
+			include: ["~DEFAULT_BRANCH"],
+			exclude: []
+		} },
+		rules
+	};
+}
+async function upsertBranchProtection(source, dryRun, requiredChecks) {
+	const step = `upsert ruleset ${RULESET_NAME}`;
+	if (dryRun) return {
+		capability: "source",
+		step,
+		status: "dry-run"
+	};
+	try {
+		const found = (await source.listRulesets()).find((r) => r.name === RULESET_NAME);
+		if (found) {
+			await source.updateRuleset(found.id, buildRulesetPayload(requiredChecks));
+			return {
+				capability: "source",
+				step,
+				status: "ok",
+				message: "updated"
+			};
+		}
+		await source.createRuleset(buildRulesetPayload(requiredChecks));
+		return {
+			capability: "source",
+			step,
+			status: "ok",
+			message: "created"
+		};
+	} catch (err) {
+		if (!(err instanceof ProviderApiError) || err.status !== 403) return {
+			capability: "source",
+			step,
+			status: "fail",
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+	try {
+		const repo = await source.getRepo();
+		await source.protectBranch(repo.defaultBranch, buildClassicProtectionPayload(requiredChecks));
+		return {
+			capability: "source",
+			step,
+			status: "ok",
+			message: `classic protection on ${repo.defaultBranch}`
+		};
+	} catch (err) {
+		if (err instanceof ProviderApiError && err.status === 403) return {
+			capability: "source",
+			step,
+			status: "skip",
+			message: "branch protection unavailable on private repos without GitHub Pro/Team"
+		};
+		return {
+			capability: "source",
+			step,
+			status: "fail",
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
 async function runSetup(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
@@ -512,13 +2265,57 @@ async function runSetup(input) {
 			"enableVulnerabilityAlerts",
 			"enableAutomatedSecurityFixes",
 			"enableSecretScanning",
-			"enablePrivateVulnerabilityReporting"
+			"enablePrivateVulnerabilityReporting",
+			"enableDependencyGraph"
 		]) {
 			steps.push(await runStep("source", method, dryRun, async () => {
 				await source[method]();
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
+		steps.push(await runStep("source", "enableCodeScanning", dryRun, async () => {
+			return await source.enableCodeScanning();
+		}));
+		print(formatStep(steps[steps.length - 1]));
+		const policy = config.project.repoPolicy;
+		if (policy && policy.preset !== "none") {
+			const preset = policy.preset ?? "balanced";
+			steps.push(await runStep("source", "updateRepoSettings", dryRun, async () => {
+				await source.updateRepoSettings(BALANCED_REPO_SETTINGS);
+			}));
+			print(formatStep(steps[steps.length - 1]));
+			const requiredChecks = preset === "strict" ? policy.requiredChecks ?? [] : [];
+			steps.push(await upsertBranchProtection(source, dryRun, requiredChecks));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
+	const workflows = config.project.workflows;
+	if (loader.has("source") && workflows && workflows.length > 0) {
+		const source = loader.get("source");
+		print("  → workflows");
+		for (const name of workflows) {
+			if (!KNOWN_WORKFLOWS.has(name)) {
+				steps.push({
+					capability: "source",
+					step: `write workflow ${name}`,
+					status: "skip",
+					message: `unknown workflow "${name}" — no template available`
+				});
+				print(formatStep(steps[steps.length - 1]));
+				continue;
+			}
+			steps.push(await runStep("source", `write workflow ${name}`, dryRun, async () => {
+				await source.writeWorkflowFile(`${name}.yml`, WORKFLOW_HEADER + WORKFLOW_TEMPLATES[name]);
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
+	if (loader.has("source") && config.project.repoPolicy?.preset !== "none") {
+		const source = loader.get("source");
+		steps.push(await runStep("source", "write .github/dependabot.yml", dryRun, async () => {
+			await source.writeRepoFile(".github/dependabot.yml", DEPENDABOT_CONFIG);
+		}));
+		print(formatStep(steps[steps.length - 1]));
 	}
 	if (loader.has("environments")) {
 		const envs = loader.get("environments");
@@ -559,6 +2356,22 @@ async function runSetup(input) {
 	if (loader.has("vault")) {
 		const vault = loader.get("vault");
 		print("  → vault");
+		if (vault.ensureProject) {
+			steps.push(await runStep("vault", `ensureProject ${config.project.name}`, dryRun, async () => {
+				return `project ${(await vault.ensureProject(config.project.name)).alreadyExists ? "exists" : "created"}`;
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+		if (vault.ensureEnvironment) for (const envName of [
+			"dev",
+			"stg",
+			"prd"
+		]) {
+			steps.push(await runStep("vault", `ensureEnvironment ${envName}`, dryRun, async () => {
+				return `${envName} ${(await vault.ensureEnvironment(config.project.name, envName)).alreadyExists ? "exists" : "created"}`;
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
 		try {
 			const keys = await vault.list();
 			steps.push({
@@ -695,6 +2508,7 @@ async function fileExists(path) {
 }
 //#endregion
 //#region src/cli.ts
+const { version: CLI_VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [options]").option("dry-run", {
 	type: "boolean",
 	default: false,
@@ -707,7 +2521,7 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	default: process.cwd(),
 	describe: "Directory to search for holocron.config.json"
 }).command("version", "Print the CLI version", () => {}, () => {
-	console.log("holocron 2.0.0-alpha.0");
+	console.log(`holocron ${CLI_VERSION}`);
 }).command("doctor", "Load the config and run a smoke check against every provider", (y) => y.option("repo", {
 	type: "string",
 	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
@@ -815,7 +2629,17 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 		branch: argv.branch,
 		...argv.target ? { target: argv.target } : {}
 	})).status === "fail") process.exitCode = 1;
-}).command("npm publish-initial", "One-shot bootstrap publish for trusted-publishing-eligible packages", (y) => y.option("tag", {
+}).command("npm", "npm-related monorepo utilities", (y) => y.command("bump-versions <new-version>", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (yy) => yy.positional("new-version", {
+	type: "string",
+	demandOption: true,
+	describe: "Version to set (e.g., 4.2.0 or 2.0.0-alpha.1)"
+}), async (argv) => {
+	if ((await runNpmBumpVersions({
+		version: argv.newVersion,
+		cwd: argv.cwd,
+		dryRun: argv.dryRun
+	})).status === "fail") process.exitCode = 1;
+}).command("publish-initial", "One-shot bootstrap publish for trusted-publishing-eligible packages", (yy) => yy.option("tag", {
 	type: "string",
 	default: "alpha",
 	describe: "npm distribution tag (defaults to alpha)"
@@ -829,10 +2653,76 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 		dryRun: argv.dryRun,
 		...argv.otp ? { otp: argv.otp } : {}
 	})).status === "fail") process.exitCode = 1;
-}).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
+}).demandCommand(1, "Run `holocron npm --help` to see available npm subcommands."), () => {}).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
 	const loaded = await loadConfig(argv.cwd);
 	console.log(JSON.stringify(loaded.resolved, null, 2));
-}).demandCommand(1, "Run `holocron --help` to see available commands.").strict().help().parse();
+}).command("plugin create <slug> <vendor>", "Scaffold a new @theholocron/holocron-plugin-<slug> package", (y) => y.positional("slug", {
+	type: "string",
+	demandOption: true,
+	describe: "Package slug (kebab-case)"
+}).positional("vendor", {
+	type: "string",
+	demandOption: true,
+	describe: "Vendor display name (PascalCase)"
+}).option("capability", {
+	type: "string",
+	describe: "Capability key: source|ci|secrets|environments|issues|deployment|storage|auth|vault|dns|tooling|notifications|analytics|observability"
+}).option("token-env", {
+	type: "string",
+	describe: "Holocron env var name (defaults to HOLOCRON_<VENDOR>_TOKEN)"
+}).option("vendor-env", {
+	type: "string",
+	describe: "Vendor-native env var name"
+}).option("base-url", {
+	type: "string",
+	describe: "REST base URL"
+}).option("verify", {
+	type: "boolean",
+	default: true,
+	describe: "Run post-scaffold pnpm install + typecheck + lint + test (default true; --no-verify skips)"
+}), (argv) => {
+	try {
+		if (!argv.capability || !argv.vendorEnv || !argv.baseUrl) throw new PluginCreateError("Phase A: --capability, --vendor-env, and --base-url are required. Interactive prompts land in Phase B.");
+		if (runPluginCreate({
+			slug: argv.slug,
+			vendorName: argv.vendor,
+			capability: argv.capability,
+			vendorEnv: argv.vendorEnv,
+			baseUrl: argv.baseUrl,
+			...argv.tokenEnv ? { tokenEnv: argv.tokenEnv } : {},
+			dryRun: argv.dryRun,
+			noVerify: !argv.verify,
+			cwd: argv.cwd
+		}).status === "fail") process.exitCode = 1;
+	} catch (err) {
+		if (err instanceof PluginCreateError) {
+			console.error(`plugin create: ${err.message}`);
+			process.exitCode = 1;
+			return;
+		}
+		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", {
+	type: "string",
+	demandOption: true
+}).positional("token", { type: "string" }), async (argv) => {
+	if ((await runAuthSet({
+		provider: argv.provider,
+		...argv.token ? { positional: argv.token } : {}
+	})).status === "fail") process.exitCode = 1;
+}).command("unset <provider>", "Remove a stored bootstrap token", (yy) => yy.positional("provider", {
+	type: "string",
+	demandOption: true
+}), (argv) => {
+	runAuthUnset({ provider: argv.provider });
+}).command("check <provider>", "Re-verify a stored bootstrap token", (yy) => yy.positional("provider", {
+	type: "string",
+	demandOption: true
+}), async (argv) => {
+	if ((await runAuthCheck({ provider: argv.provider })).status === "fail") process.exitCode = 1;
+}).command("list", "List every provider with a stored bootstrap token", () => {}, async () => {
+	await runAuthList();
+}).demandCommand(1, "Run `holocron auth --help` to see available auth subcommands."), () => {}).demandCommand(1, "Run `holocron --help` to see available commands.").strict().help().parse();
 /**
 * Parse `--scope` strings: `repo` | `env=NAME` | `org=NAME`.
 */