@theholocron/cli 5.0.0-alpha.121 → 5.0.0-alpha.123

package/dist/cli.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir, hostname, tmpdir, userInfo } from "node:os";
 import path, { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { checkbox, confirm, input, select } from "@inquirer/prompts";
 import { KNOWN_WORKFLOWS, createAstromech, deployOnRelease, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
 import { loadTasksConfig } from "@theholocron/astromech/config";
+import { LOG_LEVELS, NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { AuthError, ProviderApiError, ProviderApiError as ProviderApiError$1, createRestClient } from "@theholocron/http-client";
@@ -12,18 +14,16 @@ import { createEnvLookup } from "@theholocron/env-utils";
 import { Entry, findCredentials } from "@napi-rs/keyring";
 import { pathToFileURL } from "node:url";
 import { errorMessage } from "@theholocron/misc-utils";
-import { createLogger, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
-import ora from "ora";
+import { createLogger, isCI, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
 import chalk from "chalk";
+import ora from "ora";
 import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
-import { homedir, hostname, userInfo } from "node:os";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { generateReadme } from "@theholocron/components-doc/markdown";
 import { getClients, getConfigs, getDocs, getPlugins, getSkills, getThemes, getUtils } from "@theholocron/registry-doc";
 import { createGitHubClient } from "@theholocron/github-client";
 import { PostHogSink } from "@theholocron/observability/analytics";
-import { NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
 import { SentrySink } from "@theholocron/observability/errors";
 import load from "@commitlint/load";
 import lint from "@commitlint/lint";
@@ -303,23 +303,54 @@ function resolveConfig(raw) {
 	};
 }
 //#endregion
+//#region src/ui/style.ts
+const style = {
+	success: (msg) => `${chalk.green("✓")} ${msg}`,
+	warn: (msg) => `${chalk.yellow("⚠")} ${msg}`,
+	fail: (msg) => `${chalk.red("✗")} ${msg}`,
+	step: (msg) => `${chalk.cyan("→")} ${msg}`,
+	/** A dim `·` marker for a row that's neither a pass nor a failure — loaded but inactive, or skipped. */
+	skip: (msg) => chalk.dim(`· ${msg}`),
+	hint: (msg) => chalk.dim(msg),
+	dim: (msg) => chalk.dim(msg),
+	header: (msg) => chalk.bold(msg)
+};
+//#endregion
 //#region src/logger.ts
 /**
 * Resolve the explicit level to hand to `createLogger`, in priority order:
 *
-* 1. `--verbose` → `"debug"`   2. `--quiet` → `"error"`
-* 3. `HOLOCRON_LOG_LEVEL` env var
-* 4. `holocron.config` `log.level` (`configLevel`)
+* 1. `--log <level>`           2. `--verbose` → `"debug"`   3. `--quiet` → `"error"`
+* 4. `HOLOCRON_LOG_LEVEL` env var
+* 5. `holocron.config` `log.level` (`configLevel`)
 *
 * Returns `undefined` when nothing applies — `createLogger` then defaults
 * to `"info"`. Resolving the full chain here (rather than passing
 * `configLevel` straight through) keeps config below the env var.
 */
 function resolveLogLevel(argv, configLevel) {
+	if (argv.log) return argv.log;
 	if (argv.verbose) return "debug";
 	if (argv.quiet) return "error";
 	return parseLogLevel(env.get("HOLOCRON_LOG_LEVEL")) ?? configLevel;
 }
+/**
+* Resolve whether human-visible console output (pretty or NDJSON) should run
+* at all, independent of level — the `@theholocron/observability`
+* `consoleOutput` override.
+*
+* Local/interactive runs are quiet by default: any raw structured logger
+* output (colorized or not) stays off regardless of the resolved level,
+* unless the user explicitly asked to see it via `--log <level>`,
+* `--verbose`, or `--quiet`. CI is untouched either way — returning
+* `undefined` there preserves `createLogger`'s own `ci`/`tty`
+* auto-detection exactly, so CI's existing NDJSON-to-stdout behavior is
+* unaffected by this flag.
+*/
+function resolveConsoleOutput(argv) {
+	if (argv.log || argv.verbose || argv.quiet) return true;
+	return isCI() ? void 0 : false;
+}
 let root;
 let rootLevel;
 let rootCommand;
@@ -358,13 +389,15 @@ function buildCliLogger(argv, opts = {}) {
 	const { command, configLevel } = opts;
 	if (command) rootCommand = command;
 	const level = resolveLogLevel(argv, configLevel);
+	const consoleOutput = resolveConsoleOutput(argv);
 	const axiom = resolveCliAxiom(opts);
 	const axiomKey = axiom?.dataset;
-	const rebuildForConfig = configLevel !== void 0 && level !== rootLevel && !argv.verbose && !argv.quiet;
+	const rebuildForConfig = configLevel !== void 0 && level !== rootLevel && !argv.verbose && !argv.quiet && !argv.log;
 	if (!root || rebuildForConfig || axiomKey !== void 0 && axiomKey !== rootAxiomKey) {
 		const built = createLogger({
 			...level ? { level } : {},
-			...axiom ? { axiom } : {}
+			...axiom ? { axiom } : {},
+			...consoleOutput !== void 0 ? { consoleOutput } : {}
 		});
 		root = {
 			logger: rootCommand ? built.logger.child({ command: rootCommand }) : built.logger,
@@ -375,9 +408,35 @@ function buildCliLogger(argv, opts = {}) {
 	}
 	return root;
 }
-/** Lazily-memoized `Logger` for module-level call sites with no `argv` in scope. */
+/**
+* Lazily-memoized `Logger` for module-level call sites with no `argv` in
+* scope — notably yargs' own `.fail()` handler, which fires on a
+* pre-middleware validation failure (a missing required argument, an
+* unknown command) and therefore runs before `buildCliLogger` has ever
+* built the real root. Without an explicit `consoleOutput` here, that
+* fallback would use `createLogger`'s bare auto-detection (pretty on any
+* local TTY) and leak a structured block even though no flag asked for one
+* — so it resolves the same "quiet unless CI" default `buildCliLogger`
+* would, as if no flags were passed.
+*/
 function getLogger() {
-	return (root ??= createLogger()).logger;
+	return (root ??= createLogger({ consoleOutput: resolveConsoleOutput({}) })).logger;
+}
+/**
+* Report a fatal, command-ending CLI error: always printed to the console
+* (regardless of `consoleOutput` suppression) via `style.fail`, and also
+* sent through the structured logger for Axiom/telemetry visibility.
+*
+* Use this when a handler is returning or exiting right here with nothing
+* else for the user to see — a resolved `--token` failure, a yargs
+* validation failure, a thrown domain error. Don't use it for a per-step
+* warning inside a multi-step orchestrator that already prints its own
+* `ok / fail / skip` summary — that summary is the user-facing signal;
+* the per-step reason belongs in the structured log alone.
+*/
+function reportError(message, log = getLogger()) {
+	console.error(style.fail(message));
+	log.error(message);
 }
 /** The current root logger's correlation id, if a root has been built. */
 function getRunId() {
@@ -637,17 +696,6 @@ async function withSpinner(label, fn) {
 	}
 }
 //#endregion
-//#region src/ui/style.ts
-const style = {
-	success: (msg) => `${chalk.green("✓")} ${msg}`,
-	warn: (msg) => `${chalk.yellow("⚠")} ${msg}`,
-	fail: (msg) => `${chalk.red("✗")} ${msg}`,
-	step: (msg) => `${chalk.cyan("→")} ${msg}`,
-	hint: (msg) => chalk.dim(msg),
-	dim: (msg) => chalk.dim(msg),
-	header: (msg) => chalk.bold(msg)
-};
-//#endregion
 //#region src/commands/auth.ts
 /**
 * `holocron auth <subcommand>` — manage bootstrap credentials in the
@@ -1071,6 +1119,27 @@ async function runCleanupPreview(input) {
 	}
 }
 //#endregion
+//#region src/ui/status-row.ts
+/** Right-pads `s` to `width` with spaces — never truncates. */
+function pad(s, width) {
+	return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+/**
+* One row of a status report: a 2-space indent, the status icon (✓ / ✗ / ·),
+* then `columns` joined with a two-space gap (blank columns dropped, so a
+* row that has nothing for its last column doesn't trail whitespace).
+* Column padding (`pad`) is the caller's job — `doctor` pads capability and
+* provider to a fixed width; `clone`'s repo names and paths don't, since
+* they vary too widely for fixed-width alignment to read cleanly.
+*
+* Shared by `doctor` (capability / provider / message) and `clone` (repo /
+* destination / reason) so every status table in the CLI reads the same way.
+*/
+function statusRow(status, columns) {
+	const joined = columns.filter((c) => c.length > 0).join("  ");
+	return `  ${status === "ok" ? style.success(joined) : status === "fail" ? style.fail(joined) : style.skip(joined)}`;
+}
+//#endregion
 //#region src/commands/clone.ts
 /**
 * Accepts a bare org (`"theholocron"`) — clones every repo in it — or an
@@ -1132,7 +1201,6 @@ async function runClone(input) {
 	const fetchFn = input.fetch ?? globalThis.fetch;
 	const dryRun = input.dryRun ?? false;
 	const targetDir = resolve(input.dir ?? join(homedir(), "Code", input.org));
-	const label = input.repo ? `${input.org}/${input.repo}` : `org=${input.org}`;
 	logger.info({
 		org: input.org,
 		repo: input.repo,
@@ -1145,7 +1213,7 @@ async function runClone(input) {
 			stdio: "inherit"
 		}).status };
 	});
-	print(style.header(`Holocron clone — ${label} → ${targetDir}${dryRun ? " (dry-run)" : ""}`));
+	print("");
 	if (!existsSync(targetDir)) {
 		if (dryRun) print(style.dim(`  would create ${targetDir}`));
 		else mkdirSync(targetDir, { recursive: true });
@@ -1196,7 +1264,11 @@ async function runClone(input) {
 	for (const repo of repos) {
 		const dest = join(targetDir, repoDirName(repo));
 		if (existsSync(dest)) {
-			print(style.dim(`  skip   ${repo.full_name}`));
+			print(statusRow("skip", [
+				repo.full_name,
+				dest,
+				"already exists"
+			]));
 			skipped++;
 			continue;
 		}
@@ -1205,10 +1277,14 @@ async function runClone(input) {
 			cloned++;
 			continue;
 		}
-		print(style.step(`  clone  ${repo.full_name}`));
+		print(style.step(`  clone  ${repo.full_name} → ${dest}`));
 		const { clone_url } = repo;
 		if (!clone_url.startsWith("https://github.com/")) {
-			print(style.fail(`  failed ${repo.full_name} — unexpected clone URL: ${clone_url}`));
+			print(statusRow("fail", [
+				repo.full_name,
+				dest,
+				`unexpected clone URL: ${clone_url}`
+			]));
 			failed++;
 			continue;
 		}
@@ -1216,7 +1292,11 @@ async function runClone(input) {
 		try {
 			encodedToken = encodeTokenForGitHttpAuth(input.token);
 		} catch (err) {
-			print(style.fail(`  failed ${repo.full_name} — invalid token format: ${errorMessage(err)}`));
+			print(statusRow("fail", [
+				repo.full_name,
+				dest,
+				`invalid token format: ${errorMessage(err)}`
+			]));
 			failed++;
 			continue;
 		}
@@ -1226,15 +1306,16 @@ async function runClone(input) {
 			`https://x-access-token:${encodedToken}@github.com/${clone_url.slice(19)}`,
 			dest
 		], { cwd: targetDir }).status !== 0) {
-			print(style.fail(`  failed ${repo.full_name}`));
+			print(statusRow("fail", [repo.full_name, dest]));
 			failed++;
 		} else {
-			print(style.success(`  cloned ${repo.name}`));
+			print(statusRow("ok", [repo.full_name, dest]));
 			cloned++;
 		}
 	}
-	const summary = `${cloned} cloned, ${skipped} skipped, ${failed} failed`;
-	print(dryRun ? style.dim(`\n  dry-run: ${summary}`) : failed > 0 ? style.fail(`\n  ${summary}`) : style.success(`\n  ${summary}`));
+	const summary = `${cloned} cloned, ${failed} failed, ${skipped} skipped`;
+	print("");
+	print(dryRun ? style.dim(`  dry-run: ${summary}`) : failed > 0 ? style.fail(`  ${summary}`) : style.success(`  ${summary}`));
 	const status = dryRun ? "dry-run" : failed > 0 ? "fail" : "ok";
 	logger[failed > 0 ? "warn" : "info"]({
 		org: input.org,
@@ -1244,6 +1325,10 @@ async function runClone(input) {
 		skipped,
 		failed
 	}, "clone: done");
+	if (input.confirmOpen) {
+		const openTarget = input.repo ? join(targetDir, repoDirName(repos[0])) : targetDir;
+		if (existsSync(openTarget)) await input.confirmOpen(openTarget, dryRun && cloned > 0);
+	}
 	return {
 		status,
 		cloned,
@@ -1574,7 +1659,7 @@ async function runDoctor(input) {
 	assertPluginsResolvable(loader, "doctor");
 	const rows = [];
 	const config = input.loaded.resolved;
-	print(style.header(`Holocron doctor — ${config.name}`));
+	print("");
 	print(style.dim(`  config: ${input.loaded.filepath}`));
 	print("");
 	for (const failure of loader.loadFailures()) rows.push({
@@ -1609,10 +1694,7 @@ async function runDoctor(input) {
 			status: row.status,
 			detail: row.message
 		}, `doctor: ${row.capability}`);
-		const label = `${pad(row.capability, 14)} via ${pad(row.provider, 14)}  ${row.message}`;
-		if (row.status === "ok") print(`  ${style.success(label)}`);
-		else if (row.status === "fail") print(`  ${style.fail(label)}`);
-		else print(`  ${style.dim(`· ${label}`)}`);
+		print(statusRow(row.status, [`${pad(row.capability, 14)} via ${pad(row.provider, 14)}`, row.message]));
 	}
 	const summary = rows.reduce((acc, r) => {
 		acc[r.status] += 1;
@@ -1624,7 +1706,7 @@ async function runDoctor(input) {
 	});
 	const summaryLine = `${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped`;
 	print("");
-	print(summary.fail > 0 ? style.fail(summaryLine) : style.success(summaryLine));
+	print(style.header(summaryLine));
 	return {
 		rows,
 		summary
@@ -1678,9 +1760,6 @@ function mk(capability, provider, status, message) {
 		message
 	};
 }
-function pad(s, width) {
-	return s.length >= width ? s : s + " ".repeat(width - s.length);
-}
 //#endregion
 //#region src/commands/new.ts
 /**
@@ -8043,6 +8122,15 @@ function parseGitRemoteUrl(url) {
 * {@link promptForPositionals} for just that one command — no spawn needed,
 * the handler already has everything else it needs.
 *
+* For a command whose handler honours `--dry-run` ({@link
+* CommandEntry.supportsDryRun}), `launchMenu` always previews it first — a
+* dry run doesn't mutate anything, so there's nothing to ask permission
+* for — then, once that preview comes back clean and found something to
+* do, asks the one real decision: "proceed with the real run?". A preview
+* that finds nothing to do skips that question too. `--skip-dry-run` opts
+* a top-level invocation out of the preview entirely, straight to the
+* real run, for when you already know what you want.
+*
 * Every prompt is preceded by a `process.stdin.isTTY` check. A non-TTY run
 * (CI, a script, a pipe) throws {@link NonInteractiveError} instead of
 * hanging on `@inquirer/prompts` (which otherwise throws its own
@@ -8072,17 +8160,20 @@ const COMMAND_REGISTRY = [
 			message: "org/repo to clone (or a bare org to clone every repo in it):",
 			type: "input",
 			validate: (v) => v.trim().length > 0 || "org/repo or org is required"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "doctor",
 		description: "Load the config and run a smoke check against every provider",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "setup",
 		description: "Apply infra setup actions across every configured capability",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "secret set",
@@ -8091,7 +8182,8 @@ const COMMAND_REGISTRY = [
 			key: "name",
 			message: "Secret name:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "secrets sync",
@@ -8100,7 +8192,8 @@ const COMMAND_REGISTRY = [
 			key: "environmentId",
 			message: "Vault environment id:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "deploy",
@@ -8109,7 +8202,8 @@ const COMMAND_REGISTRY = [
 			key: "branch",
 			message: "Branch to deploy:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "cleanup-preview",
@@ -8119,7 +8213,8 @@ const COMMAND_REGISTRY = [
 			message: "PR number:",
 			type: "input",
 			validate: numeric
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "bump-versions",
@@ -8129,32 +8224,38 @@ const COMMAND_REGISTRY = [
 			cliArg: "new-version",
 			message: "New version:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "publish",
 		description: "Publish @theholocron/* packages to npm",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "sync",
 		description: "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "ci",
 		description: "Run the merge-gating checks locally, in CI order — 'will CI pass?'",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "sync-github",
 		description: "Sync workflow templates and composite actions to theholocron/.github",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "sync-readme",
 		description: "Sync the Installation + Usage block in README.md from package.json",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "config show",
@@ -8164,7 +8265,8 @@ const COMMAND_REGISTRY = [
 	{
 		name: "new",
 		description: "Scaffold a new repo from a GitHub template (e.g. cli, react, nextjs, node, monorepo, base)",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "plugin create",
@@ -8177,25 +8279,29 @@ const COMMAND_REGISTRY = [
 			key: "vendor",
 			message: "Vendor display name (PascalCase):",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "skills install",
 		description: "Copy skills from @theholocron/skills into .agents/ with agent symlinks",
 		positionals: [],
-		group: "skills"
+		group: "skills",
+		supportsDryRun: true
 	},
 	{
 		name: "skills remove",
 		description: "Remove installed skills via npx skills remove",
 		positionals: [],
-		group: "skills"
+		group: "skills",
+		supportsDryRun: true
 	},
 	{
 		name: "skills update",
 		description: "Update installed skills to their latest upstream versions via npx skills update",
 		positionals: [],
-		group: "skills"
+		group: "skills",
+		supportsDryRun: true
 	},
 	{
 		name: "upgrade node",
@@ -8206,13 +8312,15 @@ const COMMAND_REGISTRY = [
 			type: "input",
 			validate: numeric
 		}],
-		group: "upgrade"
+		group: "upgrade",
+		supportsDryRun: true
 	},
 	{
 		name: "upgrade deps",
 		description: "Bump every @theholocron/* pin to latest and migrate holocron.config.ts to the current preset API",
 		positionals: [],
-		group: "upgrade"
+		group: "upgrade",
+		supportsDryRun: true
 	},
 	{
 		name: "auth set",
@@ -8327,25 +8435,41 @@ async function promptForPositionals(entry, argv) {
 * menu-launched child should inherit from the parent invocation. Everything
 * else (command-specific options) was never captured by the top-level `$0`
 * handler in the first place, so there's nothing else to forward.
+*
+* `dryRunOverride`, when passed, wins over `argv.dryRun` — `launchMenu`'s
+* dry-run offer needs to force `--dry-run` on for the preview spawn and
+* force it back off for the real-run spawn that follows, regardless of
+* what was on the original invocation.
 */
-function forwardedFlags(argv) {
+function forwardedFlags(argv, dryRunOverride) {
 	const out = [];
 	const tokens = argv.token;
 	for (const t of tokens ?? []) out.push("--token", t);
 	if (typeof argv.org === "string") out.push("--org", argv.org);
 	if (typeof argv.cwd === "string") out.push("--cwd", argv.cwd);
-	if (argv.dryRun === true) out.push("--dry-run");
+	if (dryRunOverride ?? argv.dryRun === true) out.push("--dry-run");
 	return out;
 }
 /** `entry.name` split into tokens, resolved positionals appended, then forwarded flags. */
-function buildChildArgv(entry, positionals, parentArgv) {
+function buildChildArgv(entry, positionals, parentArgv, dryRunOverride) {
 	return [
 		...entry.name.split(" "),
 		...positionals,
-		...forwardedFlags(parentArgv)
+		...forwardedFlags(parentArgv, dryRunOverride)
 	];
 }
 /**
+* Set on a dry-run preview child's env ({@link spawnChild}'s `extraEnv`) so
+* its handler knows this specific `--dry-run` came from `launchMenu`'s own
+* preview-then-ask flow, not a direct `holocron <cmd> --dry-run` invocation.
+* A handler that supports it uses this — never bare `argv.dryRun` — to
+* decide whether to report {@link DRY_RUN_NOOP_EXIT_CODE}: that exit code
+* only has special meaning to `launchMenu` itself, so a direct/scripted
+* `--dry-run` call must never produce it — doing so unconditionally would
+* silently change the public exit-code contract for a successful dry run.
+*/
+const DRY_RUN_PREVIEW_ENV_VAR = "HOLOCRON_DRY_RUN_PREVIEW";
+/**
 * Spawn `holocron <...args>` inheriting stdio; resolve with its exit code.
 *
 * `NO_UPDATE_NOTIFIER` is forced on in the child's env — the parent's own
@@ -8353,15 +8477,17 @@ function buildChildArgv(entry, positionals, parentArgv) {
 * docstring), so without this the freshly-spawned child independently runs
 * its own `checkForUpdates()` too and the notice prints twice: once from
 * the child right after its command output, once more from the parent
-* once the child exits.
+* once the child exits. `extraEnv` layers on top — used only for {@link
+* DRY_RUN_PREVIEW_ENV_VAR} on the dry-run preview spawn.
 */
-function spawnChild(args) {
+function spawnChild(args, extraEnv) {
 	return new Promise((resolve) => {
 		const child = spawn(process.execPath, [process.argv[1], ...args], {
 			stdio: "inherit",
 			env: {
 				...process.env,
-				NO_UPDATE_NOTIFIER: "1"
+				NO_UPDATE_NOTIFIER: "1",
+				...extraEnv
 			}
 		});
 		child.on("exit", (code) => resolve(code ?? 0));
@@ -8369,6 +8495,17 @@ function spawnChild(args) {
 	});
 }
 /**
+* Whether `launchMenu` should auto-preview a picked command before running
+* it for real — only when the command's handler actually honours
+* `--dry-run` ({@link CommandEntry.supportsDryRun}) and the top-level
+* invocation didn't pass `--skip-dry-run` to opt out of the preview
+* entirely (an escape hatch for "I already know what I want, skip
+* straight to the real run").
+*/
+function shouldPreviewDryRun(entry, parentArgv) {
+	return Boolean(entry.supportsDryRun) && parentArgv.skipDryRun !== true;
+}
+/**
 * Layers 1 and 2: pick a command from `entries`, prompt for its required
 * positionals, spawn it as a fresh `holocron` invocation, and set
 * `process.exitCode` from the child — the caller (a `$0` handler in
@@ -8377,12 +8514,79 @@ function spawnChild(args) {
 * `command_completed` event fires with command name "unknown" (the
 * middleware ran before any command was picked) — left as-is rather than
 * suppressed; it's a real, useful signal ("the menu got used").
+*
+* For a command that honours `--dry-run` ({@link CommandEntry.supportsDryRun})
+* and wasn't opted out via `--skip-dry-run` ({@link shouldPreviewDryRun}),
+* this always previews first — a dry run doesn't mutate anything, so
+* there's nothing to ask permission for. A preview that exits non-zero
+* stops here; one that reports {@link DRY_RUN_NOOP_EXIT_CODE} (nothing
+* would change) stops here too, skipping the follow-up question since the
+* real run would have nothing to do either. Otherwise it asks "proceed
+* with the real run?" before the real spawn — the one actual decision
+* left to make, since this one does mutate something.
 */
 async function launchMenu(entries, parentArgv, pickMessage, nonInteractiveMessage = "Run `holocron --help` to see available commands.") {
 	if (!process.stdin.isTTY) throw new NonInteractiveError(nonInteractiveMessage);
 	const picked = await pickCommand(entries, pickMessage);
-	const childArgv = buildChildArgv(picked, await promptForPositionals(picked, {}), parentArgv);
-	process.exitCode = await spawnChild(childArgv);
+	const positionals = await promptForPositionals(picked, {});
+	if (shouldPreviewDryRun(picked, parentArgv)) {
+		const dryExit = await spawnChild(buildChildArgv(picked, positionals, parentArgv, true), { [DRY_RUN_PREVIEW_ENV_VAR]: "1" });
+		if (dryExit === 2) {
+			process.exitCode = 0;
+			return;
+		}
+		if (dryExit !== 0) {
+			process.exitCode = dryExit;
+			return;
+		}
+		if (!await confirm({
+			message: "Dry run complete — proceed with the real run?",
+			default: false
+		})) {
+			process.exitCode = 0;
+			return;
+		}
+		process.exitCode = await spawnChild(buildChildArgv(picked, positionals, parentArgv, false));
+		return;
+	}
+	process.exitCode = await spawnChild(buildChildArgv(picked, positionals, parentArgv));
+}
+//#endregion
+//#region src/ui/open-path.ts
+/** Platform-appropriate command to open a path in the OS's file browser. */
+function openCommand(path) {
+	if (process.platform === "darwin") return {
+		cmd: "open",
+		args: [path]
+	};
+	if (process.platform === "win32") return {
+		cmd: "cmd",
+		args: [
+			"/c",
+			"start",
+			"",
+			path
+		]
+	};
+	return {
+		cmd: "xdg-open",
+		args: [path]
+	};
+}
+/**
+* Open `path` in the OS's default file browser (Finder / Explorer /
+* whatever `xdg-open` resolves to on Linux). Fire-and-forget — detached so
+* it outlives this process, and never throws when the opener binary isn't
+* on PATH (e.g. no `xdg-open` in a minimal container).
+*/
+function openPath(path) {
+	const { cmd, args } = openCommand(path);
+	const child = spawn(cmd, args, {
+		stdio: "ignore",
+		detached: true
+	});
+	child.on("error", () => {});
+	child.unref();
 }
 //#endregion
 //#region src/update-notifier.ts
@@ -8528,6 +8732,19 @@ function resolveOrg(argv, config) {
 	return argv.org ?? env.get("HOLOCRON_ORG") ?? config.org;
 }
 /**
+* Print the dim version line once per terminal session — keyed by the
+* parent shell's PID, since that's stable across repeated bare `holocron`
+* invocations in the same shell but changes in a new tab/window. A marker
+* file in the OS tmpdir tracks whether this shell has already seen it, so
+* re-running `holocron` doesn't repeat the line every time.
+*/
+function printVersionHeaderOnce() {
+	const marker = join(tmpdir(), `.holocron-version-shown-${process.ppid}`);
+	if (existsSync(marker)) return;
+	console.log(style.dim(`v${CLI_VERSION}`));
+	writeFileSync(marker, "");
+}
+/**
 * `buildCliLogger` options derived from a loaded `holocron.config` — the
 * level, the Axiom dataset, and the resolved org for a keyring-backed
 * Axiom token. Used by every handler that has already called `loadConfig`.
@@ -8557,7 +8774,7 @@ function tokenContext(rawTokens) {
 		return parseTokenArgs(rawTokens);
 	} catch (err) {
 		if (err instanceof TokenParseError) {
-			getLogger().error(`--token: ${err.message}`);
+			reportError(`--token: ${err.message}`);
 			process.exitCode = 1;
 			return null;
 		}
@@ -8574,6 +8791,10 @@ try {
 		type: "boolean",
 		default: false,
 		describe: "Print what would be mutated without calling capability mutators. Commands branch on this; read-only commands ignore it."
+	}).option("skip-dry-run", {
+		type: "boolean",
+		default: false,
+		describe: "Interactive mode only: skip the automatic dry-run preview for a dry-run-capable command and run for real immediately."
 	}).option("token", {
 		type: "string",
 		array: true,
@@ -8597,6 +8818,10 @@ try {
 		type: "boolean",
 		default: false,
 		describe: "Set the log level to error — suppress info and warn."
+	}).option("log", {
+		type: "string",
+		choices: LOG_LEVELS,
+		describe: "Show structured logger output at this level. Local/interactive runs are quiet by default (no console output regardless of level) — this opts back in."
 	}).middleware((argv) => {
 		const name = argv._.slice(0, 2).join(" ") || "unknown";
 		printRunId = Boolean(argv.debug || argv.verbose);
@@ -8618,13 +8843,13 @@ try {
 		try {
 			token = resolveCloneToken({ cliToken: tokens.cliTokens?.["github"] ?? tokens.cliToken });
 		} catch (err) {
-			getLogger().error(`clone: ${err instanceof AuthError ? err.message : String(err)}`);
+			reportError(`clone: ${err instanceof AuthError ? err.message : String(err)}`);
 			process.exitCode = 1;
 			return;
 		}
 		const [targetInput] = await promptForPositionals(getEntry("clone"), argv);
 		const { org, repo } = parseCloneTarget(targetInput);
-		if ((await runClone({
+		const report = await runClone({
 			org,
 			...repo ? { repo } : {},
 			token,
@@ -8637,8 +8862,20 @@ try {
 					message: `${org} has ${total} repos — ${alreadyCloned} already cloned locally, ${toClone} new. Clone them all?`,
 					default: false
 				});
-			} } : {}
-		})).status === "fail") process.exitCode = 1;
+			} } : {},
+			confirmOpen: async (openTarget, moreToCome) => {
+				if (!process.stdin.isTTY) return;
+				if (moreToCome && env.get("HOLOCRON_DRY_RUN_PREVIEW") === "1") return;
+				if (await confirm({
+					message: `Open ${openTarget}?`,
+					default: false
+				})) openPath(openTarget);
+			}
+		});
+		if (report.status === "fail") {
+			if (report.message) reportError(`clone: ${report.message}`);
+			process.exitCode = 1;
+		} else if (report.status === "dry-run" && report.cloned === 0 && env.get("HOLOCRON_DRY_RUN_PREVIEW") === "1") process.exitCode = 2;
 	}).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."
@@ -8898,7 +9135,7 @@ try {
 		if (argv.syncTrust) {
 			const [oldFile, newFile] = argv.syncTrust;
 			if (!oldFile || !newFile) {
-				getLogger().error("publish --sync-trust requires exactly two values: <old-file> <new-file>");
+				reportError("publish --sync-trust requires exactly two values: <old-file> <new-file>");
 				process.exitCode = 1;
 				return;
 			}
@@ -9058,7 +9295,7 @@ try {
 		else try {
 			token = resolveSyncToken({ cliToken: parsed.cliTokens?.["github"] ?? parsed.cliToken });
 		} catch (err) {
-			getLogger().error(`sync-github: ${err instanceof AuthError ? err.message : String(err)}`);
+			reportError(`sync-github: ${err instanceof AuthError ? err.message : String(err)}`);
 			process.exitCode = 1;
 			return;
 		}
@@ -9078,13 +9315,17 @@ try {
 	}), async (argv) => {
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runSyncReadme({
+		const report = await runSyncReadme({
 			loaded,
 			context: {
 				repoRoot: argv.cwd,
 				dryRun: argv.dryRun
 			}
-		})).status === "fail") process.exitCode = 1;
+		});
+		if (report.status === "fail") {
+			if (report.message) reportError(`sync-readme: ${report.message}`);
+			process.exitCode = 1;
+		}
 	}).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
 		const loaded = await loadConfig(argv.cwd);
 		console.log(JSON.stringify(loaded.resolved, null, 2));
@@ -9313,12 +9554,12 @@ try {
 			}) === "yes";
 			if (skills.length === 0) skills = parseTopics(await input({ message: "Agent skills (comma-separated, optional):" }));
 			if (!type) {
-				getLogger().error("new: template type is required");
+				reportError("new: template type is required");
 				process.exitCode = 1;
 				return;
 			}
 			if (!name) {
-				getLogger().error("new: repo name is required");
+				reportError("new: repo name is required");
 				process.exitCode = 1;
 				return;
 			}
@@ -9347,7 +9588,7 @@ try {
 			})).status === "fail") process.exitCode = 1;
 		} catch (err) {
 			if (err instanceof NewError) {
-				getLogger().error(`new: ${err.message}`);
+				reportError(`new: ${err.message}`);
 				process.exitCode = 1;
 				return;
 			}
@@ -9406,7 +9647,7 @@ try {
 			}).status === "fail") process.exitCode = 1;
 		} catch (err) {
 			if (err instanceof PluginCreateError) {
-				getLogger().error(`plugin create: ${err.message}`);
+				reportError(`plugin create: ${err.message}`);
 				process.exitCode = 1;
 				return;
 			}
@@ -9434,7 +9675,7 @@ try {
 			extra
 		});
 		if (report.status === "fail") {
-			if (report.message) getLogger().error(`upgrade node: ${report.message}`);
+			if (report.message) reportError(`upgrade node: ${report.message}`);
 			process.exitCode = 1;
 		}
 	}).command("deps", "Bump every @theholocron/* pin to latest and migrate holocron.config.ts to the current preset API", (yy) => yy.option("pins-only", {
@@ -9448,7 +9689,7 @@ try {
 			pinsOnly: argv.pinsOnly
 		});
 		if (report.status === "fail") {
-			if (report.message) getLogger().error(`upgrade deps: ${report.message}`);
+			if (report.message) reportError(`upgrade deps: ${report.message}`);
 			process.exitCode = 1;
 		}
 	}).command("$0", false, () => {}, async (argv) => {
@@ -9474,25 +9715,25 @@ try {
 	}).command("$0", false, () => {}, async (argv) => {
 		await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "auth"), argv, "auth — choose a subcommand:", "Run `holocron auth --help` to see available auth subcommands.");
 	}), () => {}).command("$0", false, () => {}, async (argv) => {
-		console.log(style.dim(`holocron v${CLI_VERSION}`));
+		printVersionHeaderOnce();
 		await launchMenu(COMMAND_REGISTRY.filter((e) => !e.group), argv);
 	}).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);
+			reportError(err.message);
 			errorReported = true;
 			process.exitCode = 1;
 			return;
 		}
 		if (err) throw err;
-		getLogger().error(msg);
+		reportError(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 (!errorReported && err instanceof Error && USER_FACING_ERRORS.has(err.name)) reportError(err.message);
 	if (!process.exitCode) process.exitCode = 1;
 }
 finishCommand(!process.exitCode);