@theholocron/cli 4.16.5 → 4.17.1

package/dist/cli.mjs

@@ -379,6 +379,240 @@ function getRunId() {
 	return root?.runId;
 }
 //#endregion
+//#region src/plugin/loader.ts
+/**
+* `PluginLoader` — loads provider plugins per the resolved config and
+* builds a typed capability registry the runtime can query.
+*
+* Flow:
+*   1. Walk `config.providers[*]` from `resolveConfig()`
+*   2. For each entry, dynamic-import the resolved package name
+*      (`@theholocron/holocron-plugin-<provider>` by default)
+*   3. Call the package's exported `createPlugin(options)` to get a
+*      plugin object whose `capabilities` map holds factories
+*   4. Invoke the matching capability factory and stash the impl in
+*      the registry — single-cardinality entries hold one impl,
+*      many-cardinality entries hold an array
+*
+* A package may instead export a capability config (see
+* `CapabilityConfigPackage` in config.ts). The loader detects the shape
+* at import time and re-resolves to the underlying plugin, merging the
+* preset options with any per-project overrides from the config file
+* (project options win, mirroring ESLint's `extends` precedence).
+*
+* Loader keeps NO knowledge of vendor tokens. Each plugin reads its
+* own env vars (`HOLOCRON_ADMIN_TOKEN`, `HOLOCRON_VERCEL_TOKEN`, etc.)
+* inside its `createPlugin`. That keeps the loader vendor-agnostic
+* and the auth story per-plugin explicit.
+*
+* `importer` is injectable so tests don't need real network or
+* sibling packages installed.
+*/
+var LoaderError = class extends Error {
+	name = "LoaderError";
+};
+var PluginLoader = class {
+	config;
+	context;
+	importer;
+	registry = /* @__PURE__ */ new Map();
+	failures = [];
+	constructor(config, context, importer = defaultImporter$1) {
+		this.config = config;
+		this.context = context;
+		this.importer = importer;
+	}
+	/**
+	* Imports every configured plugin and builds the capability registry.
+	*
+	* Never throws for a single plugin's failure — a missing vendor token,
+	* an uninstalled package, or an unimplemented capability records a
+	* {@link PluginLoadFailure} and the load continues. This is the
+	* "soft-skip over hard-fail" contract: a command that needs a
+	* capability learns it is absent via `has()` / `get()` (which
+	* re-surfaces the original error), and orchestrators report the skip
+	* in their summary. Inspect {@link loadFailures} for the full list.
+	*/
+	async load() {
+		const entries = Object.entries(this.config.providers);
+		for (const [key, entry] of entries) {
+			if (!entry) continue;
+			if (entry.cardinality === "single") try {
+				this.registry.set(key, await this.loadOne(key, entry.tuple));
+			} catch (err) {
+				this.recordFailure(key, entry.tuple, err);
+			}
+			else {
+				const impls = [];
+				for (const tuple of entry.tuples) try {
+					impls.push(await this.loadOne(key, tuple));
+				} catch (err) {
+					this.recordFailure(key, tuple, err);
+				}
+				if (impls.length > 0) this.registry.set(key, impls);
+			}
+		}
+	}
+	recordFailure(key, tuple, err) {
+		this.failures.push({
+			key,
+			provider: tuple.provider,
+			packageName: tuple.packageName,
+			error: err instanceof Error ? err : new Error(String(err))
+		});
+	}
+	/** Providers that failed to load during {@link load}. Empty on a clean load. */
+	loadFailures() {
+		return this.failures;
+	}
+	/**
+	* Type-safe lookup. Single-cardinality keys return one impl;
+	* many-cardinality keys return an array. `ResolvedCapability<K>`
+	* encodes the split via the `CARDINALITY` map.
+	*/
+	get(key) {
+		const impl = this.registry.get(key);
+		if (impl === void 0) {
+			const failure = this.failures.find((f) => f.key === key);
+			if (failure) throw failure.error;
+			throw new LoaderError(`capability \`${key}\` is not loaded — is it declared in holocron.config.json?`);
+		}
+		return impl;
+	}
+	/** Whether a capability has been loaded. */
+	has(key) {
+		return this.registry.has(key);
+	}
+	/** All capability keys currently loaded. Useful for the doctor command. */
+	loadedKeys() {
+		return Array.from(this.registry.keys());
+	}
+	/** Internal — invoke a plugin's capability factory and return the impl. */
+	async loadOne(key, tuple) {
+		const mod = await this.importer(tuple.packageName).catch((err) => {
+			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
+		});
+		if (isPluginModule(mod)) {
+			const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
+			const factory = mod.createPlugin({
+				...this.projectDefaults(),
+				...this.context,
+				...effectiveToken !== void 0 ? { cliToken: effectiveToken } : {},
+				cliTokens: void 0,
+				...tuple.options
+			}).capabilities[key];
+			if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
+			return factory();
+		}
+		if (isCapabilityConfigModule(mod)) {
+			const cap = mod.default;
+			return this.loadOne(key, {
+				provider: cap.provider,
+				packageName: resolvePluginPackage(cap.provider),
+				options: {
+					...cap.options,
+					...tuple.options
+				}
+			});
+		}
+		throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\` or a capability config ({ provider, options? })`);
+	}
+	/**
+	* Project-level defaults that get merged into every plugin's options
+	* unless overridden by the CLI context or per-plugin tuple options.
+	* See `docs/wiki/specifications/tech-setup-and-config.spec.md` §Design.
+	*/
+	projectDefaults() {
+		const defaults = {};
+		if (this.config.repo?.name) defaults.repo = this.config.repo.name;
+		return defaults;
+	}
+};
+/** Default importer — resolves from cwd first so the global CLI finds project plugins. */
+const defaultImporter$1 = async (pkg) => {
+	try {
+		return import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
+	} catch {
+		return import(pkg);
+	}
+};
+function isPluginModule(mod) {
+	return typeof mod.createPlugin === "function";
+}
+function isCapabilityConfigModule(mod) {
+	return typeof mod.default?.provider === "string";
+}
+//#endregion
+//#region src/plugin/workspace.ts
+/**
+* The `workspace`-context guard.
+*
+* A `workspace` command (`sync`, `setup`, `doctor`, …) needs the
+* configured providers' `@theholocron/holocron-plugin-*` packages to
+* resolve. From a bare `npm i -g @theholocron/cli` they don't, and the
+* {@link PluginLoader} — which soft-skips every failure — leaves the
+* command with an empty registry and a stack of `Cannot find package`
+* errors.
+*
+* {@link assertPluginsResolvable} turns that specific situation (every
+* provider failed, and every failure is a module-resolution failure)
+* into one actionable {@link WorkspaceContextError} the CLI prints
+* instead of a stack trace. Any other mix — some plugins loaded, or a
+* failure that's an auth/token error rather than a missing package —
+* is left alone for the command's own soft-skip reporting.
+*
+* Spec: `docs/wiki/specifications/tech-cli-execution-contexts.spec.md`
+* (theholocron/holocron#576).
+*/
+/**
+* Raised when a `workspace` command runs somewhere its provider plugins
+* cannot be resolved — the "you're on a global install" case. Carries the
+* unresolved package names so the message can be specific.
+*/
+var WorkspaceContextError = class extends Error {
+	name = "WorkspaceContextError";
+	command;
+	packages;
+	constructor(command, packages) {
+		const [first, ...rest] = packages;
+		const subject = rest.length > 0 ? `${first} (and ${rest.length} other${rest.length === 1 ? "" : "s"})` : first ?? "its plugins";
+		super(`\`${command}\` needs ${subject}, but no plugin package resolves here.\nRun it from a repo that has the \`@theholocron/holocron-plugin-*\` packages as devDependencies, or \`pnpm exec holocron ${command}\`. A global install can't resolve them — see https://theholocron.github.io/holocron/execution-contexts`);
+		this.command = command;
+		this.packages = packages;
+	}
+};
+/**
+* A raw "package isn't installed here" error from `import()` /
+* `require.resolve` — `ERR_MODULE_NOT_FOUND` / `MODULE_NOT_FOUND`, or the
+* "Cannot find package/module" message Node prints for it.
+*/
+function isModuleNotFound(err) {
+	if (!(err instanceof Error)) return false;
+	const code = err.code;
+	if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") return true;
+	return /Cannot find (?:package|module)|MODULE_NOT_FOUND/.test(err.message);
+}
+/** Did this failure come from the dynamic `import()` not finding the package? */
+function isImportFailure(err) {
+	return err instanceof LoaderError && err.message.startsWith("failed to import");
+}
+/**
+* Throw {@link WorkspaceContextError} when a loaded `PluginLoader` shows
+* the global-install signature: nothing in the registry, at least one
+* failure, and *every* failure is a missing-package error. A no-op in
+* every other case (some capability loaded, non-import failure, or no
+* providers configured at all).
+*
+* Call it right after `await loader.load()` in a `workspace` command.
+*/
+function assertPluginsResolvable(loader, command) {
+	if (loader.loadedKeys().length > 0) return;
+	const failures = loader.loadFailures();
+	if (failures.length === 0) return;
+	if (!failures.every((f) => isImportFailure(f.error))) return;
+	throw new WorkspaceContextError(command, [...new Set(failures.map((f) => f.packageName))]);
+}
+//#endregion
 //#region src/ui/progress.ts
 /**
 * Runs `fn`, showing an ora spinner for its duration in TTY environments.
@@ -427,7 +661,7 @@ const style = {
 * don't export `verifyToken` can still store — with a warning — because
 * "no verify path" shouldn't block credential storage.
 */
