@gunshi/docs 0.27.6 → 0.28.0

package/README.md

@@ -33,6 +33,7 @@ Robust, modular, flexible, and localizable CLI library
 - [Internationalization](src/guide/advanced/internationalization)
 - [Documentation Generation](src/guide/advanced/docs-gen)
 - [Advanced Lazy Loading and Sub-Commands](src/guide/advanced/advanced-lazy-loading)
+- [Nested Sub-Commands](src/guide/advanced/nested-sub-commands)
 
 
 ### API References

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/docs",
   "description": "Documentation for gunshi",
-  "version": "0.27.6",
+  "version": "0.28.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"

package/src/api/context/interfaces/CommandContextParams.md

@@ -22,6 +22,7 @@ Parameters of [createCommandContext](../functions/createCommandContext.md)
 | <a id="callmode"></a> `callMode?` | [`CommandCallMode`](../../default/type-aliases/CommandCallMode.md) | Command call mode. |
 | <a id="clioptions"></a> `cliOptions?` | [`CliOptions`](../../default/interfaces/CliOptions.md)\<`G`\> | A command options, which is spicialized from `cli` function |
 | <a id="command"></a> `command?` | `C` | A target command |
+| <a id="commandpath"></a> `commandPath?` | `string`[] | The path of nested sub-commands resolved to reach the current command. |
 | <a id="explicit"></a> `explicit?` | `ArgExplicitlyProvided`\<`ExtractArgs`\<`G`\>\> | Explicitly provided arguments |
 | <a id="extensions"></a> `extensions?` | `E` | Plugin extensions to apply as the command context extension. |
 | <a id="omitted"></a> `omitted?` | `boolean` | Whether the command is omitted |

package/src/api/default/interfaces/Command.md

@@ -22,4 +22,5 @@ Command interface.
 | <a id="name"></a> `name?` | `string` | Command name. It's used to find command line arguments to execute from sub commands, and it's recommended to specify. |
 | <a id="rendering"></a> `rendering?` | [`RenderingOptions`](RenderingOptions.md)\<`G`\> | Rendering control options **Since** v0.27.0 |
 | <a id="run"></a> `run?` | [`CommandRunner`](../type-aliases/CommandRunner.md)\<`G`\> | Command runner. it's the command to be executed |
