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

package/src/loggers/utils.ts

@@ -1,13 +1,57 @@
+import path from 'node:path'
 import { styleText } from 'node:util'
-import { canUseTTY, formatHrtime, isGitHubActions } from '@internals/utils'
-import type { Logger, LoggerContext, LoggerOptions } from '@kubb/core'
+import { canUseTTY, formatHrtime, isGitHubActions, randomCliColor } from '@internals/utils'
+import type { Config, Logger, LoggerContext, LoggerOptions, Plugin } from '@kubb/core'
 import { logLevel as logLevelMap } from '@kubb/core'
+import { SUMMARY_MAX_BAR_LENGTH, SUMMARY_TIME_SCALE_DIVISOR } from '../constants.ts'
 import { clackLogger } from './clackLogger.ts'
 import { fileSystemLogger } from './fileSystemLogger.ts'
 import { githubActionsLogger } from './githubActionsLogger.ts'
 import { plainLogger } from './plainLogger.ts'
 import type { LoggerType } from './types.ts'
 
+/**
+ * Output sink for a hook subprocess, controlling how streamed lines and exit output are forwarded.
+ */
+type HookOutputSink = {
+  /**
+   * Called for each streamed stdout line while the hook runs.
+   */
+  onLine?: (line: string) => void
+  /**
+   * Called with stderr content after the hook exits with a non-zero code.
+   */
+  onStderr?: (text: string) => void
+  /**
+   * Called with stdout content after the hook exits with a non-zero code.
+   */
+  onStdout?: (text: string) => void
+}
+
+/**
+ * Output sink combined with stream control for a hook subprocess.
+ */
+export type HookSinkOptions = HookOutputSink & {
+  /**
+   * When `true`, streams process output line-by-line via `onLine`.
+   *
+   * @default false
+   */
+  stream?: boolean
+}
+
+/**
+ * Factory called once per hook command to build the output sink and streaming flag.
+ * The function should set up any logger UI (e.g., spinner) and return callbacks that forward subprocess output to it.
+ */
+export type HookSinkFactory = (commandWithArgs: string) => HookSinkOptions | undefined
+
+/**
+ * Logger variant that may return a {@link HookSinkFactory} from `install`.
+ * The factory is forwarded to hook execution so the logger controls subprocess output routing.
+ */
+type CLILogger = Logger<LoggerOptions, HookSinkFactory | void>
+
 /**
  * Optionally prefix a message with a [HH:MM:SS] timestamp when logLevel >= verbose.
  * Shared across all logger adapters to avoid duplication.
@@ -26,11 +70,29 @@ export function formatMessage(message: string, logLevel: number): string {
 }
 
 type ProgressState = {
+  /**
+   * Total number of plugins scheduled for this generation run.
+   */
   totalPlugins: number
+  /**
+   * Number of plugins that have finished without error.
+   */
   completedPlugins: number
+  /**
+   * Number of plugins that exited with an error.
+   */
   failedPlugins: number
+  /**
+   * Total number of files expected to be written.
+   */
   totalFiles: number
+  /**
+   * Number of files written so far.
+   */
   processedFiles: number
+  /**
+   * `process.hrtime()` snapshot taken at the start of generation, used to compute elapsed time.
+   */
   hrStart: [number, number]
 }
 
@@ -80,27 +142,111 @@ function detectLogger(): LoggerType {
   return 'plain'
 }
 
-const logMapper = {
+const logMapper: Record<LoggerType, CLILogger> = {
   clack: clackLogger,
   plain: plainLogger,
   'github-actions': githubActionsLogger,
-} as const satisfies Record<LoggerType, Logger>
+}
 
