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

package/src/index.ts

@@ -1,9 +1,8 @@
 import { styleText } from 'node:util'
-import { createCLI } from '@internals/utils'
+import { createCLI, isFlag } from '@internals/utils'
 import { version } from '../package.json'
 import { QUIET_FLAGS } from './constants.ts'
-import { isFlag } from './utils/flags.ts'
-import { isTelemetryDisabled } from './utils/telemetry.ts'
+import { isTelemetryDisabled } from './telemetry.ts'
 
 const cli = createCLI()
 
@@ -11,14 +10,17 @@ 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
 }
 

package/src/loggers/clackLogger.ts

@@ -4,10 +4,27 @@ 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 { getSummary } from './utils.ts'
 import { buildProgressLine, formatCommandWithArgs, formatMessage } from './utils.ts'
+import { Writable } from 'node:stream'
+import type { WritableOptions } from 'node:stream'
+
+/**
+ * Node.js `Writable` stream that forwards each chunk to a clack `taskLog` message.
+ * Used to pipe hook subprocess output into the clack task log UI.
+ */
+class ClackWritable extends Writable {
+  taskLog: ReturnType<typeof clack.taskLog>
+  constructor(taskLog: ReturnType<typeof clack.taskLog>, opts?: WritableOptions) {
+    super(opts)
+
+    this.taskLog = taskLog
+  }
+  _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    this.taskLog.message(`${styleText('dim', chunk.toString())}`)
+    callback()
+  }
+}
 
 /**
  * TTY logger with beautiful UI and progress indicators for local development.
@@ -364,51 +381,15 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.outro(text)
     })
 
-    context.on('kubb:hook:start', async ({ id, command, args }) => {
-      const commandWithArgs = formatCommandWithArgs(command, args)
-      const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
-
-      // Skip hook execution if no id is provided (e.g., during benchmarks or tests)
-      if (!id) {
-        return
-      }
-
+    context.on('kubb:hook:start', ({ command, args }) => {
       if (logLevel <= logLevelMap.silent) {
-        await runHook({
-          id,
-          command,
-          args,
-          commandWithArgs,
-          context,
-          sink: {
-            onStderr: (s) => console.error(s),
-            onStdout: (s) => console.log(s),
-          },
-        })
         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)
+      const commandWithArgs = formatCommandWithArgs(command, args)
+      const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
 
-      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),
-        },
-      })
+      clack.intro(text)
     })
 
     context.on('kubb:hook:end', ({ command, args }) => {
@@ -454,5 +435,26 @@ Run \`npm install -g @kubb/cli\` to update`,
     context.on('kubb:lifecycle:end', () => {
       reset()
     })
+
+    return (commandWithArgs: string) => {
+      if (logLevel <= logLevelMap.silent) {
+        return {
+          onStdout: (s: string) => console.log(s),
+          onStderr: (s: string) => console.error(s),
+        }
+      }
+
+      const logger = clack.taskLog({
+        title: getMessage(['Executing hook', logLevel >= logLevelMap.info ? styleText('dim', commandWithArgs) : undefined].filter(Boolean).join(' ')),
+      })
+      const writable = new ClackWritable(logger)
+
+      return {
+        stream: true,
+        onLine: (line: string) => writable.write(line),
+        onStdout: (s: string) => logger.message(s),
+        onStderr: (s: string) => logger.error(s),
+      }
+    }
   },
 })

package/src/loggers/fileSystemLogger.ts

@@ -4,14 +4,24 @@ import { formatMs, write } from '@internals/utils'
 import { defineLogger } from '@kubb/core'
 
 type CachedEvent = {
+  /**
+   * Timestamp when this event was captured, used to derive the log filename.
+   */
   date: Date
+  /**
+   * Accumulated log lines for this event.
+   */
   logs: string[]
