@kubb/cli 5.0.0-beta.6 → 5.0.0-beta.61

package/src/Telemetry.ts

@@ -0,0 +1,297 @@
+import { randomBytes } from 'node:crypto'
+import os from 'node:os'
+import process from 'node:process'
+import { isCIEnvironment, runtime } from '@internals/utils'
+import { OTLP_ENDPOINT } from './constants.ts'
+
+// 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: Array<OtlpAnyValue> } }
+type OtlpKvListValue = { kvlistValue: { values: Array<OtlpKeyValue> } }
+
+type OtlpAnyValue = OtlpStringValue | OtlpBoolValue | OtlpIntValue | OtlpDoubleValue | OtlpBytesValue | OtlpArrayValue | OtlpKvListValue
+
+type OtlpKeyValue = {
+  key: string
+  value: OtlpAnyValue
+}
+
+type OtlpResource = {
+  attributes: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+}
+
+type OtlpInstrumentationScope = {
+  name: string
+  version?: string
+  attributes?: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+}
+
+/**
+ * @see https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto#L103
+ */
+type OtlpSpanKind = 0 | 1 | 2 | 3 | 4 | 5
+
+/**
+ * Span status code.
+ * - `0` is unset
+ * - `1` is OK
+ * - `2` is 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?: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+  events?: Array<OtlpSpanEvent>
+  droppedEventsCount?: number
+  links?: Array<OtlpSpanLink>
+  droppedLinksCount?: number
+  status?: OtlpStatus
+}
+
+type OtlpSpanEvent = {
+  timeUnixNano: string
+  name: string
+  attributes?: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+}
+
+type OtlpSpanLink = {
+  traceId: string
+  spanId: string
+  traceState?: string
+  attributes?: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+}
+
+type OtlpScopeSpans = {
+  scope: OtlpInstrumentationScope
+  spans: Array<OtlpSpan>
+  schemaUrl?: string
+}
+
+type OtlpResourceSpans = {
+  resource: OtlpResource
+  scopeSpans: Array<OtlpScopeSpans>
+  schemaUrl?: string
+}
+
+/**
+ * Root payload sent to POST /v1/traces.
+ */
+type OtlpExportTraceServiceRequest = {
+  resourceSpans: Array<OtlpResourceSpans>
+}
+
+/**
+ * Anonymous plugin name and options snapshot sent with each telemetry event.
+ */
+export type TelemetryPlugin = {
+  /**
+   * Plugin name as registered in the Kubb config, e.g. `'@kubb/plugin-ts'`.
+   */
+  name: string
+  /**
+   * Anonymized snapshot of the plugin options. Values are included but cannot be traced back to a user.
+   */
+  options: Record<string, unknown>
+}
+
+export type TelemetryEvent = {
+  command: string
+  kubbVersion: string
+  nodeVersion: string
+  /**
+   * Name of the JavaScript runtime that executed the run, `'bun'`, `'deno'`, or `'node'`.
+   */
+  runtime: string
+  /**
+   * Major version of the active runtime, e.g. `'1'` under Bun or `'22'` under Node.
+   */
+  runtimeVersion: string
+  platform: string
+  ci: boolean
+  plugins: Array<TelemetryPlugin>
+  duration: number
+  filesCreated: number
+  status: 'success' | 'failed'
+}
+
+/**
+ * Anonymous OTLP usage telemetry for a Kubb run. The API is static, so call it as `Telemetry.build(...)`
+ * and `Telemetry.send(...)`. No file paths, OpenAPI specs, or secrets are sent, and sending fails
+ * silently so a failed request never breaks the run.
+ */
+export class Telemetry {
+  /**
+   * Returns `true` when telemetry is disabled via `DO_NOT_TRACK` or `KUBB_DISABLE_TELEMETRY`.
+   */
+  static get isDisabled(): 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'
+    )
+  }
+
+  /**
+   * Build an anonymous telemetry payload from a completed generation run.
+   */
+  static build(options: {
+    command: 'generate' | 'mcp' | 'validate' | 'agent'
+    kubbVersion: string
+    plugins?: Array<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] as string,
+      runtime: runtime.name,
+      runtimeVersion: runtime.version.split('.')[0] as string,
+      platform: os.platform(),
+      ci: isCIEnvironment(),
+      plugins: options.plugins ?? [],
+      duration,
+      filesCreated: options.filesCreated ?? 0,
+      status: options.status,
+    }
+  }
+
+  /**
+   * Convert a {@link TelemetryEvent} into an OTLP-compatible JSON trace payload.
+   * See https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/
+   */
+  static 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: Array<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.runtime', value: { stringValue: event.runtime } },
+      { key: 'kubb.runtime_version', value: { stringValue: event.runtimeVersion } },
+      { 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,
+                          usedEnumNames: undefined,
+                        }),
+                      },
+                    },
+                  ],
+                },
+              }),
+            ),
+          },
+        },
+      },
+    ]
+
+    return {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [
+              { key: 'service.name', value: { stringValue: 'kubb-core' } },
+              {
+                key: 'service.version',
+                value: { stringValue: event.kubbVersion },
+              },
+              { key: 'telemetry.sdk.language', value: { stringValue: 'nodejs' } },
+            ],
+          },
+          scopeSpans: [
+            {
+              scope: { name: 'kubb-core', 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`, and fails silently so telemetry never interrupts a run.
+   */
+  static async send(event: TelemetryEvent): Promise<void> {
+    if (Telemetry.isDisabled) {
+      return
+    }
+
+    try {
+      await fetch(`${OTLP_ENDPOINT}/v1/traces`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Kubb-Telemetry-Version': '1',
+          'Kubb-Telemetry-Source': 'kubb-core',
+        },
+        body: JSON.stringify(Telemetry.buildOtlpPayload(event)),
+        signal: AbortSignal.timeout(5_000),
+      })
+    } catch (_e) {
+      // Fail silently, telemetry must never break the run
+    }
+  }
+}

package/src/commands/generate.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from '@internals/utils'
+import type { ReporterName } from '@kubb/core'
 
 export const command = defineCommand({
   name: 'generate',
@@ -14,11 +15,11 @@ export const command = defineCommand({
     },
     logLevel: {
       type: 'string',
-      description: 'Info, silent, verbose or debug',
+      description: 'Info, silent or verbose',
       short: 'l',
       default: 'info',
-      hint: 'silent|info|verbose|debug',
-      enum: ['silent', 'info', 'verbose', 'debug'],
+      hint: 'silent|info|verbose',
+      enum: ['silent', 'info', 'verbose'],
     },
     watch: {
       type: 'boolean',
@@ -26,12 +27,6 @@ export const command = defineCommand({
       short: 'w',
       default: false,
     },
-    debug: {
-      type: 'boolean',
-      description: 'Override logLevel to debug',
-      short: 'd',
-      default: false,
-    },
     verbose: {
       type: 'boolean',
       description: 'Override logLevel to verbose',
@@ -44,16 +39,27 @@ export const command = defineCommand({
       short: 's',
       default: false,
     },
+    reporter: {
+      type: 'string',
+      description: 'Reporters that render the run, comma-separated. Overrides config.reporters',
+      hint: 'cli|json|file',
+      enum: ['cli', 'json', 'file'],
+    },
   },
   async run({ values, positionals }) {
-    const logLevel = values.debug ? 'debug' : values.verbose ? 'verbose' : values.silent ? 'silent' : values.logLevel
-    const { runGenerateCommand } = await import('../runners/generate.ts')
+    const logLevel = values.verbose ? 'verbose' : values.silent ? 'silent' : values.logLevel
+    const reporters = values.reporter
+      ?.split(',')
+      .map((name) => name.trim())
+      .filter(Boolean) as Array<ReporterName> | undefined
+    const { run } = await import('../runners/generate/run.ts')
 
-    await runGenerateCommand({
+    await run({
       input: positionals[0],
       configPath: values.config,
       logLevel,
       watch: values.watch,
+      reporters,
     })
   },
 })

package/src/commands/init.ts

@@ -38,9 +38,9 @@ export const command = defineCommand({
     },
   },
   async run({ values }) {
-    const { runInit } = await import('../runners/init.ts')
+    const { run } = await import('../runners/init/run.ts')
 
-    await runInit({
+    await run({
       yes: values.yes,
       version,
       input: values.input,

package/src/commands/mcp.ts

@@ -25,9 +25,9 @@ export const command = defineCommand({
     },
   },
   async run({ values }) {
-    const { runMcp } = await import('../runners/mcp.ts')
+    const { run } = await import('../runners/mcp/run.ts')
 
-    await runMcp({
+    await run({
       version,
       port: values.port,
       host: values.host,

package/src/commands/validate.ts

@@ -15,8 +15,8 @@ export const command = defineCommand({
     },
   },
   async run({ values }) {
-    const { runValidate } = await import('../runners/validate.ts')
+    const { run } = await import('../runners/validate/run.ts')
 
-    await runValidate({ input: values.input, version })
+    await run({ input: values.input, version })
   },
 })

package/src/constants.ts

@@ -1,5 +1,3 @@
-import { KUBB_CONFIG_FILENAME } from '@internals/shared'
-
 /**
  * NPM registry endpoint used to check for @kubb/cli updates.
  */
@@ -10,43 +8,12 @@ export const KUBB_NPM_PACKAGE_URL = 'https://registry.npmjs.org/@kubb/cli/latest
  */
 export const OTLP_ENDPOINT = 'https://otlp.kubb.dev' as const
 
-/**
- * Horizontal rule rendered above/below the plain-logger generation summary.
- */
-export const SUMMARY_SEPARATOR = '─'.repeat(27)
-
-/**
- * Maximum number of █ characters in a plugin timing bar.
- */
-export const SUMMARY_MAX_BAR_LENGTH = 10 as const
-
-/**
- * Divides elapsed milliseconds into bar-length units (1 block per 100 ms).
- */
-export const SUMMARY_TIME_SCALE_DIVISOR = 100 as const
-
 /**
  * Glob pattern for paths the file watcher ignores.
  */
 export const WATCHER_IGNORED_PATHS = '**/{.git,node_modules}/**' as const
 
 /**
- * Flags that short-circuit execution (help/version) — no telemetry notice is shown.
- */
-export const QUIET_FLAGS = new Set(['--help', '-h', '--version', '-v'] as const)
-
-export const agentDefaults = {
-  port: '3000',
-  host: 'localhost',
-  configFile: KUBB_CONFIG_FILENAME,
-  retryTimeout: '30000',
-  studioUrl: 'https://kubb.studio',
-  /**
-   * Relative path from the @kubb/agent package root to the server entry.
-   */
-  serverEntryPath: '.output/server/index.mjs',
-} as const
-
-/**
- * Color palette used by randomCliColor() for deterministic plugin name coloring.
+ * Flags that short-circuit execution (help and version). The telemetry notice is suppressed for these.
  */
+export const QUIET_FLAGS = new Set<string>(['--help', '-h', '--version', '-v'])

package/src/index.ts

@@ -1,29 +1,14 @@
 import { styleText } from 'node:util'
 import { createCLI } from '@internals/utils'
+import { Telemetry } from './Telemetry.ts'
 import { version } from '../package.json'
 import { QUIET_FLAGS } from './constants.ts'
-import { isFlag } from './utils/flags.ts'
-import { isTelemetryDisabled } from './utils/telemetry.ts'
 
 const cli = createCLI()
-
-function shouldShowTelemetryNotice(argv: Array<string>): boolean {
-  if (isTelemetryDisabled()) {
-    return false
-  }
-  // Skip when the user is just asking for help or version info
-  if (argv.some((arg) => isFlag(QUIET_FLAGS, arg))) {
-    return false
-  }
-  // Skip in non-interactive / scripting contexts
-  if (!process.stdout.isTTY) {
-    return false
-  }
-  return true
-}
-
 export async function run(argv: Array<string> = process.argv): Promise<void> {
-  if (shouldShowTelemetryNotice(argv)) {
+  const isQuietFlag = argv.some((arg) => QUIET_FLAGS.has(arg))
+
+  if (!Telemetry.isDisabled && !isQuietFlag) {
     console.log(
       `${styleText('yellow', 'Notice:')} Kubb collects anonymous telemetry data to help improve the tool. No personal data or file contents are collected. \nTo disable, set ${styleText('cyan', 'KUBB_DISABLE_TELEMETRY=1')}.\n`,
     )
@@ -32,10 +17,9 @@ export async function run(argv: Array<string> = process.argv): Promise<void> {
   const { command: generateCommand } = await import('./commands/generate.ts')
   const { command: validateCommand } = await import('./commands/validate.ts')
   const { command: mcpCommand } = await import('./commands/mcp.ts')
-  const { command: agentCommand } = await import('./commands/agent.ts')
   const { command: initCommand } = await import('./commands/init.ts')
 
-  await cli.run([generateCommand, validateCommand, mcpCommand, agentCommand, initCommand], argv, {
+  await cli.run([generateCommand, validateCommand, mcpCommand, initCommand], argv, {
     programName: 'kubb',
     defaultCommandName: 'generate',
     version,