feat: support createCommandContext exporting

packages/definition/src/index.test.ts

@@ -28,12 +28,6 @@ describe('@gunshi/definition', () => {
       args: command.args,
       values: { foo: 'bar' },
       explicit: { foo: true },
-      positionals: [],
-      rest: [],
-      argv: [],
-      tokens: [],
-      omitted: false,
-      callMode: 'entry',
       command,
       cliOptions: {
         cwd: '/path/to/cmd1',
@@ -66,12 +60,6 @@ describe('@gunshi/definition', () => {
       args: command.args,
       explicit: { foo: true },
       values: { foo: 'bar' },
-      positionals: [],
-      rest: [],
-      argv: [],
-      tokens: [],
-      omitted: false,
-      callMode: 'entry',
       command,
       cliOptions: {
         cwd: '/path/to/cmd1',

packages/gunshi/src/context.test.ts

@@ -60,13 +60,10 @@ test('basic', async () => {
     explicit: { foo: true, bar: true, baz: false, qux: false },
     values: { foo: 'foo', bar: true, baz: 42 },
     positionals: ['bar'],
-    rest: [],
     argv: ['bar'],
-    tokens: [], // dummy, due to test
     omitted: true,
     callMode: 'entry',
     command,
-    extensions: {},
     cliOptions: {
       cwd: '/path/to/cmd1',
       description: 'this is command line',
@@ -139,18 +136,10 @@ test('default', async () => {
     run: vi.fn()
   }
   const ctx = await createCommandContext({
-    args: {},
-    explicit: {},
     values: { foo: 'foo', bar: true, baz: 42 },
     positionals: ['bar'],
-    rest: [],
     argv: ['bar'],
-    tokens: [], // dummy, due to test
-    command,
-    extensions: {},
-    omitted: false,
-    callMode: 'entry',
-    cliOptions: {}
+    command
   })
 
   /**
@@ -290,18 +279,8 @@ describe('plugin extensions', () => {
       run: async _ctx => 'done'
     }
     const ctx = await createCommandContext({
-      args: {},
-      explicit: {},
-      values: {},
-      positionals: [],
-      rest: [],
-      argv: [],
-      tokens: [],
       command,
-      extensions,
-      omitted: false,
-      callMode: 'entry',
-      cliOptions: {}
+      extensions
     })
 
     expect(ctx.extensions).toEqual(
@@ -346,22 +325,12 @@ describe('plugin extensions', () => {
     }
 
     await createCommandContext({
-      args: {},
-      explicit: {},
-      values: {},
-      positionals: [],
-      rest: [],
-      argv: [],
-      tokens: [],
       command,
       extensions: {
         ext1,
         ext2,
         ext3
-      },
-      omitted: false,
-      callMode: 'entry',
-      cliOptions: {}
+      }
     })
 
     // extensions should be processed in the order they appear in the object

packages/gunshi/src/context.ts

@@ -51,7 +51,7 @@ export type ExtractExtensions<E extends Record<string, CommandContextExtension>>
 /**
  * Parameters of {@link createCommandContext}
  */
-interface CommandContextParams<
+export interface CommandContextParams<
   G extends GunshiParams | { args: Args } | { extensions: ExtendContext },
   V extends ArgValues<ExtractArgs<G>>,
   C extends Command<G> | LazyCommand<G> = Command<G>,
@@ -60,84 +60,84 @@ interface CommandContextParams<
   /**
    * An arguments of target command
    */
-  args: ExtractArgs<G>
+  args?: ExtractArgs<G>
 
   /**
    * Explicitly provided arguments
    */
-  explicit: ExtractArgExplicitlyProvided<G>
+  explicit?: ExtractArgExplicitlyProvided<G>
 
   /**
    * A values of target command
    */
-  values: V
+  values?: V
   /**
    * A positionals arguments, which passed to the target command
    */
-  positionals: string[]
+  positionals?: string[]
   /**
    * A rest arguments, which passed to the target command
    */
-  rest: string[]
+  rest?: string[]
   /**
    * Original command line arguments
    */
-  argv: string[]
+  argv?: string[]
   /**
    * Argument tokens that are parsed by the `parseArgs` function
    */
-  tokens: ArgToken[]
+  tokens?: ArgToken[]
   /**
    * Whether the command is omitted
    */
-  omitted: boolean
+  omitted?: boolean
   /**
    * Command call mode.
    */
-  callMode: CommandCallMode
+  callMode?: CommandCallMode
   /**
    * A target command
    */
-  command: C
+  command?: C
   /**
    * Plugin extensions to apply as the command context extension.
    */
   extensions?: E
   /**
    * A command options, which is spicialized from `cli` function
    */
-  cliOptions: CliOptions<G>
+  cliOptions?: CliOptions<G>
   /**
    * Validation error from argument parsing.
    */
   validationError?: AggregateError
 }
 
 /**
- * Create a {@link CommandContext | command context}
+ * Create a command context.
  *
- * @param param - A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
- * @returns A {@link CommandContext | command context}, which is readonly
+ * @param param - A {@link CommandContextParams | parameters} to create a command context.
+ * @returns A {@link CommandContext | command context}, which is readonly.
  */
 export async function createCommandContext<
   G extends GunshiParamsConstraint = DefaultGunshiParams,
   V extends ArgValues<ExtractArgs<G>> = ArgValues<ExtractArgs<G>>,
   C extends Command<G> | LazyCommand<G> = Command<G>,
   E extends Record<string, CommandContextExtension> = {}
 >({
-  args,
-  explicit,
-  values,
-  positionals,
-  rest,
-  argv,
-  tokens,
-  command,
+  args = {} as ExtractArgs<G>,
+  explicit = {} as ExtractArgExplicitlyProvided<G>,
+  values = {} as V,
+  positionals = [],
+  rest = [],
+  argv = [],
+  tokens = [],
+  command = {} as C,
   extensions = {} as E,
-  cliOptions,
+  cliOptions = {} as CliOptions<G>,
   callMode = 'entry',
   omitted = false,
-  validationError
+  validationError = undefined
 }: CommandContextParams<G, V, C, E>): Promise<
   {} extends ExtractExtensions<E>
     ? Readonly<CommandContext<G>>

packages/gunshi/src/definition.ts

@@ -49,6 +49,8 @@ import type {
   Prettify
 } from './types.ts'
 
+export { createCommandContext } from './context.ts'
+
 export type {
   Args,
   ArgSchema,
@@ -62,6 +64,8 @@ export type {
   LazyCommand
 } from './types.ts'
 
+export type { CommandContextParams } from './context.ts'
+
 /**
  * Infer command properties excluding for {@link define} function
  *

packages/gunshi/src/index.ts

@@ -4,8 +4,11 @@
  * This entry point exports the bellow APIs and types:
  * - `cli`: The main CLI function to run the command, included `global options` and `usage renderer` built-in plugins.
  * - `define`: A function to define a command.
+ * - `defineWithTypes`: A function to define a command with specific type parameters.
  * - `lazy`: A function to lazily load a command.
+ * - `lazyWithTypes`: A function to lazily load a command with specific type parameters.
  * - `plugin`: A function to create a plugin.
+ * - `createCommandContext`: A function to create a command context, mainly for testing purposes.
  * - `args-tokens` utilities, `parseArgs` and `resolveArgs` for parsing command line arguments.
  * - Some basic type definitions, such as `CommandContext`, `Plugin`, `PluginContext`, etc.
  *
@@ -26,9 +29,11 @@ export { DefaultTranslation } from '@gunshi/plugin-i18n' // TODO(kazupon): remov
 export { parseArgs, resolveArgs } from 'args-tokens'
 export * from './cli.ts'
 export { ANONYMOUS_COMMAND_NAME } from './constants.ts'
+export { createCommandContext } from './context.ts'
 export { define, defineWithTypes, lazy, lazyWithTypes } from './definition.ts'
 export { plugin } from './plugin/core.ts'
 
+export type { CommandContextParams } from './context.ts'
 export type { PluginContext } from './plugin/context.ts'
 export type {
   OnPluginExtension,

packages/gunshi/src/plugin.ts

@@ -27,6 +27,7 @@ export { ANONYMOUS_COMMAND_NAME, CLI_OPTIONS_DEFAULT } from './constants.ts'
 export { createCommandContext } from './context.ts'
 export { plugin } from './plugin/core.ts'
 
+export type { CommandContextParams } from './context.ts'
 export type { PluginContext } from './plugin/context.ts'
 export type {
   OnPluginExtension,

packages/gunshi/src/plugin/core.test.ts

@@ -438,21 +438,12 @@ describe('Plugin Extensions Integration', () => {
 
     // create command context directly
     const ctx = await createCommandContext({
-      args: {} as Args,
-      explicit: {},
       values: { user: 'admin', 'log-level': 'debug' },
-      positionals: [],
-      rest: [],
-      argv: [],
-      tokens: [],
       command: multiCommand,
-      extensions: { auth: authPlugin.extension, logger: loggerPlugin.extension },
-      omitted: false,
-      callMode: 'entry',
-      cliOptions: {}
+      extensions: { auth: authPlugin.extension, logger: loggerPlugin.extension }
     })
 
-    const result = await multiCommand.run!(ctx)
+    const result = await multiCommand.run(ctx)
     expect(result).toBe('[debug] User admin executed command; [debug] Admin access granted')
   })
 
@@ -477,17 +468,10 @@ describe('Plugin Extensions Integration', () => {
       },
       explicit: { msg: false, upper: true },
       values: { msg: 'hello', upper: true },
-      positionals: [],
-      rest: [],
-      argv: [],
-      tokens: [],
-      command: regularCommand,
-      omitted: false,
-      callMode: 'entry',
-      cliOptions: {}
+      command: regularCommand
     })
 
-    const result = await regularCommand.run!(ctx)
+    const result = await regularCommand.run(ctx)
     expect(result).toBe('HELLO')
   })
 
@@ -523,22 +507,12 @@ describe('Plugin Extensions Integration', () => {
     })
 
     const ctx = await createCommandContext({
-      args: {} as Args,
-      explicit: {},
-      values: {},
-      positionals: [],
-      rest: [],
-      argv: [],
-      tokens: [],
       command: contextCommand,
       extensions: {
         ctx: contextPlugin.extension
-      },
-      omitted: false,
-      callMode: 'entry',
-      cliOptions: {}
+      }
     })
-    await contextCommand.run!(ctx)
+    await contextCommand.run(ctx)
 
     expect(capturedContext).toHaveBeenCalledWith({
       name: 'ctx-test',

packages/gunshi/src/types.ts

@@ -345,6 +345,9 @@ export interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiPara
 
 /**
  * Command call mode.
+ *
+ * - `entry`: The command is executed as an entry command.
+ * - `subCommand`: The command is executed as a sub-command.
  */
 export type CommandCallMode = 'entry' | 'subCommand' | 'unexpected'
 
@@ -426,6 +429,7 @@ export interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshi
   toKebab?: boolean
   /**
    * Output a message.
+   *
    * If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
    *
    * @param message - an output message, @see {@linkcode console.log}