@gunshi/plugin-dryrun 0.31.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,14 +1,255 @@
1
- # `@gunshi/plugin-dryrun`
1
+ # @gunshi/plugin-dryrun
2
2
 
3
- > dryrun option plugin for gunshi
3
+ [![Version][npm-version-src]][npm-version-href]
4
+ [![InstallSize][install-size-src]][install-size-src]
5
+ [![JSR][jsr-src]][jsr-href]
6
+
7
+ > dry-run option plugin for gunshi.
8
+
9
+ This plugin provides dry-run support for CLI applications, allowing command authors to mark side-effect operations that should be skipped when users pass `--dry-run`.
10
+
11
+ ## 💿 Installation
12
+
13
+ ```sh
14
+ # npm
15
+ npm install --save @gunshi/plugin-dryrun
16
+
17
+ # pnpm
18
+ pnpm add @gunshi/plugin-dryrun
19
+
20
+ # yarn
21
+ yarn add @gunshi/plugin-dryrun
22
+
23
+ # deno
24
+ deno add jsr:@gunshi/plugin-dryrun
25
+
26
+ # bun
27
+ bun add @gunshi/plugin-dryrun
28
+ ```
29
+
30
+ ## 🚀 Usage
31
+
32
+ ```ts
33
+ import { cli, defineWithTypes } from 'gunshi'
34
+ import dryrun, { pluginId as dryrunId } from '@gunshi/plugin-dryrun'
35
+
36
+ import type { DryRunExtension } from '@gunshi/plugin-dryrun'
37
+
38
+ const command = defineWithTypes<{
39
+ extensions: {
40
+ [dryrunId]: DryRunExtension
41
+ }
42
+ }>()({
43
+ name: 'deploy',
44
+ async run(ctx) {
45
+ const dryRun = ctx.extensions[dryrunId]
46
+
47
+ await dryRun.run(
48
+ async function build() {
49
+ // build artifacts
50
+ },
51
+ {
52
+ message: 'build artifacts'
53
+ }
54
+ )
55
+ }
56
+ })
57
+
58
+ await cli(process.argv.slice(2), command, {
59
+ name: 'deploy-cli',
60
+ plugins: [
61
+ dryrun() // Adds the --dry-run option
62
+ ]
63
+ })
64
+ ```
65
+
66
+ When `--dry-run` is passed, the wrapped operation is skipped and the message is printed through `ctx.log()`:
67
+
68
+ ```txt
69
+ [dryrun] build artifacts
70
+ ```
4
71
 
5
72
  <!-- eslint-disable markdown/no-missing-label-refs -->
6
73
 
7
- > ![WARNING]
8
- > This package is still work in progress
74
+ > [!IMPORTANT]
75
+ > The dry-run plugin does not skip the whole command. It only skips operations that command authors explicitly pass to `run()` or `wrap()`, so commands can still validate input, resolve configuration, and print useful context.
9
76
 
10
77
  <!-- eslint-enable markdown/no-missing-label-refs -->
11
78
 
