# Plugin Lifecycle
Understanding the Gunshi lifecycle is crucial for effective plugin development.
This guide explains how plugins integrate with the CLI execution flow and when different plugin features are activated.
## CLI Execution Lifecycle
When a Gunshi CLI application runs, it follows a specific sequence of steps from startup to completion.
The diagram below shows the complete execution flow, with plugin-related steps highlighted in green:
```mermaid
graph TD
A[A. CLI Start] --> B[B. Load Plugins]
B --> C[C. Resolve Dependencies]
C --> D[D. Execute Plugin Setup]
D --> E[E. Parse Arguments]
E --> F[F. Resolve Command]
F --> G[G. Resolve & Validate Args]
G --> H[H. Create CommandContext
Process each plugin sequentially:
1. Create extension
2. Call onExtension]
H --> I[I. Execute Command]
I --> J[J. CLI End]
style B fill:#468c56,color:white
style C fill:#468c56,color:white
style D fill:#468c56,color:white
style H fill:#468c56,color:white
style I fill:#468c56,color:white
```
The lifecycle consists of 10 steps (A through J), where plugins are primarily involved in:
- **Steps B-D**: Plugin initialization and setup
- **Step H**: Plugin extension creation and activation during CommandContext creation
- **Step I**: Command execution with plugin decorators applied
## Plugin-Specific Lifecycle Steps
Plugins are primarily involved in specific steps of the CLI lifecycle.
This section focuses on the steps where plugins actively participate.
### Setup Phase (Steps B-D)
During the setup phase, plugins are loaded, dependencies are resolved, and plugin setup functions are executed.
This phase occurs once at CLI initialization.
**What happens in this phase:**
- Plugins configure the CLI by adding options, commands, and decorators
- All modifications are registered but not yet executed
- The `setup()` function runs for each plugin
#### Step B: Load Plugins
Plugins are collected from CLI options and prepared for initialization.
The following code shows how plugins are passed to the CLI function:
```js
import { cli } from 'gunshi'
await cli(args, command, {
plugins: [
plugin1(), // Collected
plugin2(), // Collected
plugin3() // Collected
]
})
```
#### Step C: Resolve Dependencies
Gunshi uses **topological sorting** to resolve plugin dependencies.
The following example demonstrates how plugins with dependencies are resolved in the correct order:
```js
import { plugin } from 'gunshi/plugin'
// Given these plugins:
const pluginA = plugin({
id: 'a',
dependencies: ['b', 'c']
})
const pluginB = plugin({
id: 'b',
dependencies: ['d']
})
const pluginC = plugin({
id: 'c'
})
const pluginD = plugin({
id: 'd'
})
// Resolution order: d → b → c → a
```
> [!TIP]
> For details on plugin dependency resolution, including circular dependency detection, optional dependencies, see [Plugin Dependencies](./dependencies.md).
#### Step D: Execute Plugin Setup
The `setup` function of each plugin is called in dependency order.
This example shows what actions a plugin can perform during setup. The examples of this page print with `console.log` to show the order of the phases. A real plugin prints with `ctx.log` in a command decorator, which is silenced when the command prints JSON with `--json`.
```js
import { plugin } from 'gunshi/plugin'
const myPlugin = plugin({
id: 'my-plugin',
setup: ctx => {
// This runs during Setup Phase
console.log('Plugin setting up')
// Add global options
ctx.addGlobalOption('verbose', {
type: 'boolean',
description: 'Verbose output'
})
// Register sub-commands
ctx.addCommand('plugin-cmd', {
name: 'plugin-cmd',
run: ctx => console.log('Plugin command')
})
// Add decorators (they stack in LIFO order)
ctx.decorateCommand(baseRunner => async ctx => {
console.log('Before command (from plugin)')
const result = await baseRunner(ctx)
console.log('After command (from plugin)')
return result
})
}
})
```
A `setup` that throws ends the run: `cli()` rejects with an error naming the plugin, and the error it threw is available as the `cause`. Nothing is installed after it, and no command runs. This matches how a circular or a missing dependency is reported in Step C — a CLI that cannot be assembled is not run.
```sh
Error: Failed to install the plugin `my-plugin`
[cause]: Error: Global option 'verbose' is already registered
```
Keep `setup` to registration. Work that can fail for reasons outside your control — reading a file, probing the environment, talking to a network — belongs in an extension or a decorator, where it runs per command and can be handled there.
### Command Processing (Steps E-H)
Between the setup phase and execution phase, Gunshi processes the command-line arguments and prepares the execution context:
- **Step E**: Parse command-line arguments into structured tokens
- **Step F**: Resolve which command to execute
- **Step G**: Validate arguments against the command's schema
- **Step H**: Create the CommandContext object
> [!NOTE]
> These internal processing steps are handled automatically by Gunshi. Plugin developers don't need to interact with these steps directly.
### Execution Phase (Steps H-I)
During the execution phase, the CommandContext is created with plugin extensions, and then the command is executed with all decorators applied.
### Step H: Create CommandContext & Process Plugins
The CommandContext is created and each plugin's extension is initialized:
1. Initialize CommandContext with parsed arguments and values
2. For each plugin (in dependency order):
- Call the plugin's `extension()` function to create an extension
- Store the extension in `context.extensions[pluginId]`
- Immediately call the plugin's `onExtension()` callback if present
This sequential processing ensures extensions from dependencies are available to dependent plugins.
> [!NOTE]
> For detailed information about the extension lifecycle, including execution order guarantees, the relationship between `extension` and `onExtension`, and code examples, see the [Extension Lifecycle](./extensions.md#extension-lifecycle) section in the Plugin Extensions guide.
### Step I: Execute Command
The command runner executes with:
- All decorators applied in LIFO (Last In, First Out) order
- Full access to all plugin extensions via `ctx.extensions`
- Complete CommandContext with validated arguments
This example illustrates the command execution with decorator wrapping and extension usage:
```js
import { define } from 'gunshi'
// If plugins A, B, C add decorators in that order:
// Execution order: C → B → A → original command → A → B → C
const command = define({
name: 'build',
run: ctx => {
// This is the original command
ctx.extensions.logger.log('Building project...')
// Build logic here
}
})
```
## Extension Lifecycle in Detail
Understanding the relationship between `extension` and `onExtension` is crucial for effective plugin development.
During Step H (Create CommandContext):
- Each plugin is processed sequentially in dependency order
- For each plugin: the `extension` factory is called, then immediately its `onExtension` callback
- This sequential approach ensures that when a plugin's `onExtension` runs, all previous plugins' extensions are already available through `ctx.extensions`
> [!TIP]
> For a detailed visual representation of the extension lifecycle and execution order guarantees, see [Extension Lifecycle](./extensions.md#extension-lifecycle) in the Plugin Extensions guide.
## Lifecycle with Command Hooks
Gunshi provides Command hooks (`onBeforeCommand`, `onAfterCommand`, `onErrorCommand`) that integrate with the plugin lifecycle.
The following sequence diagram illustrates how these command hooks interact with plugins during command execution:
> [!TIP]
> For details on Command Hooks, including advanced use cases like logging, performance monitoring, validation guards, and transaction management, see [Command Hooks](../advanced/command-hooks.md).
```mermaid
sequenceDiagram
participant CLI as CLI
participant Plugin as Plugin
participant Command as Command
CLI->>Plugin: Setup Phase
Plugin->>CLI: Register decorators
CLI->>CLI: Create Context
CLI->>Plugin: Create Extensions
Plugin->>CLI: Return Extensions
CLI->>CLI: onBeforeCommand
CLI->>Plugin: Apply Decorators
Plugin->>Command: Execute (decorated)
Command->>Plugin: Return
Plugin->>CLI: Return
CLI->>CLI: onAfterCommand
Note over CLI: Or on error:
Command-->>CLI: Throw Error
CLI->>CLI: onErrorCommand
```
This sequence shows:
1. **Setup Phase**: Plugins register their decorators during initialization
2. **Extension Creation**: Plugin extensions are created and returned to the CLI
3. **Command Hooks**: The `onBeforeCommand` hook runs before decorators and command execution
4. **Decorated Execution**: Plugin decorators wrap the command execution
5. **Post-Execution**: The `onAfterCommand` hook runs after successful completion
6. **Error Handling**: The `onErrorCommand` hook catches any errors during execution
## Complete Lifecycle Example
Here's a complete example showing all lifecycle phases including Command Hooks. It prints with `console.log` to show the order: a real plugin prints with `ctx.log`, which is silenced with `--json`.
Plugin Codes:
```js [lifecycle.js]
import { plugin } from 'gunshi/plugin'
export default plugin({
id: 'lifecycle',
dependencies: ['logger'], // Step C: Dependency resolution
// Step D: Setup execution
setup: ctx => {
console.log('1. lifecycle plugin setup phase started')
// Register global option
ctx.addGlobalOption('verbose', {
type: 'boolean',
alias: 'v',
description: 'Verbose output'
})
// Add sub-command
ctx.addCommand('status', {
name: 'status',
run: ctx => console.log('Status: OK')
})
// Register decorators (LIFO order)
ctx.decorateCommand(runner => async ctx => {
console.log('5. Command decorator (before)')
const result = await runner(ctx)
console.log('7. Command decorator (after)')
return result
})
console.log('2. Setup phase completed')
},
// Step H: Extension creation (during CommandContext creation)
extension: (ctx, cmd) => {
console.log('3. Extension created for:', cmd.name)
return {
demo: () => 'Hello from extension',
cleanup: () => console.log('9. Extension cleanup')
}
},
// Step H: Post-extension callback (immediately after extension creation)
onExtension: (ctx, cmd) => {
console.log('4. All extensions ready')
}
})
```
Application Codes:
```js [cli.js]
import { cli, define } from 'gunshi'
import logger from './logger.js'
import lifecycle from './lifecycle.js'
// Command definition
const command = define({
name: 'build',
args: {
fail: {
type: 'boolean'
}
},
run: ctx => {
console.log('6. Actual command execution')
console.log('Extension says:', ctx.extensions['lifecycle'].demo())
// Simulate an error for demonstration
if (ctx.values.fail) {
throw new Error('Build failed!')
}
}
})
// Running the CLI with Command Hooks
await cli(process.argv.slice(2), command, {
// Plugin installation
plugins: [logger, lifecycle],
// Command Hooks are defined at CLI level
onBeforeCommand: ctx => {
console.log('4.5. onBeforeCommand hook')
},
onAfterCommand: ctx => {
console.log('8. onAfterCommand hook')
// Cleanup can be done here
ctx.extensions['lifecycle'].cleanup()
},
onErrorCommand: (ctx, error) => {
console.log('8. onErrorCommand hook:', error.message)
// Error recovery or cleanup
ctx.extensions['lifecycle'].cleanup()
}
})
```
> [!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/lifecycle).
Run your application with plugin:
```sh
node cli.js
logger plugin setup phase started
1. lifecycle plugin setup phase started
2. Setup phase completed
3. Extension created for: build
4. All extensions ready
4.5. onBeforeCommand hook
5. Command decorator (before)
6. Actual command execution
Extension says: Hello from extension
7. Command decorator (after)
8. onAfterCommand hook
9. Extension cleanup
node index.js --fail
logger plugin setup phase started
1. lifecycle plugin setup phase started
2. Setup phase completed
3. Extension created for: build
4. All extensions ready
4.5. onBeforeCommand hook
5. Command decorator (before)
6. Actual command execution
Extension says: Hello from extension
8. onErrorCommand hook: Build failed!
9. Extension cleanup
file:///path/to/projects/gunshi/playground/plugins/lifecycle/index.js:19
throw new Error('Build failed!')
```
## Next Steps
Now that you understand how plugins integrate with the CLI lifecycle—from setup through command execution to cleanup—you're ready to explore how plugins can work together.
The next chapter, [Plugin Dependencies](./dependencies.md), will teach you how to build plugin ecosystems where plugins can depend on and interact with each other, enabling composition patterns for complex CLI applications.