@prisma-next/cli 0.12.0-dev.12 → 0.12.0-dev.13

package/src/commands/init/inputs.ts

@@ -1,9 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import * as clack from '@clack/prompts';
-import { readUserConfig, resolveGating, writeUserConfig } from '@prisma-next/cli-telemetry';
 import { extname, join, normalize } from 'pathe';
 import type { GlobalFlags } from '../../utils/global-flags';
-import { isCI } from '../../utils/is-ci';
 import {
   errorInitAuthoringSchemaPathMismatch,
   errorInitInvalidFlagValue,
@@ -71,18 +69,6 @@ export interface ResolvedInitInputs {
    * is added separately via the install step.
    */
   readonly removePreviousFacade: string | null;
-  /**
-   * Telemetry consent answer recorded during this `init` run, or `null`
-   * when no prompt was shown. The prompt fires only on the
-   * canPrompt + !autoAcceptPrompts + no env/CI opt-out +
-   * `enableTelemetry === undefined` intersection; outside that window
-   * the field is `null` and the stored preference (if any) stays
-   * unchanged. The answer has already been persisted to
-   * `$XDG_CONFIG_HOME/prisma-next/config.json` by
-   * the time `runInit` sees this value — it's surfaced here purely so
-   * the post-init summary can mention what the user chose.
-   */
-  readonly enableTelemetry: boolean | null;
   /**
    * Whether to run `npx skills add prisma/prisma-next#v<version>` at the
    * project level after install + emit. True by default; `--no-skill`
@@ -106,12 +92,6 @@ const AUTHORING_VALUES: ReadonlyMap<string, AuthoringId> = new Map([
   ['ts', 'typescript'],
 ]);
 
-export const TELEMETRY_CONSENT_MESSAGE = [
-  'Help us prioritize features by sharing anonymous CLI usage data?',
-  'The telemetry implementation is open source and fully transparent.',
-  '(packages/1-framework/3-tooling/cli-telemetry and apps/telemetry-backend).',
-].join(' ');
-
 /**
  * Resolves every required input for `runInit`. In interactive mode, missing
  * inputs are prompted via clack; in non-interactive mode, missing required
@@ -197,11 +177,6 @@ export async function resolveInitInputs(ctx: {
     autoAcceptPrompts,
   });
 
-  const enableTelemetry = await resolveTelemetryConsent({
-    canPrompt,
-    autoAcceptPrompts,
-  });
-
   // Skill-install gating. `--no-skill` (commander parses
   // `options.skill === false`) is the only escape hatch; otherwise
   // project-level install is unconditional. The skill is always
@@ -219,60 +194,10 @@ export async function resolveInitInputs(ctx: {
     strictProbe: Boolean(options.strictProbe),
     reinit,
     removePreviousFacade,
-    enableTelemetry,
     installProjectSkill,
   };
 }
 
-/**
- * The interactive telemetry consent prompt. Shown as the last
- * question of the `init` sequence iff:
- *   1. `canPrompt === true` (interactive stdin / stdout combo),
- *   2. `autoAcceptPrompts === false` (the user did not pass `--yes`),
- *   3. neither telemetry env opt-out is active,
- *   4. the process is not running in CI,
- *   5. the stored `enableTelemetry` value is `undefined` (the user
- *      has never been asked, or skipped the prompt previously).
- *
- * Outside that intersection the function returns `null` and leaves the
- * stored preference untouched. Inside it, the user's answer is
- * persisted via `writeUserConfig({ enableTelemetry })` before this
- * function returns; on an affirmative answer `writeUserConfig`
- * generates and stores the v4 `installationId` in the same write.
- *
- * The wording names CLI usage data and points to the open-source
- * client/backend paths. Default value is `true` to match precedent
- * and to make the consent answer a single keystroke once it's been
- * disclosed.
- */
-async function resolveTelemetryConsent(opts: {
-  readonly canPrompt: boolean;
-  readonly autoAcceptPrompts: boolean;
-}): Promise<boolean | null> {
-  if (!opts.canPrompt || opts.autoAcceptPrompts || isCI()) {
-    return null;
-  }
-  const config = readUserConfig();
-  const gating = resolveGating({ env: process.env, config });
-  if (!gating.enabled && gating.reason === 'env-override') {
-    return null;
-  }
-  const stored = config.enableTelemetry;
-  if (stored !== undefined) {
-    return null;
-  }
-  const result = await clack.confirm({
-    message: TELEMETRY_CONSENT_MESSAGE,
-    initialValue: true,
-    output: process.stderr,
-  });
-  if (clack.isCancel(result)) {
-    throw errorInitUserAborted();
-  }
-  writeUserConfig({ enableTelemetry: Boolean(result) });
-  return Boolean(result);
-}
-
 async function resolveWriteEnv(opts: {
   readonly flag: boolean | undefined;
   readonly canPrompt: boolean;

package/src/commands/telemetry/index.ts

@@ -0,0 +1,107 @@
+import { userConfigPath, writeUserConfig } from '@prisma-next/cli-telemetry';
+import { Command } from 'commander';
+import {
+  addGlobalOptions,
+  setCommandDescriptions,
+  setCommandExamples,
+} from '../../utils/command-helpers';
+import { formatCommandHelp } from '../../utils/formatters/help';
+import {
+  type CommonCommandOptions,
+  parseGlobalFlags,
+  parseGlobalFlagsOrExit,
+} from '../../utils/global-flags';
+import { isCI } from '../../utils/is-ci';
+import { createTerminalUI } from '../../utils/terminal-ui';
+import { formatTelemetryStatusLines, resolveTelemetryStatus } from './status';
+
+function createTelemetryStatusCommand(): Command {
+  const command = new Command('status');
+  setCommandDescriptions(
+    command,
+    'Show whether anonymous CLI telemetry is enabled and why',
+    'Reports whether telemetry is currently enabled or disabled and the reason\n' +
+      '(default-on, stored opt-out, environment opt-out, or CI), the path to your\n' +
+      'user-level config file, and whether an installation ID has been stored.\n' +
+      'Read-only: never sends an event, never mints an ID, never writes anything.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    const ui = createTerminalUI(flags);
+    const status = resolveTelemetryStatus({ env: process.env, inCI: isCI() });
+    if (flags.json) {
+      ui.output(JSON.stringify(status));
+    } else {
+      for (const line of formatTelemetryStatusLines(status)) {
+        ui.output(line);
+      }
+    }
+    process.exit(0);
+  });
+}
+
+function createTelemetryEnableCommand(): Command {
+  const command = new Command('enable');
+  setCommandDescriptions(
+    command,
+    'Enable anonymous CLI telemetry',
+    'Stores "enableTelemetry": true in your user-level config and mints an\n' +
+      'installation ID if one is not already stored.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    writeUserConfig({ enableTelemetry: true });
+    const ui = createTerminalUI(flags);
+    if (flags.json) {
+      ui.output(JSON.stringify({ enableTelemetry: true, configPath: userConfigPath() }));
+    } else {
+      ui.output(`Telemetry enabled. Preference stored in ${userConfigPath()}.`);
+    }
+    process.exit(0);
+  });
+}
+
+function createTelemetryDisableCommand(): Command {
+  const command = new Command('disable');
+  setCommandDescriptions(
+    command,
+    'Disable anonymous CLI telemetry',
+    'Stores "enableTelemetry": false in your user-level config. No installation\n' +
+      'ID is minted and no event is sent.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    writeUserConfig({ enableTelemetry: false });
+    const ui = createTerminalUI(flags);
+    if (flags.json) {
+      ui.output(JSON.stringify({ enableTelemetry: false, configPath: userConfigPath() }));
+    } else {
+      ui.output(`Telemetry disabled. Preference stored in ${userConfigPath()}.`);
+    }
+    process.exit(0);
+  });
+}
+
+export function createTelemetryCommand(): Command {
+  const command = new Command('telemetry');
+  setCommandDescriptions(
+    command,
+    'Inspect and change anonymous CLI telemetry',
+    'Show telemetry status, or enable / disable anonymous CLI usage data.\n' +
+      'Telemetry is on by default (opt-out); see https://prisma-next.dev/docs/cli/telemetry\n' +
+      'for what is collected and why.',
+  );
+  setCommandExamples(command, [
+    'prisma-next telemetry status',
+    'prisma-next telemetry disable',
+    'prisma-next telemetry enable',
+  ]);
+  command.configureHelp({
+    formatHelp: (cmd) => formatCommandHelp({ command: cmd, flags: parseGlobalFlags({}) }),
+    subcommandDescription: () => '',
+  });
+  command.addCommand(createTelemetryStatusCommand());
+  command.addCommand(createTelemetryEnableCommand());
+  command.addCommand(createTelemetryDisableCommand());
+  return command;
+}

package/src/commands/telemetry/status.ts

@@ -0,0 +1,67 @@
+import { readUserConfig, resolveGating, userConfigPath } from '@prisma-next/cli-telemetry';
+
+/**
+ * Why telemetry resolves the way it does, in the order the CLI's
+ * `resolveTelemetryGate` evaluates: CI hard-disables first, then the env
+ * opt-outs, then the stored `enableTelemetry`, then the opt-out default.
+ */
+export type TelemetryStatusReason =
+  | 'ci'
+  | 'env-opt-out'
+  | 'stored-opt-out'
+  | 'stored-opt-in'
+  | 'default-on';
+
+export interface TelemetryStatus {
+  readonly enabled: boolean;
+  readonly reason: TelemetryStatusReason;
+  readonly configPath: string;
+  readonly installationIdStored: boolean;
+}
+
+/**
+ * Resolves the same gate the runtime uses (CI check + `resolveGating`) and
+ * projects it into a user-facing status. Pure read: never mints, never
+ * writes. The `installationId` value itself is never surfaced — only its
+ * presence — so `status` discloses nothing identifying.
+ */
+export function resolveTelemetryStatus(inputs: {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly inCI: boolean;
+}): TelemetryStatus {
+  const config = readUserConfig();
+  const configPath = userConfigPath();
+  const installationIdStored =
+    typeof config.installationId === 'string' && config.installationId.length > 0;
+
+  if (inputs.inCI) {
+    return { enabled: false, reason: 'ci', configPath, installationIdStored };
+  }
+
+  const gating = resolveGating({ env: inputs.env, config });
+  if (!gating.enabled) {
+    const reason: TelemetryStatusReason =
+      gating.reason === 'env-override' ? 'env-opt-out' : 'stored-opt-out';
+    return { enabled: false, reason, configPath, installationIdStored };
+  }
+
+  const reason: TelemetryStatusReason =
+    config.enableTelemetry === true ? 'stored-opt-in' : 'default-on';
+  return { enabled: true, reason, configPath, installationIdStored };
+}
+
+const REASON_EXPLANATION: Record<TelemetryStatusReason, string> = {
+  ci: 'CI environment detected — telemetry is hard-disabled.',
+  'env-opt-out': 'an environment opt-out is set (DO_NOT_TRACK / PRISMA_NEXT_DISABLE_TELEMETRY).',
+  'stored-opt-out': '"enableTelemetry": false is stored in your config.',
+  'stored-opt-in': '"enableTelemetry": true is stored in your config.',
+  'default-on': 'no explicit choice is stored, so the opt-out default applies.',
+};
+
+export function formatTelemetryStatusLines(status: TelemetryStatus): string[] {
+  return [
+    `Telemetry is ${status.enabled ? 'enabled' : 'disabled'}: ${REASON_EXPLANATION[status.reason]}`,
+    `Config file: ${status.configPath}`,
+    `Installation ID: ${status.installationIdStored ? 'stored' : 'not stored'}`,
+  ];
+}

package/src/utils/global-flags.ts

@@ -180,3 +180,38 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
 
   return flags as GlobalFlags;
 }
