@kubb/cli 5.0.0-alpha.5 → 5.0.0-alpha.50

package/package.json

@@ -1,41 +1,31 @@
 {
   "name": "@kubb/cli",
-  "version": "5.0.0-alpha.5",
+  "version": "5.0.0-alpha.50",
   "description": "Command-line interface for Kubb, enabling easy generation of TypeScript, React-Query, Zod, and other code from OpenAPI specifications.",
   "keywords": [
     "cli",
+    "code-generator",
+    "codegen",
     "command-line",
     "command-line-tool",
-    "terminal",
-    "typescript",
-    "openapi",
-    "swagger",
+    "kubb",
     "oas",
-    "code-generator",
-    "codegen",
-    "sdk-generator",
+    "openapi",
     "plugins",
-    "kubb"
+    "sdk-generator",
+    "swagger",
+    "terminal",
+    "typescript"
   ],
+  "license": "MIT",
+  "author": "stijnvanhulle",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kubb-labs/kubb.git",
     "directory": "packages/cli"
   },
-  "license": "MIT",
-  "author": "stijnvanhulle",
-  "sideEffects": false,
-  "type": "module",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./package.json": "./package.json"
-  },
-  "types": "./dist/index.d.ts",
   "bin": {
-    "kubb": "bin/kubb.cjs"
+    "kubb": "bin/kubb.js"
   },
   "files": [
     "src",
@@ -45,6 +35,38 @@
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "chokidar": "^5.0.0",
+    "cosmiconfig": "^9.0.1",
+    "jiti": "^2.6.1",
+    "tinyexec": "^1.1.1",
+    "@kubb/adapter-oas": "5.0.0-alpha.50",
+    "@kubb/core": "5.0.0-alpha.50"
+  },
+  "devDependencies": {
+    "@internals/utils": "0.0.0"
+  },
+  "optionalDependencies": {
+    "@kubb/agent": "5.0.0-alpha.50",
+    "@kubb/mcp": "5.0.0-alpha.50"
+  },
   "size-limit": [
     {
       "path": "./dist/*.js",
@@ -52,36 +74,15 @@
       "gzip": true
     }
   ],
-  "dependencies": {
-    "@clack/prompts": "^1.1.0",
-    "chokidar": "^5.0.0",
-    "cosmiconfig": "^9.0.1",
-    "jiti": "2.5.1",
-    "tinyexec": "^1.0.4",
-    "@kubb/core": "5.0.0-alpha.5"
-  },
-  "devDependencies": {
-    "source-map-support": "^0.5.21",
-    "@internals/utils": "0.0.0",
-    "@kubb/agent": "5.0.0-alpha.5",
-    "@kubb/mcp": "5.0.0-alpha.5",
-    "@kubb/oas": "5.0.0-alpha.5"
-  },
+  "preferGlobal": true,
   "engines": {
     "node": ">=22"
   },
-  "preferGlobal": true,
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
   "scripts": {
     "build": "tsdown && size-limit",
     "clean": "npx rimraf ./dist",
-    "lint": "bun biome lint .",
-    "lint:fix": "bun biome lint --fix --unsafe .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
     "start": "tsdown --watch",

package/src/commands/agent/start.ts

@@ -6,15 +6,31 @@ 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 },
+    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 },
+    'allow-all': {
+      type: 'boolean',
+      description: 'Grant all permissions (implies --allow-write).',
+      default: false,
+    },
   },
   async run({ values }) {
     const { runAgentStart } = await import('../../runners/agent.ts')

package/src/commands/generate.ts

@@ -5,7 +5,11 @@ export const command = defineCommand({
   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' },
+    config: {
+      type: 'string',
+      description: 'Path to the Kubb config',
+      short: 'c',
+    },
     logLevel: {
       type: 'string',
       description: 'Info, silent, verbose or debug',
@@ -14,15 +18,40 @@ export const command = defineCommand({
       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 },
+    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 })
+    await runGenerateCommand({
+      input: positionals[0],
+      configPath: values.config,
+      logLevel,
+      watch: values.watch,
+    })
   },
 })

package/src/commands/init.ts

