@theholocron/cli 4.14.1 → 4.16.0

package/README.md

@@ -275,6 +275,20 @@ export default acmeConfig;
 
 ```
 
+## Upgrading
+
+- **`holocron upgrade node <to>`** — patches every Node.js version pin
+  (`engines.node`, `.nvmrc`, `.node-version`, `.github/workflows/*`,
+  `Dockerfile`, `.tool-versions`) to a new major.
+- **`holocron upgrade deps`** — bumps every `@theholocron/*` pin in
+  `pnpm-workspace.yaml` (`catalog:` and every named `catalogs.*`) to its latest
+  published version, then migrates `holocron.config.ts` from the 7.x preset
+  shape (`const { repo, workflows } = node()` + `repo.requiredChecks` +
+  `workflows:`) to the current composed-preset API (`const preset = node()` +
+  `...preset` + `tasks:` + `extraRequiredChecks:`). Mechanical transforms only —
+  review the result, then `pnpm install && holocron ci`. `--pins-only` skips
+  the config migration; `--dry-run` prints without writing.
+
 ## Auth — fine-grained tokens
 
 Each GitHub capability resolves its own fine-grained PAT so a compromised
@@ -307,8 +321,8 @@ holocron auth list                # show all stored providers
 
 ## Logging
 
-Operational output goes through [`@theholocron/logger`](../logger) — separate from
-the user-facing `print` surface. Global flags:
+Operational output goes through `@theholocron/observability/logger` — separate
+from the user-facing `print` surface. Global flags:
 
 ```sh
 holocron doctor --verbose   # log level → debug (full structured output)
@@ -356,9 +370,11 @@ export default defineConfig({
 });
 ```
 
-Each SDK sits behind a Holocron-owned interface — `ErrorSink` (Sentry) /
-`AnalyticsSink` (PostHog) in `src/telemetry/sinks.ts`; `@sentry/node` and
-`posthog-node` are imported only from their adapter modules. See the
+Each SDK sits behind an interface from `@theholocron/observability` —
+`ErrorSink` (Sentry) / `AnalyticsSink` (PostHog); the adapters, and the only
+`@sentry/node` / `posthog-node` imports, live in that package. `telemetry.ts`
+holds the orchestration + the Holocron-specific credential resolution
+(`telemetry/resolve.ts`). See the
 [telemetry guide](https://docs.theholocron.dev/holocron/telemetry/).
 
 ## What's in here
@@ -370,8 +386,8 @@ Each SDK sits behind a Holocron-owned interface — `ErrorSink` (Sentry) /
 - `src/config/load-config.ts` — `loadConfig` — reads `holocron.config.*`
   (file discovery via [`@theholocron/datapad`](../datapad))
 - `src/define-config.ts` — `defineConfig` typed pass-through
-- `src/logger.ts` — CLI-side `@theholocron/logger` wiring (`buildCliLogger`,
-  `resolveLogLevel`)
+- `src/logger.ts` — CLI-side `@theholocron/observability/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. `holocron run` / `ci` are
@@ -383,7 +399,7 @@ Each SDK sits behind a Holocron-owned interface — `ErrorSink` (Sentry) /
   never hand-edit its `.github/workflows/*`).
 - `src/commands/` — `setup`, `sync`, `doctor`, `deploy`, `secret set`,
   `secrets sync`, `npm publish-initial`, `sync-github`, `upgrade node`,
-  `plugin create`, `auth`
+  `upgrade deps`, `plugin create`, `auth`
 
 ## Status
 

package/dist/cli.mjs

@@ -11,7 +11,7 @@ import { AuthError, ProviderApiError, ProviderApiError as ProviderApiError$1, cr
 import { createEnvLookup } from "@theholocron/env-utils";
 import { Entry, findCredentials } from "@napi-rs/keyring";
 import { pathToFileURL } from "node:url";
-import { createLogger, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/logger";
+import { createLogger, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
 import ora from "ora";
 import chalk from "chalk";
 import { execFile, execFileSync, spawnSync } from "node:child_process";
@@ -21,8 +21,9 @@ 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 { PostHog } from "posthog-node";
-import * as Sentry from "@sentry/node";
+import { PostHogSink } from "@theholocron/observability/analytics";
+import { NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
+import { SentrySink } from "@theholocron/observability/errors";
 import { promisify } from "node:util";
 import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
 //#region src/env.ts
@@ -299,13 +300,6 @@ function resolveConfig(raw) {
 //#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"`
@@ -327,7 +321,7 @@ let rootCommand;
 let rootAxiomKey;
 /**
 * Resolve Axiom credentials for the CLI. Env vars win — same contract as
-* `@theholocron/logger`'s `resolveAxiomFromEnv`. Failing that, the CLI-only
+* `@theholocron/observability`'s `resolveAxiomFromEnv`. Failing that, the CLI-only
 * bridge pairs the OS-keyring token (`axiom.<org>` then bare `axiom`) with a
 * dataset from `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` or
 * `holocron.config` `log.axiom.dataset`. Returns `undefined` unless both a
@@ -5821,58 +5815,6 @@ async function writeWorkflowFile(repoRoot, filename, content) {
 	await writeFile(join(dir, filename), content, "utf8");
 }
 //#endregion
-//#region src/telemetry/posthog-sink.ts
-/**
-* `PostHogSink` — the **only** `posthog-node` call site. A portable
-* `AnalyticsSink` adapter: usage, adoption, retention. It reads no environment
-* and ships no credentials — the constructor takes a resolved `key` + `host`;
-* the caller (the CLI's `telemetry.ts`, via `telemetry/resolve.ts`) owns the
-* env chain and the fallback. An empty `key` is the caller's signal to install
-* a `NoopAnalyticsSink` instead — it is never passed here.
-*
-* Destined for `@theholocron/observability/analytics` (#635).
-*/
-var PostHogSink = class {
-	#client;
-	constructor(config) {
-		this.#client = new PostHog(config.key, { host: config.host });
-	}
-	identify(distinctId, props) {
-		this.#client.identify({
-			distinctId,
-			properties: props
-		});
-	}
-	capture(distinctId, event, props) {
-		this.#client.capture({
-			distinctId,
-			event,
-			properties: props
-		});
-	}
-	async shutdown() {
-		await this.#client.shutdown();
-	}
-};
-//#endregion
-//#region src/telemetry/redact.ts
-/**
-* Token-shape scrubbing for telemetry payloads — a raw token never leaves the
-* process, even when a value is controlled. Regex-on-the-serialised-string
-* (matches a token shape *anywhere*), distinct from `@theholocron/logger`'s
-* field-path redaction. Shared by {@link scrubError} (Sentry `beforeSend`) and
-* the PostHog `event()` path.
-*/
-const TOKEN_RE = /\b(ghp_|ghs_|glpat-|xoxb-|xoxp-|npm_|sk-|[A-Z][A-Z0-9_]{2,}_TOKEN[=\s])[^\s"]*/g;
-/** Replace token-shaped substrings in a string with `[REDACTED]`. */
-function redact(raw) {
-	return raw.replace(TOKEN_RE, "[REDACTED]");
-}
-/** Deep-scrub every string in an object by round-tripping through {@link redact}. */
-function redactObject(value) {
-	return JSON.parse(redact(JSON.stringify(value)));
-}
-//#endregion
 //#region src/telemetry/resolve.ts
 /**
 * Holocron-specific credential resolution for the telemetry sinks — the env
@@ -5908,76 +5850,16 @@ function resolvePostHogHost() {
 	return env.get("HOLOCRON_POSTHOG_HOST") ?? env.get("POSTHOG_HOST") ?? DEFAULT_POSTHOG_HOST;
 }
 //#endregion
-//#region src/telemetry/sentry-sink.ts
-/** `beforeSend` — token-shaped strings never leave the process. */
-function scrubError(event, _hint) {
-	return redactObject(event);
-}
-var SentrySink = class {
-	init(ctx) {
-		Sentry.init({
-			dsn: ctx.dsn,
-			release: ctx.release,
-			environment: ctx.environment,
-			tracesSampleRate: 1,
-			beforeSend: scrubError
-		});
-		Sentry.startSession();
-		for (const [key, value] of Object.entries(ctx.tags)) Sentry.setTag(key, value);
-	}
-	startSpan(name) {
-		Sentry.setTag("command", name);
-		const span = Sentry.startInactiveSpan({
-			name,
-			op: "holocron.command",
-			forceTransaction: true
-		});
-		return {
-			setStatus: (ok) => span.setStatus({ code: ok ? 1 : 2 }),
-			end: () => span.end()
-		};
-	}
-	captureException(err) {
-		Sentry.captureException(err);
-	}
-	endSession() {
-		Sentry.endSession();
-	}
-	async flush() {
-		await Sentry.close(2e3);
-	}
-};
-//#endregion
-//#region src/telemetry/sinks.ts
-/**
-* The disabled path made explicit — one shared no-op instead of a scatter of
-* `if (!enabled) return` guards. Used when telemetry is opted out
-* (`HOLOCRON_TELEMETRY=false`, `config.telemetry.enabled: false`) or no
-* credentials resolve.
-*/
-var NoopErrorSink = class {
-	init() {}
-	startSpan() {}
-	captureException() {}
-	endSession() {}
-	async flush() {}
-};
-/** @see NoopErrorSink */
-var NoopAnalyticsSink = class {
-	identify() {}
-	capture() {}
-	async shutdown() {}
-};
-//#endregion
 //#region src/telemetry.ts
 /**
 * CLI self-telemetry orchestration — errors (Sentry), usage analytics (PostHog).
 *
-* This module holds *no* vendor SDK import. Each concern sits behind a
-* Holocron-owned interface ({@link ErrorSink} / {@link AnalyticsSink}); the
-* concrete `SentrySink` / `PostHogSink` are the only `@sentry/node` /
-* `posthog-node` call sites, and a `Noop*Sink` is installed when telemetry is
-* off. Same seam `@theholocron/logger` uses for Pino.
+* This module holds *no* vendor SDK import. Each concern sits behind an
+* interface from `@theholocron/observability` ({@link ErrorSink} /
+* {@link AnalyticsSink}); the `SentrySink` / `PostHogSink` adapters there are
+* the only `@sentry/node` / `posthog-node` call sites, and a `Noop*Sink` is
+* installed when telemetry is off. Same seam the package's `Logger` uses for
+* Pino.
 *
 * Activation is env-var + shipped-fallback, resolved here (`telemetry/resolve.ts`)
 * and passed to the sink — the adapters read no environment. The single kill
@@ -6352,6 +6234,224 @@ async function runSyncGithub(input) {
 	});
 }
 //#endregion
+//#region src/commands/upgrade-deps.ts
+/**
+* `holocron upgrade deps` — bring a repo's `@theholocron/*` dependency pins and
+* its `holocron.config.ts` up to the current major.
+*
+* Two concerns:
+*
+* 1. **Catalog pins.** Every `@theholocron/*` entry in `pnpm-workspace.yaml`
+*    (`catalog:` and every named `catalogs.*`) is bumped to the latest published
+*    version, preserving the range prefix (`^` / `~`). Never downgrades.
+* 2. **`holocron.config.ts` migration.** `@theholocron/holocron-config@8`
+*    dropped the 7.x preset shape (`const { repo, workflows, providers } =
+*    node()` + `repo.requiredChecks` + `workflows:`) for a composed-preset
+*    (`const preset = node()` + `...preset` + `tasks:` + `extraRequiredChecks:`).
+*    This applies the mechanical transforms and flags anything that needs a
+*    human eye.
+*
+* After running, `pnpm install && holocron ci`.
+*/
+const FETCH_TIMEOUT_MS$1 = 4e3;
+/** Resolve a package's `latest` dist-tag from the npm registry. */
+const fetchLatestFromNpm = async (pkg) => {
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkg)}`, {
+			signal: AbortSignal.timeout(FETCH_TIMEOUT_MS$1),
+			headers: { accept: "application/vnd.npm.install-v1+json" }
+		});
+		if (!res.ok) return null;
+		return (await res.json())["dist-tags"]?.["latest"] ?? null;
+	} catch {
+		return null;
+	}
+};
+/** `a > b` for `x.y.z` release versions (prerelease tags are ignored). */
+function gt(a, b) {
+	const pa = a.split(".").map((n) => parseInt(n, 10));
+	const pb = b.split(".").map((n) => parseInt(n, 10));
+	for (let i = 0; i < 3; i++) {
+		const x = pa[i] ?? 0;
+		const y = pb[i] ?? 0;
+		if (x !== y) return x > y;
+	}
+	return false;
+}
+const CATALOG_LINE = /^(\s*['"]?)(@theholocron\/[a-z0-9-]+)(['"]?\s*:\s*['"]?)([~^]?)(\d+\.\d+\.\d+[\w.-]*)(['"]?\s*)$/;
+/**
+* Rewrite every `@theholocron/*` pin in a `pnpm-workspace.yaml` to `latest`,
+* keeping the range prefix. `latest` is looked up once per package.
+*/
+async function bumpCatalogs(content, fetchLatest) {
+	const lines = content.split("\n");
+	const wanted = /* @__PURE__ */ new Set();
+	for (const line of lines) {
+		const m = CATALOG_LINE.exec(line);
+		if (m) wanted.add(m[2]);
+	}
+	const latest = /* @__PURE__ */ new Map();
+	await Promise.all([...wanted].map(async (pkg) => {
+		latest.set(pkg, await fetchLatest(pkg));
+	}));
+	const bumps = [];
+	return {
+		content: lines.map((line) => {
+			const m = CATALOG_LINE.exec(line);
+			if (!m) return line;
+			const [, pre, pkg, mid, prefix, current, post] = m;
+			const next = latest.get(pkg);
+			if (!next || next === current || !gt(next, current)) return line;
+			bumps.push({
+				pkg,
+				from: current,
+				to: next
+			});
+			return `${pre}${pkg}${mid}${prefix}${next}${post}`;
+		}).join("\n"),
+		bumps
+	};
+}
+/** True if the file still uses the 7.x preset shape. */
+function isLegacyConfig(content) {
+	return /const\s*\{[^}]*\b(repo|workflows|providers)\b[^}]*\}\s*=\s*(compose\(|[a-zA-Z]+\(\))/.test(content) || /\.\.\.repo\.requiredChecks/.test(content) || /^\s*workflows\s*:/m.test(content);
+}
+/**
+* Apply the mechanical 7.x → 8.x transforms to a `holocron.config.ts`. Best
+* effort — the result should always be reviewed and run through `holocron ci`.
+*/
+function migrateConfig(content) {
+	const transforms = [];
+	const warnings = [];
+	let s = content;
+	if (!isLegacyConfig(s)) return {
+		content,
+		changed: false,
+		transforms,
+		warnings
+	};
+	s = s.replace(/const\s*\{[^}]*\}\s*=\s*((?:compose\([\s\S]*?\)|[a-zA-Z]+\([\s\S]*?\)))\s*;/, (_m, expr) => {
+		transforms.push("destructured preset → `const preset = …`");
+		return `const preset = ${expr.trim()};`;
+	});
+	if (/const preset =/.test(s) && !/\.\.\.preset\b/.test(s)) {
+		s = s.replace(/(defineConfig\(\{\s*\n)/, `$1\t...preset,\n`);
+		transforms.push("spread `...preset` into defineConfig()");
+	}
+	s = s.replace(/^\torg,\n/m, "");
+	s = s.replace(/^\tdomain,\n/m, "");
+	s = s.replace(/^\tdocs,\n/m, "");
+	if (/\.\.\.repo\.properties/.test(s)) {
+		s = s.replace(/\.\.\.repo\.properties/g, "...preset.repo?.properties");
+		transforms.push("`...repo.properties` → `...preset.repo?.properties`");
+	}
+	if (/([{[,]\s*)\.\.\.repo\b(?!\.)/.test(s)) {
+		s = s.replace(/([{[,]\s*)\.\.\.repo\b(?!\.)/g, "$1...preset.repo");
+		transforms.push("`...repo` → `...preset.repo`");
+	}
+	if (/\.\.\.providers\b/.test(s)) {
+		s = s.replace(/\.\.\.providers\b/g, "...preset.providers");
+		transforms.push("`...providers` → `...preset.providers`");
+	}
+	const rc = /(\n\s*)requiredChecks\s*:\s*\[\s*\n?\s*\.\.\.repo\.requiredChecks\s*,?\s*([\s\S]*?)\n\s*\]\s*,/.exec(s);
+	if (rc) {
+		const custom = rc[2].trim().replace(/,\s*$/, "");
+		s = s.replace(rc[0], "");
+		if (custom) {
+			const block = `\textraRequiredChecks: [\n\t\t${custom.split("\n").map((l) => l.trim()).filter(Boolean).join("\n		")}\n\t],\n`;
+			s = s.replace(/(defineConfig\(\{\s*\n(?:\t\.\.\.preset,\n)?)/, `$1${block}`);
+			transforms.push("`repo.requiredChecks` custom entries → top-level `extraRequiredChecks`");
+			warnings.push("check the moved `extraRequiredChecks` — the preset already contributes lint/test/typecheck");
+		} else {
+			s = s.replace(/,(\s*)\.\.\.repo\.requiredChecks/g, "$1");
+			transforms.push("dropped `...repo.requiredChecks`");
+		}
+	}
+	if (/^\s*workflows\s*:/m.test(s)) {
+		s = s.replace(/(\n\s*)workflows(\s*:\s*\[)/, "$1tasks$2");
+		s = s.replace(/\.\.\.workflows\b/g, "...preset.tasks");
+		transforms.push("`workflows:` → `tasks:` (`...workflows` → `...preset.tasks`)");
+		warnings.push("review the `tasks` array — a bare workflow name that should gate merges now needs `{ name, required: true }`");
+	}
+	return {
+		content: s,
+		changed: s !== content,
+		transforms,
+		warnings
+	};
+}
+async function runUpgradeDeps(input = {}) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const cwd = input.cwd ?? process.cwd();
+	const dryRun = input.dryRun ?? false;
+	const pinsOnly = input.pinsOnly ?? false;
+	const _readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const _writeFile = input.writeFile ?? ((p, c) => writeFileSync(p, c));
+	const fetchLatest = input.fetchLatest ?? fetchLatestFromNpm;
+	logger.info({
+		dryRun: dryRun || void 0,
+		pinsOnly: pinsOnly || void 0
+	}, "upgrade deps: start");
+	print(`Upgrading @theholocron/* dependencies${dryRun ? " (dry-run)" : ""}…`);
+	const wsPath = join(cwd, "pnpm-workspace.yaml");
+	let bumps = [];
+	try {
+		const result = await bumpCatalogs(_readFile(wsPath), fetchLatest);
+		bumps = result.bumps;
+		if (bumps.length > 0) {
+			if (!dryRun) _writeFile(wsPath, result.content);
+			print("");
+			print(`  pnpm-workspace.yaml — ${bumps.length} pin${bumps.length === 1 ? "" : "s"}`);
+			for (const b of bumps) print(`    ${dryRun ? "~" : "✓"} ${b.pkg}  ${b.from} → ${b.to}`);
+		} else print("  · pnpm-workspace.yaml — @theholocron/* pins already current");
+	} catch {
+		print("  · no pnpm-workspace.yaml — skipping catalog pins");
+	}
+	let configMigrated = false;
+	let configWarnings = [];
+	if (!pinsOnly) for (const name of ["holocron.config.ts", "holocron.config.js"]) {
+		let cfg;
+		try {
+			cfg = _readFile(join(cwd, name));
+		} catch {
+			continue;
+		}
+		const m = migrateConfig(cfg);
+		if (!m.changed) {
+			print(`  · ${name} — already on the current preset API`);
+			break;
+		}
+		if (!dryRun) _writeFile(join(cwd, name), m.content);
+		configMigrated = true;
+		configWarnings = m.warnings;
+		print("");
+		print(`  ${name} — ${dryRun ? "would migrate" : "migrated"} to the 8.x preset API`);
+		for (const t of m.transforms) print(`    ${dryRun ? "~" : "✓"} ${t}`);
+		for (const w of m.warnings) print(`    ⚠ ${w}`);
+		break;
+	}
+	print("");
+	if (bumps.length === 0 && !configMigrated) print("Nothing to do — already up to date.");
+	else {
+		print(`Next: ${dryRun ? "run without --dry-run, then " : ""}\`pnpm install && holocron ci\``);
+		if (configMigrated) print("      review holocron.config.ts before committing.");
+	}
+	const status = dryRun ? "dry-run" : "ok";
+	logger.info({
+		bumps: bumps.length,
+		configMigrated,
+		warnings: configWarnings.length,
+		status
+	}, "upgrade deps: done");
+	return {
+		status,
+		bumps,
+		configMigrated,
+		configWarnings
+	};
+}
+//#endregion
 //#region src/commands/upgrade-node.ts
 const SKIP_DIRS = /* @__PURE__ */ new Set([
 	"node_modules",
@@ -7551,6 +7651,20 @@ try {
 			if (report.message) getLogger().error(`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", {
+		type: "boolean",
+		default: false,
+		describe: "Only bump the catalog pins — skip the holocron.config.ts migration"
+	}), async (argv) => {
+		const report = await runUpgradeDeps({
+			cwd: argv.cwd,
+			dryRun: argv.dryRun,
+			pinsOnly: argv.pinsOnly
+		});
+		if (report.status === "fail") {
+			if (report.message) getLogger().error(`upgrade deps: ${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", {
 		type: "string",
 		demandOption: true