@gunshi/docs 0.27.0-beta.6 → 0.27.2

package/bin/init.js

@@ -7,6 +7,10 @@ import readline from 'node:readline'
 import { x } from 'tinyexec'
 import { installPackage } from '@antfu/install-pkg'
 
+const { version } = JSON.parse(
+  await fs.readFile(path.join(import.meta.dirname, '../package.json'), 'utf8')
+)
+
 const SKILL_NAME = 'use-gunshi-cli'
 
 const USE_GUNSHI_PROMPT = `
@@ -141,9 +145,9 @@ if (answer === 'y' || answer === 'yes') {
   console.log('\nInstalling gunshi and @gunshi/docs...')
   try {
     // Install gunshi as a production dependency
-    await installPackage(['gunshi'], { dev: false })
+    await installPackage([`gunshi@${version}`], { dev: false })
     // Install @gunshi/docs as a dev dependency (for LLM-assisted development)
-    await installPackage(['@gunshi/docs'], { dev: true })
+    await installPackage([`@gunshi/docs@${version}`], { dev: true })
     console.log('Successfully installed gunshi and @gunshi/docs')
   } catch (error) {
     console.error('Failed to install packages:', error.message)

package/package.json

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

package/src/api/default/functions/cli.md

@@ -22,6 +22,34 @@ A [CLI options](../interfaces/CliOptions.md)
 
 ## Call Signature
 
+```ts
+function cli(
+   args, 
+   entry, 
+options?): Promise<string | undefined>;
+```
+
+Run the command.
+
+This overload accepts any command-like object using a loose structural type.
+It bypasses TypeScript contravariance issues with callback properties.
+
+### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `args` | `string`[] | Command line arguments |
+| `entry` | [`SubCommandable`](../interfaces/SubCommandable.md) | A command-like object (command, command runner, or lazy command) |
+| `options?` | [`CliOptions`](../interfaces/CliOptions.md)\<[`DefaultGunshiParams`](../type-aliases/DefaultGunshiParams.md)\> | A [CLI options](../interfaces/CliOptions.md) |
+
+### Returns
+
+`Promise`\<`string` \| `undefined`\>
+
+A rendered usage or undefined. if you will use [`CliOptions.usageSilent`](../interfaces/CliOptions.md#usagesilent) option, it will return rendered usage string.
+
+## Call Signature
+
 ```ts
 function cli<G>(
    args, 

package/src/api/default/index.md

@@ -61,6 +61,7 @@ import { cli } from 'gunshi'
 | [PluginWithExtension](interfaces/PluginWithExtension.md) | Plugin return type with extension, which includes the plugin ID, name, dependencies, and extension. |
 | [PluginWithoutExtension](interfaces/PluginWithoutExtension.md) | Plugin return type without extension, which includes the plugin ID, name, and dependencies, but no extension. |
 | [RenderingOptions](interfaces/RenderingOptions.md) | Rendering control options |
+| [SubCommandable](interfaces/SubCommandable.md) | Sub-command entry type for use in subCommands. |
 
 ## References
 

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

@@ -27,7 +27,7 @@ CLI options of [`cli`](../functions/cli.md) function.
 | <a id="renderheader"></a> `renderHeader?` | (`ctx`) => `Promise`\<`string`\> \| `null` | Render function the header section in the command usage. |
 | <a id="renderusage"></a> `renderUsage?` | (`ctx`) => `Promise`\<`string`\> \| `null` | Render function the command usage. |
 | <a id="rendervalidationerrors"></a> `renderValidationErrors?` | (`ctx`, `error`) => `Promise`\<`string`\> \| `null` | Render function the validation errors. |
-| <a id="subcommands"></a> `subCommands?` | \| `Map`\<`string`, \| [`Command`](Command.md)\<`any`\> \| [`LazyCommand`](../type-aliases/LazyCommand.md)\<`any`, \{ \}\>\> \| `Record`\<`string`, \| [`Command`](Command.md)\<`any`\> \| [`LazyCommand`](../type-aliases/LazyCommand.md)\<`any`, \{ \}\>\> | Sub commands. |
+| <a id="subcommands"></a> `subCommands?` | \| `Record`\<`string`, [`SubCommandable`](SubCommandable.md)\> \| `Map`\<`string`, [`SubCommandable`](SubCommandable.md)\> | Sub commands. |
 | <a id="usageoptiontype"></a> `usageOptionType?` | `boolean` | Whether to display the usage optional argument type. |
 | <a id="usageoptionvalue"></a> `usageOptionValue?` | `boolean` | Whether to display the optional argument value. |
 | <a id="usagesilent"></a> `usageSilent?` | `boolean` | Whether to display the command usage. |

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

@@ -0,0 +1,35 @@
+[gunshi](../../index.md) / [default](../index.md) / SubCommandable
+
+# Interface: SubCommandable
+
+Sub-command entry type for use in subCommands.
+
+This type uses a loose structural match to bypass TypeScript's contravariance issues
+with function parameters, allowing any Command or LazyCommand to be used as a sub-command.
+
+## Since
+
+v0.27.1
+
+## Indexable
+
+```ts
+[key: string]: any
+```
+
+Index signature to allow additional properties
+
+## Properties
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="args"></a> `args?` | [`Args`](Args.md) \| `Record`\<`string`, `any`\> | Command arguments - accepts any args structure |
+| <a id="commandname"></a> `commandName?` | `string` | Command name for lazy commands |
+| <a id="description"></a> `description?` | `string` | Command description |
+| <a id="entry"></a> `entry?` | `boolean` | Whether this is an entry command |
+| <a id="examples"></a> `examples?` | `string` \| (...`args`) => `any` | Command examples |
+| <a id="internal"></a> `internal?` | `boolean` | Whether this is an internal command |
+| <a id="name"></a> `name?` | `string` | Command name |
+| <a id="rendering"></a> `rendering?` | `any` | Rendering options |
+| <a id="run"></a> `run?` | (...`args`) => `any` | Command runner |
+| <a id="tokebab"></a> `toKebab?` | `boolean` | Whether to convert camelCase to kebab-case |

package/src/guide/advanced/command-hooks.md

@@ -52,34 +52,32 @@ The following example demonstrates how to configure lifecycle hooks when initial
 In this setup, we define three hooks that will execute at different stages of the command lifecycle:
 
 ```ts [cli.ts]
-import { cli } from 'gunshi'
+import { cli, define } from 'gunshi'
 
-await cli(
-  process.argv.slice(2),
-  {
-    name: 'server',
-    run: () => {
-      console.log('Starting server...')
-    }
-  },
-  {
-    name: 'my-app',
-    version: '1.0.0',
+const command = define({
+  name: 'server',
+  run: () => {
+    console.log('Starting server...')
+  }
+})
+
+await cli(process.argv.slice(2), command, {
+  name: 'my-app',
+  version: '1.0.0',
 
-    // Define lifecycle hooks
-    onBeforeCommand: ctx => {
-      console.log(`About to run: ${ctx.name}`)
-    },
+  // Define lifecycle hooks
+  onBeforeCommand: ctx => {
+    console.log(`About to run: ${ctx.name}`)
+  },
 
-    onAfterCommand: (ctx, result) => {
-      console.log(`Command ${ctx.name} completed successfully`)
-    },
+  onAfterCommand: (ctx, result) => {
+    console.log(`Command ${ctx.name} completed successfully`)
+  },
 
-    onErrorCommand: (ctx, error) => {
-      console.error(`Command ${ctx.name} failed:`, error)
-    }
+  onErrorCommand: (ctx, error) => {
+    console.error(`Command ${ctx.name} failed:`, error)
   }
-)
+})
 ```
 
 <!-- eslint-disable markdown/no-missing-label-refs -->

package/src/guide/advanced/internationalization.md

@@ -153,16 +153,16 @@ MY_LANG=ja-JP node cli.ts --name 田中 --formal
 The `@gunshi/resources` package provides pre-translated resources for common CLI terms:
 
 ```ts
-import { cli } from 'gunshi'
+import { cli, define } from 'gunshi'
 import i18n from '@gunshi/plugin-i18n'
 import resources from '@gunshi/resources'
 
-const command = {
+const command = define({
   name: 'app',
   run: ctx => {
     console.log('Application running')
   }
-}
+})
 
 await cli(process.argv.slice(2), command, {
   name: 'my-app',

package/src/guide/essentials/declarative.md

@@ -13,7 +13,9 @@ In that guide, we created a simple greeting command. As your CLI grows with more
 A declaratively configured command in Gunshi follows this structure:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   // Command metadata
   name: 'command-name',
   description: 'Command description',
@@ -30,7 +32,7 @@ const command = {
   run: ctx => {
     // Command implementation
   }
-}
+})
 ```
 
 Let's see how this structure works in practice with a complete example.
@@ -42,10 +44,10 @@ Let's start with a simple example that demonstrates the declarative approach.
 We'll build a greeting command with a few basic options:
 
 ```js [cli.js]
-import { cli } from 'gunshi'
+import { cli, define } from 'gunshi'
 
 // Define a command with declarative configuration
-const command = {
+const command = define({
   // Command metadata
   name: 'greet',
   description: 'A greeting command with declarative configuration',
@@ -98,7 +100,7 @@ $ node cli.js --name Charlie --uppercase
 
     console.log(message)
   }
-}
+})
 
 // Run the command with the declarative configuration
 await cli(process.argv.slice(2), command, {
@@ -163,7 +165,7 @@ Each option can have the following properties:
   <!-- eslint-enable markdown/no-missing-label-refs -->
 - `description`: A description of what the option does
 - `default`: Default value if the option is not provided
-- `required`: Set to `true` if the option is required (Note: Positional arguments defined with `type: 'positional'` are implicitly required by the parser).
+- `required`: Set to `true` if the option is required (Note: Positional arguments defined with `type: 'positional'` without `multiple: true` are implicitly required by the parser).
 - `multiple`: Set to `true` if multiple option values are allowed
 - `toKebab`: Set to `true` to convert camelCase argument names to kebab-case in help text and command-line usage
 - `parse`: A function to parse and validate the argument value. Required when `type` is 'custom'
@@ -178,7 +180,9 @@ The _key_ you use for the argument in the `args` object serves as its name for a
 Here's how you define positional arguments in your command configuration:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   args: {
     // ... other options
 
@@ -195,7 +199,7 @@ const command = {
     }
     // ... potentially more positional arguments
   }
-}
+})
 ```
 
 - **Implicitly Required**: Unlike named options which can be optional, positional arguments must always be provided by the user. When you define an argument with `type: 'positional'` in the schema, Gunshi expects it to be present on the command line. If it's missing, a validation error will occur. They cannot be truly optional like named flags.
@@ -214,6 +218,7 @@ Gunshi supports custom argument types with user-defined parsing functions, allow
 To define a custom argument type:
 
 ```js
+import { define } from 'gunshi'
 import { z } from 'zod'
 
 // custom schema with `zod`
@@ -222,7 +227,7 @@ const config = z.object({
   mode: z.string()
 })
 
-const command = {
+const command = define({
   name: 'example',
   description: 'Example command with custom argument types',
   args: {
@@ -264,7 +269,7 @@ const command = {
     console.log('Config:', ctx.values.config) // Parsed JSON object
     console.log('Port:', ctx.values.port) // Validated port number
   }
-}
+})
 ```
 
 Custom type arguments support:
@@ -295,7 +300,9 @@ Gunshi supports automatic conversion of camelCase argument names to kebab-case w
    To apply kebab-case conversion to all arguments in a command, set the `toKebab` property at the command level:
 
    ```js
-   const command = {
+   import { define } from 'gunshi'
+
+   const command = define({
      name: 'example',
      description: 'Example command',
      toKebab: true, // Apply to all arguments
@@ -306,7 +313,7 @@ Gunshi supports automatic conversion of camelCase argument names to kebab-case w
      run: ctx => {
        /* ... */
      }
-   }
+   })
    ```
 
 2. **Argument level**: Apply to specific arguments only
@@ -314,7 +321,9 @@ Gunshi supports automatic conversion of camelCase argument names to kebab-case w
    Alternatively, you can apply kebab-case conversion to specific arguments only by setting it at the argument level:
 
    ```js
-   const command = {
+   import { define } from 'gunshi'
+
+   const command = define({
      name: 'example',
      description: 'Example command',
      args: {
@@ -327,7 +336,7 @@ Gunshi supports automatic conversion of camelCase argument names to kebab-case w
      run: ctx => {
        /* ... */
      }
-   }
+   })
    ```
 
 When `toKebab` is enabled:
@@ -367,7 +376,9 @@ You can define mutually exclusive options using the `conflicts` property.
 This ensures that conflicting options cannot be used together:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   name: 'server',
   description: 'Server configuration',
   args: {
@@ -410,7 +421,7 @@ const command = {
       // Minimal output
     }
   }
-}
+})
 ```
 
 When conflicting options are used together, Gunshi will throw an error:
@@ -430,7 +441,9 @@ This helps users understand how to use your command correctly and is displayed i
 You can provide examples as a simple string:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   name: 'copy',
   description: 'Copy files',
   args: {
@@ -452,7 +465,7 @@ const command = {
   run: ctx => {
     // Implementation
   }
-}
+})
 ```
 
 #### Multiple Examples
