@kubb/cli 5.0.0-beta.5 → 5.0.0-beta.51

package/src/Telemetry.ts

@@ -0,0 +1,290 @@
+import { randomBytes } from 'node:crypto'
+import os from 'node:os'
+import process from 'node:process'
+import { executeIfOnline, getRuntimeName, getRuntimeVersion, isCIEnvironment, type RuntimeName } 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
+}
+
+/** 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?: 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 plugin options snapshot, values are included but cannot be traced back to the 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: RuntimeName
+  /**
+   * 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 the Kubb run. All methods are static, so call them as
+ * `Telemetry.build(...)`, `Telemetry.send(...)`, and `Telemetry.isDisabled()`. No file paths,
+ * OpenAPI specs, or secrets are ever included, and sending fails silently to never break a run.
+ */
+export class Telemetry {
+  /**
+   * Returns `true` when telemetry is disabled via `DO_NOT_TRACK` or `KUBB_DISABLE_TELEMETRY`.
+   */
+  static 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: getRuntimeName(),
+      runtimeVersion: getRuntimeVersion().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
+    }
+
+    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-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,9 +1,12 @@
 import { defineCommand } from '@internals/utils'
+import type { ReporterName } from '@kubb/core'
 
 export const command = defineCommand({
   name: 'generate',
-  description: "[input] Generate files based on a 'kubb.config.ts' file",
+  description:
+    'Generate TypeScript types, API clients, React Query hooks, Zod schemas, and more from an OpenAPI specification. Reads kubb.config.ts by default. Pass an OpenAPI file path as the first argument to override the input without editing the config.',
   arguments: ['[input]'],
+  examples: ['kubb generate', 'kubb generate ./openapi.yaml', 'kubb generate --config kubb.config.ts', 'kubb generate --watch'],
   options: {
     config: {
       type: 'string',
@@ -12,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',
@@ -24,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',
@@ -42,16 +39,33 @@ 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'],
+    },
+    'no-cache': {
+      type: 'boolean',
+      description: 'Disable the incremental build cache and force a full regeneration',
+      default: false,
+    },
   },
   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,
+      noCache: values['no-cache'],
     })
   },
 })

package/src/commands/init.ts