+| <a id="subcommands"></a> `subCommands?` | \| `Record`\<`string`, [`SubCommandable`](SubCommandable.md)\> \| `Map`\<`string`, [`SubCommandable`](SubCommandable.md)\> | Nested sub-commands for this command. Allows building command trees like `git remote add`. Each key is the sub-command name, and the value is a command or lazy command. **Since** v0.28.0 |
 | <a id="tokebab"></a> `toKebab?` | `boolean` | Whether to convert the camel-case style argument name to kebab-case. If you will set to `true`, All [`Command.args`](#args) names will be converted to kebab-case. |

package/src/api/default/interfaces/CommandContext.md

@@ -19,6 +19,7 @@ Command context is the context of the command execution.
 | <a id="_"></a> `_` | `string`[] | Original command line arguments. This argument is passed from `cli` function. |
 | <a id="args"></a> `args` | `ExtractArgs`\<`G`\> | Command arguments, that is the arguments of the command that is executed. The command arguments is same [`Command.args`](Command.md#args). |
 | <a id="callmode"></a> `callMode` | [`CommandCallMode`](../type-aliases/CommandCallMode.md) | Command call mode. The command call mode is `entry` when the command is executed as an entry command, and `subCommand` when the command is executed as a sub-command. |
+| <a id="commandpath"></a> `commandPath` | `string`[] | The path of nested sub-commands that were resolved to reach the current command. For example, if the user runs `git remote add`, `commandPath` would be `['remote', 'add']`. For the entry command, this is an empty array. **Since** v0.28.0 |
 | <a id="description"></a> `description` | `string` \| `undefined` | Command description, that is the description of the command that is executed. The command description is same [`CommandEnvironment.description`](CommandEnvironment.md#description). |
 | <a id="env"></a> `env` | `Readonly`\<[`CommandEnvironment`](CommandEnvironment.md)\<`G`\>\> | Command environment, that is the environment of the command that is executed. The command environment is same [`CommandEnvironment`](CommandEnvironment.md). |
 | <a id="explicit"></a> `explicit` | `ExtractArgExplicitlyProvided`\<`G`\> | Whether arguments were explicitly provided by the user. - `true`: The argument was explicitly provided via command line - `false`: The argument was not explicitly provided. This means either: - The value comes from a default value defined in the argument schema - The value is `undefined` (no explicit input and no default value) |

package/src/api/default/interfaces/SubCommandable.md

@@ -32,4 +32,5 @@ Index signature to allow additional properties
 | <a id="name"></a> `name?` | `string` | see [Command.name](Command.md#name) |
 | <a id="rendering"></a> `rendering?` | `any` | see [Command.rendering](Command.md#rendering) |
 | <a id="run"></a> `run?` | (...`args`) => `any` | see [Command.run](Command.md#run) |
+| <a id="subcommands"></a> `subCommands?` | `Record`\<`string`, `any`\> \| `Map`\<`string`, `any`\> | Nested sub-commands for this command. **See** [Command.subCommands](Command.md#subcommands) **Since** v0.28.0 |
 | <a id="tokebab"></a> `toKebab?` | `boolean` | see [Command.toKebab](Command.md#tokebab) |

package/src/api/definition/functions/define.md

@@ -3,7 +3,7 @@
 # Function: define()
 
 ```ts
-function define<G, A, C>(definition): { [K in string | number | symbol]: (Pick<C, keyof C> & Partial<Pick<Command<G>, Exclude<"name", keyof C> | Exclude<"description", keyof C> | Exclude<"run", keyof C> | Exclude<"args", keyof C> | Exclude<"examples", keyof C> | Exclude<"toKebab", keyof C> | Exclude<"internal", keyof C> | Exclude<"entry", keyof C> | Exclude<"rendering", keyof C>>>)[K] };
+function define<G, A, C>(definition): { [K in string | number | symbol]: (Pick<C, keyof C> & Partial<Pick<Command<G>, Exclude<"name", keyof C> | Exclude<"description", keyof C> | Exclude<"subCommands", keyof C> | Exclude<"run", keyof C> | Exclude<"args", keyof C> | Exclude<"examples", keyof C> | Exclude<"toKebab", keyof C> | Exclude<"internal", keyof C> | Exclude<"entry", keyof C> | Exclude<"rendering", keyof C>>>)[K] };
 ```
 
 Define a [command](../../default/interfaces/Command.md).
@@ -24,7 +24,7 @@ Define a [command](../../default/interfaces/Command.md).
 
 ## Returns
 
-\{ \[K in string \| number \| symbol\]: (Pick\<C, keyof C\> & Partial\<Pick\<Command\<G\>, Exclude\<"name", keyof C\> \| Exclude\<"description", keyof C\> \| Exclude\<"run", keyof C\> \| Exclude\<"args", keyof C\> \| Exclude\<"examples", keyof C\> \| Exclude\<"toKebab", keyof C\> \| Exclude\<"internal", keyof C\> \| Exclude\<"entry", keyof C\> \| Exclude\<"rendering", keyof C\>\>\>)\[K\] \}
+\{ \[K in string \| number \| symbol\]: (Pick\<C, keyof C\> & Partial\<Pick\<Command\<G\>, Exclude\<"name", keyof C\> \| Exclude\<"description", keyof C\> \| Exclude\<"subCommands", keyof C\> \| Exclude\<"run", keyof C\> \| Exclude\<"args", keyof C\> \| Exclude\<"examples", keyof C\> \| Exclude\<"toKebab", keyof C\> \| Exclude\<"internal", keyof C\> \| Exclude\<"entry", keyof C\> \| Exclude\<"rendering", keyof C\>\>\>)\[K\] \}
 
 A defined [command](../../default/interfaces/Command.md)
 

package/src/api/generator/functions/generate.md

@@ -21,7 +21,7 @@ Generate the command usage.
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `command` | `string` \| `null` | usage generate command, if you want to generate the usage of the default command where there are target commands and sub-commands, specify `null`. |
+| `command` | `string` \| `string`[] \| `null` | usage generate command, if you want to generate the usage of the default command where there are target commands and sub-commands, specify `null`. |
 | `entry` | \| [`Command`](../../default/interfaces/Command.md)\<`G`\> \| [`LazyCommand`](../../default/type-aliases/LazyCommand.md)\<`G`\> | A [`entry command`](../../default/interfaces/Command.md) |
 | `options` | [`GenerateOptions`](../type-aliases/GenerateOptions.md)\<`G`\> | A [`cli options`](../type-aliases/GenerateOptions.md) |
 

package/src/guide/advanced/nested-sub-commands.md

@@ -0,0 +1,238 @@
+# Nested Sub-Commands
+
+Gunshi supports nested sub-commands, allowing you to build hierarchical command trees similar to tools like Git (`git remote add`) or Docker (`docker container ls`).
+
+## Why Use Nested Sub-Commands?
+
+Nested sub-commands are useful when your CLI has command groups with related operations:
+
+- **Organization**: Group related operations under a parent command (e.g., `remote add`, `remote remove`)
+- **Discoverability**: Users can explore available operations at each level with `--help`
+- **Scalability**: Add new nested commands without cluttering the top-level command list
+
+## Basic Nested Sub-Commands
+
+You can nest sub-commands by adding a `subCommands` property to any command definition:
+
+```ts [cli.ts]
+import { cli, define } from 'gunshi'
+
+// Define leaf commands
+const addCommand = define({
+  name: 'add',
+  description: 'Add a remote',
+  args: {
+    url: { type: 'string', required: true, description: 'Remote URL' }
+  },
+  run: ctx => {
+    console.log(`Adding remote: ${ctx.values.url}`)
+  }
+})
+
+const removeCommand = define({
+  name: 'remove',
+  description: 'Remove a remote',
+  args: {
+    name: { type: 'positional', description: 'Remote name' }
+  },
+  run: ctx => {
+    console.log(`Removing remote: ${ctx.values.name}`)
+  }
+})
+
+// Define an intermediate command with nested sub-commands
+const remoteCommand = define({
+  name: 'remote',
+  description: 'Manage remotes',
+  subCommands: {
+    add: addCommand,
+    remove: removeCommand
+  },
+  run: () => {
+    console.log('Use: git remote add|remove')
+  }
+})
+
+// Define the entry command
+const entry = define({
+  name: 'main',
+  description: 'Git-like CLI',
+  run: () => {
+    console.log('Run --help for available commands')
+  }
+})
+
+await cli(process.argv.slice(2), entry, {
+  name: 'git',
+  version: '1.0.0',
+  subCommands: {
+    remote: remoteCommand
+  }
+})
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> The complete example code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/nested-sub-commands).
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+Now users can run:
+
+```sh
+# Execute nested sub-command
+$ npx tsx cli.ts remote add --url https://example.com
+Adding remote: https://example.com
+
+# Show help for intermediate command
+$ npx tsx cli.ts remote --help
+Manage remotes
+
+USAGE:
+  git remote [COMMANDS] <OPTIONS>
+
+COMMANDS:
+  [remote] <OPTIONS>       Manage remotes
+  add <OPTIONS>            Add a remote
+  remove <OPTIONS>         Remove a remote
+
+For more info, run any command with the `--help` flag:
+  git remote --help
+  git remote add --help
+  git remote remove --help
+
+# Show help for leaf command
+$ npx tsx cli.ts remote add --help
+Add a remote
+
+USAGE:
+  git remote add <OPTIONS>
+
+OPTIONS:
+  --url <url>          Remote URL
+```
+
+## Three or More Levels
+
+You can nest commands to any depth:
+
+```ts
+const subSubCommand = define({
+  name: 'sub-sub',
+  description: 'A deeply nested command',
+  run: ctx => {
+    // ctx.commandPath will be ['level1', 'level2', 'sub-sub']
+    console.log(`Command path: ${ctx.commandPath.join(' > ')}`)
+  }
+})
+
+const level2Command = define({
+  name: 'level2',
+  description: 'Second level',
+  subCommands: { 'sub-sub': subSubCommand },
+  run: () => {}
+})
+
+const level1Command = define({
+  name: 'level1',
+  description: 'First level',
+  subCommands: { level2: level2Command },
+  run: () => {}
+})
+```
+
+## Using `commandPath`
+
+The `CommandContext` includes a `commandPath` property that tells you the full path of commands that were resolved:
+
+```ts
+const addCommand = define({
+  name: 'add',
+  description: 'Add a remote',
+  run: ctx => {
+    console.log(ctx.commandPath) // ['remote', 'add']
+    console.log(ctx.callMode) // 'subCommand'
+  }
+})
+```
+
+| Invocation       | `commandPath`       | `callMode`     |
+| ---------------- | ------------------- | -------------- |
+| `cli`            | `[]`                | `'entry'`      |
+| `cli remote`     | `['remote']`        | `'subCommand'` |
+| `cli remote add` | `['remote', 'add']` | `'subCommand'` |
+
+## Intermediate Commands
+
+When a user invokes an intermediate command (one that has nested sub-commands) without specifying a child, the intermediate command's `run` function is called with `omitted: true`. In this case, the built-in help system automatically shows a COMMANDS section listing the available nested sub-commands:
+
+```ts
+const remoteCommand = define({
+  name: 'remote',
+  description: 'Manage remotes',
+  subCommands: { add: addCommand },
+  run: ctx => {
+    if (ctx.omitted) {
+      // User ran `cli remote` without specifying a sub-command
+      // Help is shown automatically with COMMANDS section
+      console.log('Please specify a sub-command: add, remove')
+    }
+  }
+})
+```
+
+## Nested Sub-Commands with Lazy Loading
+
+For large CLIs, you can combine nested sub-commands with lazy loading:
+
+```ts
+import { cli, define, lazy } from 'gunshi'
+
+// Lazy-load the leaf command
+const addCommand = lazy(() => import('./commands/remote-add.ts'), {
+  name: 'add',
+  description: 'Add a remote',
+  args: {
+    url: { type: 'string', required: true, description: 'Remote URL' }
+  }
+})
+
+// The parent command can also be lazy-loaded
+const remoteCommand = lazy(() => import('./commands/remote.ts'), {
+  name: 'remote',
+  description: 'Manage remotes',
+  subCommands: {
+    add: addCommand
+  }
+})
+
+await cli(process.argv.slice(2), entry, {
+  name: 'git',
+  subCommands: { remote: remoteCommand }
+})
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!IMPORTANT]
+> When using `lazy()` with nested sub-commands, include `args` in the lazy definition (the second argument) if you want argument parsing to work before the command is loaded. The `subCommands` property is automatically carried over from the definition to the lazy command.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## Generating Documentation for Nested Commands
+
+The `generate()` function supports nested command paths:
+
+```ts
+import { generate } from 'gunshi/generator'
+
+// Generate help for a nested command using array or space-separated string
+const help = await generate(['remote', 'add'], entry, {
+  name: 'git',
+  subCommands: { remote: remoteCommand }
+})
+
+// Or using space-separated string
+const help2 = await generate('remote add', entry, { ... })
+```

package/src/guide/essentials/composable.md

@@ -319,6 +319,41 @@ This approach is particularly useful for CLIs that:
 - Want to provide a default action when no sub-command matches
 - Implement dynamic command resolution based on context
 
+## Nested Sub-Commands
+
+Gunshi also supports nested sub-commands for building hierarchical command trees like `git remote add`. You can add a `subCommands` property to any command definition:
+
+```ts [cli.ts]
+import { cli, define } from 'gunshi'
+
+const addCommand = define({
+  name: 'add',
+  description: 'Add a remote',
+  args: { url: { type: 'string', required: true } },
+  run: ctx => console.log(`Adding: ${ctx.values.url}`)
+})
+
+const remoteCommand = define({
+  name: 'remote',
+  description: 'Manage remotes',
+  subCommands: { add: addCommand },
+  run: () => console.log('Use: remote add')
+})
+
+const entry = define({
+  name: 'main',
+  description: 'Git-like CLI',
+  run: () => console.log('Run --help for available commands')
+})
+
+await cli(process.argv.slice(2), entry, {
+  name: 'git',
+  subCommands: { remote: remoteCommand }
+})
+```
+
+For more details on nested sub-commands, including lazy loading, intermediate command handling, and `commandPath`, see the [Nested Sub-Commands](../advanced/nested-sub-commands.md) guide.
+
 ## Next Steps
 
 Throughout this guide, you've learned how to build composable sub-commands that scale from simple to complex CLI applications.