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

package/src/spawn.ts

@@ -0,0 +1,124 @@
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveTelemetryEndpoint } from './endpoint';
+import { resolveGating } from './gating';
+import type { ParentToSenderPayload } from './payload';
+import { type CommanderResultShape, sanitizeCommanderResult } from './sanitize';
+import { readUserConfig, type UserConfig } from './user-config';
+
+/**
+ * Inputs the CLI entry point hands the telemetry layer at command
+ * start. The CLI is responsible for stitching commander's result, the
+ * loaded config, and the project root together; the telemetry module
+ * does no I/O of its own except for the user-config read (skipped when
+ * `userConfig` is provided).
+ */
+export interface RunTelemetryInputs {
+  /** Sanitised commander snapshot — see `CommanderResultShape`. */
+  readonly command: CommanderResultShape;
+  /** This CLI's own version (from its `package.json`). */
+  readonly version: string;
+  /** Resolved `config.target.targetId`, or `null` when the config could not be loaded. */
+  readonly databaseTarget: string | null;
+  /** Declared extension-pack IDs, in any deterministic order. */
+  readonly extensions: readonly string[];
+  /** Absolute path of the project root (typically `process.cwd()`). */
+  readonly projectRoot: string;
+  /**
+   * Path to the sender entry compiled into this package's `dist/`.
+   * Resolved by the caller because the compiled sender lives at
+   * `<package>/dist/sender.mjs` and only the consumer knows its own
+   * `import.meta.url`.
+   */
+  readonly senderPath: string;
+  /**
+   * `isCI()` result from the consumer. Telemetry is suppressed when
+   * `true` regardless of the stored consent answer — CI environments
+   * never emit (matches the colour-output convention's CI suppression).
+   */
+  readonly isCI: boolean;
+  /** Process env to read for opt-out signals. Defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Cached user config when the caller already read it to resolve gates before other work. */
+  readonly userConfig?: UserConfig;
+}
+
+/**
+ * Best-effort telemetry spawn at command start. Returns synchronously —
+ * the fork runs in the background and never blocks the parent. Every
+ * failure mode is swallowed; the parent's stdout/stderr is untouched in
+ * normal operation, the only escape valve being
+ * `PRISMA_NEXT_DEBUG=1` which routes diagnostics to stderr.
+ *
+ * Returns the spawn outcome so debug-mode logging and the test-harness
+ * probe (which verifies test runs short-circuit the fork) can inspect
+ * the decision without scraping stderr.
+ */
+export type TelemetryRunOutcome =
+  | { readonly spawned: true }
+  | { readonly spawned: false; readonly reason: 'gated-off' | 'ci' | 'fork-failed' };
+
+export function runTelemetry(inputs: RunTelemetryInputs): TelemetryRunOutcome {
+  const env = inputs.env ?? process.env;
+
+  if (inputs.isCI) {
+    return { spawned: false, reason: 'ci' };
+  }
+
+  const config = inputs.userConfig ?? readUserConfig();
+  const gating = resolveGating({ env, config });
+  if (!gating.enabled) {
+    return { spawned: false, reason: 'gated-off' };
+  }
+
+  const sanitised = sanitizeCommanderResult(inputs.command);
+  // Gating already confirmed enableTelemetry === true, so installationId
+  // must be set (writeUserConfig generates it alongside that field).
+  // Defence-in-depth: if a stale config has the flag but no id, skip
+  // rather than send a junk event.
+  if (typeof config.installationId !== 'string' || config.installationId.length === 0) {
+    return { spawned: false, reason: 'gated-off' };
+  }
+
+  const payload: ParentToSenderPayload = {
+    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 })`.
+ */
+export function senderModuleUrl(importMetaUrl: string): string {
+  return fileURLToPath(new URL('./sender.mjs', importMetaUrl));
+}

package/src/user-config.ts

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'pathe';
+
+/**
+ * The user-level config file. Persists the consent flag and the
+ * installation UUID together so an env-var opt-out never mutates disk,
+ * and so an opt-in → opt-out → opt-in cycle keeps the same UUID (correct
+ * for MAU continuity).
+ *
+ * Readers tolerate unknown fields for forward compat; writers merge
+ * partials into the existing object so unknown fields are preserved.
+ */
+export interface UserConfig {
+  readonly enableTelemetry?: boolean;
+  readonly installationId?: string;
+  readonly [key: string]: unknown;
+}
+
+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(): string {
+  if (process.platform === 'win32') {
+    const appData = process.env['APPDATA'];
+    if (appData !== undefined && appData.length > 0) {
+      return join(appData, APP_DIR);
+    }
+    return join(homedir(), 'AppData', 'Roaming', APP_DIR);
+  }
+  const xdg = process.env['XDG_CONFIG_HOME'];
+  if (xdg !== undefined && 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.
+ */
+export function userConfigPath(): string {
+  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.
+ */
+export function readUserConfig(): UserConfig {
+  const path = userConfigPath();
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as UserConfig;
+    }
+    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.
+ */
+export function writeUserConfig(partial: Partial<UserConfig>): void {
+  const current = readUserConfig();
+  const merged: Record<string, unknown> = { ...current, ...partial };
+  if (partial.enableTelemetry === true && merged['installationId'] === undefined) {
+    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);
+}