@theholocron/cli 4.13.0 → 4.14.0

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,165 @@ 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` import in the CLI. Product
+* analytics (usage, adoption, retention), activated self-contained per ADR-0008:
 *
-*   HOLOCRON_SENTRY_DSN  →  SENTRY_DSN  →  built-in fallback
+*   HOLOCRON_POSTHOG_PROJECT_TOKEN  →  POSTHOG_PROJECT_TOKEN  →  built-in fallback key
+*   HOLOCRON_POSTHOG_HOST           →  POSTHOG_HOST           →  https://us.i.posthog.com
 *
-* 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`.
+* The built-in fallback is an ingest-only project write key (`phc_…`) — it can
+* capture events, never read data — so it ships in the published package, the
+* same risk model as the hard-coded Sentry DSN. {@link resolvePostHogKey}
+* returning `""` is how the caller decides to install a `NoopAnalyticsSink`.
 */
-function resolveDsn() {
-	return env.get("HOLOCRON_SENTRY_DSN") ?? env.get("SENTRY_DSN") ?? FALLBACK_DSN;
-}
 const FALLBACK_POSTHOG_PROJECT_TOKEN = "phc_AC4vFCvYzwnzmG7Vg5nEc3PZKZztoPyfKp4Lb9BbXcLK";
 const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
-/**
-* Resolve the PostHog project key — mirrors {@link resolveDsn} and the
-* `HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN` pattern, per ADR-0008:
-*
-*   HOLOCRON_POSTHOG_PROJECT_TOKEN  →  POSTHOG_PROJECT_TOKEN  →  built-in fallback
-*
-* `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.
-*/
+/** 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;
 }
 function resolvePostHogHost() {
 	return env.get("HOLOCRON_POSTHOG_HOST") ?? env.get("POSTHOG_HOST") ?? DEFAULT_POSTHOG_HOST;
 }
+var PostHogSink = class {
+	#client;
+	constructor() {
+		this.#client = new PostHog(resolvePostHogKey(), { host: resolvePostHogHost() });
+	}
+	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/sentry-sink.ts
+const FALLBACK_DSN = "https://95cbb72ad5636c94e119a5405ee8f55f@o4508238154104832.ingest.us.sentry.io/4511810950791168";
+/** Resolve the Sentry DSN. `""` → error telemetry disabled. */
+function resolveDsn() {
+	return env.get("HOLOCRON_SENTRY_DSN") ?? env.get("SENTRY_DSN") ?? FALLBACK_DSN;
+}
+/** `beforeSend` — token-shaped strings never leave the process. */
+function scrubError(event, _hint) {
+	return redactObject(event);
+}
+var SentrySink = class {
+	init(ctx) {
+		Sentry.init({
+			dsn: resolveDsn(),
+			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 inside each sink. 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 +5988,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 +5997,74 @@ 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: {
+	if (isEnabled() && resolveDsn() !== "") {
+		errors = new SentrySink();
+		errors.init({
+			release: `holocron@${version}`,
+			environment: env.get("CI") ? "ci" : "local",
+			tags: {
+				os: process.platform,
+				node: process.version,
+				ci: String(Boolean(env.get("CI")))
+			}
+		});
+	}
+	if (isEnabled() && resolvePostHogKey() !== "") {
+		analytics = new PostHogSink();
+		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 +6074,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 +6734,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 +6831,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 +6852,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 +6919,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 +6949,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 +6978,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 +7006,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 +7054,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 +7163,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: {