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

package/src/detect-agent.ts

@@ -0,0 +1,68 @@
+/**
+ * Best-effort identification of AI coding-agent sessions from an
+ * env-var allowlist. Detector property: false positives are negligible
+ * (a marker present ⇒ confidently an agent); false negatives are
+ * expected and documented in the user-facing telemetry docs. New
+ * entries should land here, not in per-CLI hand-rolls.
+ *
+ * Each entry is a `(envVar, agent)` pair with uniform comparison shape:
+ * the marker counts as "present" when `process.env[envVar]` is set to a
+ * truthy string. Truthy = anything other than the empty string, `'0'`,
+ * or `'false'` (case-insensitive); see `gating.isTruthyOptOut` for the
+ * same convention applied to opt-out env vars.
+ *
+ * The detector runs in the **child** sender process, never the parent;
+ * the parent does not probe env at command start.
+ *
+ * Codex CLI note: `CODEX_SANDBOX` is the only clear marker available here.
+ * Non-sandboxed Codex sessions may be false negatives.
+ *
+ * TODO: a ci-info-for-agents would be nice — this allowlist drifts the
+ * moment a new agent ships its env marker, and consolidating with the
+ * other ecosystems that need the same lookup (rate-limited LLM
+ * gateways, agent-aware metrics, etc.) would let one library carry the
+ * matrix instead of every consumer re-doing it.
+ */
+export interface AgentMarker {
+  /** The env-var name to read. Exact-match; no prefix or fuzzy logic. */
+  readonly envVar: string;
+  /** The agent label written to the `agent` field of the telemetry event. */
+  readonly agent: string;
+}
+
+export const AGENT_MARKERS: readonly AgentMarker[] = [
+  { 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: string | undefined): boolean {
+  if (raw === undefined) 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.
+ */
+export function detectAgent(env: Readonly<Record<string, string | undefined>>): string | null {
+  for (const marker of AGENT_MARKERS) {
+    if (isTruthyMarker(env[marker.envVar])) {
+      return marker.agent;
+    }
+  }
+  return null;
+}

package/src/endpoint.ts

@@ -0,0 +1,33 @@
+/**
+ * Production endpoint pinned to the deployed Prisma Compute backend.
+ * Compiled as a build-time constant; not user-configurable.
+ */
+export const TELEMETRY_BACKEND_URL = 'https://cmpbfbsdp09hr3jf7pojjs5qs.ewr.prisma.build';
+
+/**
+ * Path within the backend that accepts telemetry POSTs.
+ */
+export 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.
+ */
+export function resolveTelemetryEndpoint(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): string {
+  const override = env['PRISMA_NEXT_TELEMETRY_ENDPOINT'];
+  const base = override !== undefined && 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();
+  }
+}

package/src/enrich.ts

@@ -0,0 +1,147 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'pathe';
+import { detectAgent } from './detect-agent';
+import type { ParentToSenderPayload, TelemetryEvent } from './payload';
+
+/**
+ * Versions surface the enrichment cares about. Modelled as a structural
+ * record with a required `node` field so tests can pass a literal object
+ * without faking every field of `NodeJS.ProcessVersions` (which adds
+ * properties between Node versions and includes a long tail the
+ * enrichment never touches). Both `bun` and `deno` are read on the
+ * runtime-resolution path; everything else is ignored.
+ */
+export interface VersionsSnapshot {
+  readonly node: string;
+  readonly bun?: string;
+  readonly deno?: string;
+}
+
+/**
+ * Snapshot of process-level inputs the enrichment reads. Tests pass an
+ * explicit snapshot so the enrichment is deterministic per case; the
+ * sender entry point passes a fresh snapshot from `process`.
+ */
+export interface EnrichEnvironment {
+  readonly platform: NodeJS.Platform;
+  readonly arch: string;
+  readonly versions: VersionsSnapshot;
+  /**
+   * Included because package-manager and agent detection intentionally read
+   * environment variables from the same process snapshot as platform/versions.
+   */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /**
+   * Best-effort reader for the project's `package.json`, used only to derive
+   * the optional `tsVersion` telemetry field. Returning `null` means unknown.
+   */
+  readonly readProjectPackageJson: () => string | null;
+}
+
+/**
+ * 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: VersionsSnapshot): {
+  readonly name: 'node' | 'bun' | 'deno';
+  readonly version: string;
+} {
+  if (versions.bun !== undefined) {
+    return { name: 'bun', version: versions.bun };
+  }
+  if (versions.deno !== undefined) {
+    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`.
+ */
+export function parsePackageManager(userAgent: string | undefined): string | null {
+  if (userAgent === undefined) return null;
+  const first = userAgent.split(/\s+/)[0];
+  if (first === undefined || 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.
+ */
+export function readTsVersionFromPackageJson(raw: string | null): string | null {
+  if (raw === null) return null;
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  const candidate =
+    pickStringDep(parsed['devDependencies']) ?? pickStringDep(parsed['dependencies']);
+  if (candidate === null) return null;
+  return candidate.replace(/^[\^~]/, '');
+}
+
+function pickStringDep(deps: unknown): string | null {
+  if (deps === null || typeof deps !== 'object' || Array.isArray(deps)) return null;
+  const value = (deps as Record<string, unknown>)['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`.
+ */
+export function buildTelemetryEvent(
+  payload: ParentToSenderPayload,
+  env: EnrichEnvironment,
+): TelemetryEvent {
+  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.
+ */
+export function buildTelemetryEventFromProcess(payload: ParentToSenderPayload): TelemetryEvent {
+  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;
+      }
+    },
+  });
+}

package/src/exports/index.ts

@@ -0,0 +1,14 @@
+export {
+  resolveTelemetryEndpoint,
+  TELEMETRY_BACKEND_URL,
+  TELEMETRY_ENDPOINT_PATH,
+} from '../endpoint';
+export type { GatingDisabledReason, GatingInputs, GatingResolution } from '../gating';
+export { resolveGating } from '../gating';
+export type { ParentToSenderPayload, TelemetryEvent } from '../payload';
+export type { CommanderOptionShape, CommanderResultShape, SanitisedCommand } from '../sanitize';
+export { sanitizeCommanderResult } from '../sanitize';
+export type { RunTelemetryInputs, TelemetryRunOutcome } from '../spawn';
+export { runTelemetry, senderModuleUrl } from '../spawn';
+export type { UserConfig } from '../user-config';
+export { readUserConfig, userConfigPath, writeUserConfig } from '../user-config';

package/src/gating.ts

@@ -0,0 +1,71 @@
+import type { UserConfig } from './user-config';
+
+/**
+ * Why telemetry was disabled. Useful for debug-mode logging in the
+ * parent; never surfaces to users.
+ */
+export type GatingDisabledReason = 'env-override' | 'stored-opt-out' | 'default-off';
+
+export type GatingResolution =
+  | { readonly enabled: true }
+  | { readonly enabled: false; readonly reason: GatingDisabledReason };
+
+export interface GatingInputs {
+  /**
+   * Environment-variable lookups the resolver consults. Tests pass a
+   * literal record; production passes `process.env`. The two opt-out
+   * signals are `PRISMA_NEXT_DISABLE_TELEMETRY` (Prisma-specific) and
+   * `DO_NOT_TRACK` (community convention).
+   */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** Result of `readUserConfig()` — file-missing tolerated as `{}`. */
+  readonly config: UserConfig;
+}
+
+/**
+ * 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: string | undefined): boolean {
+  if (raw === undefined) 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`.
+ */
+export function resolveGating(inputs: GatingInputs): GatingResolution {
+  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' };
+}

package/src/payload.ts

@@ -0,0 +1,74 @@
+import { type } from 'arktype';
+
+/**
+ * Wire-shape payload the parent IPC-sends to the forked child sender.
+ * Mirrors the fields the parent has naturally in hand at command start
+ * (installation id, sanitised command + flags, CLI version, db target,
+ * extension-pack ids, project root for TS-version lookup). The child
+ * fills in the rest (runtime/os/arch, package manager, ts version,
+ * agent) on its side.
+ *
+ * Both sides version-couple on this shape because the IPC carrier is
+ * structured-cloned by Node and there's no on-wire compat to maintain.
+ */
+export interface ParentToSenderPayload {
+  readonly installationId: string;
+  readonly version: string;
+  readonly command: string;
+  readonly flags: readonly string[];
+  readonly databaseTarget: string | null;
+  readonly extensions: readonly string[];
+  /** Absolute path of the user's project. The child reads `<projectRoot>/package.json` for `tsVersion`. */
+  readonly projectRoot: string;
+  /** Resolved endpoint URL (already includes the `/events` path). */
+  readonly endpoint: string;
+}
+
+/**
+ * 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();
+
+export const parentToSenderPayloadSchema = type({
+  installationId: requiredString,
+  version: requiredString,
+  command: requiredString,
+  flags: stringArray,
+  databaseTarget: type.string.or('null'),
+  extensions: stringArray,
+  projectRoot: requiredString,
+  endpoint: requiredString,
+});
+
+export function isParentToSenderPayload(value: unknown): value is ParentToSenderPayload {
+  return !(parentToSenderPayloadSchema(value) instanceof type.errors);
+}
+
+/**
+ * The full event the child POSTs to the backend. Shape matches the
+ * backend's arktype schema (`apps/telemetry-backend/src/schema.ts`).
+ */
+export interface TelemetryEvent {
+  readonly installationId: string;
+  readonly version: string;
+  readonly command: string;
+  readonly flags: readonly string[];
+  readonly runtimeName: string;
+  readonly runtimeVersion: string;
+  readonly os: string;
+  readonly arch: string;
+  readonly packageManager: string | null;
+  readonly databaseTarget: string | null;
+  readonly tsVersion: string | null;
+  readonly agent: string | null;
+  readonly extensions: readonly string[];
+}

package/src/sanitize.ts

@@ -0,0 +1,78 @@
+export interface CommanderOptionShape {
+  /** Commander's option attribute name, e.g. `dryRun` for `--dry-run`. */
+  readonly attributeName: string;
+  /** Commander's long, user-facing flag spelling, e.g. `--dry-run` or `--no-install`. */
+  readonly longName: string | null;
+  /** Commander's value source for this option. Only `cli` is user-supplied. */
+  readonly source: string | null;
+}
+
+/**
+ * Input shape: a thin projection of commander's parsed-result surface.
+ * The parent extracts the command path, positional args, and per-option
+ * metadata from the leaf command. The sanitiser never consumes raw
+ * argv, never reads `process.argv`, and never sees flag values.
+ */
+export interface CommanderResultShape {
+  /**
+   * The full command path from the root program to the leaf, including
+   * the root program name as the first element (the sanitiser drops it).
+   * Example: `['prisma-next', 'migration', 'new']`.
+   */
+  readonly commandPath: readonly string[];
+  /**
+   * Positional arguments commander parsed for the leaf command.
+   * **Intentionally never read.** Accepted so the call site doesn't have
+   * to think about whether to pass it; the sanitiser's contract is that
+   * positionals never leave the parent process.
+   */
+  readonly positionalArgs: readonly string[];
+  /**
+   * Per-option Commander metadata. The sanitiser emits only options whose
+   * source is `cli`, and uses `longName` so telemetry sees user-facing
+   * names (`dry-run`, `connection-string`, `no-install`) rather than
+   * Commander's internal camelCase attribute names or defaulted options.
+   */
+  readonly options: readonly CommanderOptionShape[];
+}
+
+/**
+ * Output shape: the sanitised projection that flows into the telemetry
+ * payload. Two fields only — command name (space-delimited subcommand
+ * path) and flag names (in commander's option declaration order).
+ */
+export interface SanitisedCommand {
+  readonly command: string;
+  readonly flags: readonly string[];
+}
+
+function flagNameFromLongName(longName: string | null): string | null {
+  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.
+ */
+export function sanitizeCommanderResult(input: CommanderResultShape): SanitisedCommand {
+  const command = input.commandPath.slice(1).join(' ');
+  const flags = input.options.flatMap((option) => {
+    if (option.source !== 'cli') return [];
+    const flagName = flagNameFromLongName(option.longName);
+    return flagName === null ? [] : [flagName];
+  });
+  return { command, flags };
+}

package/src/sender.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+import { buildTelemetryEventFromProcess } from './enrich';
+import { isParentToSenderPayload, type ParentToSenderPayload } from './payload';
+
+const REQUEST_TIMEOUT_MS = 1500;
+
+function debugLog(message: string, error?: unknown): void {
+  if (process.env['PRISMA_NEXT_DEBUG'] !== '1') return;
+  if (error !== undefined) {
+    process.stderr.write(`[cli-telemetry] ${message}: ${String(error)}\n`);
+  } else {
+    process.stderr.write(`[cli-telemetry] ${message}\n`);
+  }
+}
+
+async function postEvent(payload: ParentToSenderPayload): Promise<void> {
+  const event = buildTelemetryEventFromProcess(payload);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await fetch(payload.endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(event),
+      signal: controller.signal,
+    });
+    debugLog(`sent event: status=${response.status}`);
+  } catch (err) {
+    debugLog('send failed', err);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function exitClean(): void {
+  // `process.disconnect()` lets the parent's `.disconnect()` complete
+  // without lingering IPC handles when the parent is fast.
+  try {
+    process.disconnect?.();
+  } catch {
+    // ignore
+  }
+  process.exit(0);
+}
+
+process.once('message', (message: unknown) => {
+  if (!isParentToSenderPayload(message)) {
+    debugLog('received malformed payload; exiting');
+    exitClean();
+    return;
+  }
+  postEvent(message)
+    .catch((err) => debugLog('post threw', err))
+    .finally(exitClean);
+});
+
+// Defensive: if the parent never sends a payload (or the IPC channel
+// closes before `message` arrives), exit after a generous grace period
+// so the child process is not stuck holding a handle.
+const SENDER_IDLE_EXIT_MS = REQUEST_TIMEOUT_MS * 2;
+setTimeout(exitClean, SENDER_IDLE_EXIT_MS).unref();