@kubb/cli 4.32.4 → 4.33.1

package/src/loggers/utils.ts

@@ -1,13 +1,76 @@
+import { styleText } from 'node:util'
+import { canUseTTY, formatHrtime, isGitHubActions } from '@internals/utils'
 import type { Logger, LoggerContext, LoggerOptions } from '@kubb/core'
-import { LogLevel } from '@kubb/core'
+import { logLevel as logLevelMap } from '@kubb/core'
 import { clackLogger } from './clackLogger.ts'
-import { canUseTTY, isGitHubActions } from './envDetection.ts'
 import { fileSystemLogger } from './fileSystemLogger.ts'
 import { githubActionsLogger } from './githubActionsLogger.ts'
 import { plainLogger } from './plainLogger.ts'
 import type { LoggerType } from './types.ts'
 
-export function detectLogger(): LoggerType {
+/**
+ * Optionally prefix a message with a [HH:MM:SS] timestamp when logLevel >= verbose.
+ * Shared across all logger adapters to avoid duplication.
+ */
+export function formatMessage(message: string, logLevel: number): string {
+  if (logLevel >= logLevelMap.verbose) {
+    const timestamp = new Date().toLocaleTimeString('en-US', {
+      hour12: false,
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    })
+    return `${styleText('dim', `[${timestamp}]`)} ${message}`
+  }
+  return message
+}
+
+type ProgressState = {
+  totalPlugins: number
+  completedPlugins: number
+  failedPlugins: number
+  totalFiles: number
+  processedFiles: number
+  hrStart: [number, number]
+}
+
+/**
+ * Build the progress summary line shared by clack and GitHub Actions loggers.
+ * Returns null when there is nothing to display.
+ */
+export function buildProgressLine(state: ProgressState): string | null {
+  const parts: string[] = []
+  const duration = formatHrtime(state.hrStart)
+
+  if (state.totalPlugins > 0) {
+    const pluginStr =
+      state.failedPlugins > 0
+        ? `Plugins ${styleText('green', state.completedPlugins.toString())}/${state.totalPlugins} ${styleText('red', `(${state.failedPlugins} failed)`)}`
+        : `Plugins ${styleText('green', state.completedPlugins.toString())}/${state.totalPlugins}`
+    parts.push(pluginStr)
+  }
+
+  if (state.totalFiles > 0) {
+    parts.push(`Files ${styleText('green', state.processedFiles.toString())}/${state.totalFiles}`)
+  }
+
+  if (parts.length === 0) {
+    return null
+  }
+
+  parts.push(`${styleText('green', duration)} elapsed`)
+  return parts.join(styleText('dim', ' | '))
+}
+
+/**
+ * Join a command and its optional args into a single display string.
+ * e.g. ("prettier", ["--write", "."]) → "prettier --write ."
+ */
+export function formatCommandWithArgs(command: string, args?: readonly string[]): string {
+  return args?.length ? `${command} ${args.join(' ')}` : command
+}
+
+function detectLogger(): LoggerType {
   if (isGitHubActions()) {
     return 'github-actions'
   }
@@ -35,7 +98,7 @@ export async function setupLogger(context: LoggerContext, { logLevel }: LoggerOp
   // Install primary logger
   const cleanup = await logger.install(context, { logLevel })
 
-  if (logLevel >= LogLevel.debug) {
+  if (logLevel >= logLevelMap.debug) {
     await fileSystemLogger.install(context, { logLevel })
   }
 

package/src/runners/agent.ts

@@ -0,0 +1,100 @@
+import net from 'node:net'
+import path from 'node:path'
+import * as process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { styleText } from 'node:util'
+import * as clack from '@clack/prompts'
+import { spawnAsync } from '@internals/utils'
+import { agentDefaults } from '../constants.ts'
+import { buildTelemetryEvent, sendTelemetry } from '../utils/telemetry.ts'
+
+type AgentStartOptions = {
+  port: string | undefined
+  host: string
+  configPath: string
+  allowWrite: boolean
+  allowAll: boolean
+  version: string
+}
+
+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)
+  })
+}
+
+export async function runAgentStart({ port, host, configPath, allowWrite, allowAll, version }: AgentStartOptions): Promise<void> {
+  const hrStart = process.hrtime()
+
+  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
+    const agentPkgUrl = import.meta.resolve('@kubb/agent/package.json')
+    const agentPkgPath = fileURLToPath(agentPkgUrl)
+    const agentDir = path.dirname(agentPkgPath)
+    const serverPath = path.join(agentDir, agentDefaults.serverEntryPath)
+
+    // CLI params take priority over process.env; process.env fills in what the CLI didn't specify;
+    // agentDefaults are the last resort. Build env as: defaults ← process.env ← CLI.
+    const PORT = port !== undefined ? port : (process.env.PORT ?? agentDefaults.port)
+    const HOST = host !== agentDefaults.host ? host : (process.env.HOST ?? agentDefaults.host)
+    const KUBB_AGENT_ROOT = process.env.KUBB_AGENT_ROOT ?? process.cwd()
+    const KUBB_AGENT_CONFIG = configPath !== agentDefaults.configFile ? configPath : (process.env.KUBB_AGENT_CONFIG ?? agentDefaults.configFile)
+    const KUBB_AGENT_ALLOW_WRITE = allowAll || allowWrite ? 'true' : (process.env.KUBB_AGENT_ALLOW_WRITE ?? 'false')
+    const KUBB_AGENT_ALLOW_ALL = allowAll ? 'true' : (process.env.KUBB_AGENT_ALLOW_ALL ?? 'false')
+    const KUBB_AGENT_TOKEN = process.env.KUBB_AGENT_TOKEN
+    const KUBB_AGENT_RETRY_TIMEOUT = process.env.KUBB_AGENT_RETRY_TIMEOUT ?? agentDefaults.retryTimeout
+    const KUBB_STUDIO_URL = process.env.KUBB_STUDIO_URL ?? agentDefaults.studioUrl
+
+    const env = {
+      ...process.env,
+      PORT,
+      HOST,
+      KUBB_AGENT_ROOT,
+      KUBB_AGENT_CONFIG,
+      KUBB_AGENT_ALLOW_WRITE,
+      KUBB_AGENT_ALLOW_ALL,
+      KUBB_AGENT_TOKEN,
+      KUBB_AGENT_RETRY_TIMEOUT,
+      KUBB_STUDIO_URL,
+    }
+
+    clack.log.step(styleText('cyan', 'Starting agent server...'))
+    clack.log.info(styleText('dim', `Config: ${KUBB_AGENT_CONFIG}`))
+    clack.log.info(styleText('dim', `Host: ${HOST}`))
+    clack.log.info(styleText('dim', `Port: ${PORT}`))
+    if (!KUBB_AGENT_ALLOW_WRITE && !KUBB_AGENT_ALLOW_ALL) {
+      clack.log.warn(styleText('yellow', 'Filesystem writes disabled. Use --allow-write or --allow-all to enable.'))
+    }
+
+    if (!(await isPortAvailable(Number(PORT), HOST))) {
+      clack.log.error(styleText('red', `Port ${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,
+      cwd: process.cwd(),
+    })
+
+    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/runners/generate.ts

@@ -2,12 +2,31 @@ import { createHash } from 'node:crypto'
 import path from 'node:path'
 import process from 'node:process'
 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 * as clack from '@clack/prompts'
+import type { AsyncEventEmitter } from '@internals/utils'
+import { AsyncEventEmitter as AsyncEventEmitterClass, executeIfOnline, toError } from '@internals/utils'
+import {
+  type CLIOptions,
+  type Config,
+  detectFormatter,
+  detectLinter,
+  formatters,
+  getConfigs,
+  isInputPath,
+  type KubbEvents,
+  linters,
+  logLevel as logLevelMap,
+  PromiseManager,
+  safeBuild,
+  setup,
+} from '@kubb/core'
 import { version } from '../../package.json'
+import { KUBB_NPM_PACKAGE_URL } from '../constants.ts'
+import { setupLogger } from '../loggers/utils.ts'
 import { executeHooks } from '../utils/executeHooks.ts'
+import { getCosmiConfig } from '../utils/getCosmiConfig.ts'
 import { buildTelemetryEvent, sendTelemetry } from '../utils/telemetry.ts'
+import { startWatcher } from '../utils/watcher.ts'
 
 type GenerateProps = {
   input?: string
@@ -16,7 +35,103 @@ type GenerateProps = {
   logLevel: number
 }
 
-export async function generate({ input, config: userConfig, events, logLevel }: GenerateProps): Promise<void> {
+type ToolMap = typeof formatters | typeof linters
+
+type RunToolPassOptions = {
+  toolValue: string
+  detect: () => Promise<string | undefined>
+  toolMap: ToolMap
+  /** Short noun used in "Auto-detected <toolLabel>:" message, e.g. "formatter" or "linter". */
+  toolLabel: string
+  /** Verb prefix for the success message, e.g. "Formatting" or "Linting". */
+  successPrefix: string
+  noToolMessage: string
+  configName: string | undefined
+  outputPath: string
+  logLevel: number
+  events: AsyncEventEmitter<KubbEvents>
+  onStart: () => Promise<void>
+  onEnd: () => Promise<void>
+}
+
+async function runToolPass({
+  toolValue,
+  detect,
+  toolMap,
+  toolLabel,
+  successPrefix,
+  noToolMessage,
+  configName,
+  outputPath,
+  logLevel,
+  events,
+  onStart,
+  onEnd,
+}: RunToolPassOptions) {
+  await onStart()
+
+  let resolvedTool = toolValue
+  if (resolvedTool === 'auto') {
+    const detected = await detect()
+    if (!detected) {
+      await events.emit('warn', noToolMessage)
+    } else {
+      resolvedTool = detected
+      await events.emit('info', `Auto-detected ${toolLabel}: ${styleText('dim', resolvedTool)}`)
+    }
+  }
+
+  if (resolvedTool && resolvedTool !== 'auto' && resolvedTool in toolMap) {
+    const toolConfig = toolMap[resolvedTool as keyof ToolMap]
+
+    try {
+      const hookId = createHash('sha256').update([configName, resolvedTool].filter(Boolean).join('-')).digest('hex')
+
+      // Wire up the hook:end listener BEFORE emitting hook:start to avoid the race condition
+      // where hook:end fires synchronously inside emit('hook:start') before the listener is registered.
+      const hookEndPromise = new Promise<void>((resolve, reject) => {
+        const handler = ({ id, success, error }: { id?: string; command: string; args?: readonly string[]; success: boolean; error: Error | null }) => {
+          if (id !== hookId) return
+          events.off('hook:end', handler)
+          if (!success) {
+            reject(error ?? new Error(`${toolConfig.errorMessage}`))
+            return
+          }
+          events
+            .emit(
+              'success',
+              [
+                `${successPrefix} with ${styleText('dim', resolvedTool)}`,
+                logLevel >= logLevelMap.info ? `on ${styleText('dim', outputPath)}` : undefined,
+                'successfully',
+              ]
+                .filter(Boolean)
+                .join(' '),
+            )
+            .then(resolve)
+            .catch(reject)
+        }
+        events.on('hook:end', handler)
+      })
+
+      await events.emit('hook:start', {
+        id: hookId,
+        command: toolConfig.command,
+        args: toolConfig.args(outputPath),
+      })
+
+      await hookEndPromise
+    } catch (caughtError) {
+      const err = new Error(toolConfig.errorMessage)
+      err.cause = caughtError
+      await events.emit('error', err)
+    }
+  }
+
+  await onEnd()
+}
+
+async function generate({ input, config: userConfig, events, logLevel }: GenerateProps): Promise<void> {
   const inputPath = input ?? ('path' in userConfig.input ? userConfig.input.path : undefined)
   const hrStart = process.hrtime()
 
@@ -73,9 +188,9 @@ export async function generate({ input, config: userConfig, events, logLevel }:
         .map((it) => it.error),
     ].filter(Boolean)
 
-    allErrors.forEach((err) => {
-      events.emit('error', err)
-    })
+    for (const err of allErrors) {
+      await events.emit('error', err)
+    }
 
     await events.emit('generation:end', config, files, sources)
 
@@ -84,7 +199,7 @@ export async function generate({ input, config: userConfig, events, logLevel }:
       filesCreated: files.length,
       status: 'failed',
       hrStart,
-      pluginTimings: logLevel >= LogLevel.verbose ? pluginTimings : undefined,
+      pluginTimings: logLevel >= logLevelMap.verbose ? pluginTimings : undefined,
     })
 
     await sendTelemetry(
@@ -104,100 +219,40 @@ export async function generate({ input, config: userConfig, events, logLevel }:
   await events.emit('success', 'Generation successfully', inputPath)
   await events.emit('generation:end', config, files, sources)
 
-  // formatting
-  if (config.output.format) {
-    await events.emit('format:start')
-
-    let formatter = config.output.format
-    if (formatter === 'auto') {
-      const detectedFormatter = await detectFormatter()
-      if (!detectedFormatter) {
-        await events.emit('warn', 'No formatter found (biome, prettier, or oxfmt). Skipping formatting.')
-      } else {
-        formatter = detectedFormatter
-        await events.emit('info', `Auto-detected formatter: ${styleText('dim', formatter)}`)
-      }
-    }
-
-    if (formatter && formatter !== 'auto' && formatter in formatters) {
-      const formatterConfig = formatters[formatter as keyof typeof formatters]
-      const outputPath = path.resolve(config.root, config.output.path)
-
-      try {
-        const hookId = createHash('sha256').update([config.name, formatter].filter(Boolean).join('-')).digest('hex')
-        await events.emit('hook:start', {
-          id: hookId,
-          command: formatterConfig.command,
-          args: formatterConfig.args(outputPath),
-        })
-
-        await events.onOnce('hook:end', async ({ success, error }) => {
-          if (!success) throw error
-
-          await events.emit(
-            'success',
-            [`Formatting with ${styleText('dim', formatter)}`, logLevel >= LogLevel.info ? `on ${styleText('dim', outputPath)}` : undefined, 'successfully']
-              .filter(Boolean)
-              .join(' '),
-          )
-        })
-      } catch (caughtError) {
-        const error = new Error(formatterConfig.errorMessage)
-        error.cause = caughtError
-        await events.emit('error', error)
-      }
-    }
+  const outputPath = path.resolve(config.root, config.output.path)
 
-    await events.emit('format:end')
+  if (config.output.format) {
+    await runToolPass({
+      toolValue: config.output.format,
+      detect: detectFormatter,
+      toolMap: formatters,
+      toolLabel: 'formatter',
+      successPrefix: 'Formatting',
+      noToolMessage: 'No formatter found (biome, prettier, or oxfmt). Skipping formatting.',
+      configName: config.name,
+      outputPath,
+      logLevel,
+      events,
+      onStart: () => events.emit('format:start'),
+      onEnd: () => events.emit('format:end'),
+    })
   }
 
-  // linting
   if (config.output.lint) {
-    await events.emit('lint:start')
-
-    // Detect linter if set to 'auto'
-    let linter = config.output.lint
-    if (linter === 'auto') {
-      const detectedLinter = await detectLinter()
-      if (!detectedLinter) {
-        await events.emit('warn', 'No linter found (biome, oxlint, or eslint). Skipping linting.')
-      } else {
-        linter = detectedLinter
-        await events.emit('info', `Auto-detected linter: ${styleText('dim', linter)}`)
-      }
-    }
-
-    // Only proceed with linting if we have a valid linter
-    if (linter && linter !== 'auto' && linter in linters) {
-      const linterConfig = linters[linter as keyof typeof linters]
-      const outputPath = path.resolve(config.root, config.output.path)
-
-      try {
-        const hookId = createHash('sha256').update([config.name, linter].filter(Boolean).join('-')).digest('hex')
-        await events.emit('hook:start', {
-          id: hookId,
-          command: linterConfig.command,
-          args: linterConfig.args(outputPath),
-        })
-
-        await events.onOnce('hook:end', async ({ success, error }) => {
-          if (!success) throw error
-
-          await events.emit(
-            'success',
-            [`Linting with ${styleText('dim', linter)}`, logLevel >= LogLevel.info ? `on ${styleText('dim', outputPath)}` : undefined, 'successfully']
-              .filter(Boolean)
-              .join(' '),
-          )
-        })
-      } catch (caughtError) {
-        const error = new Error(linterConfig.errorMessage)
-        error.cause = caughtError
-        await events.emit('error', error)
-      }
-    }
-
-    await events.emit('lint:end')
+    await runToolPass({
+      toolValue: config.output.lint,
+      detect: detectLinter,
+      toolMap: linters,
+      toolLabel: 'linter',
+      successPrefix: 'Linting',
+      noToolMessage: 'No linter found (biome, oxlint, or eslint). Skipping linting.',
+      configName: config.name,
+      outputPath,
+      logLevel,
+      events,
+      onStart: () => events.emit('lint:start'),
+      onEnd: () => events.emit('lint:end'),
+    })
   }
 
   if (config.hooks) {
@@ -207,12 +262,11 @@ export async function generate({ input, config: userConfig, events, logLevel }:
     await events.emit('hooks:end')
   }
 
-  const generationStatus = failedPlugins.size > 0 || error ? 'failed' : 'success'
-
+  // Only reached when there are no failures (process.exit(1) is called above otherwise)
   await events.emit('generation:summary', config, {
     failedPlugins,
     filesCreated: files.length,
-    status: generationStatus,
+    status: 'success',
     hrStart,
     pluginTimings,
   })
@@ -223,8 +277,75 @@ export async function generate({ input, config: userConfig, events, logLevel }:
     plugins: pluginManager.plugins.map((p) => ({ name: p.name, options: p.options as Record<string, unknown> })),
     hrStart,
     filesCreated: files.length,
-    status: generationStatus,
+    status: 'success',
   })
 
   await sendTelemetry(telemetryEvent)
 }
+
+type GenerateCommandOptions = {
+  input?: string
+  configPath?: string
+  logLevel: string
+  watch: boolean
+}
+
+export async function runGenerateCommand({ input, configPath, logLevel: logLevelKey, watch }: GenerateCommandOptions): Promise<void> {
+  const logLevel = logLevelMap[logLevelKey as keyof typeof logLevelMap] ?? logLevelMap.info
+  const events = new AsyncEventEmitterClass<KubbEvents>()
+  const promiseManager = new PromiseManager()
+
+  await setupLogger(events, { logLevel })
+
+  await executeIfOnline(async () => {
+    try {
+      const res = await fetch(KUBB_NPM_PACKAGE_URL)
+      const data = (await res.json()) as { version: string }
+      const latestVersion = data.version
+
+      if (latestVersion && version < latestVersion) {
+        await events.emit('version:new', version, latestVersion)
+      }
+    } catch {
+      // Ignore network errors for version check
+    }
+  })
+
+  try {
+    const result = await getCosmiConfig('kubb', configPath)
+    const configs = await getConfigs(result.config, { input } as CLIOptions)
+
+    await events.emit('config:start')
+    await events.emit('info', 'Config loaded', path.relative(process.cwd(), result.filepath))
+    await events.emit('success', 'Config loaded successfully', path.relative(process.cwd(), result.filepath))
+    await events.emit('config:end', configs)
+
+    await events.emit('lifecycle:start', version)
+
+    const promises = configs.map((config) => {
+      return async () => {
+        if (isInputPath(config) && watch) {
+          await startWatcher([input || config.input.path], async (paths) => {
+            // remove to avoid duplicate listeners after each change
+            events.removeAll()
+
+            await generate({ input, config, logLevel, events })
+
+            clack.log.step(styleText('yellow', `Watching for changes in ${paths.join(' and ')}`))
+          })
+
+          return
+        }
+
+        await generate({ input, config, logLevel, events })
+      }
+    })
+
+    await promiseManager.run('seq', promises)
+
+    await events.emit('lifecycle:end')
+  } catch (error) {
+    await events.emit('error', toError(error))
+    process.exit(1)
+  }
+}