@gunshi/docs 0.27.0-beta.4

package/src/guide/essentials/auto-usage.md

@@ -0,0 +1,281 @@
+# Auto Usage Generation
+
+Gunshi automatically generates comprehensive usage information for your commands, ensuring your CLI is self-documenting and user-friendly without additional effort.
+
+## How Auto Usage Works
+
+When you define a command with Gunshi, the library automatically:
+
+- Adds `--help` and `-h` flags to every command
+- Adds `--version` and `-v` flags when you provide a version in the CLI options
+- Generates formatted usage text based on your command configuration
+- Displays usage information when users request help or provide invalid arguments
+- Includes descriptions, examples, and type information you provide
+
+The generated usage follows standard CLI conventions, making your application immediately familiar to users.
+
+## Understanding Bracket Notation
+
+Gunshi uses consistent bracket notation throughout the generated usage to indicate whether elements are required or optional:
+
+### Angle Brackets `<>` - Required Elements
+
+Angle brackets indicate required elements or parameters without default values:
+
+- `<OPTIONS>` - The command has required options (at least one option without a default value)
+- `<name>` - An option parameter that must be provided (no default value)
+- `<positional>` - A required positional argument
+
+Example:
+
+```sh
+USAGE:
+  app <OPTIONS>
+
+OPTIONS:
+  -n, --name <name>    Name to use (required)
+```
+
+### Square Brackets `[]` - Optional Elements
+
+Square brackets indicate optional elements or parameters with default values:
+
+- `[name]` - An option parameter with a default value
+- `[COMMANDS]` - Sub-command selection (when multiple commands exist)
+- `[commandName]` - A default command that runs when no sub-command is specified
+
+Example:
+
+```sh
+USAGE:
+  app [COMMANDS]
+
+COMMANDS:
+  [manage]    Default command for managing resources
+
+OPTIONS:
+  -t, --type [type]    Resource type (default: standard)
+```
+
+This notation provides immediate visual feedback about what users must provide versus what they can omit, making your CLI more intuitive to use.
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> Auto-usage generation is powered by the `@gunshi/plugin-renderer` plugin, which is automatically included when you use the standard `cli()` function. This plugin handles all help text rendering and formatting.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## Generated Help Output
+
+Gunshi transforms your command definitions into professional help documentation.
+
+Here's what users see when they request help.
+
+### Basic Command Help
+
+For a simple command with basic configuration (see [Getting Started](./getting-started.md) for implementation details), running with `--help` displays:
+
+```sh
+A greeting CLI (greet-cli v1.0.0)
+
+USAGE:
+  greet-cli <OPTIONS>
+
+OPTIONS:
+  -h, --help                 Display this help message
+  -v, --version              Display this version
+  -n, --name <name>          Name to greet
+  -u, --uppercase            Convert greeting to uppercase
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> The `--help` flag is automatically added - you never need to define it manually.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+### Help with Arguments and Examples
+
+When your command includes argument definitions and examples (see [Declarative Configuration](./declarative.md) for how to define these), the generated help becomes more comprehensive:
+
+```sh
+app (app v1.0.0)
+
+USAGE:
+  app <OPTIONS>
+
+OPTIONS:
+  -p, --path <path>                    File or directory path to operate on
+  -r, --recursive                      Operate recursively on directories
+  --no-recursive                       Negatable of -r, --recursive
+  -o, --operation <operation>          Operation to perform: list, copy, move, or delete
+  -h, --help                           Display this help message
+  -v, --version                        Display this version
+
+EXAMPLES:
+  # List files in current directory
+  $ app --operation list
+
+  # Copy files recursively
+  $ app --operation copy --path ./source --recursive
+
+  # Delete files
+  $ app --operation delete --path ./temp
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!IMPORTANT]
+> Boolean options automatically receive a negatable version with the `--no-` prefix. This allows users to explicitly disable boolean flags.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## Customizing Help Output
+
+### Displaying Option Types
+
+Enable type display in the usage output to help users understand what value each option expects:
+
+```js
+await cli(process.argv.slice(2), command, {
+  name: 'app',
+  version: '1.0.0',
+  usageOptionType: true // Enable type display
+})
+```
+
+This adds type information to each option:
+
+```sh
+OPTIONS:
+  -p, --path <path>              [string]   File or directory path to operate on
+  -r, --recursive                [boolean]  Operate recursively on directories
+  --no-recursive                 [boolean]  Negatable of -r, --recursive
+  -o, --operation <operation>    [string]   Operation to perform: list, copy, move, or delete
+  -h, --help                     [boolean]  Display this help message
+  -v, --version                  [boolean]  Display this version
+```
+
+## Sub-command Help Generation
+
+For CLIs with sub-commands (see [Composable Sub-commands](./composable.md) for implementation), Gunshi generates hierarchical help documentation.
+
+### Main Command Help
+
+When users run the main command with `--help`:
+
+```sh
+resource-manager (resource-manager v1.0.0)
+
+USAGE:
+  resource-manager [COMMANDS] <OPTIONS>
+
+COMMANDS:
+  [manage] <OPTIONS>       Manage resources
+  create <OPTIONS>         Create a new resource
+  list <OPTIONS>           List all resources
+
+For more info, run any command with the `--help` flag:
+  resource-manager --help
+  resource-manager create --help
+  resource-manager list --help
+
+OPTIONS:
+  -h, --help             Display this help message
+  -v, --version          Display this version
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> The brackets in `[manage]` indicate it's the default command that runs when no sub-command is specified.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+### Sub-command Specific Help
+
+Each sub-command has its own help, accessible via `command --help`. The below `create --help`:
+
+```sh
+resource-manager (resource-manager v1.0.0)
+
+Create a new resource
+
+USAGE:
+  resource-manager create <OPTIONS>
+
+OPTIONS:
+  -h, --help                 Display this help message
+  -v, --version              Display this version
+  -n, --name <name>          Name of the resource
+  -t, --type [type]          Type of resource (default: default)
+```
+
+### Positional Arguments Display
+
+When commands accept positional arguments (arguments without flags), they appear in the `ARGUMENTS` line:
+
+```sh
+resource-manager (resource-manager v1.0.0)
+
+Manage resources
+
+USAGE:
+  resource-manager manage <OPTIONS> <resource>
+
+ARGUMENTS:
+  resource           Type of resource to manage (e.g., user, project)
+
+OPTIONS:
+  -h, --help             Display this help message
+  -v, --version          Display this version
+```
+
+Positional arguments are displayed with clear, descriptive names that indicate their purpose. Currently, all positional arguments are shown as required using angle brackets (e.g., `<resource>`).
+
+## Automatic Features
+
+Gunshi provides several automatic features without requiring any configuration:
+
+### Help Flag (`--help`, `-h`)
+
+- Automatically added to all commands
+- Displays usage information and exits
+- Works at every command level (main and sub-commands)
+
+### Version Flag (`--version`, `-v`)
+
+- Automatically added when you provide a `version` in CLI options
+- Displays the version and exits
+- Available at all command levels
+
+### Negatable Boolean Options
+
+- Boolean options automatically get `--no-` prefixed versions
+- Allows explicit disabling of boolean flags
+- Example: `--recursive` automatically creates `--no-recursive`
+
+### Invalid Argument Handling
+
+- Usage is automatically displayed when users provide invalid arguments
+- Helps users understand what went wrong
+- Provides immediate guidance for correct usage
+
+## Key Points
+
+When working with auto-generated usage:
+
+- The `--help` flag is automatically added to all commands - you don't need to define it
+- Usage is displayed when users provide invalid arguments or explicitly request help
+- Descriptions in your `args` configuration become the help text for each option
+- The `examples` field accepts both single strings and multi-line strings for multiple examples
+- Sub-command help is accessible both from the main help and individually via `command --help`
+- Required options are shown with angle brackets `<option>` in the USAGE line
+- Boolean options automatically get negatable versions (`--no-` prefix) when not required
+- The `usageOptionType` CLI option adds type annotations to help output
+
+## Next Steps
+
+Learn about the [Plugin System](./plugin-system.md) to extend functionality.

package/src/guide/essentials/composable.md

@@ -0,0 +1,332 @@
+# Composable Sub-commands
+
+In [the previous chapter](./type-safe.md), you learned how to create type-safe commands using the `define` function.
+
+Now, let's extend that knowledge to build CLIs with multiple sub-commands while maintaining the same type safety benefits.
+
+Gunshi's composable sub-command system allows you to create modular, organized CLIs similar to tools like Git (with commands like `git commit` and `git push`).
+
+## Why Use Sub-commands?
+
+Sub-commands are useful when your CLI needs to perform different operations that warrant separate commands.
+
+Benefits include:
+
+- **Organization**: Group related functionality logically
+- **Scalability**: Add new commands without modifying existing ones
+- **User experience**: Provide a consistent interface for different operations
+- **Help system**: Each sub-command can have its own help documentation
+- **Plugin integration**: Plugins are shared across all sub-commands for consistent functionality
+
+## Basic Structure
+
+A CLI with sub-commands typically has this structure:
+
+```sh
+cli <command> [command options]
+```
+
+For example:
+
+```sh
+your-cli create --name my-resource
+```
+
+## Creating Type-Safe Sub-commands
+
+Building on the `define` function from the previous chapter, let's create a CLI with multiple sub-commands:
+
+```ts [cli.ts]
+import { cli, define } from 'gunshi'
+
+// Define type-safe sub-commands
+const createCommand = define({
+  name: 'create',
+  description: 'Create a new resource',
+  args: {
+    name: { type: 'string', short: 'n', required: true }
+  },
+  run: ctx => {
+    // ctx.values is fully typed
+    console.log(`Creating resource: ${ctx.values.name}`)
+  }
+})
+
+const listCommand = define({
+  name: 'list',
+  description: 'List all resources',
+  run: () => {
+    console.log('Listing all resources...')
+  }
+})
+
+// Define the main command
+const mainCommand = define({
+  name: 'manage',
+  description: 'Manage resources',
+  run: ctx => {
+    // This runs when no sub-command is provided
+    console.log('Available commands: create, list')
+    console.log('Run "manage --help" for more information')
+  }
+})
+
+// Run the CLI with composable sub-commands
+await cli(process.argv.slice(2), mainCommand, {
+  name: 'my-app',
+  version: '1.0.0',
+  subCommands: {
+    create: createCommand,
+    list: listCommand
+  }
+})
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/composable/basic).
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+This structure provides:
+
+- Full type safety for all commands and sub-commands
+- Automatic help generation for each command level
+- Shared configuration across the command hierarchy
+
+## Automatic Help for Sub-commands
+
+Gunshi automatically generates help documentation for your sub-commands.
+
+Using the code from the previous section, you can see the help for each command level:
+
+```sh
+# Show main command help
+$ npx tsx cli.ts --help
+
+# Show sub-command help
+$ npx tsx cli.ts create --help
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> [`tsx`](https://github.com/privatenumber/tsx) is a TypeScript execution tool that allows you to run TypeScript files directly without compilation. Use it directly with `npx tsx`.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> On Node.js v22.6.0, you can run TypeScript with `--experimental-strip-types`:
+>
+> ```sh
+> node --experimental-strip-types cli.ts --help
+> ```
+>
+> From Node.js v23.6.0 and newer, type stripping is enabled by default (no flag needed for erasable TS). Features requiring transformation (e.g., `enum`) still need `--experimental-transform-types`.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+Each sub-command's help includes its description, available options, and usage examples.
+
+## Organizing Your Commands
+
+As your CLI grows, organizing commands in separate files improves maintainability.
+
+Here's a recommended project structure:
+
+```sh
+my-cli/
+├── src/
+│   ├── commands/
+│   │   ├── create.ts      # Create command implementation
+│   │   └── list.ts        # List command implementation
+│   ├── main.ts            # Main command definition
+│   └── cli.ts             # CLI entry point
+├── package.json
+└── tsconfig.json
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/composable/organizing).
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+This structure provides:
+
+- Clear separation of concerns
+- Shared utilities across commands
+- Centralized type definitions
+- Easy testing of individual components
+
+### Individual Command Files
+
+```ts [commands/create.ts]
+import { define } from 'gunshi'
+
+export default define({
+  name: 'create',
+  description: 'Create a new resource',
+  args: {
+    name: {
+      type: 'string',
+      short: 'n',
+      required: true,
+      description: 'Name of the resource'
+    },
+    type: {
+      type: 'string',
+      short: 't',
+      default: 'default',
+      description: 'Type of resource'
+    }
+  },
+  run: ctx => {
+    console.log(`Creating ${ctx.values.type} resource: ${ctx.values.name}`)
+  }
+})
+```
+
+```ts [commands/list.ts]
+import { define } from 'gunshi'
+
+export default define({
+  name: 'list',
+  description: 'List all resources',
+  args: {
+    filter: {
+      type: 'string',
+      short: 'f',
+      description: 'Filter resources'
+    }
+  },
+  run: ctx => {
+    const filter = ctx.values.filter || 'all'
+    console.log(`Listing resources with filter: ${filter}`)
+  }
+})
+```
+
+### Main Command File
+
+```ts [main.ts]
+import { define } from 'gunshi'
+
+export default define({
+  name: 'manage',
+  description: 'Manage resources',
+  run: () => {
+    console.log('Use a sub-command')
+    console.log('Run "resource-manager --help" for available commands')
+  }
+})
+```
+
+### Entry Point
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> Some code examples in this guide include TypeScript file extensions (`.ts`) in import/export statements. If you use this pattern in your application, you'll need to enable `allowImportingTsExtensions` in your `tsconfig.json`.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+```ts [cli.ts]
+import { cli } from 'gunshi'
+import main from './main.ts'
+import create from './commands/create.ts'
+import list from './commands/list.ts'
+
+await cli(process.argv.slice(2), main, {
+  name: 'resource-manager',
+  version: '1.0.0',
+  subCommands: {
+    create,
+    list
+  }
+})
+```
+
+## Handling Unknown Sub-commands
+
+By default, Gunshi shows an error when users provide an unknown sub-command.
+
+You can customize this behavior using the `fallbackToEntry` option:
+
+```ts [cli.ts]
+await cli(process.argv.slice(2), main, {
+  name: 'resource-manager',
+  version: '1.0.0',
+  fallbackToEntry: true,
+  subCommands: {
+    create,
+    list
+  }
+})
+```
+
+This option enables flexible command handling:
+
+```sh
+# Runs the create sub-command
+npx tsx src/cli.ts create --name resource
+resource-manager (resource-manager v1.0.0)
+
+Creating default resource: resource
+
+# Runs the list sub-command
+npx tsx src/cli.ts list --filter active
+resource-manager (resource-manager v1.0.0)
+
+Listing resources with filter: active
+
+# Falls back to main command when "unknown" sub-command is not found
+npx tsx src/cli.ts unknown --flag value
+resource-manager (resource-manager v1.0.0)
+
+Use a sub-command
+Run "resource-manager --help" for available commands
+
+# Runs the main command directly
+npx tsx src/cli.ts --help
+resource-manager (resource-manager v1.0.0)
+
+USAGE:
+  resource-manager [COMMANDS] <OPTIONS>
+
+COMMANDS:
+  [manage] <OPTIONS>       Manage resources
+  create <OPTIONS>         Create a new resource
+  list <OPTIONS>           List all resources
+
+For more info, run any command with the `--help` flag:
+  resource-manager --help
+  resource-manager create --help
+  resource-manager list --help
+
+OPTIONS:
+  -h, --help             Display this help message
+  -v, --version          Display this version
+```
+
+This approach is particularly useful for CLIs that:
+
+- Need to handle file paths or patterns as direct arguments
+- Want to provide a default action when no sub-command matches
+- Implement dynamic command resolution based on context
+
+## Next Steps
+
+Throughout this guide, you've learned how to build composable sub-commands that scale from simple to complex CLI applications.
+
+You've seen how Gunshi maintains type safety across nested command structures, enables powerful routing patterns with default commands, and supports both synchronous and asynchronous command execution.
+
+Now that you understand how to compose commands into well-organized hierarchies, you're ready to explore how to optimize their performance.
+
+The next section on [Lazy & Async Command Loading](./lazy-async.md) will show you how to significantly improve your CLI's startup time by loading commands only when they're actually needed.
+
+With composable sub-commands as your foundation, adding lazy loading will make your CLI applications both powerful and performant, especially as they grow to include many commands with varying resource requirements.