@@ -5,7 +5,12 @@ 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 },
+    yes: {
+      type: 'boolean',
+      description: 'Skip prompts and use default options',
+      short: 'y',
+      default: false,
+    },
   },
   async run({ values }) {
     const { runInit } = await import('../runners/init.ts')

package/src/commands/validate.ts

@@ -5,7 +5,12 @@ 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 },
+    input: {
+      type: 'string',
+      description: 'Path to Swagger/OpenAPI file',
+      short: 'i',
+      required: true,
+    },
   },
   async run({ values }) {
     const { runValidate } = await import('../runners/validate.ts')

package/src/constants.ts

@@ -1,33 +1,85 @@
-/** NPM registry endpoint used to check for @kubb/cli updates. */
+/**
+ * Default filename for the Kubb configuration file.
+ *
+ * Used by the `init` command when scaffolding new projects and by the `agent` default config.
+ */
+export const KUBB_CONFIG_FILENAME = 'kubb.config.ts' as const
+
+/**
+ * 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. */
+/**
+ * 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. */
+/**
+ * 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. */
+/**
+ * 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). */
+/**
+ * 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. */
+/**
+ * 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. */
+/**
+ * Flags that short-circuit execution (help/version) — no telemetry notice is shown.
+ */
+export const QUITE_FLAGS = new Set(['--help', '-h', '--version', '-v'] as const)
+
+/**
+ * Flags accepted by the `generate` command.
+ */
+export const GENERATE_FLAGS = new Set(['--config', '-c', '--log-level', '-l', '--watch', '-w', '--debug', '-d', '--verbose', '-v', '--silent', '-s'] as const)
+
+/**
+ * Flags accepted by the `validate` command.
+ */
+export const VALIDATE_FLAGS = new Set(['--input', '-i'] as const)
+
+/**
+ * Flags accepted by the `init` command.
+ */
+export const INIT_FLAGS = new Set(['--yes', '-y'] as const)
+
+/**
+ * Flags accepted by the `agent start` command.
+ */
+export const AGENT_START_FLAGS = new Set(['--config', '-c', '--port', '-p', '--host', '--allow-write', '--allow-all'] as const)
+
+/**
+ * All known CLI flags across every command.
+ */
+export const ARGS = new Set([...QUITE_FLAGS, ...GENERATE_FLAGS, ...VALIDATE_FLAGS, ...INIT_FLAGS, ...AGENT_START_FLAGS] as const)
+
 export const agentDefaults = {
   port: '3000',
   host: 'localhost',
-  configFile: 'kubb.config.ts',
+  configFile: KUBB_CONFIG_FILENAME,
   retryTimeout: '30000',
   studioUrl: 'https://studio.kubb.dev',
-  /** Relative path from the @kubb/agent package root to the server entry. */
+  /**
+   * 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. */
+/**
+ * Default values used during interactive `init` scaffolding.
+ */
 export const initDefaults = {
   inputPath: './openapi.yaml',
   outputPath: './src/gen',
@@ -73,4 +125,6 @@ export const pluginDefaultConfigs = {
     })`,
 } as const satisfies Record<string, string>
 
-/** Color palette used by randomCliColor() for deterministic plugin name coloring. */
+/**
+ * Color palette used by randomCliColor() for deterministic plugin name coloring.
+ */

package/src/index.ts

@@ -1,17 +1,18 @@
 import { styleText } from 'node:util'
 import { createCLI } from '@internals/utils'
 import { version } from '../package.json'
+import { QUITE_FLAGS } from './constants.ts'
+import { isFlag } from './utils/flags.ts'
 import { isTelemetryDisabled } from './utils/telemetry.ts'
 
 const cli = createCLI()
 
-function shouldShowTelemetryNotice(argv: string[]): boolean {
+function shouldShowTelemetryNotice(argv: Array<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))) {
+  if (argv.some((arg) => isFlag(QUITE_FLAGS, arg))) {
     return false
   }
   // Skip in non-interactive / scripting contexts
@@ -21,21 +22,18 @@ function shouldShowTelemetryNotice(argv: string[]): boolean {
   return true
 }
 
-export async function run(argv: string[] = process.argv): Promise<void> {
+export async function run(argv: Array<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`,
     )
   }
 
