@kubb/cli 4.32.3 → 4.33.0

package/src/cli/help.ts

@@ -0,0 +1,36 @@
+import { styleText } from 'node:util'
+import { getCommandSchema } from './schema.ts'
+import type { CommandDefinition, OptionSchema } from './types.ts'
+
+/** Prints formatted help output for a command using its `CommandDefinition`. */
+export function renderHelp(def: CommandDefinition, parentName?: string): void {
+  const schema = getCommandSchema([def])[0]!
+
+  const programName = parentName ? `${parentName} ${schema.name}` : schema.name
+
+  const argsPart = schema.arguments?.length ? ` ${schema.arguments.join(' ')}` : ''
+  const subCmdPart = schema.subCommands.length ? ' <command>' : ''
+  console.log(`\n${styleText('bold', 'Usage:')} ${programName}${argsPart}${subCmdPart} [options]\n`)
+
+  if (schema.description) {
+    console.log(`  ${schema.description}\n`)
+  }
+
+  if (schema.subCommands.length) {
+    console.log(styleText('bold', 'Commands:'))
+    for (const sub of schema.subCommands) {
+      console.log(`  ${styleText('cyan', sub.name.padEnd(16))}${sub.description}`)
+    }
+    console.log()
+  }
+
+  const options: OptionSchema[] = [...schema.options, { name: 'help', flags: '-h, --help', type: 'boolean' as const, description: 'Show help' }]
+
+  console.log(styleText('bold', 'Options:'))
+  for (const opt of options) {
+    const flags = styleText('cyan', opt.flags.padEnd(30))
+    const defaultPart = opt.default !== undefined ? styleText('dim', ` (default: ${opt.default})`) : ''
+    console.log(`  ${flags}${opt.description}${defaultPart}`)
+  }
+  console.log()
+}

package/src/cli/index.ts

@@ -0,0 +1,16 @@
+export { nodeAdapter } from './adapters/nodeAdapter.ts'
+export { createCLI } from './parse.ts'
+export { getCommandSchema } from './schema.ts'
+export type {
+  BooleanOption,
+  CLIAdapter,
+  CommandDefinition,
+  CommandSchema,
+  OptionDefinition,
+  OptionSchema,
+  OptionType,
+  ParsedArgs,
+  RunOptions,
+  StringOption,
+} from './types.ts'
+export { defineCLIAdapter, defineCommand } from './types.ts'

package/src/cli/parse.ts

@@ -0,0 +1,18 @@
+import { nodeAdapter } from './adapters/nodeAdapter.ts'
+import type { CLIAdapter, CommandDefinition, RunOptions } from './types.ts'
+
+/**
+ * Create a CLI runner bound to a specific adapter.
+ * Defaults to the built-in `nodeAdapter` (Node.js `node:util parseArgs`).
+ */
+export function createCLI(options?: { adapter?: CLIAdapter }): {
+  run(commands: CommandDefinition[], argv: string[], opts: RunOptions): Promise<void>
+} {
+  const adapter = options?.adapter ?? nodeAdapter
+
+  return {
+    run(commands, argv, opts) {
+      return adapter.run(commands, argv, opts)
+    },
+  }
+}

package/src/cli/schema.ts

@@ -0,0 +1,38 @@
+import type { CommandDefinition, CommandSchema, OptionDefinition, OptionSchema } from './types.ts'
+
+/**
+ * Serializes `CommandDefinition[]` to a plain, JSON-serializable structure.
+ * Use to expose CLI capabilities to AI agents or MCP tools.
+ */
+export function getCommandSchema(defs: CommandDefinition[]): CommandSchema[] {
+  return defs.map(serializeCommand)
+}
+
+function serializeCommand(def: CommandDefinition): CommandSchema {
+  return {
+    name: def.name,
+    description: def.description,
+    arguments: def.arguments,
+    options: serializeOptions(def.options ?? {}),
+    subCommands: def.subCommands ? def.subCommands.map(serializeCommand) : [],
+  }
+}
+
+function serializeOptions(options: Record<string, OptionDefinition>): OptionSchema[] {
+  return Object.entries(options).map(([name, opt]) => {
+    const shortPart = opt.short ? `-${opt.short}, ` : ''
+    const valuePart = opt.type === 'string' ? ` <${opt.hint ?? name}>` : ''
+    const flags = `${shortPart}--${name}${valuePart}`
+
+    return {
+      name,
+      flags,
+      type: opt.type,
+      description: opt.description,
+      ...(opt.default !== undefined ? { default: opt.default } : {}),
+      ...(opt.hint ? { hint: opt.hint } : {}),
+      ...(opt.enum ? { enum: opt.enum } : {}),
+      ...(opt.required ? { required: opt.required } : {}),
+    }
+  })
+}