@@ -460,7 +473,9 @@ const command = {
 For multiple examples, use a multi-line string with clear formatting:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   name: 'deploy',
   description: 'Deploy application',
   args: {
@@ -496,7 +511,7 @@ deploy --environment production --tag latest --dry-run
   run: ctx => {
     // Implementation
   }
-}
+})
 ```
 
 #### Dynamic Examples
@@ -506,7 +521,9 @@ You can also provide examples as a function that returns a string.
 This is useful when examples need to be generated dynamically or localized:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   name: 'serve',
   description: 'Start development server',
   args: {
@@ -543,7 +560,7 @@ ${appName} -h 192.168.1.100 -p 8080
   run: ctx => {
     console.log(`Server starting on ${ctx.values.host}:${ctx.values.port}`)
   }
-}
+})
 ```
 
 #### Formatted Examples with Descriptions
@@ -551,7 +568,9 @@ ${appName} -h 192.168.1.100 -p 8080
 For better readability, you can include descriptions with your examples:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   name: 'git-flow',
   description: 'Git flow commands',
   args: {
@@ -587,7 +606,7 @@ Notes:
   run: ctx => {
     // Implementation
   }
-}
+})
 ```
 
 #### Async Examples
@@ -597,7 +616,9 @@ For complex CLIs that need to load examples from external files or generate them
 When using the function form, you can return a Promise for async example generation:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   name: 'config',
   description: 'Manage configuration',
   args: {
@@ -627,7 +648,7 @@ config --get "api.key"
   run: ctx => {
     // Implementation
   }
-}
+})
 ```
 
 The examples are displayed when users run the command with `--help` flag, making it easier for them to understand the correct usage.