79
+ ## ✨ Features
80
+
81
+ ### Global Dry-run Option
82
+
83
+ This plugin adds a global `--dry-run` option to all commands.
84
+
85
+ You can customize the option key with the `name` option. For example, `name: 'pretend'` maps to `--pretend`.
86
+
87
+ ### Explicit Side-effect Control
88
+
89
+ Dry-run behavior is opt-in per operation. Use:
90
+
91
+ - `run()`: Run or skip a single side-effect task
92
+ - `wrap()`: Wrap an existing function so every call respects dry-run mode
93
+
94
+ ### Fallback Results
95
+
96
+ For non-void operations, provide `result` or `resolve` so command code can continue in dry-run mode without executing the real side effect.
97
+
98
+ ```ts
99
+ const releaseId = await dryRun.run(
100
+ async function createRelease() {
101
+ return await api.createRelease()
102
+ },
103
+ {
104
+ result: 'dry-run-release',
105
+ message: 'create release'
106
+ }
107
+ )
108
+ ```
109
+
110
+ ### Wrapping Existing Functions
111
+
112
+ `wrap()` is useful when you already have a side-effect function, such as a function from `node:fs`.
113
+
114
+ ```ts
115
+ import { mkdir, writeFile } from 'node:fs/promises'
116
+
117
+ const writeOutputFile = dryRun.wrap(writeFile, {
118
+ message: 'write output file'
119
+ })
120
+
121
+ await dryRun.run(
122
+ async function createOutputDirectory() {
123
+ await mkdir('dist', { recursive: true })
124
+ },
125
+ {
126
+ message: 'create output directory'
127
+ }
128
+ )
129
+
130
+ await writeOutputFile('dist/result.json', JSON.stringify({ ok: true }, null, 2))
131
+ ```
132
+
133
+ ## ⚙️ Plugin Options
134
+
135
+ ### `name`
136
+
137
+ - Type: `string`
138
+ - Default: `'dryRun'`
139
+ - Description: The command value key for the dry-run option. With Gunshi's default kebab-case option handling, `dryRun` maps to `--dry-run`.
140
+
141
+ ### `description`
142
+
143
+ - Type: `string`
144
+ - Default: `'Show what would be executed without running side effects'`
145
+ - Description: Fallback description for the dry-run global option.
146
+
147
+ ### `descriptionResources`
148
+
149
+ - Type: `Record<string, string>`
150
+ - Default: `{}`
151
+ - Description: Localized global option descriptions used with `@gunshi/plugin-i18n`.
152
+
153
+ ### `prefix`
154
+
155
+ - Type: `string`
156
+ - Default: `'[dryrun]'`
157
+ - Description: Prefix printed before dry-run messages.
158
+
159
+ ## 🔗 Plugin Dependencies
160
+
161
+ The dry-run plugin has an optional dependency on the i18n plugin:
162
+
163
+ - **Plugin ID**: `g:i18n` (optional)
164
+ - **Purpose**: Provides localized descriptions for the dry-run global option
165
+ - **Effect**: When the i18n plugin is present, the dry-run option description can be localized through `descriptionResources`
166
+
167
+ Example with i18n resources:
168
+
169
+ ```ts
170
+ dryrun({
171
+ description: 'Show what would be executed without running side effects',
172
+ descriptionResources: {
173
+ 'ja-JP': '副作用のある処理を実行せず、実行予定の内容を表示する'
174
+ }
175
+ })
176
+ ```
177
+
178
+ ## 🧩 Context Extensions
179
+
180
+ When using the dry-run plugin, your command context is extended via `ctx.extensions['g:dryrun']`.
181
+
182
+ <!-- eslint-disable markdown/no-missing-label-refs -->
183
+
184
+ > [!IMPORTANT]
185
+ > This plugin extension is namespaced in `CommandContext.extensions` using this plugin ID `g:dryrun` by the gunshi plugin system.
186
+
187
+ <!-- eslint-enable markdown/no-missing-label-refs -->
188
+
189
+ Available extensions:
190
+
191
+ <!-- eslint-disable markdown/no-missing-label-refs -->
192
+
193
+ > [!NOTE]
194
+ > The `Awaitable<T>` type used in the method signatures below is equivalent to `T | Promise<T>`, meaning the methods can return either a value directly or a Promise that resolves to that value.
195
+
196
+ <!-- eslint-enable markdown/no-missing-label-refs -->
197
+
198
+ - `enabled: boolean`: Whether dry-run mode is enabled for the current command.
199
+
200
+ - `run<R>(task, options): Awaitable<R>`: Run a side-effect task normally, or skip it and print a dry-run message when dry-run mode is enabled.
201
+
202
+ - `wrap<A, R>(fn, options): (...args: A) => Awaitable<R>`: Wrap an existing side-effect function so calls are skipped and logged when dry-run mode is enabled.
203
+
204
+ ### Usage Example
205
+
206
+ ```ts
207
+ import dryrun, { pluginId as dryrunId } from '@gunshi/plugin-dryrun'
208
+ import { cli, defineWithTypes } from 'gunshi'
209
+
210
+ import type { DryRunExtension } from '@gunshi/plugin-dryrun'
211
+
212
+ const command = defineWithTypes<{
213
+ extensions: {
214
+ [dryrunId]: DryRunExtension
215
+ }
216
+ }>()({
217
+ name: 'publish',
218
+ async run(ctx) {
219
+ const dryRun = ctx.extensions[dryrunId]
220
+
221
+ if (dryRun.enabled) {
222
+ console.log('Previewing publish steps')
223
+ }
224
+
225
+ await dryRun.run(
226
+ async function publishPackage() {
227
+ // Publish package here
228
+ },
229
+ {
230
+ message: 'publish package'
231
+ }
232
+ )
233
+ }
234
+ })
235
+
236
+ await cli(process.argv.slice(2), command, {
237
+ plugins: [dryrun()]
238
+ })
239
+ ```
240
+
241
+ ## 📚 API References
242
+
243
+ See the [API References](./docs/index.md)
244
+
12
245
  ## ©️ License