-export async function setupLogger(context: LoggerContext, { logLevel }: LoggerOptions): Promise<void> {
+export async function setupLogger(context: LoggerContext, { logLevel }: LoggerOptions): Promise<HookSinkFactory | undefined> {
   const type = detectLogger()
 
-  const logger = logMapper[type] as Logger
+  const logger = logMapper[type]
 
   if (!logger) {
     throw new Error(`Unknown adapter type: ${type}`)
   }
 
-  // Install primary logger
-  const cleanup = await logger.install(context, { logLevel })
+  const makeSink = await logger.install(context, { logLevel })
 
   if (logLevel >= logLevelMap.debug) {
     await fileSystemLogger.install(context, { logLevel })
   }
 
-  return cleanup
+  return typeof makeSink === 'function' ? makeSink : undefined
+}
+
+type SummaryProps = {
+  /**
+   * Set of plugins that failed during this generation run, each with its error.
+   */
+  failedPlugins: Set<{ plugin: Plugin; error: Error }>
+  /**
+   * Overall generation status used to choose success or failure formatting.
+   */
+  status: 'success' | 'failed'
+  /**
+   * `process.hrtime()` snapshot taken at the start of generation, used to compute elapsed time.
+   */
+  hrStart: [number, number]
+  /**
+   * Total number of files written during this generation run.
+   */
+  filesCreated: number
+  /**
+   * Resolved Kubb config for this generation entry, used to read plugin count and output path.
+   */
+  config: Config
+  /**
+   * Per-plugin timing map (plugin name → duration in ms). When provided, a timing bar chart is appended.
+   */
+  pluginTimings?: Map<string, number>
+}
+
+/**
+ * Builds the generation summary lines rendered in the end-of-run box.
+ * Returns an array of styled strings, one per summary row.
+ */
+export function getSummary({ failedPlugins, filesCreated, status, hrStart, config, pluginTimings }: SummaryProps): string[] {
+  const duration = formatHrtime(hrStart)
+
+  const pluginsCount = config.plugins?.length ?? 0
+  const successCount = pluginsCount - failedPlugins.size
+
+  const meta = {
+    plugins:
+      status === 'success'
+        ? `${styleText('green', `${successCount} successful`)}, ${pluginsCount} total`
+        : `${styleText('green', `${successCount} successful`)}, ${styleText('red', `${failedPlugins.size} failed`)}, ${pluginsCount} total`,
+    pluginsFailed: status === 'failed' ? [...failedPlugins].map(({ plugin }) => randomCliColor(plugin.name)).join(', ') : undefined,
+    filesCreated,
+    time: styleText('green', duration),
+    output: path.resolve(config.root, config.output.path),
+  } as const
+
+  const labels = {
+    plugins: 'Plugins:',
+    failed: 'Failed:',
+    generated: 'Generated:',
+    pluginTimings: 'Plugin Timings:',
+    output: 'Output:',
+  }
+  const maxLength = Math.max(0, ...[...Object.values(labels), ...(pluginTimings ? Array.from(pluginTimings.keys()) : [])].map((s) => s.length))
+
+  const summaryLines: string[] = []
+  summaryLines.push(`${labels.plugins.padEnd(maxLength + 2)} ${meta.plugins}`)
+
+  if (meta.pluginsFailed) {
+    summaryLines.push(`${labels.failed.padEnd(maxLength + 2)} ${meta.pluginsFailed}`)
+  }
+
+  summaryLines.push(`${labels.generated.padEnd(maxLength + 2)} ${meta.filesCreated} files in ${meta.time}`)
+
+  if (pluginTimings && pluginTimings.size > 0) {
+    const sortedTimings = Array.from(pluginTimings.entries()).sort((a, b) => b[1] - a[1])
+
+    summaryLines.push(`${labels.pluginTimings}`)
+
+    sortedTimings.forEach(([name, time]) => {
+      const timeStr = time >= 1000 ? `${(time / 1000).toFixed(2)}s` : `${Math.round(time)}ms`
+      const barLength = Math.min(Math.ceil(time / SUMMARY_TIME_SCALE_DIVISOR), SUMMARY_MAX_BAR_LENGTH)
+      const bar = styleText('dim', '█'.repeat(barLength))
+
+      summaryLines.push(`${styleText('dim', '•')} ${name.padEnd(maxLength + 1)}${bar} ${timeStr}`)
+    })
+  }
+
+  summaryLines.push(`${labels.output.padEnd(maxLength + 2)} ${meta.output}`)
+
+  return summaryLines
 }

package/src/runners/agent/run.ts

@@ -0,0 +1,113 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import process from 'node:process'
+import { styleText } from 'node:util'
+import * as clack from '@clack/prompts'
+import { spawnAsync, getErrorMessage } from '@internals/utils'
+import { agentDefaults } from '../../constants.ts'
+import { buildTelemetryEvent, sendTelemetry } from '../../telemetry.ts'
+import { isPortAvailable, resolveAgentStartEnvironment } from './utils.ts'
+
+type AgentStartOptions = {
+  /**
+   * TCP port for the HTTP server. When `undefined`, falls back to `PORT` env var or the default (`3000`).
+   */
+  port: string | undefined
+  /**
+   * Hostname the HTTP server binds to.
+   *
+   * @default 'localhost'
+   */
+  host: string
+  /**
+   * Explicit path to the Kubb config file. When `undefined`, falls back to `KUBB_AGENT_CONFIG` or the default filename.
+   */
+  configPath: string | undefined
+  /**
+   * Grants the agent permission to write generated files to the filesystem.
+   */
+  allowWrite: boolean
+  /**
+   * Grants all agent permissions, including filesystem writes. Implies `allowWrite`.
+   */
+  allowAll: boolean
+  /**
+   * Current `@kubb/cli` version string, used for the telemetry payload.
+   */
+  version: string
+}
+
+/**
+ * Spawns the Kubb Agent HTTP server as a Node.js subprocess.
+ * Resolves config from CLI flags and environment variables, validates the port, and exits with code 1 on failure.
+ */
+export async function run({ port, host, configPath, allowWrite, allowAll, version }: AgentStartOptions): Promise<void> {
+  const hrStart = process.hrtime()
+  const report = (status: 'success' | 'failed') => sendTelemetry(buildTelemetryEvent({ command: 'agent', kubbVersion: version, hrStart, status }))
+
+  try {
+    // Load .env file into process.env using Node.js built-in (v20.12.0+)
+    try {
+      process.loadEnvFile()
+    } catch {
+      // .env file may not exist; ignore
+    }
+
+    // Resolve the @kubb/agent package path — createRequire is CJS/ESM compatible (import.meta.resolve is ESM-only)
+    const require = createRequire(import.meta.url)
+    let agentPkgPath: string
+    try {
+      agentPkgPath = require.resolve('@kubb/agent/package.json')
+    } catch (_e) {
+      console.error(styleText('red', 'The @kubb/agent package is not installed.'))
+      console.error('')
+      console.error('Install it with:')
+      console.error(styleText('cyan', '  npm install @kubb/agent'))
+      console.error(styleText('cyan', '  # or'))
+      console.error(styleText('cyan', '  pnpm install @kubb/agent'))
+      console.error('')
+      process.exit(1)
+    }
+    const agentDir = path.dirname(agentPkgPath)
+    const serverPath = path.join(agentDir, agentDefaults.serverEntryPath)
+
+    const resolvedEnv = resolveAgentStartEnvironment({
+      port,
+      host,
+      configPath,
+      allowWrite,
+      allowAll,
+    })
+    const numericPort = Number(resolvedEnv.port)
+
+    if (!Number.isInteger(numericPort) || numericPort <= 0) {
+      throw new Error(`Invalid port "${resolvedEnv.port}". Provide a positive integer with --port or PORT.`)
+    }
+
+    clack.log.step(styleText('cyan', 'Starting agent server...'))
+    clack.log.info(styleText('dim', `Config: ${resolvedEnv.agentConfigPath}`))
+    clack.log.info(styleText('dim', `Host: ${resolvedEnv.host}`))
+    clack.log.info(styleText('dim', `Port: ${resolvedEnv.port}`))
+    if (!resolvedEnv.allowWrite && !resolvedEnv.allowAll) {
+      clack.log.warn(styleText('yellow', 'Filesystem writes disabled. Use --allow-write or --allow-all to enable.'))
+    }
+
+    if (!(await isPortAvailable(numericPort, resolvedEnv.host))) {
+      clack.log.error(styleText('red', `Port ${resolvedEnv.port} is already in use. Stop the existing process or choose a different port with --port.`))
+      process.exit(1)
+    }
+
+    // Spawns the server as a detached background process so the CLI can exit independently.
+    await spawnAsync('node', [serverPath], {
+      env: resolvedEnv.env,
+      cwd: process.cwd(),
+    })
+
+    await report('success')
+  } catch (error) {
+    await report('failed')
+    clack.log.error(styleText('red', 'Failed to start agent server'))
+    clack.log.error(getErrorMessage(error))
+    process.exit(1)
+  }
+}

package/src/runners/agent/utils.ts

@@ -0,0 +1,98 @@
+import net from 'node:net'
+import path from 'node:path'
+import process from 'node:process'
+import { agentDefaults } from '../../constants.ts'
+
+type AgentStartEnvironmentInput = {
+  /**
+   * TCP port for the HTTP server. When `undefined`, falls back to `PORT` env var or the default (`3000`).
+   */
+  port: string | undefined
+  /**
+   * Hostname the HTTP server binds to.
+   */
+  host: string
+  /**
+   * Explicit path to the Kubb config file. When `undefined`, falls back to `KUBB_AGENT_CONFIG` or the default filename.
+   */
+  configPath: string | undefined
+  /**
+   * Grants the agent permission to write generated files to the filesystem.
+   */
+  allowWrite: boolean
+  /**
+   * Grants all agent permissions, including filesystem writes. Implies `allowWrite`.
+   */
+  allowAll: boolean
+}
+
+type ResolvedAgentStartEnvironment = {
+  /**
+   * Final port string after merging CLI flag, `PORT` env var, and the default.
+   */
+  port: string
+  /**
+   * Final hostname after merging CLI flag, `HOST` env var, and the default.
+   */
+  host: string
+  /**
+   * Effective write-permission flag, accounting for `allowAll` and `KUBB_AGENT_ALLOW_WRITE`.
+   */
+  allowWrite: boolean
+  /**
+   * Effective all-permissions flag, accounting for `KUBB_AGENT_ALLOW_ALL`.
+   */
+  allowAll: boolean
+  /**
+   * Absolute path to the Kubb config file passed to the agent subprocess.
+   */
+  agentConfigPath: string
+  /**
+   * Merged `process.env` object with all resolved agent environment variables applied.
+   */
+  env: NodeJS.ProcessEnv
+}
+
+/**
+ * Resolves the environment passed to the detached agent process using CLI values first, then environment values, then CLI defaults.
+ */
+export function resolveAgentStartEnvironment({ port, host, configPath, allowWrite, allowAll }: AgentStartEnvironmentInput): ResolvedAgentStartEnvironment {
+  const resolvedPort = port ?? process.env.PORT ?? agentDefaults.port
+  const resolvedHost = host !== agentDefaults.host ? host : (process.env.HOST ?? agentDefaults.host)
+  const resolvedAllowAll = allowAll || process.env.KUBB_AGENT_ALLOW_ALL === 'true'
+  const resolvedAllowWrite = resolvedAllowAll || allowWrite || process.env.KUBB_AGENT_ALLOW_WRITE === 'true'
+  const agentRoot = process.env.KUBB_AGENT_ROOT ?? process.cwd()
+  const agentConfigPath = path.resolve(process.cwd(), configPath || process.env.KUBB_AGENT_CONFIG || agentDefaults.configFile)
+
+  return {
+    port: resolvedPort,
+    host: resolvedHost,
+    allowWrite: resolvedAllowWrite,
+    allowAll: resolvedAllowAll,
+    agentConfigPath,
+    env: {
+      ...process.env,
+      PORT: resolvedPort,
+      HOST: resolvedHost,
+      KUBB_AGENT_ROOT: agentRoot,
+      KUBB_AGENT_CONFIG: agentConfigPath,
+      KUBB_AGENT_ALLOW_WRITE: String(resolvedAllowWrite),
+      KUBB_AGENT_ALLOW_ALL: String(resolvedAllowAll),
+      KUBB_AGENT_TOKEN: process.env.KUBB_AGENT_TOKEN,
+      KUBB_AGENT_RETRY_TIMEOUT: process.env.KUBB_AGENT_RETRY_TIMEOUT ?? agentDefaults.retryTimeout,
+      KUBB_STUDIO_URL: process.env.KUBB_STUDIO_URL ?? agentDefaults.studioUrl,
+    },
+  }
+}
+
+export function isPortAvailable(port: number, host: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = net.createServer()
+    server.once('error', () => resolve(false))
+    server.once('listening', () => {
+      server.close()
+      resolve(true)
+    })
+    server.listen(port, host)
+  })
+}

