@theholocron/cli 5.0.0-alpha.120 → 5.0.0-alpha.122

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, input, select } from "@inquirer/prompts";
+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,52 @@ 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}`,
+	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 +387,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 +406,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 +694,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
@@ -1072,12 +1118,34 @@ async function runCleanupPreview(input) {
 }
 //#endregion
 //#region src/commands/clone.ts
+/**
+* Accepts a bare org (`"theholocron"`) — clones every repo in it — or an
+* `org/repo` coordinate (`"theholocron/new-repo"`) — clones just that one
+* repo. The repo half is never silently discarded: if it's there, it's used.
+* A trailing slash with nothing after it (`"theholocron/"`) is treated the
+* same as a bare org.
+*/
+function parseCloneTarget(raw) {
+	const trimmed = raw.trim();
+	const slash = trimmed.indexOf("/");
+	if (slash === -1) return { org: trimmed };
+	const org = trimmed.slice(0, slash);
+	const repo = trimmed.slice(slash + 1);
+	return repo ? {
+		org,
+		repo
+	} : { org };
+}
 function encodeTokenForGitHttpAuth(token) {
 	const trimmed = token.trim();
 	if (!trimmed) throw new Error("empty token");
 	if (/[\u0000-\u001F\u007F\s]/.test(trimmed)) throw new Error("token contains whitespace or control characters");
 	return encodeURIComponent(trimmed);
 }
+/** Strip a leading dot so a hidden repo (e.g. `.github`) is still visible in Finder once cloned. */
+function repoDirName(repo) {
+	return repo.name.startsWith(".") ? repo.name.slice(1) : repo.name;
+}
 async function listOrgRepos(org, token, fetchFn) {
 	const repos = [];
 	let url = `https://api.github.com/orgs/${org}/repos?per_page=100&type=all`;
@@ -1094,6 +1162,16 @@ async function listOrgRepos(org, token, fetchFn) {
 	}
 	return repos;
 }
+async function getRepo(org, repo, token, fetchFn) {
+	const res = await fetchFn(`https://api.github.com/repos/${org}/${repo}`, { headers: {
+		Authorization: `Bearer ${token}`,
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28"
+	} });
+	if (res.status === 404) throw new Error(`${org}/${repo} not found — check the repo name and that the token can see it`);
+	if (!res.ok) throw new Error(`GitHub API ${res.status}: ${res.statusText} — check that the token has repo:read scope`);
+	return await res.json();
+}
 async function runClone(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -1102,6 +1180,7 @@ async function runClone(input) {
 	const targetDir = resolve(input.dir ?? join(homedir(), "Code", input.org));
 	logger.info({
 		org: input.org,
+		repo: input.repo,
 		targetDir,
 		dryRun: dryRun || void 0
 	}, "clone: start");
@@ -1111,20 +1190,20 @@ async function runClone(input) {
 			stdio: "inherit"
 		}).status };
 	});
-	print(style.header(`Holocron clone — org=${input.org} → ${targetDir}${dryRun ? " (dry-run)" : ""}`));
 	if (!existsSync(targetDir)) {
 		if (dryRun) print(style.dim(`  would create ${targetDir}`));
 		else mkdirSync(targetDir, { recursive: true });
 	}
 	let repos;
 	try {
-		repos = await listOrgRepos(input.org, input.token, fetchFn);
+		repos = input.repo ? [await getRepo(input.org, input.repo, input.token, fetchFn)] : await listOrgRepos(input.org, input.token, fetchFn);
 	} catch (err) {
 		const message = errorMessage(err);
 		logger.warn({
 			org: input.org,
+			repo: input.repo,
 			reason: message
-		}, "clone: failed to list org repos");
+		}, "clone: failed to list repos");
 		return {
 			status: "fail",
 			cloned: 0,
@@ -1133,14 +1212,35 @@ async function runClone(input) {
 			message
 		};
 	}
+	if (!input.repo && !dryRun && input.confirmWholeOrg) {
+		const alreadyCloned = repos.filter((r) => existsSync(join(targetDir, repoDirName(r)))).length;
+		const scope = {
+			total: repos.length,
+			alreadyCloned,
+			toClone: repos.length - alreadyCloned
+		};
+		if (!await input.confirmWholeOrg(scope)) {
+			print(style.dim("  aborted — nothing cloned"));
+			logger.info({
+				org: input.org,
+				...scope
+			}, "clone: aborted by user");
+			return {
+				status: "aborted",
+				cloned: 0,
+				skipped: 0,
+				failed: 0,
+				message: "aborted by user"
+			};
+		}
+	}
 	let cloned = 0;
 	let skipped = 0;
 	let failed = 0;
 	for (const repo of repos) {
-		const dirName = repo.name.startsWith(".") ? repo.name.slice(1) : repo.name;
-		const dest = join(targetDir, dirName);
+		const dest = join(targetDir, repoDirName(repo));
 		if (existsSync(dest)) {
-			print(style.dim(`  skip   ${repo.full_name}`));
+			print(style.dim(`  skip   ${repo.full_name} → ${dest} (already exists)`));
 			skipped++;
 			continue;
 		}
@@ -1149,10 +1249,10 @@ 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(style.fail(`  failed ${repo.full_name} → unexpected clone URL: ${clone_url}`));
 			failed++;
 			continue;
 		}
@@ -1160,7 +1260,7 @@ async function runClone(input) {
 		try {
 			encodedToken = encodeTokenForGitHttpAuth(input.token);
 		} catch (err) {
-			print(style.fail(`  failed ${repo.full_name} — invalid token format: ${errorMessage(err)}`));
+			print(style.fail(`  failed ${repo.full_name} → invalid token format: ${errorMessage(err)}`));
 			failed++;
 			continue;
 		}
@@ -1173,20 +1273,26 @@ async function runClone(input) {
 			print(style.fail(`  failed ${repo.full_name}`));
 			failed++;
 		} else {
-			print(style.success(`  cloned ${repo.name}`));
+			print(style.success(`  cloned ${repo.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}`));
+	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,
+		repo: input.repo,
 		status,
 		cloned,
 		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,
@@ -7986,6 +8092,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
@@ -8009,18 +8124,26 @@ const numeric = (value) => /^\d+$/.test(value) ? true : "enter a number";
 const COMMAND_REGISTRY = [
 	{
 		name: "clone",
-		description: "Clone all repos in a GitHub org as siblings under a single directory",
-		positionals: []
+		description: "Clone a single repo (org/repo) or every repo in an org (org)",
+		positionals: [{
+			key: "target",
+			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",
@@ -8029,7 +8152,8 @@ const COMMAND_REGISTRY = [
 			key: "name",
 			message: "Secret name:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "secrets sync",
@@ -8038,7 +8162,8 @@ const COMMAND_REGISTRY = [
 			key: "environmentId",
 			message: "Vault environment id:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "deploy",
@@ -8047,7 +8172,8 @@ const COMMAND_REGISTRY = [
 			key: "branch",
 			message: "Branch to deploy:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "cleanup-preview",
@@ -8057,7 +8183,8 @@ const COMMAND_REGISTRY = [
 			message: "PR number:",
 			type: "input",
 			validate: numeric
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "bump-versions",
@@ -8067,32 +8194,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",
@@ -8102,7 +8235,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",
@@ -8115,25 +8249,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",
@@ -8144,13 +8282,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",
@@ -8265,25 +8405,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
@@ -8291,15 +8447,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));
@@ -8307,6 +8465,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
@@ -8315,12 +8484,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
@@ -8466,6 +8702,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`.
@@ -8495,7 +8744,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;
 		}
@@ -8512,6 +8761,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,
@@ -8535,6 +8788,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);
@@ -8543,10 +8800,9 @@ try {
 			org: argv.org
 		});
 		finishCommand = startCommand(name);
-	}).command("clone", "Clone all repos in a GitHub org as siblings under a single directory", (y) => y.option("org", {
+	}).command("clone [target]", "Clone a single repo (org/repo) or every repo in an org (org)", (y) => y.positional("target", {
 		type: "string",
-		demandOption: true,
-		describe: "GitHub org to clone (e.g., theholocron)"
+		describe: "org/repo to clone, or a bare org to clone every repo in it (confirms first)."
 	}).option("dir", {
 		type: "string",
 		describe: "Parent directory to clone into (default: ~/Code/<org>)"
@@ -8557,16 +8813,39 @@ 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;
 		}
-		if ((await runClone({
-			org: argv.org,
+		const [targetInput] = await promptForPositionals(getEntry("clone"), argv);
+		const { org, repo } = parseCloneTarget(targetInput);
+		const report = await runClone({
+			org,
+			...repo ? { repo } : {},
 			token,
 			dryRun: argv.dryRun,
-			...argv.dir ? { dir: argv.dir } : {}
-		})).status === "fail") process.exitCode = 1;
+			...argv.dir ? { dir: argv.dir } : {},
+			...!repo ? { confirmWholeOrg: async ({ total, alreadyCloned, toClone }) => {
+				if (!process.stdin.isTTY) throw new NonInteractiveError(`clone: cloning every repo in "${org}" needs interactive confirmation — run this from a terminal, or pass a specific org/repo instead`);
+				if (toClone === 0) return true;
+				return confirm({
+					message: `${org} has ${total} repos — ${alreadyCloned} already cloned locally, ${toClone} new. Clone them all?`,
+					default: false
+				});
+			} } : {},
+			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."
@@ -8826,7 +9105,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;
 			}
@@ -8986,7 +9265,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;
 		}
@@ -9006,13 +9285,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));
@@ -9241,12 +9524,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;
 			}
@@ -9275,7 +9558,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;
 			}
@@ -9334,7 +9617,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;
 			}
@@ -9362,7 +9645,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", {
@@ -9376,7 +9659,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) => {
@@ -9402,25 +9685,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);