@prisma-next/cli 0.9.0 → 0.10.0-dev.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma-next/cli",
-  "version": "0.9.0",
+  "version": "0.10.0-dev.10",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
@@ -14,16 +14,18 @@
   "dependencies": {
     "@clack/prompts": "^1.3.0",
     "@dagrejs/dagre": "^3.0.0",
-    "@prisma-next/config": "0.9.0",
-    "@prisma-next/contract": "0.9.0",
-    "@prisma-next/emitter": "0.9.0",
-    "@prisma-next/errors": "0.9.0",
-    "@prisma-next/framework-components": "0.9.0",
-    "@prisma-next/migration-tools": "0.9.0",
-    "@prisma-next/psl-printer": "0.9.0",
-    "@prisma-next/utils": "0.9.0",
+    "@prisma-next/config": "0.10.0-dev.10",
+    "@prisma-next/contract": "0.10.0-dev.10",
+    "@prisma-next/emitter": "0.10.0-dev.10",
+    "@prisma-next/errors": "0.10.0-dev.10",
+    "@prisma-next/framework-components": "0.10.0-dev.10",
+    "@prisma-next/migration-tools": "0.10.0-dev.10",
+    "@prisma-next/psl-printer": "0.10.0-dev.10",
+    "@prisma-next/cli-telemetry": "0.10.0-dev.10",
+    "@prisma-next/utils": "0.10.0-dev.10",
     "arktype": "^2.2.0",
     "c12": "^3.3.4",
+    "ci-info": "^4.3.1",
     "clipanion": "4.0.0-rc.4",
     "closest-match": "^1.3.3",
     "colorette": "^2.0.20",
@@ -37,14 +39,14 @@
     "wrap-ansi": "^10.0.0"
   },
   "devDependencies": {
-    "@prisma-next/sql-contract": "0.9.0",
-    "@prisma-next/sql-contract-emitter": "0.9.0",
-    "@prisma-next/sql-contract-ts": "0.9.0",
-    "@prisma-next/sql-operations": "0.9.0",
-    "@prisma-next/sql-runtime": "0.9.0",
-    "@prisma-next/test-utils": "0.9.0",
-    "@prisma-next/tsconfig": "0.9.0",
-    "@prisma-next/tsdown": "0.9.0",
+    "@prisma-next/sql-contract": "0.10.0-dev.10",
+    "@prisma-next/sql-contract-emitter": "0.10.0-dev.10",
+    "@prisma-next/sql-contract-ts": "0.10.0-dev.10",
+    "@prisma-next/sql-operations": "0.10.0-dev.10",
+    "@prisma-next/sql-runtime": "0.10.0-dev.10",
+    "@prisma-next/test-utils": "0.10.0-dev.10",
+    "@prisma-next/tsconfig": "0.10.0-dev.10",
+    "@prisma-next/tsdown": "0.10.0-dev.10",
     "@types/node": "24.10.4",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",

package/src/cli.ts

@@ -27,6 +27,7 @@ import { setCommandDescriptions } from './utils/command-helpers';
 import { formatCommandHelp, formatRootHelp } from './utils/formatters/help';
 import { parseGlobalFlags } from './utils/global-flags';
 import { suggestCommands } from './utils/suggest-command';
+import { fireTelemetryFromPreAction } from './utils/telemetry';
 
 /**
  * Lookup table mapping removed subcommands to their replacement verbs.
@@ -68,6 +69,20 @@ const program = new Command();
 
 program.name('prisma-next').description('Prisma Next CLI').version(packageJson.version);
 
+// Telemetry hook — fires at command start, before the action body
+// runs. Every failure mode is swallowed inside `runTelemetry`; the
+// hook never throws and never blocks long enough to be perceptible.
+//
+// Fire-and-forget: `fireTelemetryFromPreAction` `await`s a c12 config
+// load before forking the sender, so awaiting it here would block the
+// command's action body behind telemetry. Use `void` to dispatch in
+// parallel; the existing `.catch(() => {})` keeps errors swallowed.
+program.hook('preAction', (_thisCommand, actionCommand) => {
+  void fireTelemetryFromPreAction(actionCommand).catch(() => {
+    // defence-in-depth — runTelemetry already swallows internally.
+  });
+});
+
 // Override version option description to match capitalization style
 const versionOption = program.options.find((opt) => opt.flags.includes('--version'));
 if (versionOption) {

package/src/commands/init/errors.ts

@@ -238,7 +238,7 @@ export function errorInitEmitFailed(options: {
 }
 
 /**
- * The project-level agent-skill install (`npx skills add
+ * The project-level skills install (`npx skills add
  * prisma/prisma-next#v<version>`) failed after a successful dependency
  * install + emit. The project's scaffold remains on disk; the user
  * can either fix the underlying issue (network, registry, PATH) and
@@ -260,7 +260,7 @@ export function errorInitSkillInstallFailed(options: {
       'Either:\n' +
       `  - Re-run \`prisma-next init --no-skill${options.filesWritten.length > 0 ? ' --force' : ''}\` to skip the skill install for this run, or\n` +
       `  - Fix the underlying issue (network, npm registry, \`npx skills\` on PATH) and install manually:\n      ${options.skillInstallCommand}`,
-    docsUrl: 'https://prisma-next.dev/docs/cli/init#agent-skill',
+    docsUrl: 'https://prisma-next.dev/docs/cli/init#skills',
     meta: {
       filesWritten: options.filesWritten,
       skillInstallCommand: options.skillInstallCommand,

package/src/commands/init/index.ts

@@ -5,6 +5,7 @@ import {
   setCommandExamples,
 } from '../../utils/command-helpers';
 import { type CommonCommandOptions, parseGlobalFlags } from '../../utils/global-flags';
+import { fireTelemetryAfterInitConsent } from '../../utils/telemetry';
 import {
   INIT_EXIT_EMIT_FAILED,
   INIT_EXIT_INSTALL_FAILED,
@@ -63,7 +64,7 @@ export function createInitCommand(): Command {
     'prisma-next init --yes --target mongodb --authoring typescript --json',
     'prisma-next init --yes --force --target postgres --authoring psl  # overwrite an existing scaffold',
     'prisma-next init --no-install                                       # skip pnpm/npm install + emit',
-    'prisma-next init --no-skill                                         # skip the agent-skill install (air-gapped / restricted env)',
+    'prisma-next init --no-skill                                         # skip the skills install (air-gapped / restricted env)',
   ]);
 
   return addGlobalOptions(command)
@@ -91,7 +92,7 @@ export function createInitCommand(): Command {
       '--no-skill',
       'Skip Prisma Next skills install (air-gapped CI, restricted registries, etc.)',
     )
-    .action(async (options: InitCommandOptions) => {
+    .action(async (options: InitCommandOptions, actionCommand: Command) => {
       const { runInit } = await import('./init');
       const flags = parseGlobalFlags(options);
       const canPrompt = deriveCanPrompt({
@@ -99,7 +100,14 @@ export function createInitCommand(): Command {
         optionInteractive: options.interactive,
         stdinIsTTY: Boolean(process.stdin.isTTY),
       });
-      const exitCode = await runInit(process.cwd(), { options, flags, canPrompt });
+      const exitCode = await runInit(process.cwd(), {
+        options,
+        flags,
+        canPrompt,
+        afterFirstTelemetryConsent: (inputs) => {
+          fireTelemetryAfterInitConsent(actionCommand, { databaseTarget: inputs.target });
+        },
+      });
       process.exit(exitCode);
     });
 }

package/src/commands/init/init.ts

@@ -7,13 +7,6 @@ import { CliStructuredError } from '../../utils/cli-errors';
 import { formatErrorJson, formatErrorOutput } from '../../utils/formatters/errors';
 import type { GlobalFlags } from '../../utils/global-flags';
 import { TerminalUI } from '../../utils/terminal-ui';
-import {
-  DEFAULT_AGENT_SKILL_SOURCES,
-  formatClaudeSkillInstallCommand,
-  formatSkillInstallCommand,
-  LEGACY_SKILL_FILE,
-  runProjectLevelSkillInstall,
-} from './agent-skill-install';
 import {
   detectPackageManager,
   formatAddArgs,
@@ -56,6 +49,13 @@ import {
 } from './output';
 import { type ProbeOutcome, type ProbeOverrides, probeServerVersion } from './probe-db';
 import { findStaleArtefacts, removeDependency } from './reinit-cleanup';
+import {
+  DEFAULT_SKILL_SOURCES,
+  formatClaudeSkillInstallCommand,
+  formatSkillInstallCommand,
+  LEGACY_SKILL_FILE,
+  runProjectLevelSkillInstall,
+} from './skill-install';
 import { configFile, dbFile, starterSchema, targetPackageName } from './templates/code-templates';
 import { envExampleContent, envFileContent, MIN_SERVER_VERSION } from './templates/env';
 import { quickReferenceMd } from './templates/quick-reference';
@@ -81,11 +81,11 @@ interface InstallReport {
   readonly warnings: readonly string[];
   /**
    * The package manager that actually ran. Equal to the detected `pm`
-   * on the common path; differs when the FR7.2 pnpm → npm fallback
-   * fired, in which case it's `'npm'`. Threaded into the agent-skill
-   * install so the runner stays consistent with the install we just
-   * ran — re-trying through `pnpm dlx` when `pnpm install` just failed
-   * for workspace/catalog reasons would fail again for the same reason.
+   * on the common path; differs when the pnpm → npm fallback fired, in
+   * which case it's `'npm'`. Threaded into the skills install so the
+   * runner stays consistent with the install we just ran — re-trying
+   * through `pnpm dlx` when `pnpm install` just failed for
+   * workspace/catalog reasons would fail again for the same reason.
    */
   readonly effectivePm: PackageManager;
 }
@@ -95,7 +95,7 @@ interface InstallReport {
  * structured CLI errors raised at every phase (input resolution, install,
  * emit) and renders them via the same UI surface as success output
  * (`--json` to stdout, human to stderr). Exit codes follow the documented
- * stable set in `./exit-codes.ts` (FR1.6) and the
+ * stable set in `./exit-codes.ts` and the
  * [Style Guide § Exit Codes](../../../../../../../docs/CLI%20Style%20Guide.md#exit-codes).
  *
  * Layered for testability: the action handler in `./index.ts` is
@@ -113,6 +113,11 @@ export async function runInit(
      * mode) — see [Style Guide § Interactivity](../../../../../../../docs/CLI%20Style%20Guide.md#interactivity).
      */
     readonly canPrompt: boolean;
+    /**
+     * Called once after the first affirmative telemetry consent is persisted.
+     * Failures are swallowed by the caller; init success must not depend on telemetry.
+     */
+    readonly afterFirstTelemetryConsent?: (inputs: ResolvedInitInputs) => void | Promise<void>;
     /**
      * FR8.3 — test-only seam for the optional database version probe.
      * Production callers omit this; tests inject stub `probePostgres` /
@@ -124,7 +129,7 @@ export async function runInit(
     readonly probeOverrides?: ProbeOverrides;
   },
 ): Promise<number> {
-  const { options, flags, canPrompt, probeOverrides } = runOptions;
+  const { options, flags, canPrompt, probeOverrides, afterFirstTelemetryConsent } = runOptions;
   const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
   const warnings: string[] = [];
   const filesWritten: string[] = [];
@@ -144,6 +149,14 @@ export async function runInit(
     throw error;
   }
 
+  if (inputs.enableTelemetry === true && afterFirstTelemetryConsent !== undefined) {
+    try {
+      await afterFirstTelemetryConsent(inputs);
+    } catch {
+      // telemetry is best-effort and must never affect init
+    }
+  }
+
   const pm = await detectPackageManager(baseDir);
   const pkgRun = formatRunCommand(pm, 'prisma-next', '').trimEnd();
 
@@ -451,7 +464,7 @@ export async function runInit(
   // potentially fails. We skip the install when the user passed
   // `--no-install` for the same reason — no `node_modules` means the
   // workspace isn't ready to consume the skill yet anyway.
-  const manualProjectSkillCommands = DEFAULT_AGENT_SKILL_SOURCES.flatMap((source) => [
+  const manualProjectSkillCommands = DEFAULT_SKILL_SOURCES.flatMap((source) => [
     formatSkillInstallCommand(install.effectivePm, source),
     formatClaudeSkillInstallCommand(install.effectivePm, source),
   ]);
@@ -459,11 +472,11 @@ export async function runInit(
   let skillRegistered = false;
   if (!inputs.installProjectSkill) {
     warnings.push(
-      `Skipped Prisma Next agent-skill install (--no-skill). To install the skills later, run: ${manualProjectSkillSummary}`,
+      `Skipped Prisma Next skills install (--no-skill). To install the skills later, run: ${manualProjectSkillSummary}`,
     );
   } else if (install.skipped) {
     warnings.push(
-      `Skipped Prisma Next agent-skill install because --no-install was passed. After you run install manually, install the skills with: ${manualProjectSkillSummary}`,
+      `Skipped Prisma Next skills install because --no-install was passed. After you run install manually, install the skills with: ${manualProjectSkillSummary}`,
     );
   } else {
     const spinner = ui.spinner();
@@ -597,7 +610,7 @@ export function exitCodeForError(error: { readonly code: string }): number {
       return INIT_EXIT_EMIT_FAILED;
     case '5009': // invalid output document — internal bug in prisma-next
       return INIT_EXIT_INTERNAL_ERROR;
-    case '5013': // agent-skill install failed
+    case '5013': // skill install failed
       return INIT_EXIT_SKILL_INSTALL_FAILED;
     default:
       // Any unexpected code is treated as an internal bug rather than

package/src/commands/init/inputs.ts

@@ -1,7 +1,9 @@
 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 {
   errorInitInvalidFlagValue,
   errorInitMissingFlags,
@@ -68,12 +70,24 @@ 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`
    * sets it to `false`. The skill is always project-level (never
    * user-level / global) so its version stays locked to the project's
-   * Prisma Next version — see `agent-skill-install.ts`.
+   * Prisma Next version — see `skill-install.ts`.
    */
   readonly installProjectSkill: boolean;
 }
@@ -91,6 +105,12 @@ 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
@@ -176,6 +196,11 @@ 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
@@ -193,10 +218,60 @@ 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/init/{agent-skill-install.ts → skill-install.ts}

@@ -11,7 +11,7 @@ const exec = promisify(execFile);
  * upstream `skills add`. Each `SkillSource` joins this base with its
  * own subpath (and optional `#ref` for version-pinned clusters).
  */
-export const DEFAULT_AGENT_SKILL_BASE = 'prisma/prisma-next';
+export const DEFAULT_SKILL_BASE = 'prisma/prisma-next';
 
 /**
  * One discovery scope inside the Prisma Next monorepo. The CLI emits
@@ -35,7 +35,7 @@ export interface SkillSource {
   readonly description: string;
 }
 
-export const DEFAULT_AGENT_SKILL_SOURCES: readonly SkillSource[] = [
+export const DEFAULT_SKILL_SOURCES: readonly SkillSource[] = [
   {
     subpath: 'skills',
     ref: 'cli',
@@ -56,7 +56,7 @@ export const DEFAULT_AGENT_SKILL_SOURCES: readonly SkillSource[] = [
 /**
  * Test-only escape hatch for pinning the install base to a local
  * checkout. Production runs leave this unset, so installs always use
- * `DEFAULT_AGENT_SKILL_BASE`.
+ * `DEFAULT_SKILL_BASE`.
  *
  * When set to an absolute filesystem path (typical for tests), the
  * `#ref` fragment is dropped — local-path mode in upstream's CLI does
@@ -66,7 +66,7 @@ export const DEFAULT_AGENT_SKILL_SOURCES: readonly SkillSource[] = [
  */
 function resolveAgentSkillBase(): string {
   const override = process.env['PRISMA_NEXT_SKILLS_BASE']?.trim();
-  return override && override.length > 0 ? override : DEFAULT_AGENT_SKILL_BASE;
+  return override && override.length > 0 ? override : DEFAULT_SKILL_BASE;
 }
 
 function isLocalPath(base: string): boolean {
@@ -162,7 +162,7 @@ function commandToExec(command: string): {
 
 /**
  * Runs the project-level skill install for every source in
- * `DEFAULT_AGENT_SKILL_SOURCES`, in order. Returns
+ * `DEFAULT_SKILL_SOURCES`, in order. Returns
  * `{ ok: true, commands }` on success; throws a structured
  * `errorInitSkillInstallFailed` on the first failure (subsequent
  * sources are not attempted — the user opted into Prisma Next by
@@ -176,7 +176,7 @@ export async function runProjectLevelSkillInstall(ctx: {
   readonly filesWritten: readonly string[];
 }): Promise<{ readonly ok: true; readonly commands: readonly string[] }> {
   const commands: string[] = [];
-  const installCommands = DEFAULT_AGENT_SKILL_SOURCES.flatMap((source) => [
+  const installCommands = DEFAULT_SKILL_SOURCES.flatMap((source) => [
     formatSkillInstallCommand(ctx.pm, source),
     formatClaudeSkillInstallCommand(ctx.pm, source),
   ]);

package/src/commands/init/templates/code-templates.ts

@@ -42,9 +42,10 @@ export function schemaSample(target: TargetId, authoring: AuthoringId): string {
 function schemaSamplePslPostgres(): string {
   return `\`\`\`prisma
 model User {
-  id    Int     @id @default(autoincrement())
-  email String  @unique
-  name  String?
+  id       Int     @id @default(autoincrement())
+  email    String  @unique
+  username String?
+  name     String?
 }
 \`\`\``;
 }
@@ -52,9 +53,10 @@ model User {
 function schemaSamplePslMongo(): string {
   return `\`\`\`prisma
 model User {
-  id    ObjectId @id @map("_id")
-  email String   @unique
-  name  String?
+  id       ObjectId @id @map("_id")
+  email    String   @unique
+  username String?
+  name     String?
   @@map("users")
 }
 \`\`\``;
@@ -74,6 +76,7 @@ export const contract = defineContract(
         fields: {
           id: field.id.uuidv7(),
           email: field.text().unique(),
+          username: field.text().optional(),
           name: field.text().optional(),
         },
       }),
@@ -98,6 +101,7 @@ export const contract = defineContract(
         fields: {
           _id: field.objectId(),
           email: field.string(),
+          username: field.string().optional(),
           name: field.string().optional(),
         },
       }),
@@ -113,6 +117,7 @@ function starterSchemaPslPostgres(): string {
 model User {
   id        Int      @id @default(autoincrement())
   email     String   @unique
+  username  String?
   name      String?
   posts     Post[]
   createdAt DateTime @default(now())
@@ -135,10 +140,11 @@ function starterSchemaPslMongo(): string {
   return `// use prisma-next
 
 model User {
-  id    ObjectId @id @map("_id")
-  email String   @unique
-  name  String?
-  posts Post[]
+  id       ObjectId @id @map("_id")
+  email    String   @unique
+  username String?
+  name     String?
+  posts    Post[]
   @@map("users")
 }
 
@@ -166,6 +172,7 @@ export const contract = defineContract(
         fields: {
           id: field.id.uuidv7(),
           email: field.text().unique(),
+          username: field.text().optional(),
           name: field.text().optional(),
           createdAt: field.temporal.createdAt(),
           updatedAt: field.temporal.updatedAt(),
@@ -208,6 +215,7 @@ export const contract = defineContract(
         fields: {
           _id: field.objectId(),
           email: field.string(),
+          username: field.string().optional(),
           name: field.string().optional(),
         },
         relations: {

package/src/commands/init/templates/quick-reference-mongo.md

@@ -22,7 +22,7 @@ const user = await db.orm.users
   .first();
 
 // Your editor will show the type of user as
-// { _id: ObjectId; email: string; name: string | null; posts: Post[] } | null
+// { _id: ObjectId; email: string; username: string | null; name: string | null; posts: Post[] } | null
 ```
 
 `db` connects to MongoDB lazily on the first query, so there is no manual `connect(...)` step in your application code. Call `await db.close()` if you need to release the underlying connection (typically only in tests or short-lived scripts). After `close()` the client is single-shot — any further query, `connect()`, or `runtime()` call rejects with `"Mongo client is closed"`. Construct a new `mongo({...})` if you need to use it again.

package/src/commands/init/templates/quick-reference-postgres.md

@@ -22,7 +22,7 @@ const user = await db.orm.User
   .first();
 
 // Your editor will show the type of user as
-// { id: number; email: string; createdAt: Date, name: string, posts: Post[] } | null
+// { id: number; email: string; username: string | null; name: string | null; createdAt: Date; posts: Post[] } | null
 ```
 
 Your contract has two companion files in the same directory:

package/src/utils/global-flags.ts

@@ -1,3 +1,5 @@
+import { isCI } from './is-ci';
+
 export interface GlobalFlags {
   readonly json?: boolean;
   readonly quiet?: boolean;
@@ -70,8 +72,10 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
   } else if (options.color !== undefined) {
     flags.color = options.color;
   } else {
-    // Default: enable color if TTY
-    flags.color = process.stdout.isTTY && !process.env['CI'];
+    // Default: enable color if TTY and not in CI. Uses the consolidated
+    // `isCI()` helper (`./is-ci.ts`) — the single source of truth shared
+    // with telemetry-skip detection.
+    flags.color = process.stdout.isTTY && !isCI();
   }
 
   // Interactivity: --interactive/--no-interactive

package/src/utils/is-ci.ts

@@ -0,0 +1,18 @@
+import { isCI as ciInfoIsCI } from 'ci-info';
+
+/**
+ * Returns true when the process is running in any CI environment recognised
+ * by the `ci-info` package. The single source of truth for CI detection
+ * across this CLI — colour-output suppression and telemetry-skip both call
+ * this helper, so neither path drifts from the other when a new CI provider
+ * is added upstream.
+ *
+ * `ci-info` checks the standard `CI=true` marker plus dozens of
+ * provider-specific environment variables (Buildkite, Jenkins, Drone,
+ * Bitbucket Pipelines, Azure Pipelines, AWS CodeBuild, …) that the raw
+ * `process.env.CI` read misses.
+ *
+ */
+export function isCI(): boolean {
+  return ciInfoIsCI;
+}