@@ -658,7 +679,9 @@ The `run` function receives a command context object (`ctx`) with:
 Among the context properties, the `explicit` property deserves special attention as it allows you to determine whether an argument was explicitly provided by the user or if it's using a default value:
 
 ```js
-const command = {
+import { define } from 'gunshi'
+
+const command = define({
   name: 'deploy',
   args: {
     environment: {
@@ -683,7 +706,7 @@ const command = {
       console.log('User explicitly requested force mode')
     }
   }
-}
+})
 ```
 
 This feature is particularly useful for:

package/src/guide/essentials/getting-started.md

@@ -86,9 +86,9 @@ Hello, Alice!
 Let's add some options to our command:
 
 ```js [cli.js]
-import { cli } from 'gunshi'
+import { cli, define } from 'gunshi'
 
-const command = {
+const command = define({
   name: 'greeter',
   description: 'A simple greeting CLI',
   args: {
@@ -113,7 +113,7 @@ const command = {
 
     console.log(greeting)
   }
-}
+})
 
 await cli(process.argv.slice(2), command)
 ```

package/src/guide/essentials/plugin-system.md

@@ -144,10 +144,9 @@ const resources = {
 const command = defineI18n({
   name: 'greet',
   description: 'Greet someone in their language',
-  // Resource function returns translations for the current locale
-  resource: async ctx => {
-    const locale = ctx.extensions['g:i18n'].locale
-    return resources[locale] || resources['en-US']
+  // Resource function receives locale and returns translations
+  resource: locale => {
+    return resources[locale.toString()] || resources['en-US']
   },
   args: {
     name: {
@@ -333,9 +332,8 @@ const resources = {
 const buildCommand = defineI18n({
   name: 'build',
   description: 'Build the project',
-  resource: async ctx => {
-    const locale = ctx.extensions['g:i18n'].locale
-    return resources[locale] || resources['en-US']
+  resource: locale => {
+    return resources[locale.toString()] || resources['en-US']
   },
   args: {
     mode: {

package/src/guide/introduction/setup.md

@@ -31,33 +31,6 @@ bun add gunshi
 
 :::
 
-### v0.27 Beta
-
-::: code-group
-
-```sh [npm]
-npm install --save gunshi@beta
-```
-
-```sh [pnpm]
-pnpm add gunshi@beta
-```
-
-```sh [yarn]
-yarn add gunshi@beta
-```
-
-```sh [deno]
-## you can specify version with `@`
-deno add jsr:@gunshi/gunshi@0.27.2
-```
-
-```sh [bun]
-bun add gunshi@beta
-```
-
-:::
-
 ## LLM-Assisted Development
 
 Gunshi provides tooling to integrate with AI coding assistants such as [Claude Code](https://claude.ai/code) and [Cursor](https://cursor.com/).
@@ -69,19 +42,19 @@ You can quickly set up LLM-assisted development for your project using the CLI t
 ::: code-group
 
 ```sh [npm]
-npx @gunshi/docs@beta
+npx @gunshi/docs
 ```
 
 ```sh [pnpm]
-pnpm dlx @gunshi/docs@beta
+pnpm dlx @gunshi/docs
 ```
 
 ```sh [yarn]
-yarn dlx @gunshi/docs@beta
+yarn dlx @gunshi/docs
 ```
 
 ```sh [bun]
-bun x @gunshi/docs@beta
+bun x @gunshi/docs
 ```
 
 :::
@@ -98,19 +71,19 @@ If you prefer manual configuration, install the documentation package as a dev d
 ::: code-group
 
 ```sh [npm]
-npm install --save-dev @gunshi/docs@beta gunshi@beta
+npm install --save-dev @gunshi/docs
 ```
 
 ```sh [pnpm]
-pnpm add -D @gunshi/docs@beta gunshi@beta
+pnpm add -D @gunshi/docs
 ```
 
 ```sh [yarn]
-yarn add -D @gunshi/docs@beta gunshi@beta
+yarn add -D @gunshi/docs
 ```
 
 ```sh [bun]
-bun add -D @gunshi/docs@beta gunshi@beta
+bun add -D @gunshi/docs
 ```
 
 :::

package/src/guide/plugin/guidelines.md

@@ -836,15 +836,15 @@ For other package managers, see [installation guide](./docs/install.md).
 <!-- eslint-disable markdown/no-missing-label-refs, markdown/no-space-in-emphasis -->
 
 \`\`\`ts
-import { cli } from 'gunshi'
+import { cli, define } from 'gunshi'
 import myPlugin from '@yourorg/gunshi-plugin-{name}'
 
-const command = {
+const command = define({
 name: 'example',
 run: ctx => {
 ctx.extensions['yourorg:{name}'].someMethod()
 }
-}
+})
 
 await cli(process.argv.slice(2), command, {
 plugins: [myPlugin({ /* options */ })]

package/src/guide/plugin/testing.md

@@ -51,6 +51,7 @@ The following test file demonstrates basic plugin testing, including initializat
 
 ```ts [src/plugin.test.ts]
 import { createCommandContext } from 'gunshi/plugin'
+import { define } from 'gunshi'
 import { describe, expect, test, vi } from 'vitest'
 import { myPlugin } from './plugin.ts'
 
@@ -65,11 +66,11 @@ describe('plugin initialization', () => {
 
   test('plugin extension factory creates correct methods', async () => {
     const plugin = myPlugin()
-    const mockCommand = {
+    const mockCommand = define({
       name: 'test',
       description: 'Test command',
       run: vi.fn()
-    }
+    })
 
     const mockContext = await createCommandContext({
       command: mockCommand
@@ -152,7 +153,7 @@ describe('configuration validation', () => {
 
   test('plugin uses configuration in extension', async () => {
     const plugin = myValidatingPlugin({ locale: 'ja-JP', timeout: 5000 })
-    const mockCommand = { name: 'test', description: 'Test', run: vi.fn() }
+    const mockCommand = define({ name: 'test', description: 'Test', run: vi.fn() })
 
     const ctx = await createCommandContext({ command: mockCommand })
     const extension = await plugin.extension.factory(ctx, mockCommand)
@@ -215,7 +216,7 @@ import { myPlugin } from './plugin.ts'
 test('extension factory creates correct extension', async () => {
   const plugin = myPlugin({ debug: true })
 
-  const command = { name: 'test', description: 'Test', run: vi.fn() }
+  const command = define({ name: 'test', description: 'Test', run: vi.fn() })
   const ctx = await createCommandContext({
     command,
     values: { verbose: true },
@@ -238,6 +239,7 @@ The following example demonstrates how to test extension methods that interact w
 
 ```ts [src/plugin.test.ts]
 import { createCommandContext } from 'gunshi/plugin'
+import { define } from 'gunshi'
 import { describe, expect, test, vi } from 'vitest'
 import { myPlugin } from './plugin.ts'
 
@@ -245,7 +247,7 @@ describe('extension methods', () => {
   test('showVersion displays version correctly', async () => {
     const plugin = myPlugin()
 
-    const command = { name: 'app', description: 'App', run: vi.fn() }
+    const command = define({ name: 'app', description: 'App', run: vi.fn() })
     const ctx = await createCommandContext({
       command,
       cliOptions: { version: '2.0.0', name: 'test-app' }
@@ -260,7 +262,7 @@ describe('extension methods', () => {
   test('handles missing version', async () => {
     const plugin = myPlugin()
 
-    const command = { name: 'app', description: 'App', run: vi.fn() }
+    const command = define({ name: 'app', description: 'App', run: vi.fn() })
     const ctx = await createCommandContext({
       command,
       cliOptions: { version: undefined, name: 'test-app' }
@@ -290,7 +292,7 @@ describe('async extension', () => {
       timeout: 5000
     })
     const plugin = myPlugin({ loadConfig })
-    const command = { name: 'test', description: 'Test', run: vi.fn() }
+    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
     const ctx = await createCommandContext({ command })
     const extension = await plugin.extension.factory(ctx, command)
 
@@ -305,7 +307,7 @@ describe('async extension', () => {
     const warnMock = vi.spyOn(console, 'warn').mockImplementation(() => {})
     const loadConfig = vi.fn().mockRejectedValue(new Error('Config not found'))
     const plugin = myPlugin({ loadConfig })
-    const command = { name: 'test', description: 'Test', run: vi.fn() }
+    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
     const ctx = await createCommandContext({ command })
     const extension = await plugin.extension.factory(ctx, command)
 
@@ -453,7 +455,7 @@ import { trackerPlugin } from './init-tracker.ts'
 describe('onExtension callback', () => {
   test('extension not initialized before onExtension', async () => {
     const plugin = trackerPlugin()
-    const command = { name: 'test', description: 'Test', run: vi.fn() }
+    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
     const ctx = await createCommandContext({ command })
     const extension = await plugin.extension.factory(ctx, command)
 
@@ -463,7 +465,7 @@ describe('onExtension callback', () => {
 
   test('onExtension initializes extension', async () => {
     const plugin = trackerPlugin()
-    const command = { name: 'deploy', description: 'Deploy', run: vi.fn() }
+    const command = define({ name: 'deploy', description: 'Deploy', run: vi.fn() })
     const ctx = await createCommandContext({ command })
     const extension = await plugin.extension.factory(ctx, command)
     await plugin.extension.onFactory?.(ctx, command)
@@ -695,7 +697,7 @@ import type { LoggingExtension, NotificationExtension } from './plugin.ts'
 
 describe('plugin interactions', () => {
   test('uses logger when available', async () => {
-    const command = { name: 'test', description: 'Test', run: vi.fn() }
+    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
 
     const logging = loggingPlugin()
     const notification = notificationPlugin()
@@ -720,7 +722,7 @@ describe('plugin interactions', () => {
   })
 
   test('falls back when logger missing', async () => {
-    const command = { name: 'test', description: 'Test', run: vi.fn() }
+    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
     const notification = notificationPlugin()
 
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})

package/src/release/v0.27.md

@@ -180,6 +180,30 @@ Use cases:
 - When built-in plugins conflict with your custom implementation
 - For embedded CLIs where every byte counts
 
+### `@gunshi/docs` - LLM-Assisted Development (Experimental)
+
+New package for integrating with AI coding assistants such as [Claude Code](https://claude.ai/code) and [Cursor](https://cursor.com/):
+
+```sh
+npx @gunshi/docs
+```
+
+This command automatically configures:
+
+- [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) at `.claude/skills/use-gunshi-cli/SKILL.md`
+- [Cursor rules](https://docs.cursor.com/context/rules-for-ai) at `.cursor/rules/use-gunshi-cli.mdc`
+- Updates `CLAUDE.md` with instructions to use the Gunshi skill
+
+Optionally, it can also install `gunshi` and `@gunshi/docs` packages for you.
+
+For manual setup, install the documentation package as a dev dependency:
+
+```sh
+npm install --save-dev @gunshi/docs
+```
+
+The package includes guide content and API references as markdown files in [llms.txt](https://llmstxt.org/) format, enabling AI assistants to provide accurate guidance when developing Gunshi CLI applications.
+
 ### Fallback to Entry Command
 
 New `fallbackToEntry` option enables graceful handling of unknown subcommands:
@@ -348,6 +372,35 @@ This feature enables:
 
 ## ⚡ Improvement Features
 
+### Multiple Positional Argument Usage Display
+
+The plugin-renderer now displays multiple positional arguments more clearly in usage output:
+
+- Required positional: `<name>`
+- Multiple positional: `[<name> ...]`
+- Required + multiple: `<name> [<name> ...]`
+
+This improvement helps users understand when a command accepts multiple positional arguments.
+
+### i18n Plugin: `registerGlobalOptionResources` Extension
+
+New extension method for dynamically registering global option resources:
+
+```ts
+const command = defineI18n({
+  name: 'app',
+  run: ctx => {
+    // Register custom global option descriptions
+    ctx.extensions['g:i18n'].registerGlobalOptionResources('custom-option', {
+      'en-US': 'Custom option description',
+      'ja-JP': 'カスタムオプションの説明'
+    })
+  }
+})
+```
+
+This enables plugins to register localized descriptions for global options dynamically.
+
 ### Type Safety Enhancements
 
 v0.27 brings comprehensive type safety improvements to all core APIs through generic type parameters, enabling full TypeScript inference for arguments and plugin extensions.
@@ -651,7 +704,7 @@ The i18n plugin comes with additional packages and helper functions to simplify
   // Define new command with i18n support
   const command = defineI18n({
     name: 'deploy',
-    resource: async ctx => ({
+    resource: locale => ({
       /* translations */
     }),
     run: ctx => {
@@ -661,7 +714,7 @@ The i18n plugin comes with additional packages and helper functions to simplify
 
   // Add i18n to existing command
   const enhancedCommand = withI18nResource(existingCommand, {
-    resource: async ctx => ({
+    resource: locale => ({
       /* translations */
     })
   })
@@ -706,12 +759,14 @@ New playground examples demonstrating:
 We'd like to thank all the contributors who made this release possible:
 
 - [@kazupon](https://github.com/kazupon) - Core maintainer, plugin system architect, i18n extraction, lifecycle hooks
-- [@yukukotani](https://github.com/yukukotani) - Fallback to entry command feature (#291)
-- [@sushichan044](https://github.com/sushichan044) - Explicit argument detection feature (#232)
-- [@43081j](https://github.com/43081j) - Exposed `Plugin` type (#159)
-- [@theoephraim](https://github.com/theoephraim) - Documentation improvements (#249)
-- [@lukekarrys](https://github.com/lukekarrys) - Documentation updates (#228)
-- [@BobbieGoede](https://github.com/BobbieGoede) - Fixed FUNDING.yml (#303)
+- [@yukukotani](https://github.com/yukukotani) - Fallback to entry command feature ([#291](https://github.com/kazupon/gunshi/pull/291))
+- [@sushichan044](https://github.com/sushichan044) - Explicit argument detection feature ([#232](https://github.com/kazupon/gunshi/pull/232))
+- [@43081j](https://github.com/43081j) - Exposed `Plugin` type ([#159](https://github.com/kazupon/gunshi/pull/159))
+- [@theoephraim](https://github.com/theoephraim) - Documentation improvements ([#249](https://github.com/kazupon/gunshi/pull/249))
+- [@lukekarrys](https://github.com/lukekarrys) - Documentation updates ([#228](https://github.com/kazupon/gunshi/pull/228))
+- [@BobbieGoede](https://github.com/BobbieGoede) - Fixed FUNDING.yml ([#303](https://github.com/kazupon/gunshi/pull/303))
+- [@ryoppippi](https://github.com/ryoppippi) - Docs init CLI feature ([#422](https://github.com/kazupon/gunshi/pull/422))
+- [@ota-meshi](https://github.com/ota-meshi) - Multiple positional argument usage display improvement ([#432](https://github.com/kazupon/gunshi/pull/432))
 
 Special thanks to the community for feedback and bug reports that helped shape v0.27!