@kubb/cli 5.0.0-beta.4 → 5.0.0-beta.40

package/src/loggers/utils.ts

@@ -1,13 +1,58 @@
+import process from 'node:process'
 import { styleText } from 'node:util'
-import { canUseTTY, formatHrtime, isGitHubActions } from '@internals/utils'
-import type { Logger, LoggerContext, LoggerOptions } from '@kubb/core'
+import { canUseTTY, formatHrtime, getElapsedMs, isGitHubActions } from '@internals/utils'
+import type { Logger, LoggerContext, LoggerOptions, Reporter, ReporterContext } from '@kubb/core'
 import { logLevel as logLevelMap } from '@kubb/core'
 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.
+ *
+ * `hookId` is the same id passed to `kubb:hook:start` / `kubb:hook:end`, letting the logger
+ * correlate streamed output with the active UI element (e.g., a clack `taskLog`) it created in the start handler.
+ */
+export type HookSinkFactory = (commandWithArgs: string, hookId: string) => HookSinkOptions | null
+
+/**
+ * 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 | undefined | null>
+
 /**
  * Optionally prefix a message with a [HH:MM:SS] timestamp when logLevel >= verbose.
  * Shared across all logger adapters to avoid duplication.
@@ -26,11 +71,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]
 }
 
@@ -39,7 +102,7 @@ type ProgressState = {
  * Returns null when there is nothing to display.
  */
 export function buildProgressLine(state: ProgressState): string | null {
-  const parts: string[] = []
+  const parts: Array<string> = []
   const duration = formatHrtime(state.hrStart)
 
   if (state.totalPlugins > 0) {
@@ -62,11 +125,85 @@ export function buildProgressLine(state: ProgressState): string | null {
   return parts.join(styleText('dim', ' | '))
 }
 
+/**
+ * Creates the per-run progress counters shared by the clack and GitHub Actions loggers.
+ */
+export function createProgressCounters(): ProgressState {
+  return {
+    totalPlugins: 0,
+    completedPlugins: 0,
+    failedPlugins: 0,
+    totalFiles: 0,
+    processedFiles: 0,
+    hrStart: process.hrtime(),
+  }
+}
+
+/**
+ * Resets the progress counters in place at the start/end of a generation run.
+ */
+export function resetProgressCounters(state: ProgressState): void {
+  state.totalPlugins = 0
+  state.completedPlugins = 0
+  state.failedPlugins = 0
+  state.totalFiles = 0
+  state.processedFiles = 0
+  state.hrStart = process.hrtime()
+}
+
+/**
+ * Records a finished plugin against the progress counters.
+ */
+export function recordPluginResult(state: ProgressState, success: boolean): void {
+  if (success) {
+    state.completedPlugins++
+  } else {
+    state.failedPlugins++
+  }
+}
+
+/**
+ * Tracks per-hook start times so a logger can report a hook's elapsed duration.
+ * Used by the loggers that key timing by hook `id` (GitHub Actions, plain).
+ */
+export type HookTimer = {
+  start(id: string): void
+  /**
+   * Returns the elapsed milliseconds since `start(id)`, or `undefined` when no start was recorded.
+   */
+  end(id: string): number | undefined
+  clear(): void
+}
+
+/**
+ * Creates a {@link HookTimer} backed by a private `id → hrtime` map.
+ */
+export function createHookTimer(): HookTimer {
+  const starts = new Map<string, [number, number]>()
+
+  return {
+    start(id: string): void {
+      starts.set(id, process.hrtime())
+    },
+    end(id: string): number | undefined {
+      const hrStart = starts.get(id)
+      if (!hrStart) {
+        return undefined
+      }
+      starts.delete(id)
+      return getElapsedMs(hrStart)
+    },
+    clear(): void {
+      starts.clear()
+    },
+  }
+}
+
 /**
  * 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 {
+export function formatCommandWithArgs(command: string, args?: ReadonlyArray<string>): string {
   return args?.length ? `${command} ${args.join(' ')}` : command
 }
 
@@ -80,27 +217,62 @@ 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> {
-  const type = detectLogger()
+}
 
-  const logger = logMapper[type] as Logger
+/**
+ * Bridges a {@link Reporter} onto the run's event emitter: calls `report` with each config's
+ * {@link GenerationResult} on `kubb:generation:end`. The reporter never touches the emitter.
+ */
+export function installReporter(context: LoggerContext, reporter: Reporter, ctx: ReporterContext): void {
+  context.on('kubb:generation:end', async ({ config, diagnostics = [], filesCreated = 0, status = 'success', hrStart = process.hrtime() }) => {
+    await reporter.report({ config, diagnostics, filesCreated, status, hrStart }, ctx)
+  })
 
-  if (!logger) {
-    throw new Error(`Unknown adapter type: ${type}`)
+  if (reporter.drain) {
+    context.on('kubb:lifecycle:end', () => reporter.drain?.(ctx))
   }
+}
+
+/**
+ * Installs the live logger (the TUI view) and the given reporters (the output), returning the
+ * terminal logger's hook sink when one was installed. The reporters are already selected by the
+ * caller (the CLI maps `--reporter` to names via `selectReporters`); this only wires them.
+ *
+ * Loggers and reporters are independent: the `cli` reporter also activates the env logger summary.
+ * The `json` reporter owns stdout, so the live logger and the `cli` summary are suppressed whenever
+ * `json` is among the reporters, even if `cli` is also listed.
+ */
+async function setupReporters(
+  context: LoggerContext,
+  { logLevel, reporters }: LoggerOptions & { reporters: ReadonlyArray<Reporter> },
+): Promise<HookSinkFactory | null> {
+  const hasJson = reporters.some((reporter) => reporter.name === 'json')
+  const ctx: ReporterContext = { logLevel }
+
+  let makeSink: HookSinkFactory | null = null
 
-  // Install primary logger
-  const cleanup = await logger.install(context, { logLevel })
+  for (const reporter of reporters) {
+    if (reporter.name === 'cli') {
+      if (hasJson) {
+        continue
+      }
+      const type = detectLogger()
+      const logger = logMapper[type]
+      if (!logger) {
+        throw new Error(`Unknown adapter type: ${type}`)
+      }
+      const sink = await logger.install(context, { logLevel })
+      makeSink = typeof sink === 'function' ? sink : null
+    }
 
-  if (logLevel >= logLevelMap.debug) {
-    await fileSystemLogger.install(context, { logLevel })
+    installReporter(context, reporter, ctx)
   }
 
-  return cleanup
+  return makeSink
 }
+
+export default setupReporters

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 { Telemetry } from '@kubb/core'
+import { agentDefaults } from '../../constants.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') => Telemetry.send(Telemetry.build({ 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)
+  })
+}