@theholocron/cli 4.13.0 → 4.14.1

package/README.md

@@ -338,7 +338,28 @@ The CLI reports on itself through three sinks: **Sentry** (errors), **Axiom**
 duration, failure rates, keyed to a one-way `sha256(hostname + username)`
 fingerprint). PostHog activates from `HOLOCRON_POSTHOG_PROJECT_TOKEN` → `POSTHOG_PROJECT_TOKEN`
 → a shipped ingest-only key (on by default). `HOLOCRON_TELEMETRY=false` disables
-all three. See the [telemetry guide](https://docs.theholocron.dev/holocron/telemetry/).
+all three.
+
+For a committed, repo-wide opt-out, add a `telemetry` block to `holocron.config`
+— the version-controlled peer of `HOLOCRON_TELEMETRY=false` (the env var still
+wins; this is an override layer applied after config loads):
+
+```ts
+import { defineConfig } from "@theholocron/cli";
+
+export default defineConfig({
+  // …
+  telemetry: {
+    enabled: false, // no-ops Sentry + PostHog for every command
+    // analytics: "none",  // alternative: PostHog off, Sentry error reporting kept
+  },
+});
+```
+
+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
+[telemetry guide](https://docs.theholocron.dev/holocron/telemetry/).
 
 ## What's in here
 

package/dist/cli.mjs

@@ -21,8 +21,8 @@ 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 * as Sentry from "@sentry/node";
 import { PostHog } from "posthog-node";
+import * as Sentry from "@sentry/node";
 import { promisify } from "node:util";
 import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
 //#region src/env.ts
@@ -292,7 +292,8 @@ function resolveConfig(raw) {
 		skills: raw.skills,
 		docs,
 		env: raw.env,
-		log: raw.log
+		log: raw.log,
+		telemetry: raw.telemetry
 	};
 }
 //#endregion
@@ -5820,50 +5821,185 @@ async function writeWorkflowFile(repoRoot, filename, content) {
 	await writeFile(join(dir, filename), content, "utf8");
 }
 //#endregion
-//#region src/telemetry.ts
-const FALLBACK_DSN = "https://95cbb72ad5636c94e119a5405ee8f55f@o4508238154104832.ingest.us.sentry.io/4511810950791168";
+//#region src/telemetry/posthog-sink.ts
 /**
-* Resolve the Sentry DSN — the `errors` capability's self-contained
-* activation, per ADR-0007:
+* `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.
 *
-*   HOLOCRON_SENTRY_DSN  →  SENTRY_DSN  →  built-in fallback
-*
-* A consumer repo with `SENTRY_DSN` set gets CLI errors routed to its own
-* project with no config. Opt out entirely with `HOLOCRON_TELEMETRY=false`.
+* Destined for `@theholocron/observability/analytics` (#635).
 */
-function resolveDsn() {
-	return env.get("HOLOCRON_SENTRY_DSN") ?? env.get("SENTRY_DSN") ?? FALLBACK_DSN;
+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]");
 }
-const FALLBACK_POSTHOG_PROJECT_TOKEN = "phc_AC4vFCvYzwnzmG7Vg5nEc3PZKZztoPyfKp4Lb9BbXcLK";
-const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+/** 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
 /**
-* Resolve the PostHog project key — mirrors {@link resolveDsn} and the
-* `HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN` pattern, per ADR-0008:
+* Holocron-specific credential resolution for the telemetry sinks — the env
+* chain plus Holocron's own shipped fallbacks. This is **CLI policy**, not part
+* of the portable adapter set: `sentry-sink.ts` / `posthog-sink.ts` take a
+* resolved DSN / key and never read the environment. When the adapters move to
+* `@theholocron/observability` (#635) this module stays here.
 *
-*   HOLOCRON_POSTHOG_PROJECT_TOKEN  →  POSTHOG_PROJECT_TOKEN  →  built-in fallback
+*   errors:    HOLOCRON_SENTRY_DSN            → SENTRY_DSN            → FALLBACK_DSN
+*   analytics: HOLOCRON_POSTHOG_PROJECT_TOKEN → POSTHOG_PROJECT_TOKEN → FALLBACK_POSTHOG_PROJECT_TOKEN
+*   host:      HOLOCRON_POSTHOG_HOST          → POSTHOG_HOST          → DEFAULT_POSTHOG_HOST
 *
-* `POSTHOG_PROJECT_TOKEN` is the vendor-native name a consumer repo sets (as a
-* plain variable, not a secret — the `phc_…` key is publishable) to route CLI
-* usage to its own project.
+* The `SENTRY_DSN` / `POSTHOG_PROJECT_TOKEN` fallbacks are the vendor-native
+* names a consumer repo sets to route CLI telemetry to its own project. The
+* built-in fallbacks are ingest-only keys — publishable by design, same risk
+* model as ADR-0007 / ADR-0008.
 */