13
246
 
14
247
  [MIT](http://opensource.org/licenses/MIT)
248
+
249
+ <!-- Badges -->
250
+
251
+ [npm-version-src]: https://img.shields.io/npm/v/@gunshi/plugin-dryrun?style=flat
252
+ [npm-version-href]: https://npmjs.com/package/@gunshi/plugin-dryrun@alpha
253
+ [jsr-src]: https://jsr.io/badges/@gunshi/plugin-dryrun
254
+ [jsr-href]: https://jsr.io/@gunshi/plugin-dryrun
255
+ [install-size-src]: https://pkg-size.dev/badge/install/@gunshi/plugin-dryrun
package/lib/index.d.ts CHANGED
@@ -1,20 +1,102 @@
1
- import { PluginWithoutExtension } from "@gunshi/plugin";
1
+ import { Awaitable, PluginWithExtension } from "@gunshi/plugin";
2
2
 
3
3
  //#region src/index.d.ts
4
- /**
5
- * @author kazuya kawaguchi (a.k.a. kazupon)
6
- * @license MIT
7
- */
8
4
 
9
5
  /**
10
- * Dry run command context.
6
+ * The unique identifier for dry-run plugin.
7
+ */
8
+ declare const pluginId: "g:dryrun";
9
+ /**
10
+ * Type representing the unique identifier for dry-run plugin.
11
+ */
12
+ type PluginId = typeof pluginId;
13
+ /**
14
+ * dry-run plugin options.
15
+ */
16
+ interface DryRunPluginOptions {
17
+ /**
18
+ * command values key for dry-run option.
19
+ *
20
+ * @default 'dryRun'
21
+ */
22
+ name?: string;
23
+ /**
24
+ * fallback dry-run option description.
25
+ */
26
+ description?: string;
27
+ /**
28
+ * localized dry-run option descriptions, used with `@gunshi/plugin-i18n`.
29
+ */
30
+ descriptionResources?: Record<string, string>;
31
+ /**
32
+ * dry-run output prefix.
33
+ *
34
+ * @default '[dryrun]'
35
+ */
36
+ prefix?: string;
37
+ }
38
+ /**
39
+ * dry-run output message option.
40
+ */
41
+ interface DryRunMessage {
42
+ /**
43
+ * dry-run output message.
44
+ */
45
+ message?: string;
46
+ }
47
+ /**
48
+ * dry-run result option for `run()`.
49
+ */
50
+ type DryRunRunResult<R> = {
51
+ result: R;
52
+ } | {
53
+ resolve: () => Awaitable<R>;
54
+ };
55
+ /**
56
+ * dry-run result option for `wrap()`.
57
+ */
58
+ type DryRunWrapResult<A extends unknown[], R> = {
59
+ result: R;
60
+ } | {
61
+ resolve: (...args: A) => Awaitable<R>;
62
+ };
63
+ /**
64
+ * dry-run options tuple for `run()` and `wrap()`.
65
+ *
66
+ * Non-void operations require a fallback result option so dry-run mode can return a value without executing the side effect.
67
+ */
68
+ type DryRunOptionsArg<R, O> = [Awaited<R>] extends [void] ? [options?: DryRunMessage & Partial<O>] : [options: DryRunMessage & O];
69
+ /**
70
+ * dry-run plugin extension.
11
71
  */
12
- interface DryRunCommandContext {}
72
+ interface DryRunExtension {
73
+ /**
74
+ * Whether dry-run mode is enabled.
75
+ */
76
+ readonly enabled: boolean;
77
+ /**
78
+ * Run a side-effect task, or skip it in dry-run mode.
79
+ *
80
+ * @param task - A side-effect task
81
+ * @param options - Dry-run message and fallback result options.
82
+ * @returns The task result, or dry-run fallback result
83
+ */
84
+ run<R>(task: () => Awaitable<R>, ...options: DryRunOptionsArg<R, DryRunRunResult<R>>): Awaitable<R>;
85
+ /**
86
+ * Wrap a side-effect function, or skip it in dry-run mode.
87
+ *
88
+ * @param fn - A side-effect function
89
+ * @param options - Dry-run message and fallback result options.
90
+ * @returns A wrapped function
91
+ */
92
+ wrap<A extends unknown[], R>(fn: (...args: A) => Awaitable<R>, ...options: DryRunOptionsArg<R, DryRunWrapResult<A, R>>): (...args: A) => Awaitable<R>;
93
+ }
13
94
  /**
14
- * dryrun plugin
95
+ * dry-run plugin
15
96
  *
16
- * @returns A defined plugin as dryrun
97
+ * @param options - A {@linkcode DryRunPluginOptions | dry-run plugin options}
98
+ * @returns A defined plugin as dry-run
17
99
  */
18
- declare function dryrun(): PluginWithoutExtension<DryRunCommandContext>;
100
+ declare function dryrun(options?: DryRunPluginOptions): PluginWithExtension<DryRunExtension>;
19
101
  //#endregion
20
- export { DryRunCommandContext, dryrun as default };
102
+ export { DryRunExtension, DryRunMessage, DryRunOptionsArg, DryRunPluginOptions, DryRunRunResult, DryRunWrapResult, PluginId, dryrun as default, pluginId };
package/lib/index.js CHANGED
@@ -1,20 +1,121 @@
1
1
  import { plugin } from "@gunshi/plugin";
2
2
  //#region src/index.ts
3
3
  /**
4
+ * The entry point of dry-run plugin
5
+ *
6
+ * @example
7
+ * ```js
8
+ * import { cli } from 'gunshi'
9
+ * import dryrun from '@gunshi/plugin-dryrun'
10
+ *
11
+ * const command = {
12
+ * name: 'deploy',
13
+ * async run(ctx) {
14
+ * const dryRun = ctx.extensions['g:dryrun']
15
+ *
16
+ * await dryRun.run(
17
+ * async function build() {
18
+ * // build artifacts
19
+ * },
20
+ * {
21
+ * message: 'build artifacts'
22
+ * }
23
+ * )
24
+ * }
25
+ * }
26
+ *
27
+ * await cli(process.argv.slice(2), command, {
28
+ * plugins: [
29
+ * dryrun()
30
+ * ]
31
+ * })
32
+ * ```
33
+ *
34
+ * @module
35
+ */
36
+ /**
4
37
  * @author kazuya kawaguchi (a.k.a. kazupon)
5
38
  * @license MIT
6
39
  */
7
40
  /**
8
- * dryrun plugin
41
+ * The unique identifier for dry-run plugin.
42
+ */
43
+ const pluginId = "g:dryrun";
44
+ const i18nPluginId = "g:i18n";
45
+ const defaultDescription = "Show what would be executed without running side effects";
46
+ /**
47
+ * dry-run plugin
9
48
  *
10
- * @returns A defined plugin as dryrun
49
+ * @param options - A {@linkcode DryRunPluginOptions | dry-run plugin options}
50
+ * @returns A defined plugin as dry-run
11
51
  */
12
- function dryrun() {
52
+ function dryrun(options = {}) {
53
+ const optionName = options.name ?? "dryRun";
54
+ const description = resolveDescription(options);
55
+ const descriptionResources = resolveDescriptionResources(options, description);
56
+ const prefix = options.prefix ?? "[dryrun]";
13
57
  return plugin({
14
- id: "g:dryrun",
58
+ id: pluginId,
15
59
  name: "dryrun",
16
- setup(_ctx) {}
60
+ dependencies: [{
61
+ id: i18nPluginId,
62
+ optional: true
63
+ }],
64
+ extension(ctx) {
65
+ const enabled = ctx.values[optionName] === true;
66
+ function resolveMessage(fn, message) {
67
+ return message || fn.name || "anonymous";
68
+ }
69
+ function output(fn, message) {
70
+ ctx.log(`${prefix} ${resolveMessage(fn, message)}`);
71
+ }
72
+ function resolveRunResult(options) {
73
+ if (!options) return;
74
+ if ("resolve" in options && options.resolve) return options.resolve();
75
+ if ("result" in options) return options.result;
76
+ }
77
+ function resolveWrapResult(args, options) {
78
+ if (!options) return;
79
+ if ("resolve" in options && options.resolve) return options.resolve(...args);
80
+ if ("result" in options) return options.result;
81
+ }
82
+ return {
83
+ enabled,
84
+ run(task, ...options) {
85
+ const [dryRunOptions] = options;
86
+ if (!enabled) return task();
87
+ output(task, dryRunOptions?.message);
88
+ return resolveRunResult(dryRunOptions);
89
+ },
90
+ wrap(fn, ...options) {
91
+ const [dryRunOptions] = options;
92
+ return (...args) => {
93
+ if (!enabled) return fn(...args);
94
+ output(fn, dryRunOptions?.message);
95
+ return resolveWrapResult(args, dryRunOptions);
96
+ };
97
+ }
98
+ };
99
+ },
100
+ setup(ctx) {
101
+ ctx.addGlobalOption(optionName, {
102
+ type: "boolean",
103
+ description
104
+ });
105
+ },
106
+ onExtension(ctx) {
107
+ ctx.extensions[i18nPluginId]?.registerGlobalOptionResources(optionName, descriptionResources);
108
+ }
17
109
  });
18
110
  }
111
+ function resolveDescription(options) {
112
+ return options.description ?? options.descriptionResources?.["en-US"] ?? Object.values(options.descriptionResources ?? {})[0] ?? defaultDescription;
113
+ }
114
+ function resolveDescriptionResources(options, description) {
115
+ return {
116
+ ...options.descriptionResources,
117
+ "en-US": description
118
+ };
119
+ }
19
120
  //#endregion
20
- export { dryrun as default };
121
+ export { dryrun as default, pluginId };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@gunshi/plugin-dryrun",
3
- "description": "dryrun option plugin for gunshi",
4
- "version": "0.31.0",
3
+ "description": "dry-run option plugin for gunshi",
4
+ "version": "0.33.0",
5
5
  "author": {
6
6
  "name": "kazuya kawaguchi",
7
7
  "email": "kawakazu80@gmail.com"
@@ -18,7 +18,7 @@
18
18
  },
19
19
  "keywords": [
20
20
  "gunshi",
21
- "completion",
21
+ "dryrun",
22
22
  "plugin",
23
23
  "cli"
24
24
  ],
@@ -52,17 +52,20 @@
52
52
  }
53
53
  },
54
54
  "dependencies": {
55
- "@gunshi/plugin": "0.31.0"
55
+ "@gunshi/plugin": "0.33.0"
56
56
  },
57
57
  "devDependencies": {
58
58
  "deno": "^2.7.14",
59
59
  "jsr": "^0.14.3",
60
60
  "jsr-exports-lint": "^0.4.2",
61
61
  "publint": "^0.3.20",
62
- "tsdown": "0.21.0"
62
+ "tsdown": "0.21.0",
63
+ "typedoc": "^0.28.19",
64
+ "typedoc-plugin-markdown": "^4.11.0"
63
65
  },
64
66
  "scripts": {
65
67
  "build": "tsdown",
68
+ "build:docs": "typedoc --excludeInternal",
66
69
  "lint:jsr": "jsr publish --dry-run --allow-dirty",
67
70
  "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
68
71
  }