@kubb/cli 5.0.0-alpha.9 → 5.0.0-beta.2

package/src/loggers/fileSystemLogger.ts

@@ -10,11 +10,8 @@ type CachedEvent = {
 }
 
 /**
- * FileSystem logger for debug log persistence
- * Captures debug and verbose events and writes them to files in .kubb directory
- *
- * Note: Logs are written on lifecycle:end or process exit. If the process crashes
- * before these events, some cached logs may be lost.
+ * 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.
  */
 export const fileSystemLogger = defineLogger({
   name: 'filesystem',
@@ -50,54 +47,56 @@ export const fileSystemLogger = defineLogger({
         }
       }
 
-      await Promise.all(Object.entries(files).map(([fileName, logs]) => write(fileName, logs.join('\n\n'))))
+      for (const [fileName, logs] of Object.entries(files)) {
+        await write(fileName, logs.join('\n\n'))
+      }
 
       return Object.keys(files)
     }
 
-    context.on('info', (message, info) => {
+    context.on('kubb:info', ({ message, info }) => {
       state.cachedLogs.add({
         date: new Date(),
         logs: [`ℹ ${message} ${info}`],
       })
     })
 
-    context.on('success', (message, info) => {
+    context.on('kubb:success', ({ message, info }) => {
       state.cachedLogs.add({
         date: new Date(),
         logs: [`✓ ${message} ${info}`],
       })
     })
 
-    context.on('warn', (message, info) => {
+    context.on('kubb:warn', ({ message, info }) => {
       state.cachedLogs.add({
         date: new Date(),
         logs: [`⚠ ${message} ${info}`],
       })
     })
 
-    context.on('error', (error) => {
+    context.on('kubb:error', ({ error }) => {
       state.cachedLogs.add({
         date: new Date(),
         logs: [`✗ ${error.message}`, error.stack || 'unknown stack'],
       })
     })
 
-    context.on('debug', (message) => {
+    context.on('kubb:debug', (message) => {
       state.cachedLogs.add({
         date: new Date(),
         logs: message.logs,
       })
     })
 
-    context.on('plugin:start', (plugin) => {
+    context.on('kubb:plugin:start', ({ plugin }) => {
       state.cachedLogs.add({
         date: new Date(),
         logs: [`Generating ${plugin.name}`],
       })
     })
 
-    context.on('plugin:end', (plugin, { duration, success }) => {
+    context.on('kubb:plugin:end', ({ plugin, duration, success }) => {
       const durationStr = formatMs(duration)
 
       state.cachedLogs.add({
@@ -106,18 +105,18 @@ export const fileSystemLogger = defineLogger({
       })
     })
 
-    context.on('files:processing:start', (files) => {
+    context.on('kubb:files:processing:start', ({ files }) => {
       state.cachedLogs.add({
         date: new Date(),
         logs: [`Start ${files.length} writing:`, ...files.map((file) => file.path)],
       })
     })
 
-    context.on('generation:end', async (config) => {
+    context.on('kubb:generation:end', async ({ config }) => {
       const writtenFilePaths = await writeLogs(config.name)
       if (writtenFilePaths.length > 0) {
         const files = writtenFilePaths.map((f) => relative(process.cwd(), f))
-        await context.emit('info', 'Debug files written to:', files.join(', '))
+        await context.emit('kubb:info', { message: 'Debug files written to:', info: files.join(', ') })
       }
       reset()
     })

package/src/loggers/githubActionsLogger.ts

@@ -5,8 +5,7 @@ import { runHook } from '../utils/runHook.ts'
 import { buildProgressLine, formatCommandWithArgs, formatMessage } from './utils.ts'
 
 /**
- * GitHub Actions adapter for CI environments
- * Uses Github group annotations for collapsible sections
+ * GitHub Actions logger using group annotations for collapsible sections in CI.
  */
 export const githubActionsLogger = defineLogger({
   name: 'github-actions',
@@ -55,7 +54,7 @@ export const githubActionsLogger = defineLogger({
       console.log('::endgroup::')
     }
 
-    context.on('info', (message, info = '') => {
+    context.on('kubb:info', ({ message, info = '' }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -65,7 +64,7 @@ export const githubActionsLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('success', (message, info = '') => {
+    context.on('kubb:success', ({ message, info = '' }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -75,7 +74,7 @@ export const githubActionsLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('warn', (message, info = '') => {
+    context.on('kubb:warn', ({ message, info = '' }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -85,7 +84,7 @@ export const githubActionsLogger = defineLogger({
       console.warn(`::warning::${text}`)
     })
 
-    context.on('error', (error) => {
+    context.on('kubb:error', ({ error }) => {
       const caused = toCause(error)
 
       if (logLevel <= logLevelMap.silent) {
@@ -112,12 +111,12 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('lifecycle:start', (version) => {
+    context.on('kubb:lifecycle:start', ({ version }) => {
       console.log(styleText('yellow', `Kubb ${version} 🧩`))
       reset()
     })
 
-    context.on('config:start', () => {
+    context.on('kubb:config:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -129,7 +128,7 @@ export const githubActionsLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('config:end', (configs) => {
+    context.on('kubb:config:end', ({ configs }) => {
       state.currentConfigs = configs
 
       if (logLevel <= logLevelMap.silent) {
@@ -143,7 +142,7 @@ export const githubActionsLogger = defineLogger({
       closeGroup('Configuration')
     })
 
-    context.on('generation:start', (config) => {
+    context.on('kubb:generation:start', ({ config }) => {
       reset()
 
       // Initialize progress tracking for this generation
@@ -160,7 +159,7 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('plugin:start', (plugin) => {
+    context.on('kubb:plugin:start', ({ plugin }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -173,7 +172,7 @@ export const githubActionsLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('plugin:end', (plugin, { duration, success }) => {
+    context.on('kubb:plugin:end', ({ plugin, duration, success }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -204,7 +203,7 @@ export const githubActionsLogger = defineLogger({
       showProgressStep()
     })
 
-    context.on('files:processing:start', (files) => {
+    context.on('kubb:files:processing:start', ({ files }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -220,7 +219,7 @@ export const githubActionsLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('files:processing:end', () => {
+    context.on('kubb:files:processing:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -236,7 +235,7 @@ export const githubActionsLogger = defineLogger({
       showProgressStep()
     })
 
-    context.on('file:processing:update', () => {
+    context.on('kubb:file:processing:update', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -244,7 +243,7 @@ export const githubActionsLogger = defineLogger({
       state.processedFiles++
     })
 
-    context.on('generation:end', (config) => {
+    context.on('kubb:generation:end', ({ config }) => {
       const text = getMessage(
         config.name ? `${styleText('blue', '✓')} Generation completed for ${styleText('dim', config.name)}` : `${styleText('blue', '✓')} Generation completed`,
       )
@@ -252,7 +251,7 @@ export const githubActionsLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('format:start', () => {
+    context.on('kubb:format:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -266,7 +265,7 @@ export const githubActionsLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('format:end', () => {
+    context.on('kubb:format:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -280,7 +279,7 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('lint:start', () => {
+    context.on('kubb:lint:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -294,7 +293,7 @@ export const githubActionsLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('lint:end', () => {
+    context.on('kubb:lint:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -308,7 +307,7 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('hook:start', async ({ id, command, args }) => {
+    context.on('kubb:hook:start', async ({ id, command, args }) => {
       const commandWithArgs = formatCommandWithArgs(command, args)
       const text = getMessage(`Hook ${styleText('dim', commandWithArgs)} started`)
 
@@ -338,7 +337,7 @@ export const githubActionsLogger = defineLogger({
       })
     })
 
-    context.on('hook:end', ({ command, args }) => {
+    context.on('kubb:hook:end', ({ command, args }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -353,7 +352,7 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('generation:summary', (config, { status, hrStart, failedPlugins }) => {
+    context.on('kubb:generation:summary', ({ config, status, hrStart, failedPlugins }) => {
       const pluginsCount = config.plugins?.length ?? 0
       const successCount = pluginsCount - failedPlugins.size
       const duration = formatHrtime(hrStart)
@@ -373,7 +372,7 @@ export const githubActionsLogger = defineLogger({
       }
     })
 
-    context.on('lifecycle:end', () => {
+    context.on('kubb:lifecycle:end', () => {
       reset()
     })
   },

package/src/loggers/plainLogger.ts

@@ -7,8 +7,7 @@ import { runHook } from '../utils/runHook.ts'
 import { formatCommandWithArgs, formatMessage } from './utils.ts'
 
 /**
- * Plain console adapter for non-TTY environments
- * Simple console.log output with indentation
+ * Plain console adapter for non-TTY environments with simple `console.log` output.
  */
 export const plainLogger = defineLogger({
   name: 'plain',
@@ -19,7 +18,7 @@ export const plainLogger = defineLogger({
       return formatMessage(message, logLevel)
     }
 
-    context.on('info', (message, info) => {
+    context.on('kubb:info', ({ message, info }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -29,7 +28,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('success', (message, info = '') => {
+    context.on('kubb:success', ({ message, info = '' }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -39,7 +38,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('warn', (message, info) => {
+    context.on('kubb:warn', ({ message, info }) => {
       if (logLevel < logLevelMap.warn) {
         return
       }
@@ -49,7 +48,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('error', (error) => {
+    context.on('kubb:error', ({ error }) => {
       const caused = toCause(error)
 
       const text = getMessage(['✗', error.message].join(' '))
@@ -74,11 +73,11 @@ export const plainLogger = defineLogger({
       }
     })
 
-    context.on('lifecycle:start', () => {
+    context.on('kubb:lifecycle:start', () => {
       console.log('Kubb CLI 🧩')
     })
 
-    context.on('config:start', () => {
+    context.on('kubb:config:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -88,7 +87,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('config:end', () => {
+    context.on('kubb:config:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -98,13 +97,13 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('generation:start', () => {
+    context.on('kubb:generation:start', () => {
       const text = getMessage('Generation started')
 
       console.log(text)
     })
 
-    context.on('plugin:start', (plugin) => {
+    context.on('kubb:plugin:start', ({ plugin }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -113,7 +112,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('plugin:end', (plugin, { duration, success }) => {
+    context.on('kubb:plugin:end', ({ plugin, duration, success }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -124,7 +123,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('files:processing:start', (files) => {
+    context.on('kubb:files:processing:start', ({ files }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -134,7 +133,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('file:processing:update', ({ file, config }) => {
+    context.on('kubb:file:processing:update', ({ file, config }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -144,7 +143,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('files:processing:end', () => {
+    context.on('kubb:files:processing:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -154,13 +153,13 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('generation:end', (config) => {
+    context.on('kubb:generation:end', ({ config }) => {
       const text = getMessage(config.name ? `Generation completed for ${config.name}` : 'Generation completed')
 
       console.log(text)
     })
 
-    context.on('format:start', () => {
+    context.on('kubb:format:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -170,7 +169,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('format:end', () => {
+    context.on('kubb:format:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -180,7 +179,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('lint:start', () => {
+    context.on('kubb:lint:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -190,7 +189,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('lint:end', () => {
+    context.on('kubb:lint:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -200,7 +199,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('hook:start', async ({ id, command, args }) => {
+    context.on('kubb:hook:start', async ({ id, command, args }) => {
       const commandWithArgs = formatCommandWithArgs(command, args)
       const text = getMessage(`Hook ${commandWithArgs} started`)
 
@@ -226,7 +225,7 @@ export const plainLogger = defineLogger({
       })
     })
 
-    context.on('hook:end', ({ command, args }) => {
+    context.on('kubb:hook:end', ({ command, args }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -237,7 +236,7 @@ export const plainLogger = defineLogger({
       console.log(text)
     })
 
-    context.on('generation:summary', (config, { pluginTimings, status, hrStart, failedPlugins, filesCreated }) => {
+    context.on('kubb:generation:summary', ({ config, pluginTimings, status, hrStart, failedPlugins, filesCreated }) => {
       const summary = getSummary({
         failedPlugins,
         filesCreated,

package/src/runners/agent.ts

@@ -17,6 +17,47 @@ type AgentStartOptions = {
   version: string
 }
 
+type ResolvedAgentStartEnvironment = {
+  port: string
+  host: string
+  allowWrite: boolean
+  allowAll: boolean
+  agentConfigPath: string
+  env: NodeJS.ProcessEnv
+}
+
+/**
+ * Resolves the environment passed to the detached agent process using CLI values first, then environment values, then CLI defaults.
+ */
+function resolveAgentStartEnvironment({ port, host, configPath, allowWrite, allowAll }: Omit<AgentStartOptions, 'version'>): 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,
+    },
+  }
+}
+
 function isPortAvailable(port: number, host: string): Promise<boolean> {
   return new Promise((resolve) => {
     const server = net.createServer()
@@ -41,60 +82,66 @@ export async function runAgentStart({ port, host, configPath, allowWrite, allowA
     }
 
     // Resolve the @kubb/agent package path
-    const agentPkgUrl = import.meta.resolve('@kubb/agent/package.json')
+    let agentPkgUrl: string
+    try {
+      agentPkgUrl = import.meta.resolve('@kubb/agent/package.json')
+    } catch (_e) {
+      console.error(`Import of '@kubb/agent' is required to start the Agent server`)
+      process.exit(1)
+    }
     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 = path.resolve(process.cwd(), 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 resolvedEnv = resolveAgentStartEnvironment({
+      port,
+      host,
+      configPath,
+      allowWrite,
+      allowAll,
+    })
+    const numericPort = Number(resolvedEnv.port)
 
-    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,
+    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: ${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.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(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.`))
+    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)
     }
 
-    console.log(env)
-
     // Spawns the server as a detached background process so the CLI can exit independently.
     await spawnAsync('node', [serverPath], {
-      env,
+      env: resolvedEnv.env,
       cwd: process.cwd(),
     })
 
-    await sendTelemetry(buildTelemetryEvent({ command: 'agent', kubbVersion: version, hrStart, status: 'success' }))
+    await sendTelemetry(
+      buildTelemetryEvent({
+        command: 'agent',
+        kubbVersion: version,
+        hrStart,
+        status: 'success',
+      }),
+    )
   } catch (error) {
-    await sendTelemetry(buildTelemetryEvent({ command: 'agent', kubbVersion: version, hrStart, status: 'failed' }))
+    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)