@zitadel/cli 0.1.0-alpha.11 → 0.1.0-alpha.12

package/dist/{oclif-B7lBzh3R.mjs → oclif-BoUVygsZ.mjs}

@@ -1,11 +1,14 @@
 import { Command, Flags } from "@oclif/core";
 import consola from "consola";
 import { ApiError } from "@zitadel/api/runtime/fetch";
+import { createHash, randomUUID } from "node:crypto";
 import { stringify } from "safe-stable-stringify";
 import { dirname, join, resolve } from "node:path";
 import { access, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
-import { constants } from "node:fs";
+import { constants, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import mixpanelLib from "mixpanel";
+import { homedir } from "node:os";
 //#region src/lib/errors.ts
 /**
 * Maps each {@link ZitadelErrorCode} to the process exit code the CLI
@@ -508,6 +511,582 @@ function readEnvServer(config, environment) {
 	return typeof branch.server === "string" ? branch.server : void 0;
 }
 //#endregion
+//#region src/lib/telemetry/config.ts
+/**
+* Resolves the Mixpanel ingestion token and API host for a CLI invocation.
+*
+* The token is a *write-only* project token: it can ingest events but cannot
+* read data back, so — unlike the project service-key — it is safe to ship
+* inside the published CLI. This mirrors how Next.js, Astro, and other dev
+* tools embed their telemetry token, and is the only workable model for a CLI
+* (we cannot ask end users to supply one). It is intentionally not a secret.
+*
+* Dev and prod are separate Mixpanel projects (the skill's Phase 2 rule: never
+* track dev traffic into the production project). By default the channel comes
+* from a build-time stamp (see {@link resolveChannel}), so the published CLI
+* routes real user traffic to production without any per-user env var while
+* source/test runs stay on dev — but a runtime `ZITADEL_TELEMETRY_ENV` or
+* `ZITADEL_TELEMETRY_BUILD_CHANNEL` overrides the stamp, and
+* `ZITADEL_TELEMETRY_TOKEN` overrides the token outright.
+*/
+/**
+* Development project token. Safe to commit (write-only ingestion key). Used
+* when running from source or any non-production build.
+*/
+const DEV_TELEMETRY_TOKEN = "0fb432b08a9797b87b0eebcbee11706e";
+/**
+* Production project token. Used by the published CLI (the build stamps the
+* production channel) and any `ZITADEL_TELEMETRY_ENV=production` run. Write-only
+* ingestion key, like the dev token — safe to commit.
+*/
+const PROD_TELEMETRY_TOKEN = "f56fd7315ccd614fba8eecb2a8966152";
+/** Mixpanel API hosts by data-residency region. */
+const HOSTS = {
+	us: "api.mixpanel.com",
+	eu: "api-eu.mixpanel.com"
+};
+/**
+* Channel stamped into the bundle at build time. tsdown's `define` always
+* replaces the bare `__ZITADEL_TELEMETRY_CHANNEL__` identifier — with
+* `"development"` by default and `"production"` only in the release build — so
+* the shipped CLI routes to the right project with no per-user env var. The
+* identifier is undefined only in unbundled runs (e.g. unit tests importing this
+* module directly); the `typeof` guard returns `""` there so those runs fall
+* through to the dev default without a ReferenceError.
+*/
+function buildStampedChannel() {
+	return "development".trim().toLowerCase();
+}
+/**
+* Decide which project the events belong to. Precedence: an explicit
+* `ZITADEL_TELEMETRY_ENV`, then a `ZITADEL_TELEMETRY_BUILD_CHANNEL` env override
+* (handy for CI/release), then the build-time channel stamp. The default —
+* source/dev/test — is the dev project. Ambient `NODE_ENV` is deliberately NOT
+* consulted: a source build with `NODE_ENV=production` must not route dev
+* traffic to prod, nor a published run with `NODE_ENV=development` to dev.
+*/
+function resolveChannel(env) {
+	const explicit = (env.ZITADEL_TELEMETRY_ENV ?? "").trim().toLowerCase();
+	if (explicit === "production") return "production";
+	if (explicit === "development") return "development";
+	return (env.ZITADEL_TELEMETRY_BUILD_CHANNEL ?? buildStampedChannel()).trim().toLowerCase() === "production" ? "production" : "development";
+}
+/**
+* Resolve the ingestion token, or `undefined` when none is configured for the
+* active channel. A `ZITADEL_TELEMETRY_TOKEN` override wins outright; otherwise
+* the channel's baked token is used. An empty string (e.g. the unset prod
+* token) resolves to `undefined`, which the caller treats as "telemetry off".
+*/
+function resolveTelemetryToken(env) {
+	const override = env.ZITADEL_TELEMETRY_TOKEN?.trim();
+	if (override) return override;
+	const token = resolveChannel(env) === "production" ? PROD_TELEMETRY_TOKEN : DEV_TELEMETRY_TOKEN;
+	return token.length > 0 ? token : void 0;
+}
+/**
+* Resolve the Mixpanel API host from `ZITADEL_TELEMETRY_REGION`. Defaults to the
+* EU host, because the Zitadel Mixpanel projects live in the EU data-residency
+* region. Set `ZITADEL_TELEMETRY_REGION=us` for a US-hosted project — events
+* sent to the wrong host are silently dropped, so verify the first event lands
+* in Live View.
+*/
+function resolveTelemetryHost(env) {
+	return (env.ZITADEL_TELEMETRY_REGION ?? "eu").trim().toLowerCase() === "us" ? HOSTS.us : HOSTS.eu;
+}
+//#endregion
+//#region src/lib/telemetry/consent.ts
+const DISABLED_VALUES$1 = new Set([
+	"",
+	"0",
+	"false",
+	"off",
+	"no"
+]);
+/**
+* Resolve telemetry consent under an opt-out model: on by default, but any of
+* several explicit signals turns it off, in precedence order.
+*
+* 1. `--no-telemetry` on the command line — the most explicit, per-invocation.
+* 2. An automated test run (`VITEST`/`NODE_ENV=test`) — never emit synthetic
+*    traffic or pay the shutdown flush; spawned CLI subprocesses inherit it.
+* 3. `DO_NOT_TRACK` — the cross-tool standard (https://consoledonottrack.com);
+*    any value other than `0`/empty disables.
+* 4. `ZITADEL_TELEMETRY` set to a falsey token (`0`/`false`/`off`/`no`).
+* 5. No ingestion token configured for the active channel — nothing to send to,
+*    so telemetry is inert regardless of consent.
+*
+* Consent being enabled does not by itself send anything; the caller still
+* builds the client lazily and fails open on any transport error.
+*/
+function resolveConsent(input) {
+	if (input.flag === false) return {
+		enabled: false,
+		reason: "flag-opt-out"
+	};
+	if (input.env.VITEST || input.env.NODE_ENV === "test") return {
+		enabled: false,
+		reason: "test-runner"
+	};
+	const doNotTrack = input.env.DO_NOT_TRACK?.trim();
+	if (doNotTrack && doNotTrack !== "0") return {
+		enabled: false,
+		reason: "do-not-track"
+	};
+	const explicit = input.env.ZITADEL_TELEMETRY?.trim().toLowerCase();
+	if (explicit !== void 0 && DISABLED_VALUES$1.has(explicit)) return {
+		enabled: false,
+		reason: "env-opt-out"
+	};
+	const token = resolveTelemetryToken(input.env);
+	if (!token) return {
+		enabled: false,
+		reason: "no-token"
+	};
+	return {
+		enabled: true,
+		reason: "enabled",
+		token
+	};
+}
+//#endregion
+//#region src/lib/telemetry/identity.ts
+/**
+* Resolve the directory the CLI persists cross-invocation state in, honoring
+* the platform conventions: `XDG_CONFIG_HOME` then `~/.config` on Unix, and
+* `%APPDATA%` on Windows. The anonymous id lives here so it survives between
+* runs without touching the user's project tree.
+*/
+function telemetryConfigDir(env) {
+	if (process.platform === "win32" && env.APPDATA) return join(env.APPDATA, "zitadel", "cli");
+	return join(env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config"), "zitadel", "cli");
+}
+/**
+* Load the persisted anonymous id, minting and storing a new one on first run.
+*
+* Fail-open: if the config dir cannot be resolved, read, or written — including
+* an `os.homedir()` throw in a restricted/containerized environment, a
+* read-only home, a CI sandbox, or a permissions error — fall back to an
+* ephemeral per-process id and report `isFirstRun: false` so we neither crash
+* nor nag the user with the notice on every run. Telemetry is best-effort,
+* never load-bearing.
+*/
+function loadOrCreateIdentity(env) {
+	let dir;
+	try {
+		dir = telemetryConfigDir(env);
+	} catch {
+		return {
+			distinctId: randomUUID(),
+			isFirstRun: false
+		};
+	}
+	const file = join(dir, "telemetry.json");
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		if (typeof parsed.distinctId === "string" && parsed.distinctId.length > 0) return {
+			distinctId: parsed.distinctId,
+			isFirstRun: false
+		};
+	} catch {}
+	const distinctId = randomUUID();
+	try {
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(file, `${JSON.stringify({ distinctId })}\n`, { mode: 384 });
+		return {
+			distinctId,
+			isFirstRun: true
+		};
+	} catch {
+		return {
+			distinctId,
+			isFirstRun: false
+		};
+	}
+}
+//#endregion
+//#region src/lib/telemetry/util.ts
+/**
+* Return a new bag with empty values stripped, per Mixpanel's "omit, never send
+* null/''" rule. Pure — the input is never mutated.
+*/
+function compact(properties) {
+	return Object.fromEntries(Object.entries(properties).filter(([, value]) => value !== void 0 && value !== null && value !== ""));
+}
+//#endregion
+//#region src/lib/telemetry/index.ts
+/**
+* A generic, application-agnostic Mixpanel client wrapper for a single short
+* process. It knows nothing about commands, CLIs, or event names — callers
+* supply fully-built property bags. Its only opinions are operational, because
+* telemetry must never degrade the host program:
+*
+* - Never throws — a missing token, opt-out, or transport error all degrade to
+*   a silent no-op.
+* - Never blocks beyond {@link shutdown}'s timeout.
+* - Never writes to stdout; the optional debug trace goes to stderr.
+*
+* Inputs are treated as immutable: {@link track}/{@link profile} build a new
+* payload via spread and never mutate the bag they are given.
+*/
+var Telemetry = class Telemetry {
+	pending = [];
+	constructor(client, distinctId, isFirstRun, debug, newId) {
+		this.client = client;
+		this.distinctId = distinctId;
+		this.isFirstRun = isFirstRun;
+		this.debug = debug;
+		this.newId = newId;
+	}
+	/** Whether events will actually be sent (consent granted and a token configured). */
+	get enabled() {
+		return this.client !== void 0;
+	}
+	/**
+	* Resolve consent, identity, token, and host, then build the Mixpanel client
+	* lazily — only when consent is granted *and* a token is configured. Any
+	* failure along the way yields an inert instance whose methods are no-ops.
+	*/
+	static create(deps) {
+		const newId = deps.newId ?? randomUUID;
+		const debug = deps.debug ?? false;
+		const inert = (firstRun) => new Telemetry(void 0, "", firstRun, debug, newId);
+		const consent = resolveConsent({
+			env: deps.env,
+			flag: deps.flag
+		});
+		if (debug) process.stderr.write(`[telemetry] consent: ${consent.reason}\n`);
+		if (!consent.enabled || !consent.token) return inert(false);
+		const identity = (deps.loadIdentity ?? loadOrCreateIdentity)(deps.env);
+		let client;
+		try {
+			client = (deps.initClient ?? defaultInit)(consent.token, resolveTelemetryHost(deps.env));
+		} catch {
+			return inert(identity.isFirstRun);
+		}
+		return new Telemetry(client, identity.distinctId, identity.isFirstRun, debug, newId);
+	}
+	/** Send an event with the given properties; `distinct_id`/`$insert_id` are stamped here. */
+	track(event, properties) {
+		if (!this.client) return;
+		const payload = compact({
+			...properties,
+			distinct_id: this.distinctId,
+			$insert_id: this.newId()
+		});
+		if (this.debug) process.stderr.write(`[telemetry] ${event} ${JSON.stringify(payload)}\n`);
+		this.enqueue((client, done) => client.track(event, payload, done));
+	}
+	/** Write a user profile via the People API. `modifiers` carries `$ip` etc. */
+	profile(properties, modifiers = {}) {
+		if (!this.client) return;
+		const payload = compact(properties);
+		if (this.debug) process.stderr.write(`[telemetry] people.set ${JSON.stringify(payload)}\n`);
+		this.enqueue((client, done) => client.people.set(this.distinctId, payload, modifiers, done));
+	}
+	/**
+	* Await in-flight sends so a short-lived process does not exit before the
+	* requests complete, bounded by `timeoutMs`. The timeout is unref'd so the
+	* losing race branch never holds the event loop open or needs a manual clear.
+	* Safe to call on an inert instance.
+	*/
+	async shutdown(timeoutMs = 2e3) {
+		if (this.pending.length === 0) return;
+		await Promise.race([Promise.allSettled(this.pending), setTimeout$1(timeoutMs, void 0, { ref: false })]);
+	}
+	/**
+	* Enqueue one fire-and-forget send. Resolves (never rejects) on any failure —
+	* a synchronous throw or an error callback must not surface to the caller or
+	* leak as an unhandled rejection.
+	*/
+	enqueue(send) {
+		const client = this.client;
+		if (!client) return;
+		this.pending.push(new Promise((resolve) => {
+			try {
+				send(client, () => resolve());
+			} catch {
+				resolve();
+			}
+		}));
+	}
+};
+/** Real Mixpanel client construction, isolated so {@link Telemetry.create} can swap it in tests. */
+function defaultInit(token, host) {
+	return mixpanelLib.init(token, {
+		host,
+		geolocate: false
+	});
+}
+//#endregion
+//#region src/lib/telemetry/dimensions/env-flag.ts
+const DISABLED_VALUES = new Set([
+	"",
+	"0",
+	"false",
+	"off",
+	"no"
+]);
+/**
+* Whether an environment variable is set to an enabled value. A present-but-
+* falsey string (`CI=false`, `CI=0`) counts as disabled — unlike a bare
+* `Boolean(env.CI)` check, which is true for any non-empty string.
+*/
+function envEnabled(value) {
+	return value !== void 0 && !DISABLED_VALUES.has(value.trim().toLowerCase());
+}
+//#endregion
+//#region src/lib/telemetry/dimensions/ci-flag.ts
+/** Whether the process is running inside an automated CI environment. */
+var CiFlag = class {
+	value(env) {
+		return envEnabled(env.CI) || envEnabled(env.GITHUB_ACTIONS) || envEnabled(env.GITLAB_CI);
+	}
+};
+const ciFlag = new CiFlag();
+const ciProvider = new class CiProvider {
+	/** Provider-marker env var → reported name, in match order. */
+	static providers = [
+		["GITHUB_ACTIONS", "github_actions"],
+		["GITLAB_CI", "gitlab_ci"],
+		["CIRCLECI", "circleci"],
+		["BUILDKITE", "buildkite"],
+		["JENKINS_URL", "jenkins"]
+	];
+	value(env) {
+		const named = CiProvider.providers.find(([marker]) => envEnabled(env[marker]));
+		if (named) return named[1];
+		return envEnabled(env.CI) ? "unknown" : void 0;
+	}
+}();
+//#endregion
+//#region src/lib/telemetry/dimensions/country.ts
+/**
+* ISO 3166-1 alpha-2 country for an IANA timezone, defaulting to the machine's
+* own zone. A curated subset of common zones — any zone not listed (or an
+* unknown/unavailable one) yields `undefined`, since we report no country
+* rather than guess. Derived from the timezone, never the IP, so no city or
+* region is ever inferred. The machine's own zone is resolved once and cached:
+* `Intl.DateTimeFormat` construction loads ICU data and is process-stable.
+*/
+var Country = class {
+	byTimezone = {
+		"Africa/Abidjan": "CI",
+		"Africa/Accra": "GH",
+		"Africa/Addis_Ababa": "ET",
+		"Africa/Algiers": "DZ",
+		"Africa/Cairo": "EG",
+		"Africa/Casablanca": "MA",
+		"Africa/Johannesburg": "ZA",
+		"Africa/Lagos": "NG",
+		"Africa/Nairobi": "KE",
+		"Africa/Tunis": "TN",
+		"America/Anchorage": "US",
+		"America/Argentina/Buenos_Aires": "AR",
+		"America/Bogota": "CO",
+		"America/Chicago": "US",
+		"America/Denver": "US",
+		"America/Halifax": "CA",
+		"America/Lima": "PE",
+		"America/Los_Angeles": "US",
+		"America/Mexico_City": "MX",
+		"America/New_York": "US",
+		"America/Phoenix": "US",
+		"America/Santiago": "CL",
+		"America/Sao_Paulo": "BR",
+		"America/Toronto": "CA",
+		"America/Vancouver": "CA",
+		"Asia/Bangkok": "TH",
+		"Asia/Dhaka": "BD",
+		"Asia/Dubai": "AE",
+		"Asia/Hong_Kong": "HK",
+		"Asia/Jakarta": "ID",
+		"Asia/Jerusalem": "IL",
+		"Asia/Karachi": "PK",
+		"Asia/Kolkata": "IN",
+		"Asia/Kuala_Lumpur": "MY",
+		"Asia/Manila": "PH",
+		"Asia/Riyadh": "SA",
+		"Asia/Seoul": "KR",
+		"Asia/Shanghai": "CN",
+		"Asia/Singapore": "SG",
+		"Asia/Taipei": "TW",
+		"Asia/Tehran": "IR",
+		"Asia/Tokyo": "JP",
+		"Australia/Adelaide": "AU",
+		"Australia/Brisbane": "AU",
+		"Australia/Melbourne": "AU",
+		"Australia/Perth": "AU",
+		"Australia/Sydney": "AU",
+		"Europe/Amsterdam": "NL",
+		"Europe/Athens": "GR",
+		"Europe/Berlin": "DE",
+		"Europe/Brussels": "BE",
+		"Europe/Bucharest": "RO",
+		"Europe/Budapest": "HU",
+		"Europe/Copenhagen": "DK",
+		"Europe/Dublin": "IE",
+		"Europe/Helsinki": "FI",
+		"Europe/Istanbul": "TR",
+		"Europe/Kyiv": "UA",
+		"Europe/Lisbon": "PT",
+		"Europe/London": "GB",
+		"Europe/Madrid": "ES",
+		"Europe/Moscow": "RU",
+		"Europe/Oslo": "NO",
+		"Europe/Paris": "FR",
+		"Europe/Prague": "CZ",
+		"Europe/Rome": "IT",
+		"Europe/Stockholm": "SE",
+		"Europe/Vienna": "AT",
+		"Europe/Warsaw": "PL",
+		"Europe/Zurich": "CH",
+		"Pacific/Auckland": "NZ",
+		"Pacific/Honolulu": "US"
+	};
+	machineZone;
+	machineZoneResolved = false;
+	value(timezone) {
+		const zone = timezone ?? this.resolveMachineZone();
+		return zone ? this.byTimezone[zone] : void 0;
+	}
+	resolveMachineZone() {
+		if (!this.machineZoneResolved) {
+			this.machineZoneResolved = true;
+			try {
+				this.machineZone = new Intl.DateTimeFormat().resolvedOptions().timeZone;
+			} catch {
+				this.machineZone = void 0;
+			}
+		}
+		return this.machineZone;
+	}
+};
+const country = new Country();
+const hostAgent = new class HostAgent {
+	/** Predicate → reported name, in match order. */
+	static agents = [
+		[(env) => Boolean(env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT), "claude_code"],
+		[(env) => Boolean(env.CURSOR_TRACE_ID || env.CURSOR_AGENT), "cursor"],
+		[(env) => env.TERM_PROGRAM === "vscode", "vscode"]
+	];
+	value(env) {
+		return HostAgent.agents.find(([matches]) => matches(env))?.[1] ?? "unknown";
+	}
+}();
+const invocationChannel = new class InvocationChannel {
+	/** Ordered so a more specific name wins — `pnpm` is matched before the `npm` prefix. */
+	static managers = [
+		"pnpm",
+		"yarn",
+		"bun",
+		"npm"
+	];
+	value(env) {
+		const userAgent = env.npm_config_user_agent ?? "";
+		return InvocationChannel.managers.find((manager) => userAgent.startsWith(manager)) ?? "unknown";
+	}
+}();
+const operatingSystem = new class OperatingSystem {
+	static labels = {
+		darwin: "Mac OS X",
+		win32: "Windows",
+		linux: "Linux",
+		freebsd: "BSD",
+		openbsd: "BSD",
+		netbsd: "BSD",
+		aix: "AIX",
+		sunos: "Solaris"
+	};
+	value(platform) {
+		return OperatingSystem.labels[platform] ?? platform;
+	}
+}();
+//#endregion
+//#region src/lib/oclif/server-kind.ts
+/**
+* Buckets the resolved backend `source` into a coarse kind. The raw URL is never
+* emitted — it can carry an internal/self-hosted hostname — only which kind of
+* backend the command targeted.
+*/
+var ServerKind = class {
+	value(source) {
+		if (source === "mock") return "local";
+		if (!URL.canParse(source)) return "unknown";
+		const { hostname } = new URL(source);
+		if (hostname === "zitadel.cloud" || hostname.endsWith(".zitadel.cloud")) return "cloud";
+		if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1") return "local";
+		return "self_hosted";
+	}
+};
+const serverKind = new ServerKind();
+//#endregion
+//#region src/lib/oclif/command-telemetry.ts
+/**
+* CLI-specific telemetry glue: the only place that turns a {@link GlobalOptions}
+* invocation into the property bags the generic `Telemetry` client sends,
+* keeping `lib/telemetry` free of CLI coupling.
+*/
+const CLI_COMMAND_STARTED = "cli_command_started";
+const CLI_COMMAND_COMPLETED = "cli_command_completed";
+const CLI_COMMAND_FAILED = "cli_command_failed";
+const FIRST_RUN_NOTICE = "Zitadel CLI collects anonymous usage analytics to help improve the tool. No personal data, project details, server URLs, or file contents are ever collected. Opt out any time with DO_NOT_TRACK=1, ZITADEL_TELEMETRY=0, or the --no-telemetry flag.";
+/**
+* Process-stable device facts shared by both the event bag and the user
+* profile, so the two never disagree on the same install's OS/arch/version.
+*/
+function deviceProperties(meta) {
+	return {
+		$os: operatingSystem.value(process.platform),
+		$country_code: country.value(void 0),
+		os: process.platform,
+		arch: process.arch,
+		node_version: process.versions.node,
+		cli_version: meta.cliVersion
+	};
+}
+/**
+* Build the dimensions shared by every lifecycle event, merged with any
+* per-command `extra`. The allow-list: only enums, booleans, counts, and
+* versions cross the boundary — never URLs, project ids, file paths, emails, or
+* secrets. `extra` is spread first so the canonical base dimensions always win;
+* callers order their own extras so reserved lifecycle fields win over command
+* props.
+*/
+function commandEventProperties(meta, invocationId, extra = {}) {
+	const { env } = meta;
+	return {
+		...extra,
+		...deviceProperties(meta),
+		ip: 0,
+		invocation_id: invocationId,
+		command: meta.command,
+		non_interactive: meta.nonInteractive,
+		is_tty: meta.isTTY,
+		is_ci: ciFlag.value(env),
+		ci_provider: ciProvider.value(env),
+		host_agent: hostAgent.value(env),
+		invocation_channel: invocationChannel.value(env),
+		dry_run: meta.dryRun,
+		force: meta.force,
+		server_kind: serverKind.value(meta.source)
+	};
+}
+/**
+* Anonymous user-profile properties for this install, so the device appears
+* under Mixpanel "Users". Only non-PII device facts; `$name` is a readable,
+* non-identifying label that falls back to the OS when the host agent is
+* unknown. `$ip` is passed separately as a modifier by the caller.
+*/
+function deviceProfileProperties(meta, distinctId) {
+	const agent = hostAgent.value(meta.env);
+	const label = agent === "unknown" ? process.platform : agent;
+	return {
+		...deviceProperties(meta),
+		$name: `${label} · ${distinctId.slice(0, 8)}`,
+		host_agent: agent
+	};
+}
+//#endregion
 //#region src/lib/oclif/base.ts
 /**
 * Base class for every oclif command. Owns the global flags, builds the
@@ -543,11 +1122,50 @@ var BaseCommand = class extends Command {
 		}),
 		"dry-run": Flags.boolean({ description: "Preview without mutating files or the platform." }),
 		verbose: Flags.boolean({ description: "Verbose logging." }),
-		debug: Flags.boolean({ description: "Debug logging." })
+		debug: Flags.boolean({ description: "Debug logging." }),
+		telemetry: Flags.boolean({
+			default: true,
+			allowNo: true,
+			description: "Send anonymous usage analytics. Disable with --no-telemetry."
+		})
 	};
 	/** Resolved context for the current invocation; set by {@link toMeta}. */
 	meta = this.fallbackMeta();
 	/**
+	* Anonymous usage analytics for this invocation, created once in
+	* {@link toMeta}. Subclasses add command-specific dimensions (framework,
+	* counts, `step`, …) via {@link recordTelemetry}; the base class
+	* fires the lifecycle events and flushes in {@link finally}.
+	*/
+	telemetry;
+	/**
+	* Per-command dimensions merged onto each lifecycle event emitted *after* they
+	* are recorded — typically `completed`/`failed`, since `started` fires from
+	* {@link openTelemetry} before a command body runs. Updated immutably via
+	* {@link recordTelemetry} — never mutated in place.
+	*/
+	telemetryProps = Object.freeze({});
+	/** Correlates the started/completed pair; minted at instance construction. */
+	telemetryInvocationId = randomUUID();
+	/**
+	* Wall-clock start used to derive `duration_ms`. Captured at instance
+	* construction (before flag parsing and server resolution) so the duration
+	* covers the full invocation, even when telemetry is opened late from
+	* {@link catch} after an early failure.
+	*/
+	telemetryStartedAt = Date.now();
+	/**
+	* Merge command-specific dimensions into {@link telemetryProps} immutably: a
+	* new frozen bag replaces the previous one, so no shared object is ever
+	* mutated. `step` advances by re-recording it at each milestone.
+	*/
+	recordTelemetry(patch) {
+		this.telemetryProps = Object.freeze({
+			...this.telemetryProps,
+			...patch
+		});
+	}
+	/**
 	* Builds {@link GlobalOptions} from parsed flags, resolving the server
 	* `source` by the documented precedence and storing the result on
 	* `this.meta` so the error handler can render a complete envelope.
@@ -590,15 +1208,69 @@ var BaseCommand = class extends Command {
 			env: process.env,
 			isTTY
 		};
+		this.openTelemetry(typeof flags.telemetry === "boolean" ? flags.telemetry : void 0);
 		return this.meta;
 	}
 	/**
+	* Create telemetry once per invocation and open the lifecycle (started event +
+	* anonymous profile + first-run notice), reading every dimension from the
+	* current {@link meta}. Guarded so a command that resolves meta more than once
+	* does not double-count. Also called from {@link catch} so a failure thrown
+	* before {@link toMeta} finished (e.g. server resolution, flag parsing) still
+	* records the run. Returns early for an inert (opted-out / no-token /
+	* test-runner) instance so a disabled run never builds the property bags —
+	* no timezone→country resolution or URL parsing for users who opted out. The
+	* anonymous device profile is install-level and stable, so it is written only
+	* on first run rather than paying a `people.set` request on every command.
+	*/
+	/**
+	* Telemetry factory seam. Production returns the real {@link Telemetry.create};
+	* tests override it to inject a recording client and assert the lifecycle
+	* ordering and opt-out behaviour that the central Vitest consent guard would
+	* otherwise make untestable.
+	*/
+	createTelemetry(deps) {
+		return Telemetry.create(deps);
+	}
+	openTelemetry(flag) {
+		if (this.telemetry) return;
+		this.telemetry = this.createTelemetry({
+			env: process.env,
+			flag,
+			debug: this.meta.debug
+		});
+		if (!this.telemetry.enabled) return;
+		this.telemetry.track(CLI_COMMAND_STARTED, commandEventProperties(this.meta, this.telemetryInvocationId, this.telemetryProps));
+		if (this.telemetry.isFirstRun) {
+			this.telemetry.profile(deviceProfileProperties(this.meta, this.telemetry.distinctId), { $ip: 0 });
+			if (this.isInteractive()) process.stderr.write(`${FIRST_RUN_NOTICE}\n`);
+		}
+	}
+	/**
+	* Whether this invocation is an interactive human session, used to gate the
+	* one-time first-run notice. Derived from argv + `jsonEnabled()` + TTY rather
+	* than `meta.nonInteractive`, so it is correct even on the early-failure path
+	* where {@link catch} opens telemetry against a fallback meta that has not yet
+	* computed `nonInteractive` from the flags.
+	*/
+	isInteractive() {
+		if (this.meta.nonInteractive || this.jsonEnabled()) return false;
+		const argv = process.argv;
+		if (argv.includes("--json") || argv.includes("--non-interactive") || argv.includes("-n")) return false;
+		return Boolean(process.stdout.isTTY && process.stdin.isTTY);
+	}
+	/**
 	* Final step of every command: in human mode it prints the rendered result
 	* (oclif suppresses {@link Command.log} under `--json`); it returns the
 	* envelope so oclif's `--json` path serialises it.
 	*/
 	emit(result) {
 		const normalized = normalizeCommandResult(result, this.meta);
+		if (this.telemetry?.enabled) this.telemetry.track(CLI_COMMAND_COMPLETED, commandEventProperties(this.meta, this.telemetryInvocationId, {
+			...this.telemetryProps,
+			status: result.status,
+			duration_ms: Date.now() - this.telemetryStartedAt
+		}));
 		this.log(renderPretty(normalized, this.meta));
 		return toEnvelope(normalized, this.meta);
 	}
@@ -606,7 +1278,10 @@ var BaseCommand = class extends Command {
 	* Renders any thrown error as the failure envelope and exits with its code.
 	* A flag-parse error fires before {@link toMeta} runs, so the local `meta`
 	* here refreshes `command` from the now-resolved command id to keep the
-	* envelope's `command` field accurate.
+	* envelope's `command` field accurate. If that early failure left telemetry
+	* unopened, {@link openTelemetry} runs here so the failure is still recorded;
+	* the flag isn't parsed yet on that path, so `--no-telemetry` is honoured from
+	* argv.
 	*/
 	async catch(error) {
 		const meta = {
@@ -614,11 +1289,39 @@ var BaseCommand = class extends Command {
 			command: this.id ?? this.meta.command
 		};
 		const zitadelError = toZitadelError(error);
+		this.meta = meta;
+		this.openTelemetry(process.argv.includes("--no-telemetry") ? false : void 0);
+		if (this.telemetry?.enabled) this.telemetry.track(CLI_COMMAND_FAILED, commandEventProperties(meta, this.telemetryInvocationId, {
+			...this.telemetryProps,
+			status: "error",
+			reason: zitadelError.code,
+			exit_code: zitadelError.exitCode,
+			duration_ms: Date.now() - this.telemetryStartedAt
+		}));
 		if (this.jsonEnabled()) this.logJson(toErrorEnvelope(zitadelError, meta));
 		else this.logToStderr(renderError(zitadelError, meta));
 		return this.exit(zitadelError.exitCode);
 	}
 	/**
+	* oclif runs this after `run`/`catch` on every path. We flush pending
+	* telemetry so a short-lived CLI process does not exit before the lifecycle
+	* event is sent. The await is bounded by the flush budget, so a hung or
+	* firewalled network adds at most ~1s.
+	*
+	* `mixpanel@0.18` always uses keep-alive agents (hardcoded; not configurable)
+	* and exposes no request timeout or handle, so a completed *or* hung request
+	* leaves a socket that keeps Node's event loop open past the await. The
+	* failure path force-exits via oclif's `exit()`, but the success path would
+	* otherwise hang, so we arm an unref'd watchdog: it cannot keep the loop alive
+	* on a clean exit, but if a telemetry socket is still holding it open after
+	* the grace, it force-exits with the resolved code.
+	*/
+	async finally(error) {
+		await this.telemetry?.shutdown(1e3);
+		if (this.telemetry?.enabled) setTimeout(() => process.exit(process.exitCode ?? 0), 250).unref();
+		await super.finally(error);
+	}
+	/**
 	* Context used before {@link toMeta} runs, so an error thrown during flag
 	* parsing still renders a complete envelope. Version comes from oclif's
 	* resolved {@link Command.config}.
@@ -805,4 +1508,4 @@ function suffixBlock(opts) {
 //#endregion
 export { isObject as C, toZitadelError as D, ZitadelError as E, resolveCwd as S, stableStringify as T, runtimeSummary as _, DEFAULT_LOCAL_SERVER_PORT as a, publicCliCommand as b, checkLocalServerHealth as c, ensureLocalState as d, localContainerName as f, removeRuntimeMetadata as g, removeLocalData as h, CONTAINER_HTTP_PORT as i, defaultLocalServerImageForCliVersion as l, readRuntimeMetadata as m, DEFAULT_SERVER as n, DEFAULT_LOCAL_SERVER_URL as o, localServerUrl as p, CONTAINER_DATA_DIR as r, assertLocalStateWritable as s, BaseCommand as t, ensureContainerIdentity as u, writeRuntimeMetadata as v, parseJsonObject as w, MANAGED_MARKER as x, npmDistTagForCliVersion as y };
 
-//# sourceMappingURL=oclif-B7lBzh3R.mjs.map
+//# sourceMappingURL=oclif-BoUVygsZ.mjs.map