@prisma-next/cli-telemetry 0.10.0-dev.8

package/dist/exports/index.mjs

@@ -0,0 +1,266 @@
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "pathe";
+//#region src/endpoint.ts
+/**
+* Production endpoint pinned to the deployed Prisma Compute backend.
+* Compiled as a build-time constant; not user-configurable.
+*/
+const TELEMETRY_BACKEND_URL = "https://cmpbfbsdp09hr3jf7pojjs5qs.ewr.prisma.build";
+/**
+* Path within the backend that accepts telemetry POSTs.
+*/
+const TELEMETRY_ENDPOINT_PATH = "/events";
+/**
+* Resolve the full POST URL the sender targets. The
+* `PRISMA_NEXT_TELEMETRY_ENDPOINT` env var is an integration-testing
+* affordance only — it lets the test suite spin up a mock HTTP server
+* on an ephemeral port and point the spawned sender at it. The override
+* is intentionally undocumented in user-facing material.
+*
+* Fail-open: a malformed override (typo in a dev shell, bad CI config)
+* silently falls back to the production backend rather than throwing,
+* matching the telemetry layer's broader silent-on-failure contract.
+*/
+function resolveTelemetryEndpoint(env = process.env) {
+	const override = env["PRISMA_NEXT_TELEMETRY_ENDPOINT"];
+	const base = override !== void 0 && override.length > 0 ? override : TELEMETRY_BACKEND_URL;
+	try {
+		return new URL(TELEMETRY_ENDPOINT_PATH, base).toString();
+	} catch {
+		return new URL(TELEMETRY_ENDPOINT_PATH, TELEMETRY_BACKEND_URL).toString();
+	}
+}
+//#endregion
+//#region src/gating.ts
+/**
+* A `PRISMA_NEXT_DISABLE_TELEMETRY` value counts as an opt-out only if
+* it parses as a truthy string. The set-but-falsy spellings (`''`,
+* `'0'`, `'false'`) are intentionally treated as not-set so a parent
+* shell that exports the variable to a benign value doesn't accidentally
+* disable telemetry for child processes.
+*/
+function isTruthyOptOut(raw) {
+	if (raw === void 0) return false;
+	const normalised = raw.trim().toLowerCase();
+	if (normalised === "") return false;
+	if (normalised === "0") return false;
+	if (normalised === "false") return false;
+	return true;
+}
+/**
+* Pure-function resolution of the gating decision. Same input → same
+* output; no I/O. The caller is responsible for reading the env and the
+* user config.
+*
+* Decision order:
+*   1. Env-var override (`PRISMA_NEXT_DISABLE_TELEMETRY` truthy, or
+*      `DO_NOT_TRACK=1`) → disabled.
+*   2. Stored `enableTelemetry === true` → enabled.
+*   3. Stored `enableTelemetry === false` → disabled (`stored-opt-out`).
+*   4. Stored `enableTelemetry === undefined` (file missing, or field
+*      not set) → disabled (`default-off`).
+*
+* Telemetry is enabled only when no env override is active **and**
+* `enableTelemetry` is explicitly `true`.
+*/
+function resolveGating(inputs) {
+	if (isTruthyOptOut(inputs.env["PRISMA_NEXT_DISABLE_TELEMETRY"]) || inputs.env["DO_NOT_TRACK"] === "1") return {
+		enabled: false,
+		reason: "env-override"
+	};
+	if (inputs.config.enableTelemetry === true) return { enabled: true };
+	if (inputs.config.enableTelemetry === false) return {
+		enabled: false,
+		reason: "stored-opt-out"
+	};
+	return {
+		enabled: false,
+		reason: "default-off"
+	};
+}
+//#endregion
+//#region src/sanitize.ts
+function flagNameFromLongName(longName) {
+	if (longName === null || !longName.startsWith("--")) return null;
+	const withoutPrefix = longName.slice(2);
+	return withoutPrefix.length > 0 ? withoutPrefix : null;
+}
+/**
+* Project commander's parsed result into the wire-shape command and
+* flag-name list. Pure; the only allowed inputs are the fields of
+* `CommanderResultShape`.
+*
+* Sanitiser contract — no flag values, no positionals, no raw argv:
+*   - Drop the root program name (`commandPath[0]`); the wire ships
+*     `migration new`, not `prisma-next migration new`.
+*   - Emit only options whose Commander source is `cli`.
+*   - Emit the long user-facing flag spelling without the `--` prefix;
+*     never emit Commander's camelCase attribute names.
+*   - `positionalArgs` is accepted but never consumed; the field exists
+*     in the input type to make it obvious at the call site that
+*     positionals were deliberately excluded.
+*/
+function sanitizeCommanderResult(input) {
+	return {
+		command: input.commandPath.slice(1).join(" "),
+		flags: input.options.flatMap((option) => {
+			if (option.source !== "cli") return [];
+			const flagName = flagNameFromLongName(option.longName);
+			return flagName === null ? [] : [flagName];
+		})
+	};
+}
+//#endregion
+//#region src/user-config.ts
+const APP_DIR = "prisma-next";
+const FILE_NAME = "config.json";
+/**
+* Resolves the user-level config directory:
+*   - Windows: `%APPDATA%\prisma-next\` (fallback: `%USERPROFILE%\AppData\Roaming\prisma-next\`).
+*   - Unix (incl. macOS): `$XDG_CONFIG_HOME/prisma-next/` if set, else
+*     `$HOME/.config/prisma-next/` per the XDG Base Directory Specification.
+*
+* The spec deliberately picks XDG over the macOS-native
+* `~/Library/Preferences/` convention so the path resolution is
+* test-overridable via `XDG_CONFIG_HOME` and matches the documented
+* behaviour on all *nix platforms. We intentionally do not use
+* `env-paths`: its macOS choice of `~/Library/Preferences` is for
+* OS-managed plist preferences, not arbitrary JSON files. Apple documents
+* that apps access that directory through system APIs such as
+* `NSUserDefaults`, while cross-platform CLI and developer tools conventionally
+* use `~/.config` on macOS too:
+* https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html
+*/
+function configDir() {
+	if (process.platform === "win32") {
+		const appData = process.env["APPDATA"];
+		if (appData !== void 0 && appData.length > 0) return join(appData, APP_DIR);
+		return join(homedir(), "AppData", "Roaming", APP_DIR);
+	}
+	const xdg = process.env["XDG_CONFIG_HOME"];
+	if (xdg !== void 0 && xdg.length > 0) return join(xdg, APP_DIR);
+	return join(homedir(), ".config", APP_DIR);
+}
+/**
+* Path to the user-level config file. Resolved per call so test
+* harnesses can mutate `$XDG_CONFIG_HOME` between cases.
+*/
+function userConfigPath() {
+	return join(configDir(), FILE_NAME);
+}
+/**
+* Reads the user-level config. File-missing, unreadable, or malformed →
+* `{}` (the absence of consent is the same answer in every error mode).
+* Unknown fields from a future client are passed through verbatim.
+*/
+function readUserConfig() {
+	const path = userConfigPath();
+	if (!existsSync(path)) return {};
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+		return {};
+	} catch {
+		return {};
+	}
+}
+/**
+* Merges `partial` into the current config and writes the result
+* atomically (temp file + rename) so a crash mid-write never leaves a
+* half-baked file readable on disk. Unknown fields already on disk are
+* preserved.
+*
+* When `partial.enableTelemetry === true` and no `installationId` is
+* stored yet, generates a v4 random UUID and persists both fields in
+* the same write. An existing `installationId` is never rotated.
+*
+* `writeUserConfig({ enableTelemetry: false })` does *not* generate an
+* installation id — only an affirmative consent answer produces one.
+*/
+function writeUserConfig(partial) {
+	const merged = {
+		...readUserConfig(),
+		...partial
+	};
+	if (partial.enableTelemetry === true && merged["installationId"] === void 0) merged["installationId"] = randomUUID();
+	const path = userConfigPath();
+	const dir = dirname(path);
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	const tmpPath = `${path}.${process.pid}.tmp`;
+	writeFileSync(tmpPath, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+	renameSync(tmpPath, path);
+}
+//#endregion
+//#region src/spawn.ts
+function runTelemetry(inputs) {
+	const env = inputs.env ?? process.env;
+	if (inputs.isCI) return {
+		spawned: false,
+		reason: "ci"
+	};
+	const config = inputs.userConfig ?? readUserConfig();
+	if (!resolveGating({
+		env,
+		config
+	}).enabled) return {
+		spawned: false,
+		reason: "gated-off"
+	};
+	const sanitised = sanitizeCommanderResult(inputs.command);
+	if (typeof config.installationId !== "string" || config.installationId.length === 0) return {
+		spawned: false,
+		reason: "gated-off"
+	};
+	const payload = {
+		installationId: config.installationId,
+		version: inputs.version,
+		command: sanitised.command,
+		flags: sanitised.flags,
+		databaseTarget: inputs.databaseTarget,
+		extensions: inputs.extensions,
+		projectRoot: inputs.projectRoot,
+		endpoint: resolveTelemetryEndpoint(env)
+	};
+	try {
+		const child = fork(inputs.senderPath, [], {
+			detached: true,
+			stdio: [
+				"pipe",
+				"ignore",
+				"ignore",
+				"ipc"
+			]
+		});
+		child.send(payload, (err) => {
+			if (err !== null && process.env["PRISMA_NEXT_DEBUG"] === "1") process.stderr.write(`[cli-telemetry] parent send error: ${String(err)}\n`);
+		});
+		child.disconnect();
+		child.unref();
+		return { spawned: true };
+	} catch (err) {
+		if (process.env["PRISMA_NEXT_DEBUG"] === "1") process.stderr.write(`[cli-telemetry] parent fork failed: ${String(err)}\n`);
+		return {
+			spawned: false,
+			reason: "fork-failed"
+		};
+	}
+}
+/**
+* Resolve the path to the compiled sender entry relative to a consumer
+* that has captured its own `import.meta.url`. The CLI's
+* `tsdown`-emitted entry sits at `<package>/dist/sender.mjs`; the
+* consumer asks `senderModuleUrl()` and forwards the result to
+* `runTelemetry({ senderPath })`.
+*/
+function senderModuleUrl(importMetaUrl) {
+	return fileURLToPath(new URL("./sender.mjs", importMetaUrl));
+}
+//#endregion
+export { TELEMETRY_BACKEND_URL, TELEMETRY_ENDPOINT_PATH, readUserConfig, resolveGating, resolveTelemetryEndpoint, runTelemetry, sanitizeCommanderResult, senderModuleUrl, userConfigPath, writeUserConfig };
+
+//# sourceMappingURL=index.mjs.map

package/dist/exports/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/endpoint.ts","../../src/gating.ts","../../src/sanitize.ts","../../src/user-config.ts","../../src/spawn.ts"],"sourcesContent":["/**\n * Production endpoint pinned to the deployed Prisma Compute backend.\n * Compiled as a build-time constant; not user-configurable.\n */\nexport const TELEMETRY_BACKEND_URL = 'https://cmpbfbsdp09hr3jf7pojjs5qs.ewr.prisma.build';\n\n/**\n * Path within the backend that accepts telemetry POSTs.\n */\nexport const TELEMETRY_ENDPOINT_PATH = '/events';\n\n/**\n * Resolve the full POST URL the sender targets. The\n * `PRISMA_NEXT_TELEMETRY_ENDPOINT` env var is an integration-testing\n * affordance only — it lets the test suite spin up a mock HTTP server\n * on an ephemeral port and point the spawned sender at it. The override\n * is intentionally undocumented in user-facing material.\n *\n * Fail-open: a malformed override (typo in a dev shell, bad CI config)\n * silently falls back to the production backend rather than throwing,\n * matching the telemetry layer's broader silent-on-failure contract.\n */\nexport function resolveTelemetryEndpoint(\n  env: Readonly<Record<string, string | undefined>> = process.env,\n): string {\n  const override = env['PRISMA_NEXT_TELEMETRY_ENDPOINT'];\n  const base = override !== undefined && override.length > 0 ? override : TELEMETRY_BACKEND_URL;\n  try {\n    return new URL(TELEMETRY_ENDPOINT_PATH, base).toString();\n  } catch {\n    return new URL(TELEMETRY_ENDPOINT_PATH, TELEMETRY_BACKEND_URL).toString();\n  }\n}\n","import type { UserConfig } from './user-config';\n\n/**\n * Why telemetry was disabled. Useful for debug-mode logging in the\n * parent; never surfaces to users.\n */\nexport type GatingDisabledReason = 'env-override' | 'stored-opt-out' | 'default-off';\n\nexport type GatingResolution =\n  | { readonly enabled: true }\n  | { readonly enabled: false; readonly reason: GatingDisabledReason };\n\nexport interface GatingInputs {\n  /**\n   * Environment-variable lookups the resolver consults. Tests pass a\n   * literal record; production passes `process.env`. The two opt-out\n   * signals are `PRISMA_NEXT_DISABLE_TELEMETRY` (Prisma-specific) and\n   * `DO_NOT_TRACK` (community convention).\n   */\n  readonly env: Readonly<Record<string, string | undefined>>;\n  /** Result of `readUserConfig()` — file-missing tolerated as `{}`. */\n  readonly config: UserConfig;\n}\n\n/**\n * A `PRISMA_NEXT_DISABLE_TELEMETRY` value counts as an opt-out only if\n * it parses as a truthy string. The set-but-falsy spellings (`''`,\n * `'0'`, `'false'`) are intentionally treated as not-set so a parent\n * shell that exports the variable to a benign value doesn't accidentally\n * disable telemetry for child processes.\n */\nfunction isTruthyOptOut(raw: string | undefined): boolean {\n  if (raw === undefined) return false;\n  const normalised = raw.trim().toLowerCase();\n  if (normalised === '') return false;\n  if (normalised === '0') return false;\n  if (normalised === 'false') return false;\n  return true;\n}\n\n/**\n * Pure-function resolution of the gating decision. Same input → same\n * output; no I/O. The caller is responsible for reading the env and the\n * user config.\n *\n * Decision order:\n *   1. Env-var override (`PRISMA_NEXT_DISABLE_TELEMETRY` truthy, or\n *      `DO_NOT_TRACK=1`) → disabled.\n *   2. Stored `enableTelemetry === true` → enabled.\n *   3. Stored `enableTelemetry === false` → disabled (`stored-opt-out`).\n *   4. Stored `enableTelemetry === undefined` (file missing, or field\n *      not set) → disabled (`default-off`).\n *\n * Telemetry is enabled only when no env override is active **and**\n * `enableTelemetry` is explicitly `true`.\n */\nexport function resolveGating(inputs: GatingInputs): GatingResolution {\n  if (\n    isTruthyOptOut(inputs.env['PRISMA_NEXT_DISABLE_TELEMETRY']) ||\n    inputs.env['DO_NOT_TRACK'] === '1'\n  ) {\n    return { enabled: false, reason: 'env-override' };\n  }\n  if (inputs.config.enableTelemetry === true) {\n    return { enabled: true };\n  }\n  if (inputs.config.enableTelemetry === false) {\n    return { enabled: false, reason: 'stored-opt-out' };\n  }\n  return { enabled: false, reason: 'default-off' };\n}\n","export interface CommanderOptionShape {\n  /** Commander's option attribute name, e.g. `dryRun` for `--dry-run`. */\n  readonly attributeName: string;\n  /** Commander's long, user-facing flag spelling, e.g. `--dry-run` or `--no-install`. */\n  readonly longName: string | null;\n  /** Commander's value source for this option. Only `cli` is user-supplied. */\n  readonly source: string | null;\n}\n\n/**\n * Input shape: a thin projection of commander's parsed-result surface.\n * The parent extracts the command path, positional args, and per-option\n * metadata from the leaf command. The sanitiser never consumes raw\n * argv, never reads `process.argv`, and never sees flag values.\n */\nexport interface CommanderResultShape {\n  /**\n   * The full command path from the root program to the leaf, including\n   * the root program name as the first element (the sanitiser drops it).\n   * Example: `['prisma-next', 'migration', 'new']`.\n   */\n  readonly commandPath: readonly string[];\n  /**\n   * Positional arguments commander parsed for the leaf command.\n   * **Intentionally never read.** Accepted so the call site doesn't have\n   * to think about whether to pass it; the sanitiser's contract is that\n   * positionals never leave the parent process.\n   */\n  readonly positionalArgs: readonly string[];\n  /**\n   * Per-option Commander metadata. The sanitiser emits only options whose\n   * source is `cli`, and uses `longName` so telemetry sees user-facing\n   * names (`dry-run`, `connection-string`, `no-install`) rather than\n   * Commander's internal camelCase attribute names or defaulted options.\n   */\n  readonly options: readonly CommanderOptionShape[];\n}\n\n/**\n * Output shape: the sanitised projection that flows into the telemetry\n * payload. Two fields only — command name (space-delimited subcommand\n * path) and flag names (in commander's option declaration order).\n */\nexport interface SanitisedCommand {\n  readonly command: string;\n  readonly flags: readonly string[];\n}\n\nfunction flagNameFromLongName(longName: string | null): string | null {\n  if (longName === null || !longName.startsWith('--')) return null;\n  const withoutPrefix = longName.slice(2);\n  return withoutPrefix.length > 0 ? withoutPrefix : null;\n}\n\n/**\n * Project commander's parsed result into the wire-shape command and\n * flag-name list. Pure; the only allowed inputs are the fields of\n * `CommanderResultShape`.\n *\n * Sanitiser contract — no flag values, no positionals, no raw argv:\n *   - Drop the root program name (`commandPath[0]`); the wire ships\n *     `migration new`, not `prisma-next migration new`.\n *   - Emit only options whose Commander source is `cli`.\n *   - Emit the long user-facing flag spelling without the `--` prefix;\n *     never emit Commander's camelCase attribute names.\n *   - `positionalArgs` is accepted but never consumed; the field exists\n *     in the input type to make it obvious at the call site that\n *     positionals were deliberately excluded.\n */\nexport function sanitizeCommanderResult(input: CommanderResultShape): SanitisedCommand {\n  const command = input.commandPath.slice(1).join(' ');\n  const flags = input.options.flatMap((option) => {\n    if (option.source !== 'cli') return [];\n    const flagName = flagNameFromLongName(option.longName);\n    return flagName === null ? [] : [flagName];\n  });\n  return { command, flags };\n}\n","import { randomUUID } from 'node:crypto';\nimport { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { dirname, join } from 'pathe';\n\n/**\n * The user-level config file. Persists the consent flag and the\n * installation UUID together so an env-var opt-out never mutates disk,\n * and so an opt-in → opt-out → opt-in cycle keeps the same UUID (correct\n * for MAU continuity).\n *\n * Readers tolerate unknown fields for forward compat; writers merge\n * partials into the existing object so unknown fields are preserved.\n */\nexport interface UserConfig {\n  readonly enableTelemetry?: boolean;\n  readonly installationId?: string;\n  readonly [key: string]: unknown;\n}\n\nconst APP_DIR = 'prisma-next';\nconst FILE_NAME = 'config.json';\n\n/**\n * Resolves the user-level config directory:\n *   - Windows: `%APPDATA%\\prisma-next\\` (fallback: `%USERPROFILE%\\AppData\\Roaming\\prisma-next\\`).\n *   - Unix (incl. macOS): `$XDG_CONFIG_HOME/prisma-next/` if set, else\n *     `$HOME/.config/prisma-next/` per the XDG Base Directory Specification.\n *\n * The spec deliberately picks XDG over the macOS-native\n * `~/Library/Preferences/` convention so the path resolution is\n * test-overridable via `XDG_CONFIG_HOME` and matches the documented\n * behaviour on all *nix platforms. We intentionally do not use\n * `env-paths`: its macOS choice of `~/Library/Preferences` is for\n * OS-managed plist preferences, not arbitrary JSON files. Apple documents\n * that apps access that directory through system APIs such as\n * `NSUserDefaults`, while cross-platform CLI and developer tools conventionally\n * use `~/.config` on macOS too:\n * https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html\n */\nfunction configDir(): string {\n  if (process.platform === 'win32') {\n    const appData = process.env['APPDATA'];\n    if (appData !== undefined && appData.length > 0) {\n      return join(appData, APP_DIR);\n    }\n    return join(homedir(), 'AppData', 'Roaming', APP_DIR);\n  }\n  const xdg = process.env['XDG_CONFIG_HOME'];\n  if (xdg !== undefined && xdg.length > 0) {\n    return join(xdg, APP_DIR);\n  }\n  return join(homedir(), '.config', APP_DIR);\n}\n\n/**\n * Path to the user-level config file. Resolved per call so test\n * harnesses can mutate `$XDG_CONFIG_HOME` between cases.\n */\nexport function userConfigPath(): string {\n  return join(configDir(), FILE_NAME);\n}\n\n/**\n * Reads the user-level config. File-missing, unreadable, or malformed →\n * `{}` (the absence of consent is the same answer in every error mode).\n * Unknown fields from a future client are passed through verbatim.\n */\nexport function readUserConfig(): UserConfig {\n  const path = userConfigPath();\n  if (!existsSync(path)) return {};\n  try {\n    const raw = readFileSync(path, 'utf-8');\n    const parsed: unknown = JSON.parse(raw);\n    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      return parsed as UserConfig;\n    }\n    return {};\n  } catch {\n    return {};\n  }\n}\n\n/**\n * Merges `partial` into the current config and writes the result\n * atomically (temp file + rename) so a crash mid-write never leaves a\n * half-baked file readable on disk. Unknown fields already on disk are\n * preserved.\n *\n * When `partial.enableTelemetry === true` and no `installationId` is\n * stored yet, generates a v4 random UUID and persists both fields in\n * the same write. An existing `installationId` is never rotated.\n *\n * `writeUserConfig({ enableTelemetry: false })` does *not* generate an\n * installation id — only an affirmative consent answer produces one.\n */\nexport function writeUserConfig(partial: Partial<UserConfig>): void {\n  const current = readUserConfig();\n  const merged: Record<string, unknown> = { ...current, ...partial };\n  if (partial.enableTelemetry === true && merged['installationId'] === undefined) {\n    merged['installationId'] = randomUUID();\n  }\n  const path = userConfigPath();\n  const dir = dirname(path);\n  if (!existsSync(dir)) {\n    mkdirSync(dir, { recursive: true });\n  }\n  const tmpPath = `${path}.${process.pid}.tmp`;\n  writeFileSync(tmpPath, `${JSON.stringify(merged, null, 2)}\\n`, 'utf-8');\n  renameSync(tmpPath, path);\n}\n","import { fork } from 'node:child_process';\nimport { fileURLToPath } from 'node:url';\nimport { resolveTelemetryEndpoint } from './endpoint';\nimport { resolveGating } from './gating';\nimport type { ParentToSenderPayload } from './payload';\nimport { type CommanderResultShape, sanitizeCommanderResult } from './sanitize';\nimport { readUserConfig, type UserConfig } from './user-config';\n\n/**\n * Inputs the CLI entry point hands the telemetry layer at command\n * start. The CLI is responsible for stitching commander's result, the\n * loaded config, and the project root together; the telemetry module\n * does no I/O of its own except for the user-config read (skipped when\n * `userConfig` is provided).\n */\nexport interface RunTelemetryInputs {\n  /** Sanitised commander snapshot — see `CommanderResultShape`. */\n  readonly command: CommanderResultShape;\n  /** This CLI's own version (from its `package.json`). */\n  readonly version: string;\n  /** Resolved `config.target.targetId`, or `null` when the config could not be loaded. */\n  readonly databaseTarget: string | null;\n  /** Declared extension-pack IDs, in any deterministic order. */\n  readonly extensions: readonly string[];\n  /** Absolute path of the project root (typically `process.cwd()`). */\n  readonly projectRoot: string;\n  /**\n   * Path to the sender entry compiled into this package's `dist/`.\n   * Resolved by the caller because the compiled sender lives at\n   * `<package>/dist/sender.mjs` and only the consumer knows its own\n   * `import.meta.url`.\n   */\n  readonly senderPath: string;\n  /**\n   * `isCI()` result from the consumer. Telemetry is suppressed when\n   * `true` regardless of the stored consent answer — CI environments\n   * never emit (matches the colour-output convention's CI suppression).\n   */\n  readonly isCI: boolean;\n  /** Process env to read for opt-out signals. Defaults to `process.env`. */\n  readonly env?: Readonly<Record<string, string | undefined>>;\n  /** Cached user config when the caller already read it to resolve gates before other work. */\n  readonly userConfig?: UserConfig;\n}\n\n/**\n * Best-effort telemetry spawn at command start. Returns synchronously —\n * the fork runs in the background and never blocks the parent. Every\n * failure mode is swallowed; the parent's stdout/stderr is untouched in\n * normal operation, the only escape valve being\n * `PRISMA_NEXT_DEBUG=1` which routes diagnostics to stderr.\n *\n * Returns the spawn outcome so debug-mode logging and the test-harness\n * probe (which verifies test runs short-circuit the fork) can inspect\n * the decision without scraping stderr.\n */\nexport type TelemetryRunOutcome =\n  | { readonly spawned: true }\n  | { readonly spawned: false; readonly reason: 'gated-off' | 'ci' | 'fork-failed' };\n\nexport function runTelemetry(inputs: RunTelemetryInputs): TelemetryRunOutcome {\n  const env = inputs.env ?? process.env;\n\n  if (inputs.isCI) {\n    return { spawned: false, reason: 'ci' };\n  }\n\n  const config = inputs.userConfig ?? readUserConfig();\n  const gating = resolveGating({ env, config });\n  if (!gating.enabled) {\n    return { spawned: false, reason: 'gated-off' };\n  }\n\n  const sanitised = sanitizeCommanderResult(inputs.command);\n  // Gating already confirmed enableTelemetry === true, so installationId\n  // must be set (writeUserConfig generates it alongside that field).\n  // Defence-in-depth: if a stale config has the flag but no id, skip\n  // rather than send a junk event.\n  if (typeof config.installationId !== 'string' || config.installationId.length === 0) {\n    return { spawned: false, reason: 'gated-off' };\n  }\n\n  const payload: ParentToSenderPayload = {\n    installationId: config.installationId,\n    version: inputs.version,\n    command: sanitised.command,\n    flags: sanitised.flags,\n    databaseTarget: inputs.databaseTarget,\n    extensions: inputs.extensions,\n    projectRoot: inputs.projectRoot,\n    endpoint: resolveTelemetryEndpoint(env),\n  };\n\n  try {\n    const child = fork(inputs.senderPath, [], {\n      detached: true,\n      stdio: ['pipe', 'ignore', 'ignore', 'ipc'],\n    });\n    child.send(payload, (err) => {\n      if (err !== null && process.env['PRISMA_NEXT_DEBUG'] === '1') {\n        process.stderr.write(`[cli-telemetry] parent send error: ${String(err)}\\n`);\n      }\n    });\n    child.disconnect();\n    child.unref();\n    return { spawned: true };\n  } catch (err) {\n    if (process.env['PRISMA_NEXT_DEBUG'] === '1') {\n      process.stderr.write(`[cli-telemetry] parent fork failed: ${String(err)}\\n`);\n    }\n    return { spawned: false, reason: 'fork-failed' };\n  }\n}\n\n/**\n * Resolve the path to the compiled sender entry relative to a consumer\n * that has captured its own `import.meta.url`. The CLI's\n * `tsdown`-emitted entry sits at `<package>/dist/sender.mjs`; the\n * consumer asks `senderModuleUrl()` and forwards the result to\n * `runTelemetry({ senderPath })`.\n */\nexport function senderModuleUrl(importMetaUrl: string): string {\n  return fileURLToPath(new URL('./sender.mjs', importMetaUrl));\n}\n"],"mappings":"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"}

package/dist/sender.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/sender.mjs

@@ -0,0 +1,253 @@
+import { readFileSync } from "node:fs";
+import { join } from "pathe";
+import { type } from "arktype";
+//#region src/detect-agent.ts
+const AGENT_MARKERS = [
+	{
+		envVar: "CLAUDECODE",
+		agent: "Claude Code"
+	},
+	{
+		envVar: "CURSOR_AGENT",
+		agent: "Cursor"
+	},
+	{
+		envVar: "CODEX_SANDBOX",
+		agent: "Codex CLI"
+	},
+	{
+		envVar: "GEMINI_CLI",
+		agent: "Gemini CLI"
+	},
+	{
+		envVar: "WINDSURF",
+		agent: "Windsurf"
+	},
+	{
+		envVar: "AIDER",
+		agent: "Aider"
+	},
+	{
+		envVar: "CODY",
+		agent: "Cody"
+	},
+	{
+		envVar: "CONTINUE",
+		agent: "Continue"
+	}
+];
+function isTruthyMarker(raw) {
+	if (raw === void 0) return false;
+	const normalised = raw.trim().toLowerCase();
+	if (normalised === "") return false;
+	if (normalised === "0") return false;
+	if (normalised === "false") return false;
+	return true;
+}
+/**
+* Resolve the agent label from an env snapshot, or `null` if no marker
+* is set. Returns the **first** matching marker in `AGENT_MARKERS`
+* order, so when multiple markers are set the agent label is
+* deterministic and the allowlist's first entry wins.
+*
+* Pure: takes an env record, returns a string or null. No I/O.
+*/
+function detectAgent(env) {
+	for (const marker of AGENT_MARKERS) if (isTruthyMarker(env[marker.envVar])) return marker.agent;
+	return null;
+}
+//#endregion
+//#region src/enrich.ts
+/**
+* Identify the runtime the sender is running in. Same-runtime as the
+* parent is a correctness requirement: the parent forked us via
+* `child_process.fork`, which inherits the parent's runtime. Detection
+* keys on the runtime-specific version field rather than env vars so a
+* spoofed env can't lie about the actual interpreter.
+*/
+function resolveRuntime(versions) {
+	if (versions.bun !== void 0) return {
+		name: "bun",
+		version: versions.bun
+	};
+	if (versions.deno !== void 0) return {
+		name: "deno",
+		version: versions.deno
+	};
+	return {
+		name: "node",
+		version: versions.node
+	};
+}
+/**
+* Parse `npm_config_user_agent` into a `<pm>/<version>` token. The
+* value, when present, looks like
+* `"pnpm/10.27.0 npm/? node/v24.13.0 darwin arm64"` — we take the first
+* whitespace-separated token. Any failure → `null`.
+*/
+function parsePackageManager(userAgent) {
+	if (userAgent === void 0) return null;
+	const first = userAgent.split(/\s+/)[0];
+	if (first === void 0 || first.length === 0) return null;
+	if (!first.includes("/")) return null;
+	return first;
+}
+/**
+* Read the user's project `package.json` and resolve a TypeScript
+* version from `devDependencies.typescript` (preferred) or
+* `dependencies.typescript`. Strips a leading `^` or `~` semver
+* prefix. Returns `null` on any failure mode — file missing,
+* unreadable, malformed JSON, key absent, not a string.
+*/
+function readTsVersionFromPackageJson(raw) {
+	if (raw === null) return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	const candidate = pickStringDep(parsed["devDependencies"]) ?? pickStringDep(parsed["dependencies"]);
+	if (candidate === null) return null;
+	return candidate.replace(/^[\^~]/, "");
+}
+function pickStringDep(deps) {
+	if (deps === null || typeof deps !== "object" || Array.isArray(deps)) return null;
+	const value = deps["typescript"];
+	return typeof value === "string" ? value : null;
+}
+/**
+* Build the full backend event from the parent's payload and the
+* child's per-process snapshot. Pure given an `EnrichEnvironment`.
+*/
+function buildTelemetryEvent(payload, env) {
+	const runtime = resolveRuntime(env.versions);
+	return {
+		installationId: payload.installationId,
+		version: payload.version,
+		command: payload.command,
+		flags: payload.flags,
+		runtimeName: runtime.name,
+		runtimeVersion: runtime.version,
+		os: env.platform,
+		arch: env.arch,
+		packageManager: parsePackageManager(env.env["npm_config_user_agent"]),
+		databaseTarget: payload.databaseTarget,
+		tsVersion: readTsVersionFromPackageJson(env.readProjectPackageJson()),
+		agent: detectAgent(env.env),
+		extensions: payload.extensions
+	};
+}
+/**
+* Convenience for the sender entry: build the event from the live
+* `process` plus a real project-package.json reader, swallowing any
+* I/O errors in the file read.
+*/
+function buildTelemetryEventFromProcess(payload) {
+	return buildTelemetryEvent(payload, {
+		platform: process.platform,
+		arch: process.arch,
+		versions: process.versions,
+		env: process.env,
+		readProjectPackageJson: () => {
+			try {
+				return readFileSync(join(payload.projectRoot, "package.json"), "utf-8");
+			} catch {
+				return null;
+			}
+		}
+	});
+}
+//#endregion
+//#region src/payload.ts
+/**
+* Runtime validator for {@link ParentToSenderPayload}. The child sender
+* uses this to gate `postEvent` so a payload missing a required field
+* cannot silently produce a degraded telemetry event downstream.
+*
+* Mirrors the backend's own arktype schema in spirit: required scalars
+* must be non-empty strings; `databaseTarget` is `string | null`; the
+* two string arrays are validated element-by-element. Size caps are
+* enforced by the backend, not here — IPC is structured-cloned and
+* the parent/child agree on the schema by version-coupling.
+*/
+const requiredString = type.string.moreThanLength(0);
+const stringArray = type.string.array();
+const parentToSenderPayloadSchema = type({
+	installationId: requiredString,
+	version: requiredString,
+	command: requiredString,
+	flags: stringArray,
+	databaseTarget: type.string.or("null"),
+	extensions: stringArray,
+	projectRoot: requiredString,
+	endpoint: requiredString
+});
+function isParentToSenderPayload(value) {
+	return !(parentToSenderPayloadSchema(value) instanceof type.errors);
+}
+//#endregion
+//#region src/sender.ts
+/**
+* Sender script entry — forked into a detached child by the parent CLI via
+* `child_process.fork(senderPath, [], { detached: true, ... })`.
+*
+* Lifecycle:
+*   1. Wait for the parent's IPC `message` event carrying a
+*      `ParentToSenderPayload`.
+*   2. Enrich with the local-process probes (runtime, os, arch, agent,
+*      package manager, tsVersion).
+*   3. POST the event to the endpoint URL with a hard 1.5 s timeout.
+*   4. Exit 0 unconditionally — successful POST, network failure, server
+*      error, parse error of the response, anything else: same outcome.
+*
+* Every error is swallowed; the only escape valve for visibility is
+* `PRISMA_NEXT_DEBUG=1`, which routes diagnostics to stderr. In normal
+* operation no telemetry-originating output ever reaches the user — the
+* parent's stdio map ignores our streams anyway, but we also gate
+* stderr writes behind the debug flag so the same binary is safe to
+* invoke directly outside the spawn flow.
+*/
+const REQUEST_TIMEOUT_MS = 1500;
+function debugLog(message, error) {
+	if (process.env["PRISMA_NEXT_DEBUG"] !== "1") return;
+	if (error !== void 0) process.stderr.write(`[cli-telemetry] ${message}: ${String(error)}\n`);
+	else process.stderr.write(`[cli-telemetry] ${message}\n`);
+}
+async function postEvent(payload) {
+	const event = buildTelemetryEventFromProcess(payload);
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+	try {
+		debugLog(`sent event: status=${(await fetch(payload.endpoint, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(event),
+			signal: controller.signal
+		})).status}`);
+	} catch (err) {
+		debugLog("send failed", err);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function exitClean() {
+	try {
+		process.disconnect?.();
+	} catch {}
+	process.exit(0);
+}
+process.once("message", (message) => {
+	if (!isParentToSenderPayload(message)) {
+		debugLog("received malformed payload; exiting");
+		exitClean();
+		return;
+	}
+	postEvent(message).catch((err) => debugLog("post threw", err)).finally(exitClean);
+});
+const SENDER_IDLE_EXIT_MS = REQUEST_TIMEOUT_MS * 2;
+setTimeout(exitClean, SENDER_IDLE_EXIT_MS).unref();
+//#endregion
+export {};
+
+//# sourceMappingURL=sender.mjs.map

package/dist/sender.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.mjs","names":[],"sources":["../src/detect-agent.ts","../src/enrich.ts","../src/payload.ts","../src/sender.ts"],"sourcesContent":["/**\n * Best-effort identification of AI coding-agent sessions from an\n * env-var allowlist. Detector property: false positives are negligible\n * (a marker present ⇒ confidently an agent); false negatives are\n * expected and documented in the user-facing telemetry docs. New\n * entries should land here, not in per-CLI hand-rolls.\n *\n * Each entry is a `(envVar, agent)` pair with uniform comparison shape:\n * the marker counts as \"present\" when `process.env[envVar]` is set to a\n * truthy string. Truthy = anything other than the empty string, `'0'`,\n * or `'false'` (case-insensitive); see `gating.isTruthyOptOut` for the\n * same convention applied to opt-out env vars.\n *\n * The detector runs in the **child** sender process, never the parent;\n * the parent does not probe env at command start.\n *\n * Codex CLI note: `CODEX_SANDBOX` is the only clear marker available here.\n * Non-sandboxed Codex sessions may be false negatives.\n *\n * TODO: a ci-info-for-agents would be nice — this allowlist drifts the\n * moment a new agent ships its env marker, and consolidating with the\n * other ecosystems that need the same lookup (rate-limited LLM\n * gateways, agent-aware metrics, etc.) would let one library carry the\n * matrix instead of every consumer re-doing it.\n */\nexport interface AgentMarker {\n  /** The env-var name to read. Exact-match; no prefix or fuzzy logic. */\n  readonly envVar: string;\n  /** The agent label written to the `agent` field of the telemetry event. */\n  readonly agent: string;\n}\n\nexport const AGENT_MARKERS: readonly AgentMarker[] = [\n  { envVar: 'CLAUDECODE', agent: 'Claude Code' },\n  { envVar: 'CURSOR_AGENT', agent: 'Cursor' },\n  { envVar: 'CODEX_SANDBOX', agent: 'Codex CLI' },\n  { envVar: 'GEMINI_CLI', agent: 'Gemini CLI' },\n  { envVar: 'WINDSURF', agent: 'Windsurf' },\n  { envVar: 'AIDER', agent: 'Aider' },\n  { envVar: 'CODY', agent: 'Cody' },\n  { envVar: 'CONTINUE', agent: 'Continue' },\n];\n\nfunction isTruthyMarker(raw: string | undefined): boolean {\n  if (raw === undefined) return false;\n  const normalised = raw.trim().toLowerCase();\n  if (normalised === '') return false;\n  if (normalised === '0') return false;\n  if (normalised === 'false') return false;\n  return true;\n}\n\n/**\n * Resolve the agent label from an env snapshot, or `null` if no marker\n * is set. Returns the **first** matching marker in `AGENT_MARKERS`\n * order, so when multiple markers are set the agent label is\n * deterministic and the allowlist's first entry wins.\n *\n * Pure: takes an env record, returns a string or null. No I/O.\n */\nexport function detectAgent(env: Readonly<Record<string, string | undefined>>): string | null {\n  for (const marker of AGENT_MARKERS) {\n    if (isTruthyMarker(env[marker.envVar])) {\n      return marker.agent;\n    }\n  }\n  return null;\n}\n","import { readFileSync } from 'node:fs';\nimport { join } from 'pathe';\nimport { detectAgent } from './detect-agent';\nimport type { ParentToSenderPayload, TelemetryEvent } from './payload';\n\n/**\n * Versions surface the enrichment cares about. Modelled as a structural\n * record with a required `node` field so tests can pass a literal object\n * without faking every field of `NodeJS.ProcessVersions` (which adds\n * properties between Node versions and includes a long tail the\n * enrichment never touches). Both `bun` and `deno` are read on the\n * runtime-resolution path; everything else is ignored.\n */\nexport interface VersionsSnapshot {\n  readonly node: string;\n  readonly bun?: string;\n  readonly deno?: string;\n}\n\n/**\n * Snapshot of process-level inputs the enrichment reads. Tests pass an\n * explicit snapshot so the enrichment is deterministic per case; the\n * sender entry point passes a fresh snapshot from `process`.\n */\nexport interface EnrichEnvironment {\n  readonly platform: NodeJS.Platform;\n  readonly arch: string;\n  readonly versions: VersionsSnapshot;\n  /**\n   * Included because package-manager and agent detection intentionally read\n   * environment variables from the same process snapshot as platform/versions.\n   */\n  readonly env: Readonly<Record<string, string | undefined>>;\n  /**\n   * Best-effort reader for the project's `package.json`, used only to derive\n   * the optional `tsVersion` telemetry field. Returning `null` means unknown.\n   */\n  readonly readProjectPackageJson: () => string | null;\n}\n\n/**\n * Identify the runtime the sender is running in. Same-runtime as the\n * parent is a correctness requirement: the parent forked us via\n * `child_process.fork`, which inherits the parent's runtime. Detection\n * keys on the runtime-specific version field rather than env vars so a\n * spoofed env can't lie about the actual interpreter.\n */\nfunction resolveRuntime(versions: VersionsSnapshot): {\n  readonly name: 'node' | 'bun' | 'deno';\n  readonly version: string;\n} {\n  if (versions.bun !== undefined) {\n    return { name: 'bun', version: versions.bun };\n  }\n  if (versions.deno !== undefined) {\n    return { name: 'deno', version: versions.deno };\n  }\n  return { name: 'node', version: versions.node };\n}\n\n/**\n * Parse `npm_config_user_agent` into a `<pm>/<version>` token. The\n * value, when present, looks like\n * `\"pnpm/10.27.0 npm/? node/v24.13.0 darwin arm64\"` — we take the first\n * whitespace-separated token. Any failure → `null`.\n */\nexport function parsePackageManager(userAgent: string | undefined): string | null {\n  if (userAgent === undefined) return null;\n  const first = userAgent.split(/\\s+/)[0];\n  if (first === undefined || first.length === 0) return null;\n  if (!first.includes('/')) return null;\n  return first;\n}\n\n/**\n * Read the user's project `package.json` and resolve a TypeScript\n * version from `devDependencies.typescript` (preferred) or\n * `dependencies.typescript`. Strips a leading `^` or `~` semver\n * prefix. Returns `null` on any failure mode — file missing,\n * unreadable, malformed JSON, key absent, not a string.\n */\nexport function readTsVersionFromPackageJson(raw: string | null): string | null {\n  if (raw === null) return null;\n  let parsed: Record<string, unknown>;\n  try {\n    parsed = JSON.parse(raw) as Record<string, unknown>;\n  } catch {\n    return null;\n  }\n  const candidate =\n    pickStringDep(parsed['devDependencies']) ?? pickStringDep(parsed['dependencies']);\n  if (candidate === null) return null;\n  return candidate.replace(/^[\\^~]/, '');\n}\n\nfunction pickStringDep(deps: unknown): string | null {\n  if (deps === null || typeof deps !== 'object' || Array.isArray(deps)) return null;\n  const value = (deps as Record<string, unknown>)['typescript'];\n  return typeof value === 'string' ? value : null;\n}\n\n/**\n * Build the full backend event from the parent's payload and the\n * child's per-process snapshot. Pure given an `EnrichEnvironment`.\n */\nexport function buildTelemetryEvent(\n  payload: ParentToSenderPayload,\n  env: EnrichEnvironment,\n): TelemetryEvent {\n  const runtime = resolveRuntime(env.versions);\n  return {\n    installationId: payload.installationId,\n    version: payload.version,\n    command: payload.command,\n    flags: payload.flags,\n    runtimeName: runtime.name,\n    runtimeVersion: runtime.version,\n    os: env.platform,\n    arch: env.arch,\n    packageManager: parsePackageManager(env.env['npm_config_user_agent']),\n    databaseTarget: payload.databaseTarget,\n    tsVersion: readTsVersionFromPackageJson(env.readProjectPackageJson()),\n    agent: detectAgent(env.env),\n    extensions: payload.extensions,\n  };\n}\n\n/**\n * Convenience for the sender entry: build the event from the live\n * `process` plus a real project-package.json reader, swallowing any\n * I/O errors in the file read.\n */\nexport function buildTelemetryEventFromProcess(payload: ParentToSenderPayload): TelemetryEvent {\n  return buildTelemetryEvent(payload, {\n    platform: process.platform,\n    arch: process.arch,\n    versions: process.versions,\n    env: process.env,\n    readProjectPackageJson: () => {\n      try {\n        return readFileSync(join(payload.projectRoot, 'package.json'), 'utf-8');\n      } catch {\n        return null;\n      }\n    },\n  });\n}\n","import { type } from 'arktype';\n\n/**\n * Wire-shape payload the parent IPC-sends to the forked child sender.\n * Mirrors the fields the parent has naturally in hand at command start\n * (installation id, sanitised command + flags, CLI version, db target,\n * extension-pack ids, project root for TS-version lookup). The child\n * fills in the rest (runtime/os/arch, package manager, ts version,\n * agent) on its side.\n *\n * Both sides version-couple on this shape because the IPC carrier is\n * structured-cloned by Node and there's no on-wire compat to maintain.\n */\nexport interface ParentToSenderPayload {\n  readonly installationId: string;\n  readonly version: string;\n  readonly command: string;\n  readonly flags: readonly string[];\n  readonly databaseTarget: string | null;\n  readonly extensions: readonly string[];\n  /** Absolute path of the user's project. The child reads `<projectRoot>/package.json` for `tsVersion`. */\n  readonly projectRoot: string;\n  /** Resolved endpoint URL (already includes the `/events` path). */\n  readonly endpoint: string;\n}\n\n/**\n * Runtime validator for {@link ParentToSenderPayload}. The child sender\n * uses this to gate `postEvent` so a payload missing a required field\n * cannot silently produce a degraded telemetry event downstream.\n *\n * Mirrors the backend's own arktype schema in spirit: required scalars\n * must be non-empty strings; `databaseTarget` is `string | null`; the\n * two string arrays are validated element-by-element. Size caps are\n * enforced by the backend, not here — IPC is structured-cloned and\n * the parent/child agree on the schema by version-coupling.\n */\nconst requiredString = type.string.moreThanLength(0);\nconst stringArray = type.string.array();\n\nexport const parentToSenderPayloadSchema = type({\n  installationId: requiredString,\n  version: requiredString,\n  command: requiredString,\n  flags: stringArray,\n  databaseTarget: type.string.or('null'),\n  extensions: stringArray,\n  projectRoot: requiredString,\n  endpoint: requiredString,\n});\n\nexport function isParentToSenderPayload(value: unknown): value is ParentToSenderPayload {\n  return !(parentToSenderPayloadSchema(value) instanceof type.errors);\n}\n\n/**\n * The full event the child POSTs to the backend. Shape matches the\n * backend's arktype schema (`apps/telemetry-backend/src/schema.ts`).\n */\nexport interface TelemetryEvent {\n  readonly installationId: string;\n  readonly version: string;\n  readonly command: string;\n  readonly flags: readonly string[];\n  readonly runtimeName: string;\n  readonly runtimeVersion: string;\n  readonly os: string;\n  readonly arch: string;\n  readonly packageManager: string | null;\n  readonly databaseTarget: string | null;\n  readonly tsVersion: string | null;\n  readonly agent: string | null;\n  readonly extensions: readonly string[];\n}\n","/**\n * Sender script entry — forked into a detached child by the parent CLI via\n * `child_process.fork(senderPath, [], { detached: true, ... })`.\n *\n * Lifecycle:\n *   1. Wait for the parent's IPC `message` event carrying a\n *      `ParentToSenderPayload`.\n *   2. Enrich with the local-process probes (runtime, os, arch, agent,\n *      package manager, tsVersion).\n *   3. POST the event to the endpoint URL with a hard 1.5 s timeout.\n *   4. Exit 0 unconditionally — successful POST, network failure, server\n *      error, parse error of the response, anything else: same outcome.\n *\n * Every error is swallowed; the only escape valve for visibility is\n * `PRISMA_NEXT_DEBUG=1`, which routes diagnostics to stderr. In normal\n * operation no telemetry-originating output ever reaches the user — the\n * parent's stdio map ignores our streams anyway, but we also gate\n * stderr writes behind the debug flag so the same binary is safe to\n * invoke directly outside the spawn flow.\n */\nimport { buildTelemetryEventFromProcess } from './enrich';\nimport { isParentToSenderPayload, type ParentToSenderPayload } from './payload';\n\nconst REQUEST_TIMEOUT_MS = 1500;\n\nfunction debugLog(message: string, error?: unknown): void {\n  if (process.env['PRISMA_NEXT_DEBUG'] !== '1') return;\n  if (error !== undefined) {\n    process.stderr.write(`[cli-telemetry] ${message}: ${String(error)}\\n`);\n  } else {\n    process.stderr.write(`[cli-telemetry] ${message}\\n`);\n  }\n}\n\nasync function postEvent(payload: ParentToSenderPayload): Promise<void> {\n  const event = buildTelemetryEventFromProcess(payload);\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);\n  try {\n    const response = await fetch(payload.endpoint, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json' },\n      body: JSON.stringify(event),\n      signal: controller.signal,\n    });\n    debugLog(`sent event: status=${response.status}`);\n  } catch (err) {\n    debugLog('send failed', err);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\nfunction exitClean(): void {\n  // `process.disconnect()` lets the parent's `.disconnect()` complete\n  // without lingering IPC handles when the parent is fast.\n  try {\n    process.disconnect?.();\n  } catch {\n    // ignore\n  }\n  process.exit(0);\n}\n\nprocess.once('message', (message: unknown) => {\n  if (!isParentToSenderPayload(message)) {\n    debugLog('received malformed payload; exiting');\n    exitClean();\n    return;\n  }\n  postEvent(message)\n    .catch((err) => debugLog('post threw', err))\n    .finally(exitClean);\n});\n\n// Defensive: if the parent never sends a payload (or the IPC channel\n// closes before `message` arrives), exit after a generous grace period\n// so the child process is not stuck holding a handle.\nconst SENDER_IDLE_EXIT_MS = REQUEST_TIMEOUT_MS * 2;\nsetTimeout(exitClean, SENDER_IDLE_EXIT_MS).unref();\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@prisma-next/cli-telemetry",
+  "version": "0.10.0-dev.8",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "CLI telemetry client for Prisma Next: detached subprocess sender, gating resolution, user-config store, and consent surface",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "arktype": "^2.2.0",
+    "pathe": "^2.0.3"
+  },
+  "devDependencies": {
+    "@prisma-next/test-utils": "0.10.0-dev.8",
+    "@prisma-next/tsconfig": "0.10.0-dev.8",
+    "@prisma-next/tsdown": "0.10.0-dev.8",
+    "@types/node": "24.10.4",
+    "tsdown": "0.22.0",
+    "typescript": "5.9.3",
+    "vitest": "4.1.6"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/exports/index.d.mts",
+      "import": "./dist/exports/index.mjs"
+    },
+    "./sender": {
+      "types": "./dist/sender.d.mts",
+      "import": "./dist/sender.mjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/3-tooling/cli-telemetry"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  }
+}