@kubb/cli 4.32.3 → 4.33.0

package/src/commands/init.ts

@@ -1,366 +1,15 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import process from 'node:process'
-import { styleText } from 'node:util'
-import * as clack from '@clack/prompts'
-import { detectPackageManager, type PackageManagerInfo } from '@kubb/core'
-import { defineCommand } from 'citty'
 import { version } from '../../package.json'
-import { hasPackageJson, initPackageJson, installPackages } from '../utils/packageManager.ts'
+import { defineCommand } from '../cli/index.ts'
 
-type PluginOption = {
-  value: string
-  label: string
-  hint?: string
-  packageName: string
-  importName: string
-  category: 'core' | 'typescript' | 'query' | 'validation' | 'testing' | 'mocking' | 'docs'
-}
-
-const plugins: PluginOption[] = [
-  {
-    value: 'plugin-oas',
-    label: 'OpenAPI Parser',
-    hint: 'Required',
-    packageName: '@kubb/plugin-oas',
-    importName: 'pluginOas',
-    category: 'core',
-  },
-  {
-    value: 'plugin-ts',
-    label: 'TypeScript',
-    hint: 'Recommended',
-    packageName: '@kubb/plugin-ts',
-    importName: 'pluginTs',
-    category: 'typescript',
-  },
-  {
-    value: 'plugin-client',
-    label: 'Client (Fetch/Axios)',
-    packageName: '@kubb/plugin-client',
-    importName: 'pluginClient',
-    category: 'typescript',
-  },
-  {
-    value: 'plugin-react-query',
-    label: 'React Query / TanStack Query',
-    packageName: '@kubb/plugin-react-query',
-    importName: 'pluginReactQuery',
-    category: 'query',
-  },
-  {
-    value: 'plugin-solid-query',
-    label: 'Solid Query',
-    packageName: '@kubb/plugin-solid-query',
-    importName: 'pluginSolidQuery',
-    category: 'query',
-  },
-  {
-    value: 'plugin-svelte-query',
-    label: 'Svelte Query',
-    packageName: '@kubb/plugin-svelte-query',
-    importName: 'pluginSvelteQuery',
-    category: 'query',
-  },
-  {
-    value: 'plugin-vue-query',
-    label: 'Vue Query',
-    packageName: '@kubb/plugin-vue-query',
-    importName: 'pluginVueQuery',
-    category: 'query',
-  },
-  {
-    value: 'plugin-swr',
-    label: 'SWR',
-    packageName: '@kubb/plugin-swr',
-    importName: 'pluginSwr',
-    category: 'query',
-  },
-  {
-    value: 'plugin-zod',
-    label: 'Zod Schemas',
-    packageName: '@kubb/plugin-zod',
-    importName: 'pluginZod',
-    category: 'validation',
-  },
-  {
-    value: 'plugin-faker',
-    label: 'Faker.js Mocks',
-    packageName: '@kubb/plugin-faker',
-    importName: 'pluginFaker',
-    category: 'mocking',
-  },
-  {
-    value: 'plugin-msw',
-    label: 'MSW Handlers',
-    packageName: '@kubb/plugin-msw',
-    importName: 'pluginMsw',
-    category: 'mocking',
-  },
-  {
-    value: 'plugin-cypress',
-    label: 'Cypress Tests',
-    packageName: '@kubb/plugin-cypress',
-    importName: 'pluginCypress',
-    category: 'testing',
-  },
-  {
-    value: 'plugin-redoc',
-    label: 'ReDoc Documentation',
-    packageName: '@kubb/plugin-redoc',
-    importName: 'pluginRedoc',
-    category: 'docs',
+export const command = defineCommand({
+  name: 'init',
+  description: 'Initialize a new Kubb project with interactive setup',
+  options: {
+    yes: { type: 'boolean', description: 'Skip prompts and use default options', short: 'y', default: false },
   },
-]
+  async run({ values }) {
+    const { runInit } = await import('../runners/init.ts')
 
-function generateConfigFile(selectedPlugins: PluginOption[], inputPath: string, outputPath: string): string {
-  const imports = selectedPlugins.map((plugin) => `import { ${plugin.importName} } from '${plugin.packageName}'`).join('\n')
-
-  const pluginConfigs = selectedPlugins
-    .map((plugin) => {
-      if (plugin.value === 'plugin-oas') {
-        return '    pluginOas(),'
-      }
-      if (plugin.value === 'plugin-ts') {
-        return `    pluginTs({\n      output: {\n        path: 'models',\n      },\n    }),`
-      }
-      if (plugin.value === 'plugin-client') {
-        return `    pluginClient({\n      output: {\n        path: 'clients',\n      },\n    }),`
-      }
-      if (plugin.value === 'plugin-react-query') {
-        return `    pluginReactQuery({\n      output: {\n        path: 'hooks',\n      },\n    }),`
-      }
-      if (plugin.value === 'plugin-zod') {
-        return `    pluginZod({\n      output: {\n        path: 'zod',\n      },\n    }),`
-      }
-      if (plugin.value === 'plugin-faker') {
-        return `    pluginFaker({\n      output: {\n        path: 'mocks',\n      },\n    }),`
-      }
-      if (plugin.value === 'plugin-msw') {
-        return `    pluginMsw({\n      output: {\n        path: 'msw',\n      },\n    }),`
-      }
-      if (plugin.value === 'plugin-swr') {
-        return `    pluginSwr({\n      output: {\n        path: 'hooks',\n      },\n    }),`
-      }
-      // Default config for other plugins
-      return `    ${plugin.importName}(),`
-    })
-    .join('\n')
-
-  return `import { defineConfig } from '@kubb/core'
-${imports}
-
-export default defineConfig({
-  root: '.',
-  input: {
-    path: '${inputPath}',
-  },
-  output: {
-    path: '${outputPath}',
-    clean: true,
+    await runInit({ yes: values.yes, version })
   },
-  plugins: [
-${pluginConfigs}
-  ],
 })
-`
-}
-
-const DEFAULT_INPUT_PATH = './openapi.yaml'
-const DEFAULT_OUTPUT_PATH = './src/gen'
-const DEFAULT_PLUGINS = ['plugin-oas', 'plugin-ts']
-
-const command = defineCommand({
-  meta: {
-    name: 'init',
-    description: 'Initialize a new Kubb project with interactive setup',
-  },
-  args: {
-    yes: {
-      type: 'boolean',
-      alias: 'y',
-      description: 'Skip prompts and use default options',
-      default: false,
-    },
-  },
-  async run({ args }) {
-    const cwd = process.cwd()
-    const yes = args.yes
-
-    clack.intro(styleText('bgCyan', styleText('black', ' Kubb Init ')))
-
-    try {
-      // Check/create package.json
-      let packageManager: PackageManagerInfo
-      if (!hasPackageJson(cwd)) {
-        if (!yes) {
-          const shouldInit = await clack.confirm({
-            message: 'No package.json found. Would you like to create one?',
-            initialValue: true,
-          })
-
-          if (clack.isCancel(shouldInit) || !shouldInit) {
-            clack.cancel('Operation cancelled.')
-            process.exit(0)
-          }
-        }
-
-        // Detect package manager before initializing
-        packageManager = detectPackageManager(cwd)
-
-        const spinner = clack.spinner()
-        spinner.start(`Initializing package.json with ${packageManager.name}`)
-
-        await initPackageJson(cwd, packageManager)
-
-        spinner.stop(`Created package.json with ${packageManager.name}`)
-      } else {
-        packageManager = detectPackageManager(cwd)
-        clack.log.info(`Detected package manager: ${styleText('cyan', packageManager.name)}`)
-      }
-
-      // Prompt for OpenAPI spec path
-      let inputPath: string
-      if (yes) {
-        inputPath = DEFAULT_INPUT_PATH
-        clack.log.info(`Using input path: ${styleText('cyan', inputPath)}`)
-      } else {
-        const inputPathResult = await clack.text({
-          message: 'Where is your OpenAPI specification located?',
-          placeholder: DEFAULT_INPUT_PATH,
-          defaultValue: DEFAULT_INPUT_PATH,
-          validate: (value) => {
-            if (!value) return 'Input path is required'
-          },
-        })
-
-        if (clack.isCancel(inputPathResult)) {
-          clack.cancel('Operation cancelled.')
-          process.exit(0)
-        }
-        inputPath = inputPathResult as string
-      }
-
-      // Prompt for output directory
-      let outputPath: string
-      if (yes) {
-        outputPath = DEFAULT_OUTPUT_PATH
-        clack.log.info(`Using output path: ${styleText('cyan', outputPath)}`)
-      } else {
-        const outputPathResult = await clack.text({
-          message: 'Where should the generated files be output?',
-          placeholder: DEFAULT_OUTPUT_PATH,
-          defaultValue: DEFAULT_OUTPUT_PATH,
-          validate: (value) => {
-            if (!value) return 'Output path is required'
-          },
-        })
-
-        if (clack.isCancel(outputPathResult)) {
-          clack.cancel('Operation cancelled.')
-          process.exit(0)
-        }
-        outputPath = outputPathResult as string
-      }
-
-      // Plugin selection
-      let selectedPlugins: PluginOption[]
-      if (yes) {
-        selectedPlugins = plugins.filter((plugin) => DEFAULT_PLUGINS.includes(plugin.value))
-        clack.log.info(`Using plugins: ${styleText('cyan', selectedPlugins.map((p) => p.label).join(', '))}`)
-      } else {
-        const selectedPluginValues = await clack.multiselect({
-          message: 'Select plugins to use:',
-          options: plugins.map((plugin) => ({
-            value: plugin.value,
-            label: plugin.label,
-            hint: plugin.hint,
-          })),
-          initialValues: DEFAULT_PLUGINS,
-          required: true,
-        })
-
-        if (clack.isCancel(selectedPluginValues)) {
-          clack.cancel('Operation cancelled.')
-          process.exit(0)
-        }
-
-        selectedPlugins = plugins.filter((plugin) => (selectedPluginValues as string[]).includes(plugin.value))
-      }
-
-      // Ensure plugin-oas is always included
-      if (!selectedPlugins.find((p) => p.value === 'plugin-oas')) {
-        selectedPlugins.unshift(plugins.find((p) => p.value === 'plugin-oas')!)
-      }
-
-      // Install packages
-      const packagesToInstall = ['@kubb/core', '@kubb/cli', '@kubb/agent', ...selectedPlugins.map((p) => p.packageName)]
-
-      const spinner = clack.spinner()
-      spinner.start(`Installing ${packagesToInstall.length} packages with ${packageManager.name}`)
-
-      try {
-        await installPackages(packagesToInstall, packageManager, cwd)
-        spinner.stop(`Installed ${packagesToInstall.length} packages`)
-      } catch (error) {
-        spinner.stop('Installation failed')
-        throw error
-      }
-
-      // Generate config file
-      const configSpinner = clack.spinner()
-      configSpinner.start('Creating kubb.config.ts')
-
-      const configContent = generateConfigFile(selectedPlugins, inputPath, outputPath)
-      const configPath = path.join(cwd, 'kubb.config.ts')
-
-      // Check if config already exists
-      if (fs.existsSync(configPath)) {
-        configSpinner.stop('kubb.config.ts already exists')
-
-        if (!yes) {
-          const shouldOverwrite = await clack.confirm({
-            message: 'kubb.config.ts already exists. Overwrite?',
-            initialValue: false,
-          })
-
-          if (clack.isCancel(shouldOverwrite) || !shouldOverwrite) {
-            clack.cancel('Keeping existing configuration. Packages have been installed.')
-            process.exit(0)
-          }
-        }
-
-        configSpinner.start('Overwriting kubb.config.ts')
-      }
-
-      fs.writeFileSync(configPath, configContent, 'utf-8')
-
-      configSpinner.stop('Created kubb.config.ts')
-
-      // Success message
-      clack.outro(
-        styleText('green', '✓ All set!') +
-          '\n\n' +
-          styleText('dim', 'Next steps:') +
-          '\n' +
-          styleText('cyan', `  1. Make sure your OpenAPI spec is at: ${inputPath}`) +
-          '\n' +
-          styleText('cyan', '  2. Generate code with: npx kubb generate') +
-          '\n' +
-          styleText('cyan', '     Or start a stream server with: npx kubb start') +
-          '\n' +
-          styleText('cyan', `  3. Find generated files in: ${outputPath}`) +
-          '\n\n' +
-          styleText('dim', `Using ${packageManager.name} • Kubb v${version}`),
-      )
-    } catch (error) {
-      clack.log.error(styleText('red', 'An error occurred during initialization'))
-      if (error instanceof Error) {
-        clack.log.error(error.message)
-      }
-      process.exit(1)
-    }
-  },
-})
-
-export default command

package/src/commands/mcp.ts

@@ -1,57 +1,12 @@
-import process from 'node:process'
-import { styleText } from 'node:util'
-import type { ArgsDef } from 'citty'
-import { defineCommand, showUsage } from 'citty'
-import { createJiti } from 'jiti'
 import { version } from '../../package.json'
-import { buildTelemetryEvent, sendTelemetry } from '../utils/telemetry.ts'
+import { defineCommand } from '../cli/index.ts'
 
-const jiti = createJiti(import.meta.url, {
-  sourceMaps: true,
-})
-
-const args = {
-  help: {
-    type: 'boolean',
-    description: 'Show help',
-    alias: 'h',
-    default: false,
-  },
-} as const satisfies ArgsDef
-
-const command = defineCommand({
-  meta: {
-    name: 'mcp',
-    description: 'Start the server to enable the MCP client to interact with the LLM.',
-  },
-  args,
-  async run(commandContext) {
-    const { args } = commandContext
-
-    if (args.help) {
-      return showUsage(command)
-    }
+export const command = defineCommand({
+  name: 'mcp',
+  description: 'Start the server to enable the MCP client to interact with the LLM.',
+  async run() {
+    const { runMcp } = await import('../runners/mcp.ts')
 
-    let mod: any
-    try {
-      mod = await jiti.import('@kubb/mcp', { default: true })
-    } catch (_e) {
-      console.error(`Import of '@kubb/mcp' is required to start the MCP server`)
-      process.exit(1)
-    }
-
-    const { run } = mod
-    const hrStart = process.hrtime()
-    try {
-      console.log('⏳ Starting MCP server...')
-      console.warn(styleText('yellow', 'This feature is still under development — use with caution'))
-      run()
-      await sendTelemetry(buildTelemetryEvent({ command: 'mcp', kubbVersion: version, hrStart, status: 'success' }))
-    } catch (error) {
-      await sendTelemetry(buildTelemetryEvent({ command: 'mcp', kubbVersion: version, hrStart, status: 'failed' }))
-      console.error((error as Error)?.message)
-    }
+    await runMcp({ version })
   },
 })
-
-export default command

package/src/commands/validate.ts

@@ -1,66 +1,15 @@
-import process from 'node:process'
-import type { ArgsDef } from 'citty'
-import { defineCommand, showUsage } from 'citty'
-import { createJiti } from 'jiti'
 import { version } from '../../package.json'
-import { buildTelemetryEvent, sendTelemetry } from '../utils/telemetry.ts'
+import { defineCommand } from '../cli/index.ts'
 
-const jiti = createJiti(import.meta.url, {
-  sourceMaps: true,
-})
-
-const args = {
-  input: {
-    type: 'string',
-    description: 'Path to Swagger/OpenAPI file',
-    alias: 'i',
-  },
-  help: {
-    type: 'boolean',
-    description: 'Show help',
-    alias: 'h',
-    default: false,
+export const command = defineCommand({
+  name: 'validate',
+  description: 'Validate a Swagger/OpenAPI file',
+  options: {
+    input: { type: 'string', description: 'Path to Swagger/OpenAPI file', short: 'i', required: true },
   },
-} as const satisfies ArgsDef
+  async run({ values }) {
+    const { runValidate } = await import('../runners/validate.ts')
 
-const command = defineCommand({
-  meta: {
-    name: 'validate',
-    description: 'Validate a Swagger/OpenAPI file',
-  },
-  args,
-  async run(commandContext) {
-    const { args } = commandContext
-
-    if (args.help) {
-      return showUsage(command)
-    }
-
-    if (args.input) {
-      let mod: any
-      try {
-        mod = await jiti.import('@kubb/oas', { default: true })
-      } catch (_e) {
-        console.error(`Import of '@kubb/oas' is required to do validation`)
-        process.exit(1)
-      }
-
-      const { parse } = mod
-      const hrStart = process.hrtime()
-      try {
-        const oas = await parse(args.input)
-        await oas.validate()
-
-        await sendTelemetry(buildTelemetryEvent({ command: 'validate', kubbVersion: version, hrStart, status: 'success' }))
-        console.log('✅ Validation success')
-      } catch (error) {
-        await sendTelemetry(buildTelemetryEvent({ command: 'validate', kubbVersion: version, hrStart, status: 'failed' }))
-        console.error('❌ Validation failed')
-        console.log((error as Error)?.message)
-        process.exit(1)
-      }
-    }
+    await runValidate({ input: values.input, version })
   },
 })
-
-export default command

package/src/constants.ts

@@ -0,0 +1,77 @@
+/** NPM registry endpoint used to check for @kubb/cli updates. */
+export const KUBB_NPM_PACKAGE_URL = 'https://registry.npmjs.org/@kubb/cli/latest' as const
+
+/** OpenTelemetry ingestion endpoint for anonymous usage telemetry. */
+export const OTLP_ENDPOINT = 'https://otlp.kubb.dev' as const
+
+/** Horizontal rule rendered above/below the plain-logger generation summary. */
+export const SUMMARY_SEPARATOR = '─'.repeat(27)
+
+/** Maximum number of █ characters in a plugin timing bar. */
+export const SUMMARY_MAX_BAR_LENGTH = 10 as const
+
+/** Divides elapsed milliseconds into bar-length units (1 block per 100 ms). */
+export const SUMMARY_TIME_SCALE_DIVISOR = 100 as const
+
+/** Glob pattern for paths the file watcher ignores. */
+export const WATCHER_IGNORED_PATHS = '**/{.git,node_modules}/**' as const
+
+/** Default runtime values for the `agent start` command. */
+export const agentDefaults = {
+  port: '3000',
+  host: 'localhost',
+  configFile: 'kubb.config.ts',
+  retryTimeout: '30000',
+  studioUrl: 'https://studio.kubb.dev',
+  /** Relative path from the @kubb/agent package root to the server entry. */
+  serverEntryPath: '.output/server/index.mjs',
+} as const
+
+/** Default values used during interactive `init` scaffolding. */
+export const initDefaults = {
+  inputPath: './openapi.yaml',
+  outputPath: './src/gen',
+  plugins: ['plugin-oas', 'plugin-ts'],
+} as const
+
+/**
+ * Maps each plugin value to the default config snippet inserted by `init`.
+ * The `satisfies` constraint ensures all values remain plain strings while
+ * `as const` keeps the object deeply immutable.
+ */
+export const pluginDefaultConfigs = {
+  'plugin-oas': 'pluginOas()',
+  'plugin-ts': `pluginTs({
+      output: { path: 'models' },
+    })`,
+  'plugin-client': `pluginClient({
+      output: { path: 'clients' },
+    })`,
+  'plugin-react-query': `pluginReactQuery({
+      output: { path: 'hooks' },
+    })`,
+  'plugin-solid-query': `pluginSolidQuery({
+      output: { path: 'hooks' },
+    })`,
+  'plugin-svelte-query': `pluginSvelteQuery({
+      output: { path: 'hooks' },
+    })`,
+  'plugin-vue-query': `pluginVueQuery({
+      output: { path: 'hooks' },
+    })`,
+  'plugin-swr': `pluginSwr({
+      output: { path: 'hooks' },
+    })`,
+  'plugin-zod': `pluginZod({
+      output: { path: 'zod' },
+    })`,
+  'plugin-faker': `pluginFaker({
+      output: { path: 'mocks' },
+    })`,
+  'plugin-msw': `pluginMsw({
+      output: { path: 'msw' },
+    })`,
+} as const satisfies Record<string, string>
+
+/** Color palette used by randomCliColor() for deterministic plugin name coloring. */
+export const randomColors = ['black', 'red', 'green', 'yellow', 'blue', 'white', 'magenta', 'cyan', 'gray', 'blue'] as const

package/src/index.ts

@@ -1,51 +1,45 @@
 import { styleText } from 'node:util'
-import { defineCommand, runCommand, runMain } from 'citty'
 import { version } from '../package.json'
+import { createCLI } from './cli/index.ts'
 import { isTelemetryDisabled } from './utils/telemetry.ts'
 
-const main = defineCommand({
-  meta: {
-    name: 'kubb',
-    version,
-    description: 'Kubb generation',
-  },
-  args: {
-    version: {
-      type: 'boolean',
-      alias: 'v',
-      description: 'Show version number',
-    },
-  },
-  async setup({ rawArgs, args }) {
-    if (args.version) {
-      console.log(version)
-      process.exit(0)
-    }
-
-    if (!isTelemetryDisabled()) {
-      console.log(
-        `${styleText('yellow', 'Notice:')} Kubb collects anonymous telemetry data to help improve the tool. No personal data or file contents are collected. \nTo disable, set ${styleText('cyan', 'KUBB_DISABLE_TELEMETRY=1')}.\n`,
-      )
-    }
+const cli = createCLI()
 
-    if (!['generate', 'validate', 'mcp', 'agent', 'init'].includes(rawArgs[0] as string)) {
-      // generate is not being used
-      const generateCommand = await import('./commands/generate.ts').then((r) => r.default)
+function shouldShowTelemetryNotice(argv: string[]): boolean {
+  if (isTelemetryDisabled()) {
+    return false
+  }
+  // Skip when the user is just asking for help or version info
+  const quietFlags = new Set(['--help', '-h', '--version', '-v'])
+  if (argv.some((arg) => quietFlags.has(arg))) {
+    return false
+  }
+  // Skip in non-interactive / scripting contexts
+  if (!process.stdout.isTTY) {
+    return false
+  }
+  return true
+}
 
-      await runCommand(generateCommand, { rawArgs })
+export async function run(argv: string[] = process.argv): Promise<void> {
+  if (shouldShowTelemetryNotice(argv)) {
+    console.log(
+      `${styleText('yellow', 'Notice:')} Kubb collects anonymous telemetry data to help improve the tool. No personal data or file contents are collected. \nTo disable, set ${styleText('cyan', 'KUBB_DISABLE_TELEMETRY=1')}.\n`,
+    )
+  }
 
-      process.exit(0)
-    }
-  },
-  subCommands: {
-    generate: () => import('./commands/generate.ts').then((r) => r.default),
-    validate: () => import('./commands/validate.ts').then((r) => r.default),
-    mcp: () => import('./commands/mcp.ts').then((r) => r.default),
-    agent: () => import('./commands/agent.ts').then((r) => r.default),
-    init: () => import('./commands/init.ts').then((r) => r.default),
-  },
-})
+  const [{ command: generateCommand }, { command: validateCommand }, { command: mcpCommand }, { command: agentCommand }, { command: initCommand }] =
+    await Promise.all([
+      import('./commands/generate.ts'),
+      import('./commands/validate.ts'),
+      import('./commands/mcp.ts'),
+      import('./commands/agent.ts'),
+      import('./commands/init.ts'),
+    ])
 
-export async function run(_argv?: string[]): Promise<void> {
-  await runMain(main)
+  await cli.run([generateCommand, validateCommand, mcpCommand, agentCommand, initCommand], argv, {
+    programName: 'kubb',
+    defaultCommandName: 'generate',
+    version,
+  })
 }