gunshi 0.5.3 → 0.6.0

package/README.md

@@ -18,8 +18,8 @@ Gunshi is a modern javascript command-line library
 Gunshi is designed to simplify the creation of modern command-line interfaces:
 
 - 📏 **Simple**: Run the commands with a simple API.
-- 🛡️ **Type Safe**: Arguments parsing and options value resolution type-safely by [args-tokens](https://github.com/kazupon/args-tokens)
 - ⚙️ **Declarative configuration**: Configure the command modules declaratively.
+- 🛡️ **Type Safe**: Arguments parsing and options value resolution type-safely by [args-tokens](https://github.com/kazupon/args-tokens)
 - 🧩 **Composable**: Sub-commands that can be composed with modularized commands.
 - ⏳ **Lazy & Async**: Command modules lazy loading and asynchronously executing.
 - 📜 **Auto usage generation**: Automatic usage message generation with modularized commands.
@@ -62,52 +62,14 @@ Gunshi has a simple API that is a facade:
 ```js
 import { cli } from 'gunshi'
 
-// Run a simple command
-cli(process.argv.slice(2), () => {
-  console.log('Hello from Gunshi!')
+const args = process.argv.slice(2)
+// run a simple command
+cli(args, () => {
+  // something logic ...
+  console.log('Hello from Gunshi!', args)
 })
 ```
 
-### 🛡️ Type-Safe Arguments
-
-Gunshi provides type-safe argument parsing with TypeScript:
-
-```ts
-import { cli } from 'gunshi'
-import type { ArgOptions, Command, CommandContext } from 'gunshi'
-
-// Define interfaces for options and values
-interface UserOptions extends ArgOptions {
-  name: { type: 'string'; short: 'n' }
-  age: { type: 'number'; short: 'a'; default: number }
-  verbose: { type: 'boolean'; short: 'v' }
-}
-
-interface UserValues {
-  name?: string
-  age: number
-  verbose?: boolean
-}
-
-// Create a type-safe command
-const command: Command<UserOptions> = {
-  name: 'type-safe',
-  options: {
-    name: { type: 'string', short: 'n' },
-    age: { type: 'number', short: 'a', default: 25 },
-    verbose: { type: 'boolean', short: 'v' }
-  },
-  run: (ctx: CommandContext<UserOptions, UserValues>) => {
-    const { name, age, verbose } = ctx.values
-    console.log(`Hello, ${name || 'World'}! You are ${age} years old.`)
-  }
-}
-
-await cli(process.argv.slice(2), command)
-```
-
-For more detailed examples, check out the [playground/type-safe](https://github.com/kazupon/gunshi/tree/main/playground/type-safe) in the repository.
-
 ### ⚙️ Declarative Configuration
 
 Configure commands declaratively:
@@ -115,7 +77,7 @@ Configure commands declaratively:
 ```js
 import { cli } from 'gunshi'
 
-// Define a command with declarative configuration
+// define a command with declarative configuration, using commandable object
 const command = {
   name: 'greet',
   description: 'A greeting command',
@@ -139,6 +101,8 @@ const command = {
   }
 }
 
+// run a command that is defined above
+// (the 3rd argument of `cli` is the command option)
 cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0',
@@ -148,14 +112,60 @@ cli(process.argv.slice(2), command, {
 
 For more detailed examples, check out the [playground/declarative](https://github.com/kazupon/gunshi/tree/main/playground/declarative) in the repository.
 
+### 🛡️ Type-Safe Arguments
+
+Gunshi provides type-safe argument parsing with TypeScript:
+
+```ts
+import { cli } from 'gunshi'
+import type { ArgOptions, Command, CommandContext } from 'gunshi'
+
+// type-safe arguments parsing example
+// this demonstrates how to define and use typed command options with `satisfies`
+
+// define 'type-safe' command options with types
+const options = {
+  // define string option with short alias
+  name: {
+    type: 'string',
+    short: 'n'
+  },
+  // define number option with default value
+  age: {
+    type: 'number',
+    short: 'a',
+    default: 25
+  },
+  // define boolean flag
+  verbose: {
+    type: 'boolean',
+    short: 'v'
+  }
+} satisfies ArgOptions
+
+// define 'type-safe' command
+const command = {
+  name: 'type-safe',
+  options,
+  run: (ctx: CommandContext<UserOptions, UserValues>) => {
+    const { name, age, verbose } = ctx.values
+    console.log(`Hello, ${name || 'World'}! You are ${age} years old.`)
+  }
+} satisfies Command<typeof options>
+
+await cli(process.argv.slice(2), command)
+```
+
+For more detailed examples, check out the [playground/type-safe](https://github.com/kazupon/gunshi/tree/main/playground/type-safe) in the repository.
+
 ### 🧩 Composable Sub-commands
 
-Create a CLI with composable sub-commands:
+Run a CLI with composable sub-commands:
 
 ```js
 import { cli } from 'gunshi'
 
-// Define sub-commands
+// define 'create' command
 const createCommand = {
   name: 'create',
   description: 'Create a new resource',
@@ -167,6 +177,7 @@ const createCommand = {
   }
 }
 
+// define 'list' command
 const listCommand = {
   name: 'list',
   description: 'List all resources',
@@ -175,12 +186,12 @@ const listCommand = {
   }
 }
 
-// Create a Map of sub-commands
+// prepare a Map of sub-commands
 const subCommands = new Map()
 subCommands.set('create', createCommand)
 subCommands.set('list', listCommand)
 
-// Define the main command
+// define the main ('resource-manager') command
 const mainCommand = {
   name: 'resource-manager',
   description: 'Manage resources',
@@ -189,7 +200,7 @@ const mainCommand = {
   }
 }
 
-// Run the CLI with composable sub-commands
+// run the CLI with composable sub-commands
 cli(process.argv.slice(2), mainCommand, {
   name: 'my-app',
   version: '1.0.0',
@@ -206,28 +217,28 @@ Load commands lazily and execute them asynchronously:
 ```js
 import { cli } from 'gunshi'
 
-// Define a command that will be loaded lazily
+// define a command that will be loaded lazily
 const lazyCommand = async () => {
-  // Simulate async loading
+  // simulate async loading
   await new Promise(resolve => setTimeout(resolve, 1000))
 
-  // Return the actual command
+  // return the actual command
   return {
     name: 'lazy',
     description: 'A command that is loaded lazily',
     run: async ctx => {
-      // Async execution
+      // async execution
       await new Promise(resolve => setTimeout(resolve, 500))
       console.log('Command executed!')
     }
   }
 }
 
-// Create a Map of sub-commands with lazy-loaded commands
+// prepare a Map of sub-commands with lazy-loaded commands
 const subCommands = new Map()
 subCommands.set('lazy', lazyCommand)
 
-// Run the CLI with lazy-loaded commands
+// run the CLI with lazy-loaded commands
 cli(
   process.argv.slice(2),
   { name: 'main', run: () => {} },
@@ -255,6 +266,7 @@ const command = {
     recursive: { type: 'boolean', short: 'r' },
     operation: { type: 'string', short: 'o', required: true }
   },
+  // define usage with object
   usage: {
     options: {
       path: 'File or directory path',
@@ -264,11 +276,11 @@ const command = {
     examples: '# Example\n$ my-app --operation list --path ./src'
   },
   run: ctx => {
-    // Command implementation
+    // command implementation
   }
 }
 
-// Run with --help to see the automatically generated usage information
+// run with --help to see the automatically generated usage information
 cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0'
@@ -284,7 +296,7 @@ Customize the usage message generation:
 ```js
 import { cli } from 'gunshi'
 
-// Custom header renderer
+// define custom header renderer
 const customHeaderRenderer = ctx => {
   return Promise.resolve(`
 ╔═══════════════════════╗
@@ -295,7 +307,7 @@ Version: ${ctx.env.version}
 `)
 }
 
-// Custom usage renderer
+// define custom usage renderer
 const customUsageRenderer = ctx => {
   const lines = []
   lines.push('USAGE:')
@@ -303,7 +315,7 @@ const customUsageRenderer = ctx => {
   lines.push('')
   lines.push('OPTIONS:')
 
-  for (const [key, option] of Object.entries(ctx.options || {})) {
+  for (const [key, option] of Object.entries(ctx.options || Object.create(null))) {
     const shortFlag = option.short ? `-${option.short}, ` : '    '
     lines.push(`  ${shortFlag}--${key.padEnd(10)} ${ctx.translation(key)}`)
   }
@@ -311,7 +323,7 @@ const customUsageRenderer = ctx => {
   return Promise.resolve(lines.join('\n'))
 }
 
-// Run with custom renderers
+// run with custom renderers
 cli(
   process.argv.slice(2),
   { name: 'app', run: () => {} },
@@ -341,14 +353,14 @@ const command = {
     name: { type: 'string', short: 'n' },
     formal: { type: 'boolean', short: 'f' }
   },
-  // Resource fetcher for translations
+  // resource fetcher for translations
   resource: async ctx => {
     if (ctx.locale.toString() === 'ja-JP') {
       const resource = await import('./locales/ja-JP.json', { with: { type: 'json' } })
       return resource.default
     }
 
-    // Default to English
+    // default to English
     return enUS
   },
   run: ctx => {
@@ -358,12 +370,12 @@ const command = {
   }
 }
 
-// Run with locale support
+// run with locale support
 cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0',
-  // Set the locale via an environment variable
-  // If Node v21 or later is used, you can use the built-in `navigator.language` instead)
+  // set the locale via an environment variable
+  // if Node v21 or later is used, you can use the built-in `navigator.language` instead)
   locale: new Intl.Locale(process.env.MY_LOCALE || 'en-US')
 })
 ```
@@ -380,7 +392,7 @@ If you are interested in contributing to `gunshi`, I highly recommend checking o
 
 ## 💖 Credits
 
-This project is inspired by:
+This project is inspired and powered by:
 
 - [`citty`](https://github.com/unjs/citty), created by UnJS team and contributors
 - cline and claude 3.7 sonnet, examples and docs is generated

package/lib/context.d.ts

@@ -1,5 +1,5 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-veidyA82.js';
+import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-CxaX4FVV.js';
 
 /**
 * The default locale string, which format is BCP 47 language tag
@@ -43,7 +43,7 @@ interface CommandContextParams<
 * @returns A {@link CommandContext | command context}, which is readonly
 */
 declare function createCommandContext<
-	Options extends ArgOptions,
+	Options extends ArgOptions = ArgOptions,
 	Values = ArgValues<Options>
 >({ options, values, positionals, command, commandOptions, omitted }: CommandContextParams<Options, Values>): Promise<Readonly<CommandContext<Options, Values>>>;
 

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import { ArgOptions } from 'args-tokens';
 export { ArgOptionSchema, ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, c as CommandRunner, a as CommandOptions } from './types.d-veidyA82.js';
-export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, b as CommandContext, g as CommandEnvironment, h as CommandResource, i as CommandResourceFetcher, L as LazyCommand } from './types.d-veidyA82.js';
+import { C as Command, c as CommandRunner, a as CommandOptions } from './types.d-CxaX4FVV.js';
+export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, b as CommandContext, g as CommandEnvironment, h as CommandResource, i as CommandResourceFetcher, j as Commandable, L as LazyCommand } from './types.d-CxaX4FVV.js';
 
 /**
 * Run the command
@@ -9,6 +9,6 @@ export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBu
 * @param entry - A {@link Command | entry command} or an {@link CommandRunner | inline command runner}
 * @param opts - A {@link CommandOptions | command options}
 */
-declare function cli<Options extends ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<void>;
+declare function cli<Options extends ArgOptions = ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<string | undefined>;
 
 export { Command, CommandOptions, CommandRunner, cli };

package/lib/index.js

@@ -26,10 +26,13 @@ async function cli(args, entry, opts = {}) {
 		showVersion(ctx);
 		return;
 	}
-	await showHeader(ctx);
+	const usageBuffer = [];
+	const header = await showHeader(ctx);
+	if (header) usageBuffer.push(header);
 	if (values.help) {
-		await showUsage(ctx);
-		return;
+		const usage = await showUsage(ctx);
+		if (usage) usageBuffer.push(usage);
+		return usageBuffer.join("\n");
 	}
 	if (error) {
 		await showValidationErrors(ctx, error);
@@ -50,8 +53,11 @@ function getSubCommand(tokens) {
 }
 async function showUsage(ctx) {
 	if (ctx.env.renderUsage === null) return;
-	const render = ctx.env.renderUsage || renderUsage;
-	log(await render(ctx));
+	const usage = await (ctx.env.renderUsage || renderUsage)(ctx);
+	if (usage) {
+		log(usage);
+		return usage;
+	}
 }
 function showVersion(ctx) {
 	log(ctx.env.version);
@@ -62,6 +68,7 @@ async function showHeader(ctx) {
 	if (header) {
 		log(header);
 		log();
+		return header;
 	}
 }
 async function showValidationErrors(ctx, error) {

package/lib/renderer/index.d.ts

@@ -1,19 +1,19 @@
 import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from '../types.d-veidyA82.js';
+import { b as CommandContext } from '../types.d-CxaX4FVV.js';
 
 /**
 * Render the header
 * @param ctx A {@link CommandContext | command context}
 * @returns A rendered header
 */
-declare function renderHeader<Options extends ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
+declare function renderHeader<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
 
 /**
 * Render the usage
 * @param ctx A {@link CommandContext | command context}
 * @returns A rendered usage
 */
-declare function renderUsage<Options extends ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
+declare function renderUsage<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
 
 /**
 * Render the validation errors
@@ -21,6 +21,6 @@ declare function renderUsage<Options extends ArgOptions>(ctx: Readonly<CommandCo
 * @param error An {@link AggregateError} of option in `args-token` validation
 * @returns A rendered validation error
 */
-declare function renderValidationErrors<Options extends ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
+declare function renderValidationErrors<Options extends ArgOptions = ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{types.d-veidyA82.d.ts → types.d-CxaX4FVV.d.ts}

@@ -88,7 +88,7 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	* Sub commands
 	* @see {@link CommandOptions.subCommands}
 	*/
-	subCommands: Map<string, Command<Options> | LazyCommand<Options>> | undefined;
+	subCommands: Map<string, Command<any> | LazyCommand<any>> | undefined;
 	/**
 	* Render function the command usage
 	*/
@@ -105,7 +105,7 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 /**
 * Command options
 */
-interface CommandOptions<Options extends ArgOptions> {
+interface CommandOptions<Options extends ArgOptions = ArgOptions> {
 	/**
 	* Current working directory
 	*/
@@ -130,7 +130,7 @@ interface CommandOptions<Options extends ArgOptions> {
 	/**
 	* Sub commands
 	*/
-	subCommands?: Map<string, Command<Options> | LazyCommand<Options>>;
+	subCommands?: Map<string, Command<any> | LazyCommand<any>>;
 	/**
 	* Left margin of the command output
 	*/
@@ -161,7 +161,7 @@ interface CommandOptions<Options extends ArgOptions> {
 * @description Command context is the context of the command execution
 */
 interface CommandContext<
-	Options extends ArgOptions,
+	Options extends ArgOptions = ArgOptions,
 	Values = ArgValues<Options>
 > {
 	/**
@@ -227,7 +227,7 @@ interface CommandContext<
 /**
 * Command usage
 */
-interface CommandUsage<Options extends ArgOptions> {
+interface CommandUsage<Options extends ArgOptions = ArgOptions> {
 	/**
 	* Options usage
 	*/
@@ -240,7 +240,7 @@ interface CommandUsage<Options extends ArgOptions> {
 /**
 * Command interface
 */
-interface Command<Options extends ArgOptions> {
+interface Command<Options extends ArgOptions = ArgOptions> {
 	/**
 	* Command name
 	* @description
@@ -282,7 +282,7 @@ interface Command<Options extends ArgOptions> {
 * Command resource
 * @experimental
 */
-interface CommandResource<Options extends ArgOptions> {
+interface CommandResource<Options extends ArgOptions = ArgOptions> {
 	/**
 	* Command description
 	*/
@@ -302,16 +302,20 @@ interface CommandResource<Options extends ArgOptions> {
 * @returns A fetched {@link CommandResource | command resource}
 * @experimental
 */
-type CommandResourceFetcher<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
+type CommandResourceFetcher<Options extends ArgOptions = ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
 /**
 * Command runner
 * @param ctx A {@link CommandContext | command context}
 */
-type CommandRunner<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Awaitable<void>;
+type CommandRunner<Options extends ArgOptions = ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Awaitable<void>;
 /**
 * Lazy command interface
 * @description lazy command that's not loaded until it is executed
 */
-type LazyCommand<Options extends ArgOptions> = () => Awaitable<Command<Options>>;
+type LazyCommand<Options extends ArgOptions = ArgOptions> = () => Awaitable<Command<Options>>;
+/**
+* Define a command type
+*/
+type Commandable<Options extends ArgOptions> = Command<Options> | LazyCommand<Options>;
 
-export type { Command as C, LazyCommand as L, CommandOptions as a, CommandContext as b, CommandRunner as c, CommandBuiltinOptionsKeys as d, CommandBuiltinResourceKeys as e, CommandBuiltinKeys as f, CommandEnvironment as g, CommandResource as h, CommandResourceFetcher as i };
+export type { Command as C, LazyCommand as L, CommandOptions as a, CommandContext as b, CommandRunner as c, CommandBuiltinOptionsKeys as d, CommandBuiltinResourceKeys as e, CommandBuiltinKeys as f, CommandEnvironment as g, CommandResource as h, CommandResourceFetcher as i, Commandable as j };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"