-const defaultImporter$1 = async (pkg) => {
+const defaultImporter = async (pkg) => {
 	try {
 		return await import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
 	} catch {
@@ -448,7 +682,7 @@ function resolveAuthSetToken(input) {
 async function runAuthSet(input) {
 	const print = input.print ?? ((l) => console.log(l));
 	const logger = input.logger ?? getLogger();
-	const importer = input.importer ?? defaultImporter$1;
+	const importer = input.importer ?? defaultImporter;
 	const { provider } = input;
 	const keyringKey = input.org ? `${provider}.${input.org}` : provider;
 	const token = resolveAuthSetToken({
@@ -551,7 +785,7 @@ function runAuthUnset(input) {
 async function runAuthCheck(input) {
 	const print = input.print ?? ((l) => console.log(l));
 	const logger = input.logger ?? getLogger();
-	const importer = input.importer ?? defaultImporter$1;
+	const importer = input.importer ?? defaultImporter;
 	const { provider } = input;
 	const keyringKey = input.org ? `${provider}.${input.org}` : provider;
 	const token = getToken(keyringKey);
@@ -616,6 +850,19 @@ async function runAuthCheck(input) {
 		};
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
+		if (isModuleNotFound(err)) {
+			print(style.warn(`${keyringKey}: token present — verification skipped (plugin not available here)`));
+			logger.info({
+				provider,
+				keyringKey,
+				status: "ok",
+				reason: "plugin not resolvable"
+			}, `auth check: ${keyringKey}`);
+			return {
+				status: "ok",
+				message: "stored, unverified (plugin not available)"
+			};
+		}
 		print(style.fail(`${keyringKey}: cannot verify — ${msg}`));
 		logger.warn({
 			provider,
@@ -632,7 +879,7 @@ async function runAuthCheck(input) {
 async function runAuthList(input = {}) {
 	const print = input.print ?? ((l) => console.log(l));
 	const logger = input.logger ?? getLogger();
-	const importer = input.importer ?? defaultImporter$1;
+	const importer = input.importer ?? defaultImporter;
 	const providers = listStoredProviders();
 	if (providers.length === 0) {
 		print(style.dim("no stored tokens."));
@@ -677,170 +924,6 @@ async function tryLoadHint(importer, packageName) {
 	}
 }
 //#endregion
-//#region src/plugin/loader.ts
-/**
-* `PluginLoader` — loads provider plugins per the resolved config and
-* builds a typed capability registry the runtime can query.
-*
-* Flow:
-*   1. Walk `config.providers[*]` from `resolveConfig()`
-*   2. For each entry, dynamic-import the resolved package name
-*      (`@theholocron/holocron-plugin-<provider>` by default)
-*   3. Call the package's exported `createPlugin(options)` to get a
-*      plugin object whose `capabilities` map holds factories
-*   4. Invoke the matching capability factory and stash the impl in
-*      the registry — single-cardinality entries hold one impl,
-*      many-cardinality entries hold an array
-*
-* A package may instead export a capability config (see
-* `CapabilityConfigPackage` in config.ts). The loader detects the shape
-* at import time and re-resolves to the underlying plugin, merging the
-* preset options with any per-project overrides from the config file
-* (project options win, mirroring ESLint's `extends` precedence).
-*
-* Loader keeps NO knowledge of vendor tokens. Each plugin reads its
-* own env vars (`HOLOCRON_ADMIN_TOKEN`, `HOLOCRON_VERCEL_TOKEN`, etc.)
-* inside its `createPlugin`. That keeps the loader vendor-agnostic
-* and the auth story per-plugin explicit.
-*
-* `importer` is injectable so tests don't need real network or
-* sibling packages installed.
-*/
-var LoaderError = class extends Error {
-	name = "LoaderError";
-};
-var PluginLoader = class {
-	config;
-	context;
-	importer;
-	registry = /* @__PURE__ */ new Map();
-	failures = [];
-	constructor(config, context, importer = defaultImporter) {
-		this.config = config;
-		this.context = context;
-		this.importer = importer;
-	}
-	/**
-	* Imports every configured plugin and builds the capability registry.
-	*
-	* Never throws for a single plugin's failure — a missing vendor token,
-	* an uninstalled package, or an unimplemented capability records a
-	* {@link PluginLoadFailure} and the load continues. This is the
-	* "soft-skip over hard-fail" contract: a command that needs a
-	* capability learns it is absent via `has()` / `get()` (which
-	* re-surfaces the original error), and orchestrators report the skip
-	* in their summary. Inspect {@link loadFailures} for the full list.
-	*/
-	async load() {
-		const entries = Object.entries(this.config.providers);
-		for (const [key, entry] of entries) {
-			if (!entry) continue;
-			if (entry.cardinality === "single") try {
-				this.registry.set(key, await this.loadOne(key, entry.tuple));
-			} catch (err) {
-				this.recordFailure(key, entry.tuple, err);
-			}
-			else {
-				const impls = [];
-				for (const tuple of entry.tuples) try {
-					impls.push(await this.loadOne(key, tuple));
-				} catch (err) {
-					this.recordFailure(key, tuple, err);
-				}
-				if (impls.length > 0) this.registry.set(key, impls);
-			}
-		}
-	}
-	recordFailure(key, tuple, err) {
-		this.failures.push({
-			key,
-			provider: tuple.provider,
-			packageName: tuple.packageName,
-			error: err instanceof Error ? err : new Error(String(err))
-		});
-	}
-	/** Providers that failed to load during {@link load}. Empty on a clean load. */
-	loadFailures() {
-		return this.failures;
-	}
-	/**
-	* Type-safe lookup. Single-cardinality keys return one impl;
-	* many-cardinality keys return an array. `ResolvedCapability<K>`
-	* encodes the split via the `CARDINALITY` map.
-	*/
-	get(key) {
-		const impl = this.registry.get(key);
-		if (impl === void 0) {
-			const failure = this.failures.find((f) => f.key === key);
-			if (failure) throw failure.error;
-			throw new LoaderError(`capability \`${key}\` is not loaded — is it declared in holocron.config.json?`);
-		}
-		return impl;
-	}
-	/** Whether a capability has been loaded. */
-	has(key) {
-		return this.registry.has(key);
-	}
-	/** All capability keys currently loaded. Useful for the doctor command. */
-	loadedKeys() {
-		return Array.from(this.registry.keys());
-	}
-	/** Internal — invoke a plugin's capability factory and return the impl. */
-	async loadOne(key, tuple) {
-		const mod = await this.importer(tuple.packageName).catch((err) => {
-			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
-		});
-		if (isPluginModule(mod)) {
-			const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
-			const factory = mod.createPlugin({
-				...this.projectDefaults(),
-				...this.context,
-				...effectiveToken !== void 0 ? { cliToken: effectiveToken } : {},
-				cliTokens: void 0,
-				...tuple.options
-			}).capabilities[key];
-			if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
-			return factory();
-		}
-		if (isCapabilityConfigModule(mod)) {
-			const cap = mod.default;
-			return this.loadOne(key, {
-				provider: cap.provider,
-				packageName: resolvePluginPackage(cap.provider),
-				options: {
-					...cap.options,
-					...tuple.options
-				}
-			});
-		}
-		throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\` or a capability config ({ provider, options? })`);
-	}
-	/**
-	* Project-level defaults that get merged into every plugin's options
-	* unless overridden by the CLI context or per-plugin tuple options.
-	* See `docs/wiki/specifications/tech-setup-and-config.spec.md` §Design.
-	*/
-	projectDefaults() {
-		const defaults = {};
-		if (this.config.repo?.name) defaults.repo = this.config.repo.name;
-		return defaults;
-	}
-};
-/** Default importer — resolves from cwd first so the global CLI finds project plugins. */
-const defaultImporter = async (pkg) => {
-	try {
-		return import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
-	} catch {
-		return import(pkg);
-	}
-};
-function isPluginModule(mod) {
-	return typeof mod.createPlugin === "function";
-}
-function isCapabilityConfigModule(mod) {
-	return typeof mod.default?.provider === "string";
-}
-//#endregion
 //#region src/commands/cleanup-preview.ts
 function prStateLabel(pr) {
 	if (pr.merged) return style.success("merged");
@@ -853,6 +936,7 @@ async function runCleanupPreview(input) {
 	// c8 ignore next -- real PluginLoader construction is integration-level; unit tests always supply loader
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await loader.load();
+	assertPluginsResolvable(loader, "cleanup-preview");
 	logger.info({
 		pr: input.prNumber,
 		project: input.project
@@ -1101,12 +1185,59 @@ async function runClone(input) {
 	};
 }
 //#endregion
+//#region src/commands/contexts.ts
+/**
+* Command → context. Keys are the command name as it lands in yargs'
+* `argv._` — the full path for sub-commands (`"auth set"`, `"upgrade
+* node"`), the bare verb otherwise.
+*
+* - **`global`** — needs nothing but the CLI binary. Works anywhere.
+* - **`repo-aware`** — reads `./holocron.config` + `./package.json`
+*   relative to cwd, but never touches the plugin loader.
+* - **`workspace`** — needs the configured providers' plugin packages to
+*   resolve (devDeps in a repo, or `pnpm exec`).
+*/
+const COMMAND_CONTEXTS = {
+	version: "global",
+	clone: "global",
+	new: "global",
+	"upgrade node": "global",
+	"upgrade deps": "global",
+	"plugin create": "global",
+	"auth set": "global",
+	"auth unset": "global",
+	"auth list": "global",
+	"auth check": "global",
+	"bump-versions": "global",
+	publish: "global",
+	"skills install": "global",
+	"skills remove": "global",
+	"skills update": "global",
+	run: "repo-aware",
+	ci: "repo-aware",
+	"config show": "repo-aware",
+	"sync-readme": "repo-aware",
+	doctor: "workspace",
+	setup: "workspace",
+	"secret set": "workspace",
+	"secrets sync": "workspace",
+	deploy: "workspace",
+	"cleanup-preview": "workspace",
+	sync: "workspace",
+	"sync-github": "workspace"
+};
+/** Command names in a given context, in registration order. */
+function commandsInContext(context) {
+	return Object.entries(COMMAND_CONTEXTS).filter(([, c]) => c === context).map(([name]) => name);
+}
+//#endregion
 //#region src/commands/deploy.ts
 async function runDeploy(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await loader.load();
+	assertPluginsResolvable(loader, "deploy");
 	const dryRun = input.context.dryRun ?? false;
 	logger.info({
 		branch: input.branch,
@@ -1162,6 +1293,7 @@ async function runDoctor(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await withSpinner("Loading plugins…", () => loader.load());
+	assertPluginsResolvable(loader, "doctor");
 	const rows = [];
 	const config = input.loaded.resolved;
 	print(style.header(`Holocron doctor — ${config.name}`));
@@ -1712,226 +1844,55 @@ async function runNpmBumpVersions(input) {
 	let entries;
 	try {
 		entries = listDir(packagesDir);
-	} catch {
-		const status = dryRun ? "dry-run" : "ok";
-		logger.info({
-			version,
-			status,
-			bumped: bumped.length,
-			skipped: skipped.length
-		}, "npm bump-versions: done");
-		return {
-			status,
-			bumped,
-			skipped
-		};
-	}
-	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}`);
-	}
-	const status = dryRun ? "dry-run" : "ok";
-	logger.info({
-		version,
-		status,
-		bumped: bumped.length,
-		skipped: skipped.length
-	}, "npm bump-versions: done");
-	return {
-		status,
-		bumped,
-		skipped
-	};
-}
-//#endregion
-//#region src/commands/npm-publish-initial.ts
-/**
-* `holocron npm publish-initial` — bottles up the chicken-and-egg
-* bootstrap that every new npm-published holocron monorepo hits.
-*
-* npm requires a package to exist before Trusted Publishing can be
-* configured on it. So the first publish has to happen outside the
-* OIDC flow — using either a browser-auth session (`npm login
-* --auth-type=web`) or an ephemeral automation token. This command
-* runs the publish step + tells you exactly what to do next.
-*
-* Workflow:
-*
-*   $ npm login --auth-type=web          # one-time, browser-based
-*   $ pnpm install --frozen-lockfile
-*   $ pnpm build
-*   $ pnpm exec tsx packages/cli/src/cli.ts npm publish-initial
-*
-* The command itself only handles the publish step + the post-publish
-* Trusted Publisher setup reminder. `pnpm install` + `pnpm build`
-* stay outside the command (no pnpm-inside-pnpm).
-*
-* If `NPM_TOKEN` is detected in env, the command prints a final
-* "revoke this token at <url>" reminder — same pattern as `rando vc
-* setup` for the ephemeral GH admin PAT.
-*/
-async function runNpmPublishInitial(input = {}) {
-	const print = input.print ?? ((line) => console.log(line));
-	const logger = input.logger ?? getLogger();
-	const cwd = input.cwd ?? process.cwd();
-	const tag = input.tag ?? "alpha";
-	const dryRun = input.dryRun ?? false;
-	const otp = input.otp;
-	const env = makeEnv(input.env);
-	const exec = input.exec ?? defaultExec$2;
-	const publishArgs = [
-		"-r",
-		"--filter=./packages/*",
-		"publish",
-		"--access",
-		"public",
-		"--no-git-checks",
-		"--tag",
-		tag,
-		...otp ? ["--otp", otp] : []
-	];
-	print(`Holocron npm publish-initial${dryRun ? " (dry-run)" : ""}`);
-	print(`  cwd: ${cwd}`);
-	print(`  tag: ${tag}`);
-	logger.info({
-		tag,
-		dryRun: dryRun || void 0
-	}, "npm publish-initial: start");
-	if (otp) print(`  otp: <${otp.length} chars>`);
-	print("");
-	print("  → verifying npm auth (`npm whoami`)…");
-	const whoami = await exec("npm", ["whoami"], { cwd });
-	if (whoami.exitCode !== 0) {
-		const message = "npm is not authenticated. Run `npm login --auth-type=web` (browser flow, no token stored) or `npm login`, then re-run this command.";
-		print(`  ✗ ${message}`);
-		const packageNames = input.packages ?? discoverPublicPackages(cwd);
-		logger.warn({ reason: "npm not authenticated" }, "npm publish-initial: done");
-		return {
-			status: "fail",
-			message,
-			packageNames
-		};
-	}
-	print(`    ✓ authed as ${whoami.stdout.trim() || "<unknown>"}`);
-	const packageNames = input.packages ?? discoverPublicPackages(cwd);
-	const repoName = input.repoName ?? await resolveRepoName(cwd, exec);
-	if (dryRun) {
-		print("");
-		print("  … (dry-run) skipping actual publish");
-		print(`    would run: pnpm ${publishArgs.join(" ")}`);
-		printNextSteps$1(print, env, packageNames, repoName);
-		logger.info({
-			tag,
-			status: "dry-run",
-			packages: packageNames.length
-		}, "npm publish-initial: done");
-		return {
-			status: "dry-run",
-			message: "dry-run — no publish executed",
-			packageNames
-		};
-	}
-	print("");
-	print("  → publishing all public @theholocron/* packages…");
-	const publish = await exec("pnpm", publishArgs, { cwd });
-	if (publish.exitCode !== 0) {
-		const message = `publish failed (exit ${publish.exitCode}): ${publish.stderr.trim() || publish.stdout.trim() || "no output"}`;
-		print(`  ✗ ${message}`);
-		if (publish.stdout.includes("EOTP") || publish.stderr.includes("EOTP")) {
-			print("");
-			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
-			print(`    pnpm exec tsx packages/cli/src/cli.ts npm publish-initial --otp <6-digit-code>`);
-		}
-		logger.warn({
-			tag,
-			reason: message
-		}, "npm publish-initial: done");
+	} catch {
+		const status = dryRun ? "dry-run" : "ok";
+		logger.info({
+			version,
+			status,
+			bumped: bumped.length,
+			skipped: skipped.length
+		}, "npm bump-versions: done");
 		return {
-			status: "fail",
-			message,
-			packageNames
+			status,
+			bumped,
+			skipped
 		};
 	}
-	print("    ✓ publish complete");
-	printNextSteps$1(print, env, packageNames, repoName);
-	logger.info({
-		tag,
-		status: "ok",
-		packages: packageNames.length
-	}, "npm publish-initial: done");
-	return {
-		status: "ok",
-		packageNames
-	};
-}
-function discoverPublicPackages(cwd) {
-	const packagesDir = join(cwd, "packages");
-	if (!existsSync(packagesDir)) return [];
-	return readdirSync(packagesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
-		const pkgPath = join(packagesDir, e.name, "package.json");
-		if (!existsSync(pkgPath)) return [];
+	for (const entry of entries) {
+		const pkgDir = join(packagesDir, entry);
 		try {
-			const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-			return !pkg.private && pkg.name ? [pkg.name] : [];
+			if (!isDir(pkgDir)) continue;
 		} catch {
-			return [];
+			continue;
 		}
-	});
-}
-async function resolveRepoName(cwd, exec) {
-	const result = await exec("git", [
-		"remote",
-		"get-url",
-		"origin"
-	], { cwd });
-	if (result.exitCode !== 0) return "unknown";
-	return /[/:]([^/:]+?)(?:\.git)?$/.exec(result.stdout.trim())?.[1] ?? "unknown";
-}
-function printNextSteps$1(print, env, packageNames, repoName) {
-	print("");
-	print("  → next: configure Trusted Publisher for each package on npm:");
-	for (const name of packageNames) print(`    https://www.npmjs.com/package/${name}/access`);
-	print(`    Publisher: GitHub Actions   Org: theholocron   Repo: ${repoName}   Workflow: release.yml`);
-	if (env.get("NPM_TOKEN")) {
-		print("");
-		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
-		print("    https://www.npmjs.com/settings/~/tokens");
+		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}`);
 	}
-}
-const defaultExec$2 = async (cmd, args, opts) => {
-	const result = spawnSync(cmd, args, {
-		cwd: opts.cwd,
-		encoding: "utf8",
-		stdio: [
-			"inherit",
-			"pipe",
-			"pipe"
-		]
-	});
+	const status = dryRun ? "dry-run" : "ok";
+	logger.info({
+		version,
+		status,
+		bumped: bumped.length,
+		skipped: skipped.length
+	}, "npm bump-versions: done");
 	return {
-		exitCode: result.status ?? -1,
-		stdout: result.stdout ?? "",
-		stderr: result.stderr ?? ""
+		status,
+		bumped,
+		skipped
 	};
-};
+}
 //#endregion
 //#region src/commands/plugin-create/template-inputs.ts
 /** Derive the standard defaults from a slug + vendor name. */
@@ -2905,7 +2866,7 @@ function runPluginCreate(input) {
 		filesWritten.push(resolvedPath);
 	}
 	if (!input.dryRun && !input.noVerify) {
-		const execFn = input.exec ?? defaultExec$1;
+		const execFn = input.exec ?? defaultExec$2;
 		const pkg = `@theholocron/holocron-plugin-${inputs.slug}`;
 		print("");
 		print("  Verifying scaffold…");
@@ -2956,7 +2917,7 @@ function runPluginCreate(input) {
 			};
 		}
 	}
-	if (!input.dryRun) printNextSteps(print, inputs);
+	if (!input.dryRun) printNextSteps$1(print, inputs);
 	logger.info({
 		slug: inputs.slug,
 		capability: inputs.capability,
@@ -3005,13 +2966,13 @@ function defaultWrite(filepath, content) {
 	mkdirSync(path.dirname(filepath), { recursive: true });
 	writeFileSync(filepath, content, "utf8");
 }
-function defaultExec$1(cmd, args, opts) {
+function defaultExec$2(cmd, args, opts) {
 	execFileSync(cmd, args, {
 		cwd: opts.cwd,
 		stdio: opts.stdio
 	});
 }
-function printNextSteps(print, inputs) {
+function printNextSteps$1(print, inputs) {
 	print("");
 	print(`  Scaffolded @theholocron/holocron-plugin-${inputs.slug} (18 files).`);
 	print("");
@@ -3025,12 +2986,242 @@ function printNextSteps(print, inputs) {
 	print("    7. Commit + push when capability is functionally complete.");
 }
 //#endregion
+//#region src/commands/publish.ts
+/**
+* `holocron publish --initial` — bottles up the chicken-and-egg bootstrap
+* that every new npm-published holocron monorepo hits.
+*
+* npm requires a package to exist before Trusted Publishing can be
+* configured on it. So the first publish has to happen outside the OIDC
+* flow — a browser-auth session (`npm login --auth-type=web`) or an
+* ephemeral automation token. This command drives the login step itself
+* (when `npm whoami` shows you're not authenticated), runs the publish
+* step, and tells you exactly what to do next.
+*
+* Workflow:
+*
+*   $ pnpm install --frozen-lockfile
+*   $ pnpm build
+*   $ pnpm exec tsx packages/cli/src/cli.ts publish --initial
+*
+* `npm login --auth-type=web` runs automatically the first time — no
+* separate manual step. `pnpm install` + `pnpm build` stay outside the
+* command (no pnpm-inside-pnpm).
+*
+* `--initial` is required today — this command only implements the
+* bootstrap publish. A non-initial `holocron publish` (for a manual publish
+* outside the semantic-release/OIDC steady state) isn't built yet; the flag
+* exists so the surface doesn't need another rename when it is.
+*
+* If `NPM_TOKEN` is detected in env, the command prints a final
+* "revoke this token at <url>" reminder — same pattern as `rando vc
+* setup` for the ephemeral GH admin PAT.
+*/
+async function runPublish(input = {}) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const cwd = input.cwd ?? process.cwd();
+	const tag = input.tag ?? "alpha";
+	const dryRun = input.dryRun ?? false;
+	const otp = input.otp;
+	const env = makeEnv(input.env);
+	const exec = input.exec ?? defaultExec$1;
+	const login = input.login ?? defaultLogin;
+	const publishArgs = [
+		...hasPackagesDir(cwd) ? ["-r", "--filter=./packages/*"] : [],
+		"publish",
+		"--access",
+		"public",
+		"--no-git-checks",
+		"--tag",
+		tag,
+		...otp ? ["--otp", otp] : []
+	];
+	print(`Holocron publish --initial${dryRun ? " (dry-run)" : ""}`);
+	print(`  cwd: ${cwd}`);
+	print(`  tag: ${tag}`);
+	logger.info({
+		tag,
+		dryRun: dryRun || void 0
+	}, "publish --initial: start");
+	if (otp) print(`  otp: <${otp.length} chars>`);
+	print("");
+	print("  → verifying npm auth (`npm whoami`)…");
+	let whoami = await exec("npm", ["whoami"], { cwd });
+	if (whoami.exitCode !== 0) {
+		print("    not authenticated — running `npm login --auth-type=web`…");
+		logger.info({}, "publish --initial: npm login");
+		if ((await login(cwd)).exitCode !== 0) {
+			const message = "npm login failed. Run `npm login --auth-type=web` (or `npm login`) manually, then re-run.";
+			print(`  ✗ ${message}`);
+			const packageNames = input.packages ?? discoverPublicPackages(cwd);
+			logger.warn({ reason: "npm login failed" }, "publish --initial: done");
+			return {
+				status: "fail",
+				message,
+				packageNames
+			};
+		}
+		whoami = await exec("npm", ["whoami"], { cwd });
+		if (whoami.exitCode !== 0) {
+			const message = "npm login completed but `npm whoami` still fails — check your npm account.";
+			print(`  ✗ ${message}`);
+			const packageNames = input.packages ?? discoverPublicPackages(cwd);
+			logger.warn({ reason: "npm whoami still fails after login" }, "publish --initial: done");
+			return {
+				status: "fail",
+				message,
+				packageNames
+			};
+		}
+	}
+	print(`    ✓ authed as ${whoami.stdout.trim() || "<unknown>"}`);
+	const packageNames = input.packages ?? discoverPublicPackages(cwd);
+	const repoName = input.repoName ?? await resolveRepoName(cwd, exec);
+	if (packageNames.length === 0) {
+		const message = "nothing to publish (no packages/* and root package.json is private or unnamed)";
+		print(`  ✗ ${message}`);
+		logger.warn({ reason: message }, "publish --initial: done");
+		return {
+			status: "fail",
+			message,
+			packageNames
+		};
+	}
+	if (dryRun) {
+		print("");
+		print("  … (dry-run) skipping actual publish");
+		print(`    would run: pnpm ${publishArgs.join(" ")}`);
+		printNextSteps(print, env, packageNames, repoName);
+		logger.info({
+			tag,
+			status: "dry-run",
+			packages: packageNames.length
+		}, "publish --initial: done");
+		return {
+			status: "dry-run",
+			message: "dry-run — no publish executed",
+			packageNames
+		};
+	}
+	print("");
+	print("  → publishing all public @theholocron/* packages…");
+	const publish = await exec("pnpm", publishArgs, { cwd });
+	if (publish.exitCode !== 0) {
+		const message = `publish failed (exit ${publish.exitCode}): ${publish.stderr.trim() || publish.stdout.trim() || "no output"}`;
+		print(`  ✗ ${message}`);
+		if (publish.stdout.includes("EOTP") || publish.stderr.includes("EOTP")) {
+			print("");
+			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
+			print(`    pnpm exec tsx packages/cli/src/cli.ts publish --initial --otp <6-digit-code>`);
+		}
+		logger.warn({
+			tag,
+			reason: message
+		}, "publish --initial: done");
+		return {
+			status: "fail",
+			message,
+			packageNames
+		};
+	}
+	print("    ✓ publish complete");
+	printNextSteps(print, env, packageNames, repoName);
+	logger.info({
+		tag,
+		status: "ok",
+		packages: packageNames.length
+	}, "publish --initial: done");
+	return {
+		status: "ok",
+		packageNames
+	};
+}
+function hasPackagesDir(cwd) {
+	return existsSync(join(cwd, "packages"));
+}
+/** Read a `package.json`'s `name`, when it's public (`!private && name`). */
+function publicPackageName(pkgPath) {
+	if (!existsSync(pkgPath)) return void 0;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		return !pkg.private && pkg.name ? pkg.name : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Monorepo (`packages/` present): every public `packages/*` workspace.
+* Single package (no `packages/`): the root `package.json`, if it's public —
+* most `node-template` scaffolds are one package at the repo root.
+*/
+function discoverPublicPackages(cwd) {
+	if (!hasPackagesDir(cwd)) {
+		const name = publicPackageName(join(cwd, "package.json"));
+		return name ? [name] : [];
+	}
+	const packagesDir = join(cwd, "packages");
+	return readdirSync(packagesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
+		const name = publicPackageName(join(packagesDir, e.name, "package.json"));
+		return name ? [name] : [];
+	});
+}
+async function resolveRepoName(cwd, exec) {
+	const result = await exec("git", [
+		"remote",
+		"get-url",
+		"origin"
+	], { cwd });
+	if (result.exitCode !== 0) return "unknown";
+	return /[/:]([^/:]+?)(?:\.git)?$/.exec(result.stdout.trim())?.[1] ?? "unknown";
+}
+function printNextSteps(print, env, packageNames, repoName) {
+	print("");
+	print("  → next: configure Trusted Publisher for each package on npm:");
+	for (const name of packageNames) print(`    https://www.npmjs.com/package/${name}/access`);
+	print(`    Publisher: GitHub Actions   Org: theholocron   Repo: ${repoName}   Workflow: release.yml`);
+	if (env.get("NPM_TOKEN")) {
+		print("");
+		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
+		print("    https://www.npmjs.com/settings/~/tokens");
+	}
+}
+const defaultExec$1 = async (cmd, args, opts) => {
+	const result = spawnSync(cmd, args, {
+		cwd: opts.cwd,
+		encoding: "utf8",
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		]
+	});
+	return {
+		exitCode: result.status ?? -1,
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? ""
+	};
+};
+/**
+* Fully interactive — `npm login --auth-type=web` prints a URL and waits for
+* the browser flow to complete; the operator needs to see that live, so all
+* three stdio streams are inherited (unlike `defaultExec`, which pipes
+* stdout/stderr for capture).
+*/
+const defaultLogin = async (cwd) => {
+	return { exitCode: spawnSync("npm", ["login", "--auth-type=web"], {
+		cwd,
+		stdio: "inherit"
+	}).status ?? -1 };
+};
+//#endregion
 //#region src/commands/secret-set.ts
 async function runSecretSet(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await loader.load();
+	assertPluginsResolvable(loader, "secret set");
 	const dryRun = input.context.dryRun ?? false;
 	const scope = input.scope ?? { kind: "repo" };
 	if (!loader.has("secrets")) throw new Error("`secrets` capability is not configured — add a `secrets` provider to holocron.config.json");
@@ -3104,6 +3295,7 @@ async function runSecretsSync(input) {
 	const logger = input.logger ?? getLogger();
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await withSpinner("Loading plugins…", () => loader.load());
+	assertPluginsResolvable(loader, "secrets sync");
 	logger.info({
 		environment: input.environmentId,
 		dryRun: (input.context.dryRun ?? false) || void 0
@@ -4373,6 +4565,7 @@ async function runSetup(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await withSpinner("Loading plugins…", () => loader.load());
+	assertPluginsResolvable(loader, "setup");
 	const config = input.loaded.resolved;
 	const dryRun = input.context.dryRun ?? false;
 	const steps = [];
@@ -6886,6 +7079,11 @@ const resolveSyncToken = createFeatureResolver({
 	envName: "HOLOCRON_SYNC_TOKEN",
 	keyringKey: "github.sync"
 });
+/**
+* Error class names whose `.message` is a complete, actionable sentence —
+* the top-level catch prints it and suppresses the stack trace.
+*/
+const USER_FACING_ERRORS = /* @__PURE__ */ new Set(["WorkspaceContextError", "ConfigFileError"]);
 const { version: CLI_VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 /** Whether to print the correlation id at command end (`--debug` / `--verbose`). */
 let printRunId = false;
@@ -6938,6 +7136,8 @@ function tokenContext(rawTokens) {
 init(CLI_VERSION);
 const updateCheckPromise = checkForUpdates(CLI_VERSION);
 let finishCommand = () => {};
+/** Set by `.fail()` once it has printed an error, so the outer catch doesn't repeat it. */
+let errorReported = false;
 try {
 	await yargs(hideBin(process.argv)).scriptName("").usage("holocron <command> [options]").parserConfiguration({ "populate--": true }).option("dry-run", {
 		type: "boolean",
@@ -7195,7 +7395,7 @@ try {
 			project: argv.project,
 			...argv.repo ? { repo: argv.repo } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).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", {
+	}).command("bump-versions <new-version>", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (y) => y.positional("new-version", {
 		type: "string",
 		demandOption: true,
 		describe: "Version to set (e.g., 4.2.0 or 2.0.0-alpha.1)"
@@ -7205,7 +7405,11 @@ try {
 			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", {
+	}).command("publish", "Publish @theholocron/* packages to npm", (y) => y.option("initial", {
+		type: "boolean",
+		default: false,
+		describe: "One-shot bootstrap publish for trusted-publishing-eligible packages (npm needs the package to exist before Trusted Publishing can be configured for it). Required today — a non-initial `publish` isn't implemented yet."
+	}).option("tag", {
 		type: "string",
 		default: "alpha",
 		describe: "npm distribution tag (defaults to alpha)"
@@ -7213,13 +7417,18 @@ try {
 		type: "string",
 		describe: "One-time password from your authenticator (required if npm needs 2FA for writes)"
 	}), async (argv) => {
-		if ((await runNpmPublishInitial({
+		if (!argv.initial) {
+			getLogger().error("publish: only `--initial` is supported today. Run `holocron publish --initial`.");
+			process.exitCode = 1;
+			return;
+		}
+		if ((await runPublish({
 			cwd: argv.cwd,
 			tag: argv.tag,
 			dryRun: argv.dryRun,
 			...argv.otp ? { otp: argv.otp } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).demandCommand(1, "Run `holocron npm --help` to see available npm subcommands."), () => {}).command("sync [steps..]", "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)", (y) => y.positional("steps", {
+	}).command("sync [steps..]", "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)", (y) => y.positional("steps", {
 		type: "string",
 		array: true,
 		describe: "Steps to run: labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki (default: all)"
@@ -7739,9 +7948,23 @@ try {
 		})).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();
+	}).demandCommand(1, "Run `holocron auth --help` to see available auth subcommands."), () => {}).demandCommand(1, "Run `holocron --help` to see available commands.").strict().help().epilogue(`Execution contexts:
+  global      works from a bare 'npm i -g': ${commandsInContext("global").join(", ")}\n  repo-aware  needs ./holocron.config in cwd: ${commandsInContext("repo-aware").join(", ")}\n  workspace   also needs the plugin packages: ${commandsInContext("workspace").join(", ")}\n  https://theholocron.github.io/holocron/execution-contexts`).fail((msg, err) => {
+		if (err instanceof Error && USER_FACING_ERRORS.has(err.name)) {
+			captureException(err);
+			getLogger().error(err.message);
+			errorReported = true;
+			process.exitCode = 1;
+			return;
+		}
+		if (err) throw err;
+		getLogger().error(msg);
+		errorReported = true;
+		process.exitCode = 1;
+	}).parse();
 } catch (err) {
 	captureException(err);
+	if (!errorReported && err instanceof Error && USER_FACING_ERRORS.has(err.name)) getLogger().error(err.message);
 	if (!process.exitCode) process.exitCode = 1;
 }
 finishCommand(!process.exitCode);