package/src/cli/types.ts

@@ -0,0 +1,95 @@
+type BaseOption = {
+  /** Single-character short alias, e.g. `'c'` for `--config`. */
+  short?: string
+  description: string
+  hint?: string
+  required?: boolean
+  /** Allowed values for string options. Used in help output and AI/MCP tool schemas. */
+  enum?: string[]
+}
+
+export type StringOption = BaseOption & { type: 'string'; default?: string }
+export type BooleanOption = BaseOption & { type: 'boolean'; default?: boolean }
+export type OptionDefinition = StringOption | BooleanOption
+export type OptionType = OptionDefinition['type']
+
+type OptionTypeMap = { string: string; boolean: boolean }
+
+type IsRequired<O extends OptionDefinition> = O['default'] extends string | boolean ? true : O['required'] extends true ? true : false
+
+/** Infers typed values from an options record. Options with a `default` or `required: true` are always defined. */
+type InferValues<O extends Record<string, OptionDefinition>> = {
+  [K in keyof O as IsRequired<O[K]> extends true ? K : never]: OptionTypeMap[O[K]['type']]
+} & {
+  [K in keyof O as IsRequired<O[K]> extends true ? never : K]?: OptionTypeMap[O[K]['type']]
+}
+
+export type ParsedArgs = {
+  values: Record<string, string | boolean | undefined>
+  positionals: string[]
+}
+
+export type CommandDefinition = {
+  name: string
+  description: string
+  /** Positional argument labels shown in usage line, e.g. `['[input]']`. */
+  arguments?: string[]
+  options?: Record<string, OptionDefinition>
+  subCommands?: CommandDefinition[]
+  run?: (args: ParsedArgs) => Promise<void>
+}
+
+/**
+ * Returns a `CommandDefinition` with typed `values` in `run()`.
+ * The callback receives `values` typed from the declared options — no casts needed.
+ */
+export function defineCommand<O extends Record<string, OptionDefinition>>(def: {
+  name: string
+  description: string
+  arguments?: string[]
+  options?: O
+  subCommands?: CommandDefinition[]
+  run?: (args: { values: InferValues<O>; positionals: string[] }) => Promise<void>
+}): CommandDefinition {
+  const { run, ...rest } = def
+  if (!run) return rest
+  return {
+    ...rest,
+    run: (args) => run({ values: args.values as InferValues<O>, positionals: args.positionals }),
+  }
+}
+
+export type RunOptions = {
+  programName: string
+  defaultCommandName: string
+  version: string
+}
+
+export type CLIAdapter = {
+  run(commands: CommandDefinition[], argv: string[], opts: RunOptions): Promise<void>
+  renderHelp(def: CommandDefinition, parentName?: string): void
+}
+
+/** Returns a `CLIAdapter` with type inference. Pass a different adapter to `createCLI` to swap the CLI engine. */
+export function defineCLIAdapter(adapter: CLIAdapter): CLIAdapter {
+  return adapter
+}
+
+export type OptionSchema = {
+  name: string
+  flags: string
+  type: OptionType
+  description: string
+  default?: string | boolean
+  hint?: string
+  required?: boolean
+  enum?: string[]
+}
+
+export type CommandSchema = {
+  name: string
+  description: string
+  arguments?: string[]
+  options: OptionSchema[]
+  subCommands: CommandSchema[]
+}

package/src/commands/agent/start.ts

@@ -1,141 +1,32 @@
-import { spawn } from 'node:child_process'
 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 type { ArgsDef } from 'citty'
-import { defineCommand } from 'citty'
 import { version } from '../../../package.json'