package/src/runners/generate/run.ts

@@ -0,0 +1,276 @@
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import process from 'node:process'
+import { styleText } from 'node:util'
+import * as clack from '@clack/prompts'
+import type { AsyncEventEmitter } from '@internals/utils'
+import { AsyncEventEmitter as AsyncEventEmitterClass, detectFormatter, detectLinter, executeIfOnline, formatters, linters, toError } from '@internals/utils'
+import { type Config, createKubb, isInputPath, type KubbHooks, logLevel as logLevelMap } from '@kubb/core'
+import { version } from '../../../package.json'
+import { KUBB_NPM_PACKAGE_URL } from '../../constants.ts'
+import { setupLogger, type HookSinkFactory } from '../../loggers/utils.ts'
+import { buildTelemetryEvent, sendTelemetry } from '../../telemetry.ts'
+import { executeHooks, getConfigs, startWatcher } from './utils.ts'
+
+type GenerateProps = {
+  input?: string
+  config: Config
+  hooks: AsyncEventEmitter<KubbHooks>
+  logLevel: number
+  makeSink?: HookSinkFactory
+}
+
+type ToolMap = typeof formatters | typeof linters
+
+type RunToolPassOptions = {
+  toolValue: string
+  detect: () => Promise<string | null>
+  toolMap: ToolMap
+  toolLabel: string
+  successPrefix: string
+  noToolMessage: string
+  configName: string | undefined
+  outputPath: string
+  logLevel: number
+  hooks: AsyncEventEmitter<KubbHooks>
+  onStart: () => Promise<void>
+  onEnd: () => Promise<void>
+}
+
+/**
+ * Registers a one-shot `kubb:hook:end` listener for `hookId` BEFORE the caller emits `kubb:hook:start`,
+ * avoiding the race where a synchronous emitter fires end before the listener is attached.
+ */
+function waitForHookEnd(hooks: AsyncEventEmitter<KubbHooks>, hookId: string, onSuccess: () => Promise<void>, fallbackErrorMessage: string): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const handler = (ctx: { id?: string; command: string; args?: readonly string[]; success: boolean; error: Error | null }) => {
+      if (ctx.id !== hookId) return
+      hooks.off('kubb:hook:end', handler)
+      if (!ctx.success) {
+        reject(ctx.error ?? new Error(fallbackErrorMessage))
+        return
+      }
+      onSuccess().then(resolve).catch(reject)
+    }
+    hooks.on('kubb:hook:end', handler)
+  })
+}
+
+async function runToolPass({
+  toolValue,
+  detect,
+  toolMap,
+  toolLabel,
+  successPrefix,
+  noToolMessage,
+  configName,
+  outputPath,
+  logLevel,
+  hooks,
+  onStart,
+  onEnd,
+}: RunToolPassOptions) {
+  await onStart()
+
+  let resolvedTool = toolValue
+  if (resolvedTool === 'auto') {
+    const detected = await detect()
+    if (!detected) {
+      await hooks.emit('kubb:warn', { message: noToolMessage })
+    } else {
+      resolvedTool = detected
+      await hooks.emit('kubb:info', { message: `Auto-detected ${toolLabel}: ${styleText('dim', resolvedTool)}` })
+    }
+  }
+
+  let toolError: Error | undefined
+
+  if (resolvedTool && resolvedTool !== 'auto' && resolvedTool in toolMap) {
+    const toolConfig = toolMap[resolvedTool as keyof ToolMap]
+    const hookId = createHash('sha256').update([configName, resolvedTool].filter(Boolean).join('-')).digest('hex')
+
+    const successMessage = [
+      `${successPrefix} with ${styleText('dim', resolvedTool)}`,
+      logLevel >= logLevelMap.info ? `on ${styleText('dim', outputPath)}` : undefined,
+      'successfully',
+    ]
+      .filter(Boolean)
+      .join(' ')
+
+    try {
+      const hookEndPromise = waitForHookEnd(hooks, hookId, () => hooks.emit('kubb:success', { message: successMessage }), toolConfig.errorMessage)
+
+      await hooks.emit('kubb:hook:start', { id: hookId, command: toolConfig.command, args: toolConfig.args(outputPath) })
+
+      await hookEndPromise
+    } catch (caughtError) {
+      const err = toError(caughtError)
+      await hooks.emit('kubb:error', { error: err })
+      toolError = err
+    }
+  }
+
+  await onEnd()
+
+  if (toolError) {
+    throw toolError
+  }
+}
+
+async function generate(options: GenerateProps): Promise<void> {
+  const { input, hooks, logLevel, makeSink } = options
+
+  const hrStart = process.hrtime()
+  const inputPath = input ?? (options.config.input && 'path' in options.config.input ? options.config.input.path : undefined)
+
+  const config: Config = {
+    ...options.config,
+    input: inputPath ? { ...options.config.input, path: inputPath } : options.config.input,
+    ...options.config.output,
+  } satisfies Config
+
+  const kubb = createKubb(config, { hooks })
+  await kubb.setup()
+
+  await hooks.emit('kubb:generation:start', { config })
+  await hooks.emit('kubb:info', { message: config.name ? `Setup generation ${styleText('bold', config.name)}` : 'Setup generation', info: inputPath })
+  await hooks.emit('kubb:info', { message: config.name ? `Build generation ${styleText('bold', config.name)}` : 'Build generation', info: inputPath })
+
+  const { files, failedPlugins, pluginTimings, error, driver } = await kubb.safeBuild()
+
+  await hooks.emit('kubb:info', { message: 'Load summary' })
+
+  const telemetryPlugins = Array.from(driver.plugins.values(), (p) => ({ name: p.name, options: p.options as Record<string, unknown> }))
+
+  const reportTelemetry = (status: 'success' | 'failed') =>
+    sendTelemetry(buildTelemetryEvent({ command: 'generate', kubbVersion: version, plugins: telemetryPlugins, hrStart, filesCreated: files.length, status }))
+
+  if (failedPlugins.size > 0 || error) {
+    const allErrors = [error, ...Array.from(failedPlugins, (it) => it.error)].filter(Boolean) as Error[]
+
+    for (const err of allErrors) {
+      await hooks.emit('kubb:error', { error: err })
+    }
+
+    await hooks.emit('kubb:generation:end', { config, files, sources: kubb.sources })
+    await hooks.emit('kubb:generation:summary', {
+      config,
+      failedPlugins,
+      filesCreated: files.length,
+      status: 'failed',
+      hrStart,
+      pluginTimings: logLevel >= logLevelMap.verbose ? pluginTimings : undefined,
+    })
+
+    await reportTelemetry('failed')
+    process.exit(1)
+  }
+
+  await hooks.emit('kubb:success', { message: 'Generation succeeded', info: inputPath })
+  await hooks.emit('kubb:generation:end', { config, files, sources: kubb.sources })
+
+  const outputPath = path.resolve(config.root, config.output.path)
+
+  const toolPasses = [
+    config.output.format && {
+      toolValue: config.output.format,
+      detect: detectFormatter,
+      toolMap: formatters,
+      toolLabel: 'formatter',
+      successPrefix: 'Formatting',
+      noToolMessage: 'No formatter found (oxfmt, biome, or prettier). Skipping formatting.',
+      onStart: () => hooks.emit('kubb:format:start'),
+      onEnd: () => hooks.emit('kubb:format:end'),
+    },
+    config.output.lint && {
+      toolValue: config.output.lint,
+      detect: detectLinter,
+      toolMap: linters,
+      toolLabel: 'linter',
+      successPrefix: 'Linting',
+      noToolMessage: 'No linter found (oxlint, biome, or eslint). Skipping linting.',
+      onStart: () => hooks.emit('kubb:lint:start'),
+      onEnd: () => hooks.emit('kubb:lint:end'),
+    },
+  ].filter(Boolean) as Omit<RunToolPassOptions, 'configName' | 'outputPath' | 'logLevel' | 'hooks'>[]
+
+  for (const pass of toolPasses) {
+    await runToolPass({ ...pass, configName: config.name, outputPath, logLevel, hooks })
+  }
+
+  if (config.hooks) {
+    await hooks.emit('kubb:hooks:start')
+    await executeHooks({ configHooks: config.hooks, hooks, makeSink })
+    await hooks.emit('kubb:hooks:end')
+  }
+
+  await hooks.emit('kubb:generation:summary', { config, failedPlugins, filesCreated: files.length, status: 'success', hrStart, pluginTimings })
+
+  await reportTelemetry('success')
+}
+
+type GenerateCommandOptions = {
+  input?: string
+  configPath?: string
+  logLevel: string
+  watch: boolean
+}
+
+async function checkForUpdate(hooks: AsyncEventEmitter<KubbHooks>): Promise<void> {
+  await executeIfOnline(async () => {
+    try {
+      const res = await fetch(KUBB_NPM_PACKAGE_URL)
+      const data = (await res.json()) as { version: string }
+      if (data.version && version < data.version) {
+        await hooks.emit('kubb:version:new', { currentVersion: version, latestVersion: data.version })
+      }
+    } catch {
+      // Ignore network errors
+    }
+  })
+}
+
+/**
+ * Runs the full Kubb generation lifecycle for the given CLI options.
+ * Sets up the logger, checks for a newer version, loads configs, and calls `generate` for each config entry.
+ */
+export async function run({ input, configPath, logLevel: logLevelKey, watch }: GenerateCommandOptions): Promise<void> {
+  const logLevel = logLevelMap[logLevelKey as keyof typeof logLevelMap] ?? logLevelMap.info
+  const hooks = new AsyncEventEmitterClass<KubbHooks>()
+
+  const makeSink = await setupLogger(hooks, { logLevel })
+
+  await checkForUpdate(hooks)
+
+  try {
+    const { configs, configPath: resolvedConfigPath } = await getConfigs({ configPath, input })
+    const relativeConfigPath = path.relative(process.cwd(), resolvedConfigPath)
+
+    await hooks.emit('kubb:config:start')
+    await hooks.emit('kubb:info', { message: 'Config loaded', info: relativeConfigPath })
+    await hooks.emit('kubb:success', { message: 'Config loaded successfully', info: relativeConfigPath })
+    await hooks.emit('kubb:config:end', { configs })
+    await hooks.emit('kubb:lifecycle:start', { version })
+
+    for (const config of configs) {
+      if (isInputPath(config) && watch) {
+        await startWatcher(
+          [input || config.input.path],
+          async (paths) => {
+            hooks.removeAll()
+            await generate({ input, config, logLevel, hooks, makeSink })
+            clack.log.step(styleText('yellow', `Watching for changes in ${paths.join(' and ')}`))
+          },
+          { info: (msg) => clack.log.info(msg), error: (msg) => clack.log.error(msg) },
+        )
+      } else {
+        await generate({ input, config, logLevel, hooks, makeSink })
+      }
+    }
+
+    await hooks.emit('kubb:lifecycle:end')
+  } catch (error) {
+    await hooks.emit('kubb:error', { error: toError(error) })
+    process.exit(1)
+  }
+}