+/** Holocron's own Sentry project — the fallback when no env var points elsewhere. */
+const FALLBACK_DSN = "https://95cbb72ad5636c94e119a5405ee8f55f@o4508238154104832.ingest.us.sentry.io/4511810950791168";
+/** Holocron's own PostHog project write key — ingest-only. */
+const FALLBACK_POSTHOG_PROJECT_TOKEN = "phc_AC4vFCvYzwnzmG7Vg5nEc3PZKZztoPyfKp4Lb9BbXcLK";
+const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+/** Resolve the Sentry DSN. `""` → error telemetry disabled. */
+function resolveDsn() {
+	return env.get("HOLOCRON_SENTRY_DSN") ?? env.get("SENTRY_DSN") ?? FALLBACK_DSN;
+}
+/** Resolve the PostHog project key. `""` → usage analytics disabled. */
 function resolvePostHogKey() {
 	return env.get("HOLOCRON_POSTHOG_PROJECT_TOKEN") ?? env.get("POSTHOG_PROJECT_TOKEN") ?? FALLBACK_POSTHOG_PROJECT_TOKEN;
 }
+/** Resolve the PostHog ingest host. */
 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.
+*
+* Activation is env-var + shipped-fallback, resolved here (`telemetry/resolve.ts`)
+* and passed to the sink — the adapters read no environment. The single kill
+* switch is `HOLOCRON_TELEMETRY=false` (legacy alias `NO_HOLOCRON_TELEMETRY`);
+* see ADR-0007 / ADR-0008.
+*/
+let errors = new NoopErrorSink();
+let analytics = new NoopAnalyticsSink();
+/**
+* The shared opt-out. `HOLOCRON_TELEMETRY=false` (going-forward) or
+* `NO_HOLOCRON_TELEMETRY` (any truthy value, back-compat) disables all sinks.
+*/
 function isEnabled() {
 	return env.get("HOLOCRON_TELEMETRY") !== "false" && !env.get("NO_HOLOCRON_TELEMETRY");
 }
-const sentryEnabled = () => isEnabled() && resolveDsn() !== "";
-const posthogEnabled = () => isEnabled() && resolvePostHogKey() !== "";
-let posthog;
 let commandStartedAt = 0;
 let currentCommand = "unknown";