+  /**
+   * Optional override for the output filename inside `.kubb/`. When omitted, the filename is derived from `date`.
+   */
   fileName?: string
 }
 
 /**
  * FileSystem logger that captures debug events and writes them to `.kubb` directory files.
- * Note: Logs write on `lifecycle:end` or process exit. Cached logs may be lost if the process crashes before these events.
+ *
+ * @note Logs are written on `kubb:lifecycle:end` or process exit. Cached logs may be lost if the process crashes before either event.
  */
 export const fileSystemLogger = defineLogger({
   name: 'filesystem',

package/src/loggers/githubActionsLogger.ts

@@ -1,7 +1,6 @@
 import { styleText } from 'node:util'
 import { formatHrtime, formatMs, formatMsWithColor, toCause } from '@internals/utils'
 import { type Config, defineLogger, logLevel as logLevelMap } from '@kubb/core'
-import { runHook } from '../utils/runHook.ts'
 import { buildProgressLine, formatCommandWithArgs, formatMessage } from './utils.ts'
 
 /**
@@ -307,34 +306,18 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('kubb:hook:start', async ({ id, command, args }) => {
+    context.on('kubb:hook:start', ({ command, args }) => {
+      if (logLevel <= logLevelMap.silent) {
+        return
+      }
+
       const commandWithArgs = formatCommandWithArgs(command, args)
       const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
 
-      if (logLevel > logLevelMap.silent) {
-        if (state.currentConfigs.length === 1) {
-          openGroup(`Hook ${commandWithArgs}`)
-        }
-        console.log(text)
-      }
-
-      // Skip hook execution if no id is provided (e.g., during benchmarks or tests)
-      if (!id) {
-        return
+      if (state.currentConfigs.length === 1) {
+        openGroup(`Hook ${commandWithArgs}`)
       }
-
-      await runHook({
-        id,
-        command,
-        args,
-        commandWithArgs,
-        context,
-        sink: {
-          // GHA formats errors with the ::error:: annotation
-          onStdout: logLevel > logLevelMap.silent ? (s) => console.log(s) : undefined,
-          onStderr: logLevel > logLevelMap.silent ? (s) => console.error(`::error::${s}`) : undefined,
-        },
-      })
+      console.log(text)
     })
 
     context.on('kubb:hook:end', ({ command, args }) => {
@@ -375,5 +358,10 @@ export const githubActionsLogger = defineLogger({
     context.on('kubb:lifecycle:end', () => {
       reset()
     })
+
+    return (_commandWithArgs: string) => ({
+      onStdout: logLevel > logLevelMap.silent ? (s: string) => console.log(s) : undefined,
+      onStderr: logLevel > logLevelMap.silent ? (s: string) => console.error(`::error::${s}`) : undefined,
+    })
   },
 })

package/src/loggers/plainLogger.ts

@@ -2,8 +2,7 @@ import { relative } from 'node:path'
 import { formatMs, toCause } from '@internals/utils'
 import { defineLogger, logLevel as logLevelMap } from '@kubb/core'
 import { SUMMARY_SEPARATOR } from '../constants.ts'
-import { getSummary } from '../utils/getSummary.ts'
-import { runHook } from '../utils/runHook.ts'
+import { getSummary } from './utils.ts'
 import { formatCommandWithArgs, formatMessage } from './utils.ts'
 
 /**
@@ -199,30 +198,15 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('kubb:hook:start', async ({ id, command, args }) => {
-      const commandWithArgs = formatCommandWithArgs(command, args)
-      const text = getMessage(`Hook ${commandWithArgs} started`)
-
-      if (logLevel > logLevelMap.silent) {
-        console.log(text)
-      }
-
-      // Skip hook execution if no id is provided (e.g., during benchmarks or tests)
-      if (!id) {
+    context.on('kubb:hook:start', ({ command, args }) => {
+      if (logLevel <= logLevelMap.silent) {
         return
       }
 
-      await runHook({
-        id,
-        command,
-        args,
-        commandWithArgs,
-        context,
-        sink: {
-          onStdout: logLevel > logLevelMap.silent ? (s) => console.log(s) : undefined,
-          onStderr: logLevel > logLevelMap.silent ? (s) => console.error(s) : undefined,
-        },
-      })
+      const commandWithArgs = formatCommandWithArgs(command, args)
+      const text = getMessage(`Hook ${commandWithArgs} started`)
+
+      console.log(text)
     })
 
     context.on('kubb:hook:end', ({ command, args }) => {
@@ -250,5 +234,10 @@ export const plainLogger = defineLogger({
       console.log(summary.join('\n'))
       console.log(SUMMARY_SEPARATOR)
     })
+
+    return (_commandWithArgs: string) => ({
+      onStdout: logLevel > logLevelMap.silent ? (s: string) => console.log(s) : undefined,
+      onStderr: logLevel > logLevelMap.silent ? (s: string) => console.error(s) : undefined,
+    })
   },
 })

package/src/loggers/types.ts

@@ -1 +1,7 @@
+/**
+ * Logger adapter selected by `setupLogger` based on the runtime environment.
+ * - `'clack'`: TTY-aware output with spinners and progress bars.
+ * - `'github-actions'`: CI output using `::group::` annotations.
+ * - `'plain'`: Plain `console.log` output for non-TTY environments.
+ */
 export type LoggerType = 'clack' | 'github-actions' | 'plain'

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)
+  }
+}