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

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,104 +1,19 @@
-/**
- * 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.
  */
 export const KUBB_NPM_PACKAGE_URL = 'https://registry.npmjs.org/@kubb/cli/latest' as const
 
-/**
- * OpenTelemetry ingestion endpoint for anonymous usage telemetry.
- */
-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.
+ * 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 '@kubb/core'
 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,

package/src/loggers/clackLogger.ts

@@ -2,12 +2,9 @@ import { relative } from 'node:path'
 import process from 'node:process'
 import { styleText } from 'node:util'
 import * as clack from '@clack/prompts'
-import { formatMs, formatMsWithColor, getIntro, toCause } from '@internals/utils'
-import { defineLogger, logLevel as logLevelMap } from '@kubb/core'
-import { getSummary } from '../utils/getSummary.ts'
-import { runHook } from '../utils/runHook.ts'
-import { ClackWritable } from '../utils/Writables.ts'
-import { buildProgressLine, formatCommandWithArgs, formatMessage } from './utils.ts'
+import { formatMsWithColor, getElapsedMs, getIntro, toCause } from '@internals/utils'
+import { defineLogger, Diagnostics, type KubbHooks, logLevel as logLevelMap } from '@kubb/core'
+import { buildProgressLine, createProgressCounters, formatCommandWithArgs, formatMessage, recordPluginResult, resetProgressCounters } from './utils.ts'
 
 /**
  * TTY logger with beautiful UI and progress indicators for local development.
@@ -17,34 +14,39 @@ export const clackLogger = defineLogger({
   install(context, options) {
     const logLevel = options?.logLevel ?? logLevelMap.info
     const state = {
-      totalPlugins: 0,
-      completedPlugins: 0,
-      failedPlugins: 0,
-      totalFiles: 0,
-      processedFiles: 0,
-      hrStart: process.hrtime(),
+      ...createProgressCounters(),
       spinner: clack.spinner(),
       isSpinning: false,
+      runningPlugins: new Set<string>(),
       activeProgress: new Map<string, { interval?: NodeJS.Timeout; progressBar: clack.ProgressResult }>(),
+      activeHookLogs: new Map<string, { taskLog: ReturnType<typeof clack.taskLog>; hrStart: [number, number] }>(),
     }
 
-    function reset() {
-      for (const [_key, active] of state.activeProgress) {
+    // Clear every active progress bar's interval, stop it, and drop the map.
+    function stopActiveProgress() {
+      for (const [, active] of state.activeProgress) {
         if (active.interval) {
           clearInterval(active.interval)
         }
         active.progressBar?.stop()
       }
+      state.activeProgress.clear()
+    }
 
-      state.totalPlugins = 0
-      state.completedPlugins = 0
-      state.failedPlugins = 0
-      state.totalFiles = 0
-      state.processedFiles = 0
-      state.hrStart = process.hrtime()
+    function reset() {
+      stopActiveProgress()
+
+      resetProgressCounters(state)
       state.spinner = clack.spinner()
       state.isSpinning = false
-      state.activeProgress.clear()
+      state.runningPlugins.clear()
+      state.activeHookLogs.clear()
+    }
+
+    // Label for the shared plugin bar, listing the plugins currently generating.
+    function pluginProgressText(): string {
+      const running = [...state.runningPlugins].map((name) => styleText('bold', name))
+      return getMessage(running.length > 0 ? `Generating ${running.join(', ')}` : 'Generating plugins')
     }
 
     function showProgressStep() {
@@ -62,12 +64,25 @@ export const clackLogger = defineLogger({
       return formatMessage(message, logLevel)
     }
 
+    // Registers a handler that prints a fixed step message, skipped at silent level.
+    function onStep<E extends keyof KubbHooks>(event: E, message: string): void {
+      context.on(event, () => {
+        if (logLevel <= logLevelMap.silent) {
+          return
+        }
+        clack.log.step(getMessage(message))
+      })
+    }
+
     function startSpinner(text?: string) {
       state.spinner.start(text)
       state.isSpinning = true
     }
 
     function stopSpinner(text?: string) {
+      if (!state.isSpinning) {
+        return
+      }
       state.spinner.stop(text)
       state.isSpinning = false
     }
@@ -77,13 +92,13 @@ export const clackLogger = defineLogger({
         return
       }
 
-      const text = getMessage([styleText('blue', 'ℹ'), message, styleText('dim', info)].join(' '))
+      const text = getMessage([styleText('blue', 'ℹ'), message, info ? styleText('dim', info) : undefined].filter(Boolean).join(' '))
 
       if (state.isSpinning) {
         state.spinner.message(text)
-      } else {
-        clack.log.info(text)
+        return
       }
+      clack.log.info(text)
     })
 
     context.on('kubb:success', ({ message, info = '' }) => {
@@ -95,9 +110,9 @@ export const clackLogger = defineLogger({
 
       if (state.isSpinning) {
         stopSpinner(text)
-      } else {
-        clack.log.success(text)
+        return
       }
+      clack.log.success(text)
     })
 
     context.on('kubb:warn', ({ message, info }) => {
@@ -119,12 +134,12 @@ export const clackLogger = defineLogger({
 
       if (state.isSpinning) {
         stopSpinner(getMessage(text))
-      } else {
-        clack.log.error(getMessage(text))
+        return
       }
+      clack.log.error(getMessage(text))
 
-      // Show stack trace in debug mode (first 3 frames)
-      if (logLevel >= logLevelMap.debug && error.stack) {
+      // Show stack trace in verbose mode (first 3 frames)
+      if (logLevel >= logLevelMap.verbose && error.stack) {
         const frames = error.stack.split('\n').slice(1, 4)
         for (const frame of frames) {
           clack.log.message(getMessage(styleText('dim', frame.trim())))
@@ -141,14 +156,21 @@ export const clackLogger = defineLogger({
       }
     })
 
-    context.on('kubb:version:new', ({ currentVersion, latestVersion }) => {
-      if (logLevel <= logLevelMap.silent) {
+    context.on('kubb:diagnostic', ({ diagnostic }) => {
+      // Silent still surfaces errors so failures stay visible. It drops warnings and info.
+      if (logLevel <= logLevelMap.silent && diagnostic.severity !== 'error') {
         return
       }
 
-      try {
+      stopSpinner()
+
+      // Stop any lingering progress UI so the multi-line block renders cleanly.
+      stopActiveProgress()
+
+      // The version-update notice keeps its own framed box instead of the diagnostic gutter.
+      if (Diagnostics.isUpdate(diagnostic)) {
         clack.box(
-          `\`v${currentVersion}\` → \`v${latestVersion}\`
+          `\`v${diagnostic.currentVersion}\` → \`v${diagnostic.latestVersion}\`
 Run \`npm install -g @kubb/cli\` to update`,
           'Update available for `Kubb`',
           {
@@ -160,14 +182,19 @@ Run \`npm install -g @kubb/cli\` to update`,
             titleAlign: 'center',
           },
         )
-      } catch {
-        console.log(`Update available for Kubb: v${currentVersion} → v${latestVersion}`)
-        console.log('Run `npm install -g @kubb/cli` to update')
+
+        return
       }
+
+      // Hand the severity glyph to clack as the gutter `symbol`, then let it draw the
+      // bar on each detail line via the default `secondarySymbol`. The headline and
+      // details carry their own colors, so clack only owns the gutter.
+      const { symbol, headline, details } = Diagnostics.format(diagnostic)
+      clack.log.message([headline, ...details], { symbol })
     })
 
     context.on('kubb:lifecycle:start', async ({ version }) => {
-      console.log(`\n${getIntro({ title: 'The ultimate toolkit for working with APIs', description: 'Ready to start', version, areEyesOpen: true })}\n`)
+      console.log(`\n${getIntro({ title: 'The meta framework for code generation', description: 'Ready to start', version, areEyesOpen: true })}\n`)
 
       reset()
     })
@@ -199,11 +226,17 @@ Run \`npm install -g @kubb/cli\` to update`,
       // Initialize progress tracking for this generation
       state.totalPlugins = config.plugins?.length ?? 0
 
+      if (logLevel <= logLevelMap.silent) {
+        return
+      }
+
       const text = getMessage(['Generation started', config.name ? `for ${styleText('dim', config.name)}` : undefined].filter(Boolean).join(' '))
 
       clack.intro(text)
     })
 
+    // Plugins run concurrently, so they share a single progress bar. A bar per plugin
+    // would make clack render them side by side and pile up keypress listeners.
     context.on('kubb:plugin:start', ({ plugin }) => {
       if (logLevel <= logLevelMap.silent) {
         return
@@ -211,50 +244,44 @@ Run \`npm install -g @kubb/cli\` to update`,
 
       stopSpinner()
 
+      state.runningPlugins.add(plugin.name)
+
+      const active = state.activeProgress.get('plugins')
+      if (active) {
+        active.progressBar.advance(0, pluginProgressText())
+        return
+      }
+
       const progressBar = clack.progress({
         style: 'block',
-        max: 100,
+        max: Math.max(state.totalPlugins, 1),
         size: 30,
       })
-      const text = getMessage(`Generating ${styleText('bold', plugin.name)}`)
-      progressBar.start(text)
-
-      const interval = setInterval(() => {
-        progressBar.advance()
-      }, 100)
-
-      state.activeProgress.set(plugin.name, { progressBar, interval })
+      progressBar.start(pluginProgressText())
+      // Catch up to plugins already finished before this bar opened.
+      progressBar.advance(state.completedPlugins + state.failedPlugins, pluginProgressText())
+      state.activeProgress.set('plugins', { progressBar })
     })
 
-    context.on('kubb:plugin:end', ({ plugin, duration, success }) => {
+    context.on('kubb:plugin:end', ({ plugin, success }) => {
       stopSpinner()
 
-      const active = state.activeProgress.get(plugin.name)
+      const active = state.activeProgress.get('plugins')
 
       if (!active || logLevel === logLevelMap.silent) {
         return
       }
 
-      clearInterval(active.interval)
+      state.runningPlugins.delete(plugin.name)
+      recordPluginResult(state, success)
+      active.progressBar.advance(1, pluginProgressText())
 
-      if (success) {
-        state.completedPlugins++
-      } else {
-        state.failedPlugins++
+      // Close the bar once nothing is generating, then print the progress step.
+      if (state.runningPlugins.size === 0) {
+        active.progressBar.stop(getMessage('Plugins generated'))
+        state.activeProgress.delete('plugins')
+        showProgressStep()
       }
-
-      const durationStr = formatMsWithColor(duration)
-      const text = getMessage(
-        success
-          ? `${styleText('bold', plugin.name)} completed in ${durationStr}`
-          : `${styleText('bold', plugin.name)} failed in ${styleText('red', formatMs(duration))}`,
-      )
-
-      active.progressBar.stop(text)
-      state.activeProgress.delete(plugin.name)
-
-      // Show progress step after each plugin
-      showProgressStep()
     })
 
     context.on('kubb:files:processing:start', ({ files }) => {
@@ -279,23 +306,20 @@ Run \`npm install -g @kubb/cli\` to update`,
       state.activeProgress.set('files', { progressBar })
     })
 
-    context.on('kubb:file:processing:update', ({ file, config }) => {
+    context.on('kubb:files:processing:update', ({ files }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
 
       stopSpinner()
 
-      state.processedFiles++
-
-      const text = `Writing ${relative(config.root, file.path)}`
       const active = state.activeProgress.get('files')
-
-      if (!active) {
-        return
+      for (const { file, config } of files) {
+        state.processedFiles++
+        if (active) {
+          active.progressBar.advance(undefined, `Writing ${relative(config.root, file.path)}`)
+        }
       }
-
-      active.progressBar.advance(undefined, text)
     })
     context.on('kubb:files:processing:end', () => {
       if (logLevel <= logLevelMap.silent) {
@@ -319,135 +343,70 @@ Run \`npm install -g @kubb/cli\` to update`,
     })
 
     context.on('kubb:generation:end', ({ config }) => {
+      stopSpinner()
+
       const text = getMessage(config.name ? `Generation completed for ${styleText('dim', config.name)}` : 'Generation completed')
 
       clack.outro(text)
     })
 
-    context.on('kubb:format:start', () => {
-      if (logLevel <= logLevelMap.silent) {
-        return
-      }
+    onStep('kubb:format:start', 'Formatting')
+    onStep('kubb:lint:start', 'Linting')
+    onStep('kubb:hooks:start', 'Running hooks')
 
-      const text = getMessage('Format started')
-
-      clack.intro(text)
-    })
-
-    context.on('kubb:format:end', () => {
-      if (logLevel <= logLevelMap.silent) {
+    context.on('kubb:hook:start', ({ id, command, args }) => {
+      if (logLevel <= logLevelMap.silent || !id) {
         return
       }
 
-      const text = getMessage('Format completed')
-
-      clack.outro(text)
-    })
-
-    context.on('kubb:lint:start', () => {
-      if (logLevel <= logLevelMap.silent) {
-        return
-      }
-
-      const text = getMessage('Lint started')
-
-      clack.intro(text)
-    })
-
-    context.on('kubb:lint:end', () => {
-      if (logLevel <= logLevelMap.silent) {
-        return
-      }
+      stopSpinner()
 
-      const text = getMessage('Lint completed')
+      const commandWithArgs = formatCommandWithArgs(command, args)
+      const title = getMessage(`Running ${styleText('dim', commandWithArgs)}`)
+      const taskLog = clack.taskLog({ title })
 
-      clack.outro(text)
+      state.activeHookLogs.set(id, { taskLog, hrStart: process.hrtime() })
     })
 
-    context.on('kubb:hook:start', async ({ id, command, args }) => {
-      const commandWithArgs = formatCommandWithArgs(command, args)
-      const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
+    // Registered only when not silent, so its presence is what tells the runner to stream
+    // (`kubb:hook:line` listenerCount). At silent level the listener is absent, so no streaming happens.
+    if (logLevel > logLevelMap.silent) {
+      context.on('kubb:hook:line', ({ id, line }) => {
+        const active = state.activeHookLogs.get(id)
+        active?.taskLog.message(styleText('dim', line))
+      })
+    }
 
-      // Skip hook execution if no id is provided (e.g., during benchmarks or tests)
+    context.on('kubb:hook:end', ({ id, command, args, success, error, stdout, stderr }) => {
       if (!id) {
         return
       }
 
       if (logLevel <= logLevelMap.silent) {
-        await runHook({
-          id,
-          command,
-          args,
-          commandWithArgs,
-          context,
-          sink: {
-            onStderr: (s) => console.error(s),
-            onStdout: (s) => console.log(s),
-          },
-        })
+        // Even when silent, surface a failed hook's captured output.
+        if (!success) {
+          if (stdout) console.log(stdout)
+          if (stderr) console.error(stderr)
+        }
         return
       }
 
-      clack.intro(text)
-
-      const logger = clack.taskLog({
-        title: getMessage(['Executing hook', logLevel >= logLevelMap.info ? styleText('dim', commandWithArgs) : undefined].filter(Boolean).join(' ')),
-      })
-
-      const writable = new ClackWritable(logger)
-
-      await runHook({
-        id,
-        command,
-        args,
-        commandWithArgs,
-        context,
-        stream: true,
-        sink: {
-          onLine: (line) => writable.write(line),
-          onStderr: (s) => logger.error(s),
-          onStdout: (s) => logger.message(s),
-        },
-      })
-    })
-
-    context.on('kubb:hook:end', ({ command, args }) => {
-      if (logLevel <= logLevelMap.silent) {
+      const active = state.activeHookLogs.get(id)
+      if (!active) {
         return
       }
+      state.activeHookLogs.delete(id)
 
       const commandWithArgs = formatCommandWithArgs(command, args)
-      const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} successfully executed`)
+      const duration = formatMsWithColor(getElapsedMs(active.hrStart))
 
-      clack.outro(text)
-    })
-
-    context.on('kubb:generation:summary', ({ config, pluginTimings, failedPlugins, filesCreated, status, hrStart }) => {
-      const summary = getSummary({
-        failedPlugins,
-        filesCreated,
-        config,
-        status,
-        hrStart,
-        pluginTimings: logLevel >= logLevelMap.verbose ? pluginTimings : undefined,
-      })
-      const title = config.name || ''
-
-      summary.unshift('\n')
-      summary.push('\n')
-
-      const borderColor = status === 'success' ? 'green' : 'red'
-      try {
-        clack.box(summary.join('\n'), getMessage(title), {
-          width: 'auto',
-          formatBorder: (s: string) => styleText(borderColor, s),
-          rounded: true,
-          withGuide: false,
-          contentAlign: 'left',
-          titleAlign: 'center',
-        })
-      } catch {
-        console.log(summary.join('\n'))
+      if (success) {
+        active.taskLog.success(getMessage(`${styleText('dim', commandWithArgs)} completed in ${duration}`))
+      } else {
+        // The hook's output already reached the taskLog live via `kubb:hook:line`, so `showLog`
+        // replays it here; `kubb:hook:end` carries no captured output on the streaming path.
+        const reason = error?.message ? ` (${error.message})` : ''
+        active.taskLog.error(getMessage(`${styleText('dim', commandWithArgs)} failed${reason}`), { showLog: true })
       }
     })