repository·main·Indexed 19 days ago
https://github.com/kazupon/gunshiA modern JavaScript command-line library for creating type-safe, declarative, and composable CLIs. It supports Node.js, Deno, and Bun runtimes. The ecosystem includes a monorepo with packages such as @gunshi/bone for minimal footprints, @gunshi/combinators for type-safe argument schemas, @gunshi/definition for command definitions, and plugins for shell completion (@gunshi/plugin-completion) and dry-run support (@gunshi/plugin-dryrun).
Gunshi allows you to define CLI commands using a declarative structure via the define function. This approach separates the command's metadata, argument definitions, and usage examples from the actual execution logic (run function), making your CLI code more maintainable as complexity grows.
A command definition object includes:
name and description to identify the command.args): A map of argument definitions (type, short flags, descriptions, defaults).ctx) and executes the command logic.import { define } from 'gunshi'
const command = define({
name: 'command-name',
description: 'Command description',
args: {
// Argument definitions
},
examples: 'Example usage',
run: ctx => {
// Command implementation
}
})In Gunshi, the command context (ctx) is the central object passed to every command runner. Plugins enhance this context by adding new capabilities through the ctx.extensions property.
To prevent naming collisions, each plugin registers its extension under a unique identifier (plugin ID) within the ctx.extensions object. This namespacing ensures that different plugins can coexist without overwriting each other's functionality. When a plugin is added to your CLI configuration, its extension becomes available to all commands via ctx.extensions[pluginId].
import { define } from 'gunshi'
import { pluginId as globalId } from '@gunshi/plugin-global'
const command = define({
run: ctx => {
// Access global plugin extension via its unique ID
const globalExtension = ctx.extensions[globalId]
// Use extension methods
globalExtension.showVersion()
globalExtension.showHeader()
}
})When multiple plugins register renderer decorators, Gunshi builds a chain using a for loop that iterates through the decorator array from first to last. Each decorator wraps the result of the previous one.
@gunshi/plugin-renderer (a default plugin) wraps the base and provides the actual implementation.plugins array.If you call await baseRenderer(ctx) at the start of your decorator, your logic executes after the underlying renderer has finished, but your return value will be the last thing processed in the chain.
Example Chain:
Base $\rightarrow$ plugin-renderer $\rightarrow$ Plugin A $\rightarrow$ Plugin B (where Plugin B wraps Plugin A).
If Plugin B calls baseRenderer first, it waits for Plugin A to finish, then adds its own content. This results in Plugin B's content appearing last in the output.
Gunshi uses a composition pattern to extend the CommandContext.
extension, it is registered via a unique Symbol.extensions field.createCommandContext is called. It identifies the required extensions, runs their factory functions using the CommandContextCore (the base context containing arguments and values), and merges the results into a new ext property on the final CommandContext.ExtendedCommand type ensures that the run function's ctx.ext object is mapped to the return types of the extension factories, providing full IDE autocompletion and compile-time checks.Gunshi v0.27 uses a type parameter system to provide compile-time safety for CLI applications. It ensures that command arguments and plugin extensions are correctly typed throughout the lifecycle of a command.
Key components include:
GunshiParams: The core type used to define the shape of command arguments (args) and plugin extensions (extensions).define and lazy provide automatic type inference for standard commands.defineWithTypes and lazyWithTypes allow commands to declare expected extensions from plugins that are installed at runtime.cli function uses type parameters to ensure the entry command is correctly typed.Gunshi uses a decorator pattern via plugin-renderer to handle the display of command information. The rendering flow involves three main components:
renderHeader: Displays command header information.renderUsage: Displays command usage instructions.renderValidationErrors: Displays errors encountered during validation.Important Behavior:
Decorators are applied in a chain and follow a LIFO (Last In, First Out) execution order. This means the last plugin registered will be the first one to execute its decorator. This can lead to conflicts where a later plugin overrides the rendering intent of an earlier one if not managed via the rendering property or dedicated control plugins.
Choosing between define and plain JavaScript objects depends on your environment and needs:
Use define when:
Use plain objects when:
The APIs and TypeScript type definitions provided by @gunshi/plugin are identical to those found in the gunshi/plugin entry point of the main gunshi package.
When to use @gunshi/plugin:
When to use gunshi/plugin:
gunshi package in your project and want to avoid adding an extra dependency.Gunshi uses two different mechanisms for controlling execution:
cli() configuration.decorateCommand to add or modify functionality. Multiple decorators form a chain applied in reverse order (LIFO - last registered, first executed).Execution Sequence:
onBeforeCommand Hookrun function)onAfterCommand Hook (if successful)onErrorCommand Hook (if any step above fails)Gunshi provides automatic help generation (e.g., via --help) and versioning (e.g., via --version). When using the standard cli() function from the main gunshi package, these features are enabled by default via two built-in plugins:
@gunshi/plugin-global: Provides global options like --help and --version.@gunshi/plugin-renderer: Handles formatted output for help messages, error messages, and usage information.Note: If you use the lower-level run() function instead of cli(), you must manually configure these plugins to enable help and version functionality.