+let lastErrorType;
+let currentSpan;
 /**
 * Anonymous, stable per-machine id — `sha256(hostname + username)` truncated
-* (ADR-0008). A one-way fingerprint: no raw hostname or username is ever
-* transmitted, and it is not personal data under this project's rule.
+* (ADR-0008). One-way: no raw hostname or username is ever transmitted.
 */
 function machineId() {
 	try {
@@ -5872,7 +6008,7 @@ function machineId() {
 		return "unknown";
 	}
 }
-/** Properties every event carries, so any event can be pivoted to its Axiom trace. */
+/** Properties every analytics event carries — pivot key to the Axiom trace. */
 function baseProps() {
 	const runId = getRunId();
 	return {
@@ -5881,76 +6017,80 @@ function baseProps() {
 		...runId ? { runId } : {}
 	};
 }
-/**
-* Capture a PostHog event. Runs every `properties` object through the same
-* token scrubber Sentry uses (defence-in-depth — values are controlled).
-*/
-function event(name, properties = {}) {
-	if (!posthogEnabled() || !posthog) return;
-	const merged = {
-		...baseProps(),
-		...properties
-	};
-	posthog.capture({
-		distinctId: machineId(),
-		event: name,
-		properties: JSON.parse(redact(JSON.stringify(merged)))
-	});
-}
 function init(version) {
-	initSentry(version);
-	initPostHog(version);
-}
-function initSentry(version) {
-	if (!sentryEnabled()) return;
-	Sentry.init({
-		dsn: resolveDsn(),
-		release: `holocron@${version}`,
-		environment: env.get("CI") ? "ci" : "local",
-		tracesSampleRate: 1,
-		beforeSend: scrubError
-	});
-	Sentry.startSession();
-	Sentry.setTag("os", process.platform);
-	Sentry.setTag("node", process.version);
-	Sentry.setTag("ci", String(Boolean(env.get("CI"))));
-}
-function initPostHog(version) {
-	if (!posthogEnabled()) return;
-	posthog = new PostHog(resolvePostHogKey(), { host: resolvePostHogHost() });
-	posthog.identify({
-		distinctId: machineId(),
-		properties: {
+	const dsn = resolveDsn();
+	if (isEnabled() && dsn !== "") {
+		errors = new SentrySink();
+		errors.init({
+			dsn,
+			release: `holocron@${version}`,
+			environment: env.get("CI") ? "ci" : "local",
+			tags: {
+				os: process.platform,
+				node: process.version,
+				ci: String(Boolean(env.get("CI")))
+			}
+		});
+	}
+	const posthogKey = resolvePostHogKey();
+	if (isEnabled() && posthogKey !== "") {
+		analytics = new PostHogSink({
+			key: posthogKey,
+			host: resolvePostHogHost()
+		});
+		analytics.identify(machineId(), {
 			ci: Boolean(env.get("CI")),
 			os: process.platform,
 			node: process.version,
 			cli: version,
 			...env.get("HOLOCRON_ORG") ? { org: env.get("HOLOCRON_ORG") } : {}
-		}
-	});
+		});
+	}
 }
-let lastErrorType;
-/** Start a Sentry command span, or `undefined` when Sentry is off. */
-function startSpan(name) {
-	if (!sentryEnabled()) return void 0;
-	Sentry.setTag("command", name);
-	return Sentry.startInactiveSpan({
-		name,
-		op: "holocron.command",
-		forceTransaction: true
-	});
+/**
+* Apply the `telemetry` config block — the committed override layer, run once
+* per command *after* config loads (so it lands after {@link init}). Env still
+* wins: this only ever *narrows* what `init` turned on, never re-enables.
+*
+* - `enabled: false` → swap both sinks to no-ops for the rest of the run.
+* - `analytics: "none"` → drop usage analytics only; error reporting stays.
+*
+* A live sink is drained best-effort before it is dropped so an in-flight
+* Sentry session / PostHog queue still leaves the process cleanly.
+*/
+function applyConfig(cfg) {
+	if (!cfg) return;
+	const drain = (p) => {
+		p.catch(() => {});
+	};
+	if (cfg.enabled === false) {
+		drain(errors.flush());
+		drain(analytics.shutdown());
+		errors = new NoopErrorSink();
+		analytics = new NoopAnalyticsSink();
+		return;
+	}
+	if (cfg.analytics === "none") {
+		drain(analytics.shutdown());
+		analytics = new NoopAnalyticsSink();
+	}
+}
+/** Capture a PostHog event. Every `properties` object runs through the scrubber. */
+function event(name, properties = {}) {
+	analytics.capture(machineId(), name, redactObject({
+		...baseProps(),
+		...properties
+	}));
 }
 function startCommand(name) {
 	currentCommand = name;
 	commandStartedAt = Date.now();
 	lastErrorType = void 0;
-	const span = startSpan(name);
+	currentSpan = errors.startSpan(name);
 	event("command_started", { dry_run: process.argv.includes("--dry-run") });
 	return (ok) => {
-		if (span) {
-			span.setStatus({ code: ok ? 1 : 2 });
-			span.end();
-		}
+		currentSpan?.setStatus(ok);
+		currentSpan?.end();
 		event(ok ? "command_completed" : "command_failed", {
 			status: ok ? "ok" : "fail",
 			duration_ms: Date.now() - commandStartedAt,
@@ -5960,26 +6100,16 @@ function startCommand(name) {
 }
 function captureException(err) {
 	lastErrorType = err instanceof Error ? err.constructor.name : "Error";
-	if (!sentryEnabled()) return;
-	Sentry.captureException(err);
+	errors.captureException(err);
 }
 function endSession() {
-	if (!sentryEnabled()) return;
-	Sentry.endSession();
+	errors.endSession();
 }
 async function flush() {
-	if (sentryEnabled()) await Sentry.close(2e3);
-	if (posthog) {
-		await posthog.shutdown();
-		posthog = void 0;
-	}
-}
-const TOKEN_RE = /\b(ghp_|ghs_|glpat-|xoxb-|xoxp-|npm_|sk-|[A-Z][A-Z0-9_]{2,}_TOKEN[=\s])[^\s"]*/g;
-function redact(raw) {
-	return raw.replace(TOKEN_RE, "[REDACTED]");
-}
-function scrubError(event, _hint) {
-	return JSON.parse(redact(JSON.stringify(event)));
+	await errors.flush();
+	await analytics.shutdown();
+	errors = new NoopErrorSink();
+	analytics = new NoopAnalyticsSink();
 }
 //#endregion
 //#region src/commands/sync-github.ts
@@ -6630,6 +6760,17 @@ function cliLoggerOpts(argv, resolved) {
 		org: resolveOrg(argv, resolved)
 	};
 }
+/**
+* Fold a loaded `holocron.config` into the running process: reconfigure the
+* logger from `log:`, then apply the `telemetry:` override layer. Every handler
+* that has called `loadConfig` runs this, so a repo's `telemetry.enabled: false`
+* (or `analytics: "none"`) is honoured for that command. Env still wins —
+* `applyConfig` only narrows what `init` already turned on.
+*/
+function applyResolvedConfig(argv, resolved) {
+	buildCliLogger(argv, cliLoggerOpts(argv, resolved));
+	applyConfig(resolved.telemetry);
+}
 /** Parses --token values and returns the context spread, or null on parse error (exits with code 1). */
 function tokenContext(rawTokens) {
 	if (!rawTokens?.length) return {};
@@ -6716,7 +6857,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
-		buildCliLogger(argv, cliLoggerOpts(argv, loaded.resolved));
+		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runDoctor({
 			loaded,
 			context: {
@@ -6737,7 +6878,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
-		buildCliLogger(argv, cliLoggerOpts(argv, loaded.resolved));
+		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runSetup({
 			loaded,
 			context: {
@@ -6804,7 +6945,7 @@ try {
 		const scopeArg = argv.scope;
 		const scope = parseScope(scopeArg);
 		const loaded = await loadConfig(argv.cwd);
-		buildCliLogger(argv, cliLoggerOpts(argv, loaded.resolved));
+		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runSecretSet({
 			loaded,
 			context: {
@@ -6834,7 +6975,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
-		buildCliLogger(argv, cliLoggerOpts(argv, loaded.resolved));
+		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runSecretsSync({
 			loaded,
 			context: {
@@ -6863,7 +7004,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
-		buildCliLogger(argv, cliLoggerOpts(argv, loaded.resolved));
+		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runDeploy({
 			loaded,
 			context: {
@@ -6891,7 +7032,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
-		buildCliLogger(argv, cliLoggerOpts(argv, loaded.resolved));
+		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runCleanupPreview({
 			loaded,
 			context: {
@@ -6939,7 +7080,7 @@ try {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const loaded = await loadConfig(argv.cwd);
-		buildCliLogger(argv, cliLoggerOpts(argv, loaded.resolved));
+		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runSync({
 			loaded,
 			context: {
@@ -7048,7 +7189,7 @@ try {
 		default: false
 	}), async (argv) => {
 		const loaded = await loadConfig(argv.cwd);
-		buildCliLogger(argv, cliLoggerOpts(argv, loaded.resolved));
+		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runSyncReadme({
 			loaded,
 			context: {