-  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'),
-    ])
+  const { command: generateCommand } = await import('./commands/generate.ts')
+  const { command: validateCommand } = await import('./commands/validate.ts')
+  const { command: mcpCommand } = await import('./commands/mcp.ts')
+  const { command: agentCommand } = await import('./commands/agent.ts')
+  const { command: initCommand } = await import('./commands/init.ts')
 
   await cli.run([generateCommand, validateCommand, mcpCommand, agentCommand, initCommand], argv, {
     programName: 'kubb',

package/src/loggers/clackLogger.ts

@@ -2,9 +2,8 @@ import { relative } from 'node:path'
 import process from 'node:process'
 import { styleText } from 'node:util'
 import * as clack from '@clack/prompts'
-import { formatMs, formatMsWithColor, toCause } from '@internals/utils'
+import { formatMs, formatMsWithColor, getIntro, toCause } from '@internals/utils'
 import { defineLogger, logLevel as logLevelMap } from '@kubb/core'
-import { getIntro } from '../utils/getIntro.ts'
 import { getSummary } from '../utils/getSummary.ts'
 import { runHook } from '../utils/runHook.ts'
 import { ClackWritable } from '../utils/Writables.ts'
@@ -74,7 +73,7 @@ export const clackLogger = defineLogger({
       state.isSpinning = false
     }
 
-    context.on('info', (message, info = '') => {
+    context.on('kubb:info', (message, info = '') => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -88,7 +87,7 @@ export const clackLogger = defineLogger({
       }
     })
 
-    context.on('success', (message, info = '') => {
+    context.on('kubb:success', (message, info = '') => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -102,7 +101,7 @@ export const clackLogger = defineLogger({
       }
     })
 
-    context.on('warn', (message, info) => {
+    context.on('kubb:warn', (message, info) => {
       if (logLevel < logLevelMap.warn) {
         return
       }
@@ -114,7 +113,7 @@ export const clackLogger = defineLogger({
       clack.log.warn(text)
     })
 
-    context.on('error', (error) => {
+    context.on('kubb:error', (error) => {
       const caused = toCause(error)
 
       const text = [styleText('red', '✗'), error.message].join(' ')
@@ -143,33 +142,38 @@ export const clackLogger = defineLogger({
       }
     })
 
-    context.on('version:new', (version, latestVersion) => {
+    context.on('kubb:version:new', (version, latestVersion) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
 
-      clack.box(
-        `\`v${version}\` → \`v${latestVersion}\`
+      try {
+        clack.box(
+          `\`v${version}\` → \`v${latestVersion}\`
 Run \`npm install -g @kubb/cli\` to update`,
-        'Update available for `Kubb`',
-        {
-          width: 'auto',
-          formatBorder: (s: string) => styleText('yellow', s),
-          rounded: true,
-          withGuide: false,
-          contentAlign: 'center',
-          titleAlign: 'center',
-        },
-      )
+          'Update available for `Kubb`',
+          {
+            width: 'auto',
+            formatBorder: (s: string) => styleText('yellow', s),
+            rounded: true,
+            withGuide: false,
+            contentAlign: 'center',
+            titleAlign: 'center',
+          },
+        )
+      } catch {
+        console.log(`Update available for Kubb: v${version} → v${latestVersion}`)
+        console.log('Run `npm install -g @kubb/cli` to update')
+      }
     })
 
-    context.on('lifecycle:start', async (version) => {
+    context.on('kubb:lifecycle:start', async (version) => {
       console.log(`\n${getIntro({ title: 'The ultimate toolkit for working with APIs', description: 'Ready to start', version, areEyesOpen: true })}\n`)
 
       reset()
     })
 
-    context.on('config:start', () => {
+    context.on('kubb:config:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -180,7 +184,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       startSpinner(getMessage('Configuration loading'))
     })
 
-    context.on('config:end', (_configs) => {
+    context.on('kubb:config:end', (_configs) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -190,7 +194,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.outro(text)
     })
 
-    context.on('generation:start', (config) => {
+    context.on('kubb:generation:start', (config) => {
       reset()
 
       // Initialize progress tracking for this generation
@@ -201,7 +205,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.intro(text)
     })
 
-    context.on('plugin:start', (plugin) => {
+    context.on('kubb:plugin:start', (plugin) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -223,7 +227,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       state.activeProgress.set(plugin.name, { progressBar, interval })
     })
 
-    context.on('plugin:end', (plugin, { duration, success }) => {
+    context.on('kubb:plugin:end', (plugin, { duration, success }) => {
       stopSpinner()
 
       const active = state.activeProgress.get(plugin.name)
@@ -254,7 +258,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       showProgressStep()
     })
 
-    context.on('files:processing:start', (files) => {
+    context.on('kubb:files:processing:start', (files) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -271,12 +275,12 @@ Run \`npm install -g @kubb/cli\` to update`,
         size: 30,
       })
 
-      context.emit('info', text)
+      context.emit('kubb:info', text)
       progressBar.start(getMessage(text))
       state.activeProgress.set('files', { progressBar })
     })
 
-    context.on('file:processing:update', ({ file, config }) => {
+    context.on('kubb:file:processing:update', ({ file, config }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -294,7 +298,7 @@ Run \`npm install -g @kubb/cli\` to update`,
 
       active.progressBar.advance(undefined, text)
     })
-    context.on('files:processing:end', () => {
+    context.on('kubb:files:processing:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -315,13 +319,13 @@ Run \`npm install -g @kubb/cli\` to update`,
       showProgressStep()
     })
 
-    context.on('generation:end', (config) => {
+    context.on('kubb:generation:end', (config) => {
       const text = getMessage(config.name ? `Generation completed for ${styleText('dim', config.name)}` : 'Generation completed')
 
       clack.outro(text)
     })
 
-    context.on('format:start', () => {
+    context.on('kubb:format:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -331,7 +335,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.intro(text)
     })
 
-    context.on('format:end', () => {
+    context.on('kubb:format:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -341,7 +345,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.outro(text)
     })
 
-    context.on('lint:start', () => {
+    context.on('kubb:lint:start', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -351,7 +355,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.intro(text)
     })
 
-    context.on('lint:end', () => {
+    context.on('kubb:lint:end', () => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -361,7 +365,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.outro(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 ${styleText('dim', commandWithArgs)} started`)
 
@@ -408,7 +412,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       })
     })
 
-    context.on('hook:end', ({ command, args }) => {
+    context.on('kubb:hook:end', ({ command, args }) => {
       if (logLevel <= logLevelMap.silent) {
         return
       }
@@ -419,7 +423,7 @@ Run \`npm install -g @kubb/cli\` to update`,
       clack.outro(text)
     })
 
-    context.on('generation:summary', (config, { pluginTimings, failedPlugins, filesCreated, status, hrStart }) => {
+    context.on('kubb:generation:summary', (config, { pluginTimings, failedPlugins, filesCreated, status, hrStart }) => {
       const summary = getSummary({
         failedPlugins,
         filesCreated,
@@ -434,17 +438,21 @@ Run \`npm install -g @kubb/cli\` to update`,
       summary.push('\n')
 
       const borderColor = status === 'success' ? 'green' : 'red'
-      clack.box(summary.join('\n'), getMessage(title), {
-        width: 'auto',
-        formatBorder: (s: string) => styleText(borderColor, s),
-        rounded: true,
-        withGuide: false,
-        contentAlign: 'left',
-        titleAlign: 'center',
-      })
+      try {
+        clack.box(summary.join('\n'), getMessage(title), {
+          width: 'auto',
+          formatBorder: (s: string) => styleText(borderColor, s),
+          rounded: true,
+          withGuide: false,
+          contentAlign: 'left',
+          titleAlign: 'center',
+        })
+      } catch {
+        console.log(summary.join('\n'))
+      }
     })
 
-    context.on('lifecycle:end', () => {
+    context.on('kubb:lifecycle:end', () => {
       reset()
     })
   },