feat: support plugins option on cli

package.json

@@ -46,7 +46,7 @@
     "test": "vitest --typecheck run",
     "typecheck": "pnpm run --stream --color \"/^typecheck:/\"",
     "typecheck:deno": "pnpm -r --if-present typecheck:deno",
-    "typecheck:tsc": "tsc --noEmit --diagnostics"
+    "typecheck:tsc": "tsgo --noEmit --diagnostics"
   },
   "devDependencies": {
     "@eslint/compat": "^1.2.9",

packages/gunshi/src/cli.test.ts

@@ -3,6 +3,7 @@ import { z } from 'zod/v4-mini'
 import { defineMockLog } from '../test/utils.ts'
 import { cli } from './cli.ts'
 import { define, lazy } from './definition.ts'
+import { plugin } from './plugin.ts'
 import { renderValidationErrors } from './renderer.ts'
 
 import type { Args } from 'args-tokens'
@@ -1152,6 +1153,45 @@ describe('command decorators', () => {
   })
 })
 
+test('plugins option', async () => {
+  const msgs: string[] = []
+  vi.spyOn(console, 'log').mockImplementation(msg => msgs.push(msg))
+
+  function logger() {
+    return plugin({
+      name: 'logger',
+      setup: ctx => {
+        ctx.decorateCommand(baseRunner => ctx => {
+          console.log(`before command: ${ctx.name}`)
+          const ret = baseRunner(ctx)
+          if (typeof ret === 'string') {
+            console.log(`command output: ${ret}`)
+          }
+          console.log(`after command: ${ctx.name}`)
+          return ret
+        })
+      }
+    })
+  }
+
+  const command = {
+    name: 'test',
+    run: ctx => {
+      return `executed ${ctx.name}`
+    }
+  } satisfies Command<GunshiParams>
+
+  await cli([], command, {
+    plugins: [logger()]
+  })
+
+  expect(msgs).toEqual([
+    'before command: test',
+    'command output: executed test',
+    'after command: test'
+  ])
+})
+
 describe('edge cases', () => {
   test(`'description' option`, async () => {
     const command = define({

packages/gunshi/src/cli.ts

@@ -54,7 +54,7 @@ export async function cli<G extends GunshiParams = DefaultGunshiParams>(
     completion(),
     dryRun()
   ]
-  const plugins = await applyPlugins(pluginContext, builtInPlugins)
+  const plugins = await applyPlugins(pluginContext, [...builtInPlugins, ...(options.plugins || [])])
 
   const cliOptions = normalizeCliOptions(options, entry, decorators)
 

packages/gunshi/src/constants.ts

@@ -66,7 +66,8 @@ export const COMMAND_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams> = {
   renderHeader: undefined,
   renderUsage: undefined,
   renderValidationErrors: undefined,
-  translationAdapterFactory: undefined
+  translationAdapterFactory: undefined,
+  plugins: undefined
 }
 
 export const COMMAND_BUILTIN_RESOURCE_KEYS = [

packages/gunshi/src/types.ts

@@ -3,9 +3,10 @@
  * @license MIT
  */
 
-import type { Args, ArgToken, ArgValues } from 'args-tokens'
-
 import { ARG_PREFIX, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX } from './constants.ts'
+import { Plugin } from './plugin.ts'
+
+import type { Args, ArgToken, ArgValues } from 'args-tokens'
 
 export type Awaitable<T> = T | Promise<T>
 
@@ -254,6 +255,10 @@ export interface CliOptions<G extends GunshiParams<any> = DefaultGunshiParams> {
    * Translation adapter factory.
    */
   translationAdapterFactory?: TranslationAdapterFactory
+  /**
+   * User plugins.
+   */
+  plugins?: Plugin[]
 }
 
 /**