-import { buildTelemetryEvent, sendTelemetry } from '../../utils/telemetry.ts'
-
-const args = {
-  config: {
-    type: 'string',
-    description: 'Path to the Kubb config',
-    alias: 'c',
-  },
-  port: {
-    type: 'string',
-    description: 'Port for the server. If not specified, an available port is automatically selected.',
-    alias: 'p',
-  },
-  host: {
-    type: 'string',
-    description: 'Host for the server',
-    default: 'localhost',
-  },
-  'no-cache': {
-    type: 'boolean',
-    description: 'Disable session caching',
-    default: false,
-  },
-  'allow-write': {
-    type: 'boolean',
-    description: 'Allow writing generated files to the filesystem. When not set, no files are written and the config patch is not persisted.',
-    default: false,
-  },
-  'allow-all': {
-    type: 'boolean',
-    description: 'Grant all permissions (implies --allow-write).',
-    default: false,
-  },
-} as const satisfies ArgsDef
-
-type StartServerProps = {
-  port: number
-  host: string
-  configPath: string
-  allowWrite: boolean
-  allowAll: boolean
-}
-
-async function startServer({ port, host, configPath, allowWrite, allowAll }: StartServerProps): Promise<void> {
-  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, '.output', 'server', 'index.mjs')
-
-    // nitro env
-    const PORT = process.env.PORT || (port === 0 ? '3000' : String(port))
-    const HOST = process.env.HOST || host || '0.0.0.0'
-
-    // kubb env
-    const KUBB_AGENT_ROOT = process.env.KUBB_AGENT_ROOT || process.cwd()
-    const KUBB_AGENT_CONFIG = process.env.KUBB_AGENT_CONFIG || configPath || 'kubb.config.ts'
-    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 || '30000'
-    const KUBB_STUDIO_URL = process.env.KUBB_STUDIO_URL || 'https://studio.kubb.dev'
-
-    // Set environment variables
-    const 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.'))
-    }
-
-    spawn('node', [serverPath], {
-      env: { ...process.env, ...env },
-      stdio: 'inherit',
-      cwd: process.cwd(),
+import { defineCommand } from '../../cli/index.ts'
+import { agentDefaults } from '../../constants.ts'
+
+export const command = defineCommand({
+  name: 'start',
+  description: 'Start the Agent server',
+  options: {
+    config: { type: 'string', description: 'Path to the Kubb config', short: 'c' },
+    port: { type: 'string', description: `Port for the server (default: ${agentDefaults.port})`, short: 'p' },
+    host: { type: 'string', description: 'Host for the server', default: agentDefaults.host },
+    'allow-write': {
+      type: 'boolean',
+      description: 'Allow writing generated files to the filesystem. When not set, no files are written and the config patch is not persisted.',
+      default: false,
+    },
+    'allow-all': { type: 'boolean', description: 'Grant all permissions (implies --allow-write).', default: false },
+  },
+  async run({ values }) {
+    const { runAgentStart } = await import('../../runners/agent.ts')
+
+    await runAgentStart({
+      port: values.port !== undefined ? values.port : undefined,
+      host: values.host,
+      configPath: path.resolve(process.cwd(), values.config ?? agentDefaults.configFile),
+      allowWrite: values['allow-write'],
+      allowAll: values['allow-all'],
+      version,
     })
-  } catch (error) {
-    console.error('Failed to start agent server:', error)
-    process.exit(1)
-  }
-}
-
-const command = defineCommand({
-  meta: {
-    name: 'start',
-    description: 'Start the Agent server',
-  },
-  args,
-  async run(commandContext) {
-    const { args } = commandContext
-    const hrStart = process.hrtime()
-
-    try {
-      const configPath = path.resolve(process.cwd(), args.config || 'kubb.config.ts')
-      const port = args.port ? Number.parseInt(args.port, 10) : 0
-      const host = args.host
-      const allowWrite = args['allow-write']
-      const allowAll = args['allow-all']
-
-      startServer({ port, host, configPath, allowWrite, allowAll })
-      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)
-    }
   },
 })
-
-export default command

package/src/commands/agent.ts

@@ -1,27 +1,8 @@
-import type { ArgsDef } from 'citty'
-import { defineCommand, showUsage } from 'citty'
+import { defineCommand } from '../cli/index.ts'
+import { command as startCommand } from './agent/start.ts'
 
-const args = {
-  help: {
-    type: 'boolean',
-    description: 'Show help',
-    alias: 'h',
-    default: false,
-  },
-} as const satisfies ArgsDef
-
-const command = defineCommand({
-  args,
-  subCommands: {
-    start: () => import('./agent/start.ts').then((m) => m.default),
-  },
-  async run(commandContext) {
-    const { args } = commandContext
-
-    if (args.help) {
-      return showUsage(command)
-    }
-  },
+export const command = defineCommand({
+  name: 'agent',
+  description: 'Manage the Kubb Agent server',
+  subCommands: [startCommand],
 })
-
-export default command

package/src/commands/generate.ts

@@ -1,160 +1,28 @@
-import path from 'node:path'
-import * as process from 'node:process'
-import { styleText } from 'node:util'
-import * as clack from '@clack/prompts'
-import { type CLIOptions, isInputPath, type KubbEvents, LogLevel, PromiseManager } from '@kubb/core'
-import { AsyncEventEmitter, executeIfOnline, getConfigs } from '@kubb/core/utils'
-import type { ArgsDef, ParsedArgs } from 'citty'
-import { defineCommand, showUsage } from 'citty'
-import { version } from '../../package.json'
-import { setupLogger } from '../loggers/utils.ts'
-import { generate } from '../runners/generate.ts'
-import { getCosmiConfig } from '../utils/getCosmiConfig.ts'
-import { startWatcher } from '../utils/watcher.ts'
-
-const args = {
-  config: {
-    type: 'string',
-    description: 'Path to the Kubb config',
-    alias: 'c',
-  },
-  logLevel: {
-    type: 'string',
-    description: 'Info, silent, verbose or debug',
-    alias: 'l',
-    default: 'info',
-    valueHint: 'silent|info|verbose|debug',
-  },
-  watch: {
-    type: 'boolean',
-    description: 'Watch mode based on the input file',
-    alias: 'w',
-    default: false,
-  },
-  debug: {
-    type: 'boolean',
-    description: 'Override logLevel to debug',
-    alias: 'd',
-    default: false,
-  },
-  verbose: {
-    type: 'boolean',
-    description: 'Override logLevel to verbose',
-    alias: 'v',
-    default: false,
-  },
-  silent: {
-    type: 'boolean',
-    description: 'Override logLevel to silent',
-    alias: 's',
-    default: false,
-  },
-  help: {
-    type: 'boolean',
-    description: 'Show help',
-    alias: 'h',
-    default: false,
-  },
-} as const satisfies ArgsDef
-
-export type Args = ParsedArgs<typeof args>
-
-const command = defineCommand({
-  meta: {
-    name: 'generate',
-    description: "[input] Generate files based on a 'kubb.config.ts' file",
-  },
-  args,
-  async run(commandContext) {
-    const { args } = commandContext
-    const input = args._[0]
-    const events = new AsyncEventEmitter<KubbEvents>()
-    const promiseManager = new PromiseManager()
-
-    if (args.help) {
-      return showUsage(command)
-    }
-
-    if (args.debug) {
-      args.logLevel = 'debug'
-    }
-
-    if (args.verbose) {
-      args.logLevel = 'verbose'
-    }
-
-    if (args.silent) {
-      args.logLevel = 'silent'
-    }
-
-    const logLevel = LogLevel[args.logLevel as keyof typeof LogLevel] || 3
-
-    await setupLogger(events, { logLevel })
-
-    await executeIfOnline(async () => {
-      try {
-        const res = await fetch('https://registry.npmjs.org/@kubb/cli/latest')
-        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', args.config)
-      const configs = await getConfigs(result.config, args 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) && args.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', error as Error)
-      process.exit(1)
-    }
+import { defineCommand } from '../cli/index.ts'
+
+export const command = defineCommand({
+  name: 'generate',
+  description: "[input] Generate files based on a 'kubb.config.ts' file",
+  arguments: ['[input]'],
+  options: {
+    config: { type: 'string', description: 'Path to the Kubb config', short: 'c' },
+    logLevel: {
+      type: 'string',
+      description: 'Info, silent, verbose or debug',
+      short: 'l',
+      default: 'info',
+      hint: 'silent|info|verbose|debug',
+      enum: ['silent', 'info', 'verbose', 'debug'],
+    },
+    watch: { type: 'boolean', description: 'Watch mode based on the input file', short: 'w', default: false },
+    debug: { type: 'boolean', description: 'Override logLevel to debug', short: 'd', default: false },
+    verbose: { type: 'boolean', description: 'Override logLevel to verbose', short: 'v', default: false },
+    silent: { type: 'boolean', description: 'Override logLevel to silent', short: 's', default: false },
+  },
+  async run({ values, positionals }) {
+    const logLevel = values.debug ? 'debug' : values.verbose ? 'verbose' : values.silent ? 'silent' : values.logLevel
+    const { runGenerateCommand } = await import('../runners/generate.ts')
+
+    await runGenerateCommand({ input: positionals[0], configPath: values.config, logLevel, watch: values.watch })
   },
 })
-
-export default command