@kubb/cli 4.29.0 → 4.31.0

package/dist/{validate-DOeZKiGx.js → validate-zO3bvm66.js}

@@ -1,4 +1,6 @@
 import { t as __name } from "./chunk-DKWOrOAv.js";
+import { t as version } from "./package-BYVzWUJV.js";
+import { n as sendTelemetry, t as buildTelemetryEvent } from "./telemetry-Ccka73zO.js";
 import { defineCommand, showUsage } from "citty";
 import process from "node:process";
 import { createJiti } from "jiti";
@@ -35,10 +37,23 @@ const command = defineCommand({
 				process.exit(1);
 			}
 			const { parse } = mod;
+			const hrStart = process.hrtime();
 			try {
 				await (await parse(args.input)).validate();
+				await sendTelemetry(buildTelemetryEvent({
+					command: "validate",
+					kubbVersion: version,
+					hrStart,
+					status: "success"
+				}));
 				console.log("✅ Validation success");
 			} catch (error) {
+				await sendTelemetry(buildTelemetryEvent({
+					command: "validate",
+					kubbVersion: version,
+					hrStart,
+					status: "failed"
+				}));
 				console.error("❌ Validation failed");
 				console.log(error?.message);
 				process.exit(1);
@@ -49,4 +64,4 @@ const command = defineCommand({
 
 //#endregion
 export { command as default };
-//# sourceMappingURL=validate-DOeZKiGx.js.map
+//# sourceMappingURL=validate-zO3bvm66.js.map

package/dist/validate-zO3bvm66.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-zO3bvm66.js","names":[],"sources":["../src/commands/validate.ts"],"sourcesContent":["import process from 'node:process'\nimport type { ArgsDef } from 'citty'\nimport { defineCommand, showUsage } from 'citty'\nimport { createJiti } from 'jiti'\nimport { version } from '../../package.json'\nimport { buildTelemetryEvent, sendTelemetry } from '../utils/telemetry.ts'\n\nconst jiti = createJiti(import.meta.url, {\n  sourceMaps: true,\n})\n\nconst args = {\n  input: {\n    type: 'string',\n    description: 'Path to Swagger/OpenAPI file',\n    alias: 'i',\n  },\n  help: {\n    type: 'boolean',\n    description: 'Show help',\n    alias: 'h',\n    default: false,\n  },\n} as const satisfies ArgsDef\n\nconst command = defineCommand({\n  meta: {\n    name: 'validate',\n    description: 'Validate a Swagger/OpenAPI file',\n  },\n  args,\n  async run(commandContext) {\n    const { args } = commandContext\n\n    if (args.help) {\n      return showUsage(command)\n    }\n\n    if (args.input) {\n      let mod: any\n      try {\n        mod = await jiti.import('@kubb/oas', { default: true })\n      } catch (_e) {\n        console.error(`Import of '@kubb/oas' is required to do validation`)\n        process.exit(1)\n      }\n\n      const { parse } = mod\n      const hrStart = process.hrtime()\n      try {\n        const oas = await parse(args.input)\n        await oas.validate()\n\n        await sendTelemetry(buildTelemetryEvent({ command: 'validate', kubbVersion: version, hrStart, status: 'success' }))\n        console.log('✅ Validation success')\n      } catch (error) {\n        await sendTelemetry(buildTelemetryEvent({ command: 'validate', kubbVersion: version, hrStart, status: 'failed' }))\n        console.error('❌ Validation failed')\n        console.log((error as Error)?.message)\n        process.exit(1)\n      }\n    }\n  },\n})\n\nexport default command\n"],"mappings":";;;;;;;;AAOA,MAAM,OAAO,WAAW,OAAO,KAAK,KAAK,EACvC,YAAY,MACb,CAAC;AAgBF,MAAM,UAAU,cAAc;CAC5B,MAAM;EACJ,MAAM;EACN,aAAa;EACd;CACD,MAnBW;EACX,OAAO;GACL,MAAM;GACN,aAAa;GACb,OAAO;GACR;EACD,MAAM;GACJ,MAAM;GACN,aAAa;GACb,OAAO;GACP,SAAS;GACV;EACF;CAQC,MAAM,IAAI,gBAAgB;EACxB,MAAM,EAAE,SAAS;AAEjB,MAAI,KAAK,KACP,QAAO,UAAU,QAAQ;AAG3B,MAAI,KAAK,OAAO;GACd,IAAI;AACJ,OAAI;AACF,UAAM,MAAM,KAAK,OAAO,aAAa,EAAE,SAAS,MAAM,CAAC;YAChD,IAAI;AACX,YAAQ,MAAM,qDAAqD;AACnE,YAAQ,KAAK,EAAE;;GAGjB,MAAM,EAAE,UAAU;GAClB,MAAM,UAAU,QAAQ,QAAQ;AAChC,OAAI;AAEF,WADY,MAAM,MAAM,KAAK,MAAM,EACzB,UAAU;AAEpB,UAAM,cAAc,oBAAoB;KAAE,SAAS;KAAY,aAAa;KAAS;KAAS,QAAQ;KAAW,CAAC,CAAC;AACnH,YAAQ,IAAI,uBAAuB;YAC5B,OAAO;AACd,UAAM,cAAc,oBAAoB;KAAE,SAAS;KAAY,aAAa;KAAS;KAAS,QAAQ;KAAU,CAAC,CAAC;AAClH,YAAQ,MAAM,sBAAsB;AACpC,YAAQ,IAAK,OAAiB,QAAQ;AACtC,YAAQ,KAAK,EAAE;;;;CAItB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/cli",
-  "version": "4.29.0",
+  "version": "4.31.0",
   "description": "Command-line interface for Kubb, enabling easy generation of TypeScript, React-Query, Zod, and other code from OpenAPI specifications.",
   "keywords": [
     "cli",
@@ -42,7 +42,8 @@
     "dist",
     "bin",
     "!/**/**.test.**",
-    "!/**/__tests__/**"
+    "!/**/__tests__/**",
+    "!/**/__snapshots__/**"
   ],
   "size-limit": [
     {
@@ -55,16 +56,16 @@
     "@clack/prompts": "^1.0.1",
     "chokidar": "^5.0.0",
     "citty": "^0.1.6",
-    "cosmiconfig": "^9.0.0",
+    "cosmiconfig": "^9.0.1",
     "jiti": "2.5.1",
     "tinyexec": "^1.0.2",
-    "@kubb/core": "4.29.0"
+    "@kubb/core": "4.31.0"
   },
   "devDependencies": {
     "source-map-support": "^0.5.21",
-    "@kubb/agent": "4.29.0",
-    "@kubb/mcp": "4.29.0",
-    "@kubb/oas": "4.29.0"
+    "@kubb/agent": "4.31.0",
+    "@kubb/mcp": "4.31.0",
+    "@kubb/oas": "4.31.0"
   },
   "engines": {
     "node": ">=20"

package/src/commands/agent/start.ts

@@ -6,6 +6,8 @@ import { styleText } from 'node:util'
 import * as clack from '@clack/prompts'
 import type { ArgsDef } from 'citty'
 import { defineCommand } from 'citty'
+import { version } from '../../../package.json'
+import { buildTelemetryEvent, sendTelemetry } from '../../utils/telemetry.ts'
 
 const args = {
   config: {
@@ -122,6 +124,7 @@ const command = defineCommand({
   args,
   async run(commandContext) {
     const { args } = commandContext
+    const hrStart = process.hrtime()
 
     try {
       const configPath = path.resolve(process.cwd(), args.config || 'kubb.config.ts')
@@ -131,8 +134,10 @@ const command = defineCommand({
       const allowWrite = args['allow-write']
       const allowAll = args['allow-all']
 
-      await startServer({ port, host, configPath, noCache, allowWrite, allowAll })
+      startServer({ port, host, configPath, noCache, allowWrite, allowAll })
+      await sendTelemetry(buildTelemetryEvent({ command: 'agent', kubbVersion: version, hrStart, status: 'success' }))
     } catch (error) {
+      await sendTelemetry(buildTelemetryEvent({ command: 'agent', kubbVersion: version, hrStart, status: 'failed' }))
       clack.log.error(styleText('red', 'Failed to start agent server'))
       console.error(error)
       process.exit(1)

package/src/commands/generate.ts

@@ -122,6 +122,9 @@ const command = defineCommand({
         return async () => {
           if (isInputPath(config) && args.watch) {
             await startWatcher([input || config.input.path], async (paths) => {
+              // remove to avoid duplicate listeners after each change
+              events.removeAll()
+
               await generate({
                 input,
                 config,

package/src/commands/init.ts

@@ -3,9 +3,10 @@ import path from 'node:path'
 import process from 'node:process'
 import { styleText } from 'node:util'
 import * as clack from '@clack/prompts'
+import { detectPackageManager, type PackageManagerInfo } from '@kubb/core'
 import { defineCommand } from 'citty'
 import { version } from '../../package.json'
-import { detectPackageManager, hasPackageJson, initPackageJson, installPackages, type PackageManagerInfo } from '../utils/packageManager.ts'
+import { hasPackageJson, initPackageJson, installPackages } from '../utils/packageManager.ts'
 
 type PluginOption = {
   value: string

package/src/commands/mcp.ts

@@ -1,7 +1,10 @@
+import process from 'node:process'
 import { styleText } from 'node:util'
 import type { ArgsDef } from 'citty'
 import { defineCommand, showUsage } from 'citty'
 import { createJiti } from 'jiti'
+import { version } from '../../package.json'
+import { buildTelemetryEvent, sendTelemetry } from '../utils/telemetry.ts'
 
 const jiti = createJiti(import.meta.url, {
   sourceMaps: true,
@@ -38,11 +41,14 @@ const command = defineCommand({
     }
 
     const { run } = mod
+    const hrStart = process.hrtime()
     try {
       console.log('⏳ Starting MCP server...')
       console.warn(styleText('yellow', 'This feature is still under development — use with caution'))
-      await run()
+      run()
+      await sendTelemetry(buildTelemetryEvent({ command: 'mcp', kubbVersion: version, hrStart, status: 'success' }))
     } catch (error) {
+      await sendTelemetry(buildTelemetryEvent({ command: 'mcp', kubbVersion: version, hrStart, status: 'failed' }))
       console.error((error as Error)?.message)
     }
   },

package/src/commands/validate.ts

@@ -2,6 +2,8 @@ import process from 'node:process'
 import type { ArgsDef } from 'citty'
 import { defineCommand, showUsage } from 'citty'
 import { createJiti } from 'jiti'
+import { version } from '../../package.json'
+import { buildTelemetryEvent, sendTelemetry } from '../utils/telemetry.ts'
 
 const jiti = createJiti(import.meta.url, {
   sourceMaps: true,
@@ -44,12 +46,15 @@ const command = defineCommand({
       }
 
       const { parse } = mod
+      const hrStart = process.hrtime()
       try {
         const oas = await parse(args.input)
         await oas.validate()
 
+        await sendTelemetry(buildTelemetryEvent({ command: 'validate', kubbVersion: version, hrStart, status: 'success' }))
         console.log('✅ Validation success')
       } catch (error) {
+        await sendTelemetry(buildTelemetryEvent({ command: 'validate', kubbVersion: version, hrStart, status: 'failed' }))
         console.error('❌ Validation failed')
         console.log((error as Error)?.message)
         process.exit(1)

package/src/runners/generate.ts

@@ -5,7 +5,9 @@ import { styleText } from 'node:util'
 import { type Config, type KubbEvents, LogLevel, safeBuild, setup } from '@kubb/core'
 import type { AsyncEventEmitter } from '@kubb/core/utils'
 import { detectFormatter, detectLinter, formatters, linters } from '@kubb/core/utils'
+import { version } from '../../package.json'
 import { executeHooks } from '../utils/executeHooks.ts'
+import { buildTelemetryEvent, sendTelemetry } from '../utils/telemetry.ts'
 
 type GenerateProps = {
   input?: string
@@ -80,11 +82,22 @@ export async function generate({ input, config: userConfig, events, logLevel }:
     await events.emit('generation:summary', config, {
       failedPlugins,
       filesCreated: files.length,
-      status: failedPlugins.size > 0 || error ? 'failed' : 'success',
+      status: 'failed',
       hrStart,
       pluginTimings: logLevel >= LogLevel.verbose ? pluginTimings : undefined,
     })
 
+    await sendTelemetry(
+      buildTelemetryEvent({
+        command: 'generate',
+        kubbVersion: version,
+        plugins: pluginManager.plugins.map((p) => ({ name: p.name, options: p.options as Record<string, unknown> })),
+        hrStart,
+        filesCreated: files.length,
+        status: 'failed',
+      }),
+    )
+
     process.exit(1)
   }
 
@@ -194,11 +207,24 @@ export async function generate({ input, config: userConfig, events, logLevel }:
     await events.emit('hooks:end')
   }
 
+  const generationStatus = failedPlugins.size > 0 || error ? 'failed' : 'success'
+
   await events.emit('generation:summary', config, {
     failedPlugins,
     filesCreated: files.length,
-    status: failedPlugins.size > 0 || error ? 'failed' : 'success',
+    status: generationStatus,
     hrStart,
     pluginTimings,
   })
+
+  const telemetryEvent = buildTelemetryEvent({
+    command: 'generate',
+    kubbVersion: version,
+    plugins: pluginManager.plugins.map((p) => ({ name: p.name, options: p.options as Record<string, unknown> })),
+    hrStart,
+    filesCreated: files.length,
+    status: generationStatus,
+  })
+
+  await sendTelemetry(telemetryEvent)
 }

package/src/utils/packageManager.ts

@@ -1,72 +1,14 @@
 import { spawn } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
-
-export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun'
-
-export interface PackageManagerInfo {
-  name: PackageManager
-  lockFile: string
-  installCommand: string[]
-}
-
-const packageManagers: Record<PackageManager, PackageManagerInfo> = {
-  pnpm: {
-    name: 'pnpm',
-    lockFile: 'pnpm-lock.yaml',
-    installCommand: ['add', '-D'],
-  },
-  yarn: {
-    name: 'yarn',
-    lockFile: 'yarn.lock',
-    installCommand: ['add', '-D'],
-  },
-  bun: {
-    name: 'bun',
-    lockFile: 'bun.lockb',
-    installCommand: ['add', '-d'],
-  },
-  npm: {
-    name: 'npm',
-    lockFile: 'package-lock.json',
-    installCommand: ['install', '--save-dev'],
-  },
-}
-
-export function detectPackageManager(cwd: string = process.cwd()): PackageManagerInfo {
-  // Check for packageManager field in package.json
-  const packageJsonPath = path.join(cwd, 'package.json')
-  if (fs.existsSync(packageJsonPath)) {
-    try {
-      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
-      if (packageJson.packageManager) {
-        const [name] = packageJson.packageManager.split('@')
-        if (name in packageManagers) {
-          return packageManagers[name as PackageManager]
-        }
-      }
-    } catch {
-      // Continue to lock file detection
-    }
-  }
-
-  // Check for lock files
-  for (const pm of Object.values(packageManagers)) {
-    if (fs.existsSync(path.join(cwd, pm.lockFile))) {
-      return pm
-    }
-  }
-
-  // Default to npm
-  return packageManagers.npm
-}
+import type { PackageManagerInfo, PackageManagerName } from '@kubb/core'
 
 export function hasPackageJson(cwd: string = process.cwd()): boolean {
   return fs.existsSync(path.join(cwd, 'package.json'))
 }
 
 export async function initPackageJson(cwd: string, packageManager: PackageManagerInfo): Promise<void> {
-  const commands: Record<PackageManager, string[]> = {
+  const commands: Record<PackageManagerName, string[]> = {
     npm: ['init', '-y'],
     pnpm: ['init'],
     yarn: ['init', '-y'],

package/src/utils/telemetry.ts

@@ -0,0 +1,278 @@
+import { randomBytes } from 'node:crypto'
+import os from 'node:os'
+import process from 'node:process'
+import { executeIfOnline } from '@kubb/core/utils'
+
+const OTLP_ENDPOINT = 'https://otlp.kubb.dev'
+
+// ---------------------------------------------------------------------------
+// OpenTelemetry OTLP JSON types
+// https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto
+// https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/common/v1/common.proto
+// ---------------------------------------------------------------------------
+
+type OtlpStringValue = { stringValue: string }
+type OtlpBoolValue = { boolValue: boolean }
+type OtlpIntValue = { intValue: number }
+type OtlpDoubleValue = { doubleValue: number }
+type OtlpBytesValue = { bytesValue: string }
+type OtlpArrayValue = { arrayValue: { values: OtlpAnyValue[] } }
+type OtlpKvListValue = { kvlistValue: { values: OtlpKeyValue[] } }
+
+type OtlpAnyValue = OtlpStringValue | OtlpBoolValue | OtlpIntValue | OtlpDoubleValue | OtlpBytesValue | OtlpArrayValue | OtlpKvListValue
+
+type OtlpKeyValue = {
+  key: string
+  value: OtlpAnyValue
+}
+
+type OtlpResource = {
+  attributes: OtlpKeyValue[]
+  droppedAttributesCount?: number
+}
+
+type OtlpInstrumentationScope = {
+  name: string
+  version?: string
+  attributes?: OtlpKeyValue[]
+  droppedAttributesCount?: number
+}
+
+/** https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto#L103 */
+type OtlpSpanKind = 0 | 1 | 2 | 3 | 4 | 5
+
+/** 0 = STATUS_CODE_UNSET, 1 = STATUS_CODE_OK, 2 = STATUS_CODE_ERROR */
+type OtlpStatusCode = 0 | 1 | 2
+
+type OtlpStatus = {
+  code: OtlpStatusCode
+  message?: string
+}
+
+type OtlpSpan = {
+  traceId: string
+  spanId: string
+  traceState?: string
+  parentSpanId?: string
+  name: string
+  kind: OtlpSpanKind
+  startTimeUnixNano: string
+  endTimeUnixNano: string
+  attributes?: OtlpKeyValue[]
+  droppedAttributesCount?: number
+  events?: OtlpSpanEvent[]
+  droppedEventsCount?: number
+  links?: OtlpSpanLink[]
+  droppedLinksCount?: number
+  status?: OtlpStatus
+}
+
+type OtlpSpanEvent = {
+  timeUnixNano: string
+  name: string
+  attributes?: OtlpKeyValue[]
+  droppedAttributesCount?: number
+}
+
+type OtlpSpanLink = {
+  traceId: string
+  spanId: string
+  traceState?: string
+  attributes?: OtlpKeyValue[]
+  droppedAttributesCount?: number
+}
+
+type OtlpScopeSpans = {
+  scope: OtlpInstrumentationScope
+  spans: OtlpSpan[]
+  schemaUrl?: string
+}
+
+type OtlpResourceSpans = {
+  resource: OtlpResource
+  scopeSpans: OtlpScopeSpans[]
+  schemaUrl?: string
+}
+
+/** Root payload sent to POST /v1/traces */
+export type OtlpExportTraceServiceRequest = {
+  resourceSpans: OtlpResourceSpans[]
+}
+
+// ---------------------------------------------------------------------------
+
+export type TelemetryPlugin = {
+  name: string
+  options: Record<string, unknown>
+}
+
+export type TelemetryEvent = {
+  command: string
+  kubbVersion: string
+  nodeVersion: string
+  platform: string
+  ci: boolean
+  plugins: TelemetryPlugin[]
+  duration: number
+  filesCreated: number
+  status: 'success' | 'failed'
+}
+
+/**
+ * Detect whether the current process is running inside a CI environment by
+ * checking the well-known environment variables set by all major CI systems.
+ */
+export function isCi(): boolean {
+  return !!(
+    (
+      process.env['CI'] || // Generic (GitHub Actions, GitLab CI, CircleCI, Travis CI, etc.)
+      process.env['GITHUB_ACTIONS'] || // GitHub Actions
+      process.env['GITLAB_CI'] || // GitLab CI
+      process.env['BITBUCKET_BUILD_NUMBER'] || // Bitbucket Pipelines
+      process.env['JENKINS_URL'] || // Jenkins
+      process.env['CIRCLECI'] || // CircleCI
+      process.env['TRAVIS'] || // Travis CI
+      process.env['TEAMCITY_VERSION'] || // TeamCity
+      process.env['BUILDKITE'] || // Buildkite
+      process.env['TF_BUILD']
+    ) // Azure Pipelines
+  )
+}
+
+/**
+ * Check if telemetry is disabled via DO_NOT_TRACK or KUBB_DISABLE_TELEMETRY.
+ * Respects the standard DO_NOT_TRACK convention used across development tools.
+ */
+export function isTelemetryDisabled(): boolean {
+  return (
+    process.env['DO_NOT_TRACK'] === '1' ||
+    process.env['DO_NOT_TRACK'] === 'true' ||
+    process.env['KUBB_DISABLE_TELEMETRY'] === '1' ||
+    process.env['KUBB_DISABLE_TELEMETRY'] === 'true'
+  )
+}
+
+/**
+ * Convert a TelemetryEvent into an OTLP-compatible JSON trace payload.
+ * See https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/
+ */
+export function buildOtlpPayload(event: TelemetryEvent): OtlpExportTraceServiceRequest {
+  const traceId = randomBytes(16).toString('hex')
+  const spanId = randomBytes(8).toString('hex')
+  const endTimeNs = BigInt(Date.now()) * 1_000_000n
+  const startTimeNs = endTimeNs - BigInt(event.duration) * 1_000_000n
+
+  const attributes: OtlpKeyValue[] = [
+    { key: 'kubb.command', value: { stringValue: event.command } },
+    { key: 'kubb.version', value: { stringValue: event.kubbVersion } },
+    { key: 'kubb.node_version', value: { stringValue: event.nodeVersion } },
+    { key: 'kubb.platform', value: { stringValue: event.platform } },
+    { key: 'kubb.ci', value: { boolValue: event.ci } },
+    { key: 'kubb.files_created', value: { intValue: event.filesCreated } },
+    { key: 'kubb.status', value: { stringValue: event.status } },
+    {
+      key: 'kubb.plugins',
+      value: {
+        arrayValue: {
+          values: event.plugins.map(
+            (p): OtlpKvListValue => ({
+              kvlistValue: {
+                values: [
+                  { key: 'name', value: { stringValue: p.name } },
+                  { key: 'options', value: { stringValue: JSON.stringify(p.options) } },
+                ],
+              },
+            }),
+          ),
+        },
+      },
+    },
+  ]
+
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            { key: 'service.name', value: { stringValue: 'kubb-cli' } },
+            { key: 'service.version', value: { stringValue: event.kubbVersion } },
+            { key: 'telemetry.sdk.language', value: { stringValue: 'nodejs' } },
+          ],
+        },
+        scopeSpans: [
+          {
+            scope: { name: 'kubb-cli', version: event.kubbVersion },
+            spans: [
+              {
+                traceId,
+                spanId,
+                name: event.command,
+                kind: 1 satisfies OtlpSpanKind,
+                startTimeUnixNano: String(startTimeNs),
+                endTimeUnixNano: String(endTimeNs),
+                attributes,
+                status: { code: (event.status === 'success' ? 1 : 2) satisfies OtlpStatusCode },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  }
+}
+
+/**
+ * Send an anonymous telemetry event to the Kubb OTLP endpoint.
+ * Respects DO_NOT_TRACK and KUBB_DISABLE_TELEMETRY environment variables.
+ * Fails silently to never interrupt the generation process.
+ */
+export async function sendTelemetry(event: TelemetryEvent): Promise<void> {
+  if (isTelemetryDisabled()) {
+    return
+  }
+
+  await executeIfOnline(async () => {
+    try {
+      await fetch(`${OTLP_ENDPOINT}/v1/traces`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Kubb-Telemetry-Version': '1',
+          'Kubb-Telemetry-Source': 'kubb-cli',
+        },
+        body: JSON.stringify(buildOtlpPayload(event)),
+        signal: AbortSignal.timeout(5_000),
+      })
+    } catch (_e) {
+      // Fail silently – telemetry must never break the CLI
+    }
+  })
+}
+
+/**
+ * Build an anonymous telemetry payload from a completed generation run.
+ * No file paths, OpenAPI specs, or secrets are included.
+ */
+export function buildTelemetryEvent(options: {
+  command: 'generate' | 'mcp' | 'validate' | 'agent'
+  kubbVersion: string
+  plugins?: TelemetryPlugin[]
+  hrStart: [number, number]
+  filesCreated?: number
+  status: 'success' | 'failed'
+}): TelemetryEvent {
+  const [seconds, nanoseconds] = process.hrtime(options.hrStart)
+  const duration = Math.round(seconds * 1000 + nanoseconds / 1e6)
+
+  return {
+    command: options.command,
+    kubbVersion: options.kubbVersion,
+    nodeVersion: process.versions.node.split('.')[0] ?? 'unknown',
+    platform: os.platform(),
+    ci: isCi(),
+    plugins: options.plugins ?? [],
+    duration,
+    filesCreated: options.filesCreated ?? 0,
+    status: options.status,
+  }
+}