@theholocron/cli 3.53.0 → 3.55.0

package/README.md

@@ -168,6 +168,31 @@ holocron auth unset github.read   # remove a stored token
 holocron auth list                # show all stored providers
 ```
 
+## Logging
+
+Operational output goes through [`@theholocron/logger`](../logger) — separate from
+the user-facing `print` surface. Global flags:
+
+```sh
+holocron doctor --verbose   # log level → debug (full structured output)
+holocron doctor --quiet     # log level → error (suppress info + warn)
+holocron doctor --debug     # print "Run ID: <uuid>" at command end for Axiom lookup
+```
+
+Level resolution (highest priority first): `--verbose` / `--quiet` →
+`HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` → `"info"`.
+
+```ts
+export default defineConfig({
+  log: { level: "warn" },
+});
+```
+
+Axiom credentials (`HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN`,
+`HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET`) come from env vars only.
+`HOLOCRON_TELEMETRY=false` disables the Axiom transport (and Sentry). See the
+[logging guide](https://docs.theholocron.dev/holocron/logging/).
+
 ## What's in here
 
 - `src/capabilities/` — the 14 capability interfaces that providers
@@ -176,6 +201,8 @@ holocron auth list                # show all stored providers
   `CapabilityConfigPackage`
 - `src/load-config.ts` — `loadConfig` — reads JSON/JS/TS config files
 - `src/define-config.ts` — `defineConfig` typed pass-through
+- `src/logger.ts` — CLI-side `@theholocron/logger` wiring (`buildCliLogger`,
+  `resolveLogLevel`)
 - `src/loader.ts` — `PluginLoader` — dynamic-imports plugins, resolves
   capability config packages, builds the capability registry
 - `src/cli.ts` — yargs entry, dispatches subcommands

package/dist/cli.mjs

@@ -14,6 +14,7 @@ import chalk from "chalk";
 import { execFile, execFileSync, spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { createLogger, parseLogLevel } from "@theholocron/logger";
 import { createHash } from "node:crypto";
 import { generateReadme } from "@theholocron/components-doc/markdown";
 import { getClients, getConfigs, getDocs, getPlugins, getSkills, getThemes, getUtils } from "@theholocron/registry-doc";
@@ -172,7 +173,8 @@ const CARDINALITY = {
 	tooling: "many",
 	notifications: "many",
 	analytics: "many",
-	observability: "many",
+	errors: "single",
+	logs: "single",
 	wiki: "single",
 	workers: "single"
 };
@@ -184,31 +186,6 @@ const CARDINALITY = {
 const REQUIRED_CAPABILITIES = [];
 //#endregion
 //#region src/config/config.ts
-/**
-* `holocron.config.json` schema, parser, and provider resolution.
-*
-* ESLint-style entry forms:
-*
-*   "source": "github"                              ← single, short
-*   "deployment": ["vercel", { team: "rando" }]    ← single, with options
-*   "notifications": ["slack", "discord"]          ← multi, short
-*   "notifications": [
-*     ["slack",   { channel: "#ops" }],
-*     ["discord", { webhook: "env:HOOK" }]
-*   ]                                              ← multi, with options
-*
-* Discriminator: an array entry is a `[provider, options]` tuple when
-* the length is 2 AND element[1] is a non-array, non-null object.
-* Otherwise it's a multi-provider list (string[] or tuple[]).
-*
-* Validation rules:
-*   - `vault` is REQUIRED (every project has secrets somewhere)
-*   - Entries for `'many'` capabilities are normalized to an array of
-*     normalized tuples; entries for `'single'` capabilities are
-*     normalized to one tuple
-*   - Tokens / secret values never appear in config — providers read
-*     them from env (or pull from `vault` at runtime)
-*/
 var ConfigError = class extends Error {
 	name = "ConfigError";
 };
@@ -306,7 +283,8 @@ function resolveConfig(raw) {
 		agent: raw.agent,
 		skills: raw.skills,
 		docs,
-		env: raw.env
+		env: raw.env,
+		log: raw.log
 	};
 }
 //#endregion
@@ -986,6 +964,19 @@ async function smokeCheck(key, provider, impl) {
 				const desc = await impl.describe();
 				return mk(key, provider, "ok", `provider: ${desc.provider}; env keys: ${desc.envKeys.join(", ")}`);
 			}
+			case "errors": {
+				const desc = await impl.describe();
+				return mk(key, provider, "ok", `provider: ${desc.provider}; env keys: ${desc.envKeys.join(", ")}`);
+			}
+			case "logs": {
+				const logs = impl;
+				const desc = await logs.describe();
+				if (logs.whoami) {
+					const who = await logs.whoami();
+					return mk(key, provider, who.ok ? "ok" : "fail", `dataset: ${who.dataset}`);
+				}
+				return mk(key, provider, "ok", `provider: ${desc.provider}; env keys: ${desc.envKeys.join(", ")}`);
+			}
 			default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
 		}
 	} catch (err) {
@@ -3121,6 +3112,59 @@ var dependabot_default = "version: 2\nupdates:\n  - package-ecosystem: npm\n
 //#region src/templates/labeler.yml
 var labeler_default = "bug:\n  - '^fix'\n\nchore:\n  - '^chore(?!\\(deps)'\n\nci:\n  - '^ci'\n\ndependencies:\n  - '^chore\\(deps'\n\ndocumentation:\n  - '^docs'\n\nenhancement:\n  - '^feat'\n\nperformance:\n  - '^perf'\n\nrefactor:\n  - '^refactor'\n\ntest:\n  - '^test'\n";
 //#endregion
+//#region src/logger.ts
+/**
+* CLI-side wiring for `@theholocron/logger`.
+*
+* `logger` is the operational-output channel — internal state, debug
+* traces, errors, structured context that routes to Axiom. It runs in
+* parallel to `print` (user-facing UX output) and does not replace it.
+*/
+/**
+* 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`)
+*
+* 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.verbose) return "debug";
+	if (argv.quiet) return "error";
+	return parseLogLevel(env.get("HOLOCRON_LOG_LEVEL")) ?? configLevel;
+}
+let root;
+let rootLevel;
+/**
+* The process-wide root logger. Built once (from `cli.ts`'s middleware,
+* with flags + env only). Rebuilt at most once more when a command's
+* handler supplies its `holocron.config` `log.level` — a case the
+* flag/env-only first pass could not have known — as long as no
+* higher-priority `--verbose` / `--quiet` already fixed the level. That
+* rebuild generates a fresh `runId`, which is harmless: nothing logs
+* between the middleware and the handler.
+*/
+function buildCliLogger(argv, configLevel) {
+	const level = resolveLogLevel(argv, configLevel);
+	const rebuildForConfig = configLevel !== void 0 && level !== rootLevel && !argv.verbose && !argv.quiet;
+	if (!root || rebuildForConfig) {
+		root = createLogger(level ? { level } : {});
+		rootLevel = level;
+	}
+	return root;
+}
+/** Lazily-memoized `Logger` for module-level call sites with no `argv` in scope. */
+function getLogger() {
+	return (root ??= createLogger()).logger;
+}
+/** The current root logger's correlation id, if a root has been built. */
+function getRunId() {
+	return root?.runId;
+}
+//#endregion
 //#region src/commands/setup-workflows/index.ts
 /**
 * Thin workflow wrapper templates for `holocron setup`.
@@ -3210,7 +3254,7 @@ function generateThinCallerContent(name, withOverrides, additionalPaths) {
 	}
 	const withBlock = Object.entries(withOverrides).map(([k, v]) => fmt(k, v)).join("\n");
 	const injected = result.replace(/ {4}secrets: inherit\n$/, `    with:\n${withBlock}\n    secrets: inherit\n`);
-	if (injected === result) console.warn(`[generateThinCallerContent] could not inject with: overrides into "${name}" template`);
+	if (injected === result) getLogger().warn({ template: name }, "generateThinCallerContent: could not inject `with:` overrides");
 	return injected;
 }
 /**
@@ -4585,6 +4629,17 @@ async function runSetup(input) {
 		}
 		print(formatStep(steps[steps.length - 1]));
 	}
+	if (loader.has("logs")) {
+		const logs = loader.get("logs");
+		print(style.step("logs"));
+		if (logs.ensureDataset) for (const dataset of ["holocron-ci", "holocron-local"]) {
+			steps.push(await runStep("logs", `ensureDataset ${dataset}`, dryRun, async () => {
+				const result = await logs.ensureDataset(dataset);
+				return `${dataset} ${result.alreadyExists ? "exists" : "created"}`;
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
 	if (loader.has("tooling")) {
 		const tools = loader.get("tooling");
 		print(style.step("tooling"));
@@ -4724,13 +4779,14 @@ async function runSkillsInstall(input) {
 function runSkillsRemove(input) {
 	const { dryRun, repoRoot } = input.context;
 	const exec = input.exec ?? defaultExec;
+	const logger = input.logger ?? getLogger();
 	const args = [
 		"skills",
 		"remove",
 		...input.names ?? []
 	];
 	if (dryRun) {
-		console.log(`Would run: npx ${args.join(" ")}`);
+		logger.info({ argv: args }, `Would run: npx ${args.join(" ")}`);
 		return { status: "dry-run" };
 	}
 	const { exitCode } = exec("npx", args, { cwd: repoRoot });
@@ -4739,13 +4795,14 @@ function runSkillsRemove(input) {
 function runSkillsUpdate(input) {
 	const { dryRun, repoRoot } = input.context;
 	const exec = input.exec ?? defaultExec;
+	const logger = input.logger ?? getLogger();
 	const args = [
 		"skills",
 		"update",
 		...input.name ? [input.name] : []
 	];
 	if (dryRun) {
-		console.log(`Would run: npx ${args.join(" ")}`);
+		logger.info({ argv: args }, `Would run: npx ${args.join(" ")}`);
 		return { status: "dry-run" };
 	}
 	const { exitCode } = exec("npx", args, { cwd: repoRoot });
@@ -6109,7 +6166,7 @@ async function fileExists(path) {
 //#region src/telemetry.ts
 const DSN = "https://95cbb72ad5636c94e119a5405ee8f55f@o4508238154104832.ingest.us.sentry.io/4511810950791168";
 function isEnabled() {
-	return !env.get("NO_HOLOCRON_TELEMETRY") && true;
+	return !(env.get("HOLOCRON_TELEMETRY") === "false" || Boolean(env.get("NO_HOLOCRON_TELEMETRY"))) && true;
 }
 function init(version) {
 	if (!isEnabled()) return;
@@ -6280,6 +6337,8 @@ const resolveSyncToken = createFeatureResolver({
 	keyringKey: "github.sync"
 });
 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;
 /**
 * Resolves the active org in priority order:
 *   1. `--org` CLI flag
@@ -6296,7 +6355,7 @@ function tokenContext(rawTokens) {
 		return parseTokenArgs(rawTokens);
 	} catch (err) {
 		if (err instanceof TokenParseError) {
-			console.error(`--token: ${err.message}`);
+			getLogger().error(`--token: ${err.message}`);
 			process.exitCode = 1;
 			return null;
 		}
@@ -6307,9 +6366,7 @@ init(CLI_VERSION);
 const updateCheckPromise = checkForUpdates(CLI_VERSION);
 let finishCommand = () => {};
 try {
-	await yargs(hideBin(process.argv)).middleware((argv) => {
-		finishCommand = startCommand(argv._.slice(0, 2).join(" ") || "unknown");
-	}).scriptName("").usage("holocron <command> [options]").option("dry-run", {
+	await yargs(hideBin(process.argv)).scriptName("").usage("holocron <command> [options]").option("dry-run", {
 		type: "boolean",
 		default: false,
 		describe: "Print what would be mutated without calling capability mutators. Commands branch on this; read-only commands ignore it."
@@ -6324,6 +6381,22 @@ try {
 		type: "string",
 		default: process.cwd(),
 		describe: "Directory to search for holocron.config.json"
+	}).option("verbose", {
+		type: "boolean",
+		default: false,
+		describe: "Set the log level to debug — full structured operational output."
+	}).option("debug", {
+		type: "boolean",
+		default: false,
+		describe: "Print the run ID at command end for Axiom lookup. Does not change the log level."
+	}).option("quiet", {
+		type: "boolean",
+		default: false,
+		describe: "Set the log level to error — suppress info and warn."
+	}).middleware((argv) => {
+		finishCommand = startCommand(argv._.slice(0, 2).join(" ") || "unknown");
+		printRunId = Boolean(argv.debug || argv.verbose);
+		buildCliLogger(argv);
 	}).command("version", "Print the CLI version", () => {}, () => {
 		console.log(`holocron ${CLI_VERSION}`);
 	}).command("clone", "Clone all repos in a GitHub org as siblings under a single directory", (y) => y.option("org", {
@@ -6340,7 +6413,7 @@ try {
 		try {
 			token = resolveCloneToken({ cliToken: tokens.cliTokens?.["github"] ?? tokens.cliToken });
 		} catch (err) {
-			console.error(`clone: ${err instanceof AuthError ? err.message : String(err)}`);
+			getLogger().error(`clone: ${err instanceof AuthError ? err.message : String(err)}`);
 			process.exitCode = 1;
 			return;
 		}
@@ -6357,6 +6430,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
+		buildCliLogger(argv, loaded.resolved.log?.level);
 		if ((await runDoctor({
 			loaded,
 			context: {
@@ -6374,6 +6448,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
+		buildCliLogger(argv, loaded.resolved.log?.level);
 		if ((await runSetup({
 			loaded,
 			context: {
@@ -6439,6 +6514,7 @@ try {
 		const scopeArg = argv.scope;
 		const scope = parseScope(scopeArg);
 		const loaded = await loadConfig(argv.cwd);
+		buildCliLogger(argv, loaded.resolved.log?.level);
 		if ((await runSecretSet({
 			loaded,
 			context: {
@@ -6468,6 +6544,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
+		buildCliLogger(argv, loaded.resolved.log?.level);
 		if ((await runSecretsSync({
 			loaded,
 			context: {
@@ -6496,6 +6573,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
+		buildCliLogger(argv, loaded.resolved.log?.level);
 		if ((await runDeploy({
 			loaded,
 			context: {
@@ -6523,6 +6601,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
+		buildCliLogger(argv, loaded.resolved.log?.level);
 		if ((await runCleanupPreview({
 			loaded,
 			context: {
@@ -6570,6 +6649,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
+		buildCliLogger(argv, loaded.resolved.log?.level);
 		if ((await runSync({
 			loaded,
 			context: {
@@ -6607,7 +6687,7 @@ try {
 		else try {
 			token = resolveSyncToken({ cliToken: parsed.cliTokens?.["github"] ?? parsed.cliToken });
 		} catch (err) {
-			console.error(`sync-github: ${err instanceof AuthError ? err.message : String(err)}`);
+			getLogger().error(`sync-github: ${err instanceof AuthError ? err.message : String(err)}`);
 			process.exitCode = 1;
 			return;
 		}
@@ -6625,8 +6705,10 @@ try {
 		describe: "Print what would change without writing",
 		default: false
 	}), async (argv) => {
+		const loaded = await loadConfig(argv.cwd);
+		buildCliLogger(argv, loaded.resolved.log?.level);
 		if ((await runSyncReadme({
-			loaded: await loadConfig(argv.cwd),
+			loaded,
 			context: {
 				repoRoot: argv.cwd,
 				dryRun: argv.dryRun
@@ -6860,12 +6942,12 @@ try {
 			}) === "yes";
 			if (skills.length === 0) skills = parseTopics(await input({ message: "Agent skills (comma-separated, optional):" }));
 			if (!type) {
-				console.error("new: template type is required");
+				getLogger().error("new: template type is required");
 				process.exitCode = 1;
 				return;
 			}
 			if (!name) {
-				console.error("new: repo name is required");
+				getLogger().error("new: repo name is required");
 				process.exitCode = 1;
 				return;
 			}
@@ -6894,7 +6976,7 @@ try {
 			})).status === "fail") process.exitCode = 1;
 		} catch (err) {
 			if (err instanceof NewError) {
-				console.error(`new: ${err.message}`);
+				getLogger().error(`new: ${err.message}`);
 				process.exitCode = 1;
 				return;
 			}
@@ -6910,7 +6992,7 @@ try {
 		describe: "Vendor display name (PascalCase)"
 	}).option("capability", {
 		type: "string",
-		describe: "Capability key: source|ci|secrets|environments|issues|deployment|storage|auth|vault|dns|tooling|notifications|analytics|observability"
+		describe: "Capability key: source|ci|secrets|environments|issues|deployment|storage|auth|vault|dns|tooling|notifications|analytics|errors|logs|wiki|workers"
 	}).option("token-env", {
 		type: "string",
 		describe: "Holocron env var name (defaults to HOLOCRON_<VENDOR>_TOKEN)"
@@ -6955,7 +7037,7 @@ try {
 			}).status === "fail") process.exitCode = 1;
 		} catch (err) {
 			if (err instanceof PluginCreateError) {
-				console.error(`plugin create: ${err.message}`);
+				getLogger().error(`plugin create: ${err.message}`);
 				process.exitCode = 1;
 				return;
 			}
@@ -6983,7 +7065,7 @@ try {
 			extra
 		});
 		if (report.status === "fail") {
-			if (report.message) console.error(`upgrade node: ${report.message}`);
+			if (report.message) getLogger().error(`upgrade node: ${report.message}`);
 			process.exitCode = 1;
 		}
 	}).demandCommand(1, "Run `holocron upgrade --help` to see available upgrade subcommands."), () => {}).command("auth <subcommand>", "Manage bootstrap credentials in the OS keyring", (y) => y.command("set <provider> [value]", "Verify + store a bootstrap token for a provider", (yy) => yy.positional("provider", {
@@ -7017,6 +7099,8 @@ try {
 }
 finishCommand(!process.exitCode);
 endSession();
+const rid = getRunId();
+if (printRunId && rid) console.log(`Run ID: ${rid}`);
 (await updateCheckPromise)?.();
 await flush();
 /**