@theholocron/cli 4.16.5 → 4.17.0

package/README.md

@@ -14,6 +14,22 @@ holocron --help
 
 ```
 
+## Execution contexts
+
+Every command is tagged with how much of a repo it needs:
+
+| Context      | Needs                                                    | Examples                                                                                     |
+| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `global`     | just the CLI binary                                      | `version`, `clone`, `new`, `upgrade node`, `auth set` / `check`, `plugin create`, `skills …` |
+| `repo-aware` | `./holocron.config` in cwd, no plugins                   | `run`, `ci`, `config show`, `sync-readme`                                                    |
+| `workspace`  | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `setup`, `sync`, `secrets sync`, `deploy`                                          |
+
+A `workspace` command run from a bare global install (no plugins next to the
+CLI) fails with one actionable line — install the plugins as devDependencies or
+use `pnpm exec holocron <cmd>`. `auth check` degrades to "token present,
+verification skipped" instead. `holocron --help` prints the grouping; see
+[Execution Contexts](https://theholocron.github.io/holocron/execution-contexts).
+
 ## Config file
 
 Holocron reads `holocron.config.{json,js,ts}` from the project root

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",
+	"npm bump-versions": "global",
+	"npm publish-initial": "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}`));
@@ -3031,6 +3163,7 @@ async function runSecretSet(input) {
 	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 +3237,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 +4507,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 +7021,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 +7078,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",
@@ -7739,9 +7881,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);