+
+/**
+ * Bridges the two TTY checks (stdout via `flags`, stdin via
+ * `process.stdin.isTTY`) into the `canPrompt` boolean the interactive
+ * `init` flow consumes.
+ *
+ * Per the [Style Guide § Interactivity](../../../../../../../docs/CLI%20Style%20Guide.md#interactivity):
+ *
+ * - `flags.interactive` governs *decoration* (TerminalUI, intro/outro,
+ *   spinners) and is derived from stdout-TTY by `parseGlobalFlags`,
+ *   honouring `--interactive` / `--no-interactive`.
+ * - Prompting additionally requires a stdin TTY — closing stdin is a
+ *   common signal in CI / agent environments even when stdout stays
+ *   attached.
+ * - `--interactive` is the explicit override: when the user passes it,
+ *   we honour it (e.g. testing flows where stdin is stubbed).
+ *
+ * Single source of truth for the interactive-prompt decision: both the
+ * `init` action handler and the preAction telemetry bridge derive
+ * prompt-eligibility from this helper so they cannot drift. Lives in
+ * `global-flags` (alongside `parseGlobalFlags`) to keep
+ * `utils/telemetry` and `commands/init/index` free of an import cycle.
+ *
+ * Exported so callers and tests can derive the same value without
+ * touching `process` globals.
+ */
+export function deriveCanPrompt(opts: {
+  readonly flagsInteractive: boolean | undefined;
+  readonly optionInteractive: boolean | undefined;
+  readonly stdinIsTTY: boolean;
+}): boolean {
+  if (opts.optionInteractive === true) return true;
+  if (opts.flagsInteractive === false) return false;
+  return opts.stdinIsTTY;
+}

package/src/utils/telemetry.ts

@@ -2,13 +2,14 @@ import { fileURLToPath } from 'node:url';
 import {
   type CommanderOptionShape,
   type CommanderResultShape,
+  ensureInstallationId,
   readUserConfig,
   resolveGating,
   runTelemetry,
   type TelemetryRunOutcome,
   type UserConfig,
+  userConfigPath,
 } from '@prisma-next/cli-telemetry';
-import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
 import { version as CLI_VERSION } from '../../package.json' with { type: 'json' };
 import { isCI } from './is-ci';
@@ -78,11 +79,7 @@ function senderPath(): string {
   return fileURLToPath(new URL(import.meta.resolve('@prisma-next/cli-telemetry/sender')));
 }
 
-function fireTelemetry(
-  actionCommand: Command,
-  userConfig: UserConfig,
-  overrides: { readonly databaseTarget?: string } = {},
-): TelemetryRunOutcome {
+function fireTelemetry(actionCommand: Command, userConfig: UserConfig): TelemetryRunOutcome {
   return runTelemetry({
     command: commanderSnapshotForTelemetry(actionCommand),
     version: CLI_VERSION,
@@ -91,7 +88,6 @@ function fireTelemetry(
     isCI: isCI(),
     env: process.env,
     userConfig,
-    ...ifDefined('databaseTarget', overrides.databaseTarget),
   });
 }
 
@@ -107,35 +103,75 @@ function fireTelemetry(
  * config touches disk. The child loading user TS code is acceptable
  * only because it's gated behind the same resolved-enabled signal.
  */
+/**
+ * Builds the one-time first-run disclosure. The resolved absolute path to
+ * the user-level config file is substituted in so the user can see exactly
+ * which file to edit (it must not be confused with `prisma-next.config.ts`).
+ * `prisma-next telemetry disable` is named as the primary, friendliest
+ * opt-out, alongside the env vars and the config edit.
+ */
+function firstRunNotice(configPath: string): string {
+  return [
+    'Prisma Next collects anonymous CLI usage data, enabled by default.',
+    "What's collected and why: https://prisma-next.dev/docs/cli/telemetry.",
+    'Opt out: run "prisma-next telemetry disable", set DO_NOT_TRACK=1 or',
+    `PRISMA_NEXT_DISABLE_TELEMETRY=1, or set "enableTelemetry": false in ${configPath}.`,
+  ].join(' ');
+}
+
+/**
+ * Best-effort first-run disclosure + installationId mint. Runs only on the
+ * gating-enabled path. Prints the notice to stderr (never stdout) and mints
+ * a persistent id without touching `enableTelemetry`, so the opt-out default
+ * stays intact and no unasked-for consent is recorded.
+ *
+ * Every step is wrapped so an un-writable config dir (or any other failure)
+ * never throws and never blocks the command. Returns the minted (or
+ * pre-existing) id so the caller can forward it to `runTelemetry` without a
+ * redundant disk read. On mint failure it returns `undefined`: the notice may
+ * reprint next run, and `runTelemetry` no-ops on the missing id.
+ */
+function discloseAndMintOnFirstRun(): string | undefined {
+  try {
+    process.stderr.write(`${firstRunNotice(userConfigPath())}\n`);
+  } catch {}
+  try {
+    return ensureInstallationId();
+  } catch {}
+  return undefined;
+}
+
+/**
+ * True when the run is the `telemetry` command (or one of its
+ * subcommands). The usage-telemetry preAction fire is exempted for it:
+ * it would be absurd for `telemetry disable` to send a usage event before
+ * disabling, or for `telemetry status` to mint an id + send while merely
+ * reporting state. This is the only command-specific exemption.
+ *
+ * The check is rooted at the program: the path must be
+ * `['prisma-next', 'telemetry', …]`, so it matches the top-level
+ * `telemetry` command and its subcommands without matching a hypothetical
+ * nested `… telemetry` elsewhere.
+ */
+function isTelemetryCommand(actionCommand: Command): boolean {
+  return commandPathFor(actionCommand)[1] === 'telemetry';
+}
+
 export function fireTelemetryFromPreAction(actionCommand: Command): TelemetryRunOutcome {
+  if (isTelemetryCommand(actionCommand)) {
+    return { spawned: false, reason: 'gated-off' };
+  }
   const gate = resolveTelemetryGate();
   if (!gate.enabled) {
     return gate.outcome;
   }
+  const storedId = gate.userConfig.installationId;
+  if (typeof storedId !== 'string' || storedId.length === 0) {
+    const installationId = discloseAndMintOnFirstRun();
+    return fireTelemetry(
+      actionCommand,
+      installationId === undefined ? gate.userConfig : { ...gate.userConfig, installationId },
+    );
+  }
   return fireTelemetry(actionCommand, gate.userConfig);
 }
-
-/**
- * Manual one-shot telemetry path for the first `init` run where the user
- * explicitly answers Yes to the consent prompt. The preAction hook for
- * that same run has already resolved before consent existed, so it is
- * default-off. After consent is persisted, `runInit` calls this helper
- * exactly for that first affirmative answer; subsequent init runs skip
- * it because the prompt is not shown again.
- *
- * The child's c12 load would return `databaseTarget: null` for this
- * specific invocation because `prisma-next.config.*` is not yet on
- * disk (init writes it later in the same run). To preserve the
- * prompt-chosen target in the first-init telemetry event, this
- * helper forwards the value as a parent-side IPC override on
- * `ParentToSenderPayload.databaseTarget` — the child consults the
- * override first and falls back to its c12 result when absent.
- */
-export function fireTelemetryAfterInitConsent(
-  actionCommand: Command,
-  inputs: { readonly databaseTarget: string },
-): TelemetryRunOutcome {
-  return fireTelemetry(actionCommand, readUserConfig(), {
-    databaseTarget: inputs.databaseTarget,
-  });
-}