@@ -3,7 +3,14 @@ import { version } from '../../package.json'
 
 export const command = defineCommand({
   name: 'init',
-  description: 'Initialize a new Kubb project with interactive setup',
+  description:
+    'Scaffold a kubb.config.ts and install plugins for code generation from an OpenAPI spec. Run without flags for interactive setup, or pass --input, --output, and --plugins to skip the prompts.',
+  examples: [
+    'kubb init',
+    'kubb init --yes',
+    'kubb init --input ./openapi.yaml --output ./src/gen --plugins plugin-ts,plugin-zod',
+    'kubb init --plugins plugin-ts,plugin-client,plugin-react-query',
+  ],
   options: {
     yes: {
       type: 'boolean',
@@ -11,10 +18,34 @@ export const command = defineCommand({
       short: 'y',
       default: false,
     },
+    input: {
+      type: 'string',
+      description: 'Path to the OpenAPI specification',
+      short: 'i',
+      hint: 'path',
+    },
+    output: {
+      type: 'string',
+      description: 'Output directory for generated files',
+      short: 'o',
+      hint: 'path',
+    },
+    plugins: {
+      type: 'string',
+      description:
+        'Comma-separated list of plugins to use (plugin-ts, plugin-client, plugin-react-query, plugin-vue-query, plugin-zod, plugin-faker, plugin-msw, plugin-cypress, plugin-mcp, plugin-redoc)',
+      hint: 'plugin-ts,plugin-zod,...',
+    },
   },
   async run({ values }) {
-    const { runInit } = await import('../runners/init.ts')
+    const { run } = await import('../runners/init/run.ts')
 
-    await runInit({ yes: values.yes, version })
+    await run({
+      yes: values.yes,
+      version,
+      input: values.input,
+      output: values.output,
+      plugins: values.plugins,
+    })
   },
 })

package/src/commands/mcp.ts

@@ -3,10 +3,34 @@ import { version } from '../../package.json'
 
 export const command = defineCommand({
   name: 'mcp',
-  description: 'Start the server to enable the MCP client to interact with the LLM.',
-  async run() {
-    const { runMcp } = await import('../runners/mcp.ts')
+  description:
+    'Start a Model Context Protocol (MCP) server that exposes Kubb code generation as tools for AI assistants. Once running, configure your AI client (Claude, Cursor, Windsurf, etc.) to connect to it — the assistant can then call kubb generate directly without leaving the chat.',
+  examples: [
+    'kubb mcp',
+    'kubb mcp --port 3001',
+    '# Then add to your MCP client config:',
+    '# { "mcpServers": { "kubb": { "command": "npx", "args": ["kubb", "mcp"] } } }',
+  ],
+  options: {
+    port: {
+      type: 'string',
+      short: 'p',
+      description: 'Port for HTTP MCP server (omit for stdio)',
+      hint: 'number',
+    },
+    host: {
+      type: 'string',
+      description: 'Hostname to bind to (HTTP mode only)',
+      default: 'localhost',
+    },
+  },
+  async run({ values }) {
+    const { run } = await import('../runners/mcp/run.ts')
 
-    await runMcp({ version })
+    await run({
+      version,
+      port: values.port,
+      host: values.host,
+    })
   },
 })

package/src/commands/validate.ts

@@ -3,18 +3,20 @@ import { version } from '../../package.json'
 
 export const command = defineCommand({
   name: 'validate',
-  description: 'Validate a Swagger/OpenAPI file',
+  description:
+    'Parse and validate an OpenAPI/Swagger file for structural correctness. Reports schema errors, missing required fields, and malformed references. Use this before running generate to catch spec issues early.',
+  examples: ['kubb validate --input ./openapi.yaml', 'kubb validate --input https://petstore3.swagger.io/api/v3/openapi.json'],
   options: {
     input: {
       type: 'string',
-      description: 'Path to Swagger/OpenAPI file',
+      description: 'Path or URL to the OpenAPI/Swagger file to validate',
       short: 'i',
       required: true,
     },
   },
   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,10 +1,3 @@
-/**
- * Default filename for the Kubb configuration file.
- *
- * Used by the `init` command when scaffolding new projects and by the `agent` default config.
- */
-export const KUBB_CONFIG_FILENAME = 'kubb.config.ts' as const
-
 /**
  * NPM registry endpoint used to check for @kubb/cli updates.
  */
@@ -20,85 +13,12 @@ export const OTLP_ENDPOINT = 'https://otlp.kubb.dev' as const
  */
 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.
+ * 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
-
-/**
- * Default values used during interactive `init` scaffolding.
- */
-export const initDefaults = {
-  inputPath: './openapi.yaml',
-  outputPath: './src/gen',
-  plugins: ['plugin-ts'],
-} as const
-
-/**
- * Maps each plugin value to the default config snippet inserted by `init`.
- * The `satisfies` constraint ensures all values remain plain strings while
- * `as const` keeps the object deeply immutable.
- */
-export const pluginDefaultConfigs = {
-  'plugin-ts': `pluginTs({
-      output: { path: 'models' },
-    })`,
-  'plugin-client': `pluginClient({
-      output: { path: 'clients' },
-    })`,
-  'plugin-react-query': `pluginReactQuery({
-      output: { path: 'hooks' },
-    })`,
-  'plugin-vue-query': `pluginVueQuery({
-      output: { path: 'hooks' },
-    })`,
-  'plugin-zod': `pluginZod({
-      output: { path: 'zod' },
-    })`,
-  'plugin-faker': `pluginFaker({
-      output: { path: 'mocks' },
-    })`,
-  'plugin-msw': `pluginMsw({
-      output: { path: 'msw' },
-    })`,
-  'plugin-cypress': `pluginCypress({
-      output: { path: 'cypress' },
-    })`,
-  'plugin-mcp': `pluginMcp({
-      output: { path: 'mcp' },
-    })`,
-  'plugin-redoc': `pluginRedoc({
-      output: { path: 'redoc' },
-    })`,
-} as const satisfies Record<string, string>
-
-/**
- * Color palette used by randomCliColor() for deterministic plugin name coloring.
- */

package/src/index.ts

@@ -1,24 +1,26 @@
 import { styleText } from 'node:util'
-import { createCLI } from '@internals/utils'
+import { createCLI, isFlag } 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()) {
+  if (Telemetry.isDisabled()) {
     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
 }
 
@@ -32,10 +34,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,