gunshi 0.8.0 → 0.10.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-	<img width="196" src="./assets/logo.webp">
+	<img width="196" src="./assets/logo.png">
 </p>
 <h1 align="center">🏯 Gunshi</h1>
 
@@ -10,21 +10,25 @@
 
 Gunshi is a modern javascript command-line library
 
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
 > [!TIP]
 > gunshi (軍師) is a position in ancient Japanese samurai battle in which a samurai devised strategies and gave orders. That name is inspired by the word "command".
 
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
 ## ✨ Features
 
 Gunshi is designed to simplify the creation of modern command-line interfaces:
 
-- 📏 **Simple**: Run the commands with a simple API.
-- ⚙️ **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.
-- 🎨 **Custom usage generation**: Usage message generation customizable.
-- 🌍 **Internationalization**: I18n out of the box and locale resource lazy loading.
+- 📏 **Simple & Universal**: Run the commands with simple API and support universal runtime.
+- ⚙️ **Declarative configuration**: Configure command modules declaratively for better organization and maintainability.
+- 🛡️ **Type Safe**: TypeScript support with type-safe argument parsing and option resolution by [args-tokens](https://github.com/kazupon/args-tokens)
+- 🧩 **Composable**: Create modular sub-commands that can be composed together for complex CLIs.
+- ⏳ **Lazy & Async**: Load command modules lazily and execute them asynchronously for better performance.
+- 📜 **Auto usage generation**: Generate helpful usage messages automatically for your commands.
+- 🎨 **Custom usage generation**: Customize how usage messages are generated to match your CLI's style.
+- 🌍 **Internationalization**: Support multiple languages with built-in i18n, locale resource lazy loading and i18n library integration.
 
 ## 💿 Installation
 
@@ -64,7 +68,7 @@ import { cli } from 'gunshi'
 
 const args = process.argv.slice(2)
 // run a simple command
-cli(args, () => {
+await cli(args, () => {
   // something logic ...
   console.log('Hello from Gunshi!', args)
 })
@@ -82,15 +86,22 @@ const command = {
   name: 'greet',
   description: 'A greeting command',
   options: {
-    name: { type: 'string', short: 'n' },
-    greeting: { type: 'string', short: 'g', default: 'Hello' },
-    times: { type: 'number', short: 't', default: 1 }
-  },
-  usage: {
-    options: {
-      name: 'Name to greet',
-      greeting: 'Greeting to use (default: "Hello")',
-      times: 'Number of times to repeat the greeting (default: 1)'
+    name: {
+      type: 'string',
+      short: 'n',
+      description: 'Name to greet'
+    },
+    greeting: {
+      type: 'string',
+      short: 'g',
+      default: 'Hello',
+      description: 'Greeting to use (default: "Hello")'
+    },
+    times: {
+      type: 'number',
+      short: 't',
+      default: 1,
+      description: 'Number of times to repeat the greeting (default: 1)'
     }
   },
   run: ctx => {
@@ -103,7 +114,7 @@ const command = {
 
 // run a command that is defined above
 // (the 3rd argument of `cli` is the command option)
-cli(process.argv.slice(2), command, {
+await cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0',
   description: 'My CLI application'
@@ -201,7 +212,7 @@ const mainCommand = {
 }
 
 // run the CLI with composable sub-commands
-cli(process.argv.slice(2), mainCommand, {
+await cli(process.argv.slice(2), mainCommand, {
   name: 'my-app',
   version: '1.0.0',
   subCommands
@@ -239,7 +250,7 @@ const subCommands = new Map()
 subCommands.set('lazy', lazyCommand)
 
 // run the CLI with lazy-loaded commands
-cli(
+await cli(
   process.argv.slice(2),
   { name: 'main', run: () => {} },
   {
@@ -262,26 +273,32 @@ const command = {
   name: 'app',
   description: 'My application',
   options: {
-    path: { type: 'string', short: 'p' },
-    recursive: { type: 'boolean', short: 'r' },
-    operation: { type: 'string', short: 'o', required: true }
-  },
-  // define usage with object
-  usage: {
-    options: {
-      path: 'File or directory path',
-      recursive: 'Operate recursively on directories',
-      operation: 'Operation to perform (list, copy, move, delete)'
+    path: {
+      type: 'string',
+      short: 'p',
+      description: 'File or directory path'
+    },
+    recursive: {
+      type: 'boolean',
+      short: 'r',
+      description: 'Operate recursively on directories'
     },
-    examples: '# Example\n$ my-app --operation list --path ./src'
+    operation: {
+      type: 'string',
+      short: 'o',
+      required: true,
+      description: 'Operation to perform (list, copy, move, delete)'
+    }
   },
+  // define examples
+  examples: '# Example\n$ my-app --operation list --path ./src',
   run: ctx => {
     // command implementation
   }
 }
 
 // run with --help to see the automatically generated usage information
-cli(process.argv.slice(2), command, {
+await cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0'
 })
@@ -324,7 +341,7 @@ const customUsageRenderer = ctx => {
 }
 
 // run with custom renderers
-cli(
+await cli(
   process.argv.slice(2),
   { name: 'app', run: () => {} },
   {
@@ -350,8 +367,14 @@ import enUS from './locales/en-US.json' with { type: 'json' }
 const command = {
   name: 'greeter',
   options: {
-    name: { type: 'string', short: 'n' },
-    formal: { type: 'boolean', short: 'f' }
+    name: {
+      type: 'string',
+      short: 'n'
+    },
+    formal: {
+      type: 'boolean',
+      short: 'f'
+    }
   },
   // resource fetcher for translations
   resource: async ctx => {
@@ -371,7 +394,7 @@ const command = {
 }
 
 // run with locale support
-cli(process.argv.slice(2), command, {
+await cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0',
   // set the locale via an environment variable
@@ -394,7 +417,8 @@ If you are interested in contributing to `gunshi`, I highly recommend checking o
 
 This project is inspired and powered by:
 
-- [`citty`](https://github.com/unjs/citty), created by UnJS team and contributors
+- [`citty`](https://github.com/unjs/citty), created by [UnJS team](https://github.com/unjs) and contributors
+- [`ordana`](https://github.com/sapphi-red/ordana), createdy by [sapphi-red](https://github.com/sapphi-red), inspired documentation generation
 - cline and claude 3.7 sonnet, examples and docs is generated
 
 Thank you!

package/lib/cli-BmK-tBjI.js

@@ -0,0 +1,96 @@
+import { createCommandContext } from "./context-BeFe0i70.js";
+import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, resolveLazyCommand } from "./utils-DhI1qcqR.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-CZGhbue4.js";
+import { parseArgs, resolveArgs } from "args-tokens";
+
+//#region src/cli.ts
+async function cli(args, entry, opts = {}) {
+	const tokens = parseArgs(args);
+	const subCommand = getSubCommand(tokens);
+	const resolvedCommandOptions = resolveCommandOptions(opts, entry);
+	const [name, command] = await resolveCommand(subCommand, entry, resolvedCommandOptions);
+	if (!command) throw new Error(`Command not found: ${name || ""}`);
+	const options = resolveArgOptions(command.options);
+	const { values, positionals, error } = resolveArgs(options, tokens);
+	const omitted = !subCommand;
+	const ctx = await createCommandContext({
+		options,
+		values,
+		positionals,
+		omitted,
+		command,
+		commandOptions: resolvedCommandOptions
+	});
+	if (values.version) {
+		showVersion(ctx);
+		return;
+	}
+	const usageBuffer = [];
+	const header = await showHeader(ctx);
+	if (header) usageBuffer.push(header);
+	if (values.help) {
+		const usage = await showUsage(ctx);
+		if (usage) usageBuffer.push(usage);
+		return usageBuffer.join("\n");
+	}
+	if (error) {
+		await showValidationErrors(ctx, error);
+		return;
+	}
+	await command.run(ctx);
+}
+function resolveArgOptions(options) {
+	return Object.assign(create(), options, COMMON_OPTIONS);
+}
+function resolveCommandOptions(options, entry) {
+	const subCommands = new Map(options.subCommands);
+	if (typeof entry === "object" && entry.name) subCommands.set(entry.name, entry);
+	const resolvedOptions = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, options, { subCommands });
+	return resolvedOptions;
+}
+function getSubCommand(tokens) {
+	const firstToken = tokens[0];
+	return firstToken && firstToken.kind === "positional" && firstToken.index === 0 && firstToken.value ? firstToken.value : "";
+}
+async function showUsage(ctx) {
+	if (ctx.env.renderUsage === null) return;
+	const usage = await (ctx.env.renderUsage || renderUsage)(ctx);
+	if (usage) {
+		ctx.log(usage);
+		return usage;
+	}
+}
+function showVersion(ctx) {
+	ctx.log(ctx.env.version);
+}
+async function showHeader(ctx) {
+	if (ctx.env.renderHeader === null) return;
+	const header = await (ctx.env.renderHeader || renderHeader)(ctx);
+	if (header) {
+		ctx.log(header);
+		ctx.log();
+		return header;
+	}
+}
+async function showValidationErrors(ctx, error) {
+	if (ctx.env.renderValidationErrors === null) return;
+	const render = ctx.env.renderValidationErrors || renderValidationErrors;
+	ctx.log(await render(ctx, error));
+}
+async function resolveCommand(sub, entry, options) {
+	const omitted = !sub;
+	if (typeof entry === "function") return [void 0, {
+		run: entry,
+		default: true
+	}];
+	else if (omitted) return typeof entry === "object" ? [entry.name, await resolveLazyCommand(entry, void 0, true)] : [void 0, void 0];
+	else {
+		if (options.subCommands == null) return [sub, void 0];
+		const cmd = options.subCommands?.get(sub);
+		if (cmd == null) return [sub, void 0];
+		return [sub, await resolveLazyCommand(cmd, sub)];
+	}
+}
+
+//#endregion
+export { cli };

package/lib/{context-DYokJ5k3.js → context-BeFe0i70.js}

@@ -1,4 +1,4 @@
-import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE, create, deepFreeze, mapResourceWithBuiltinKey, resolveLazyCommand } from "./utils-CU_LSsUg.js";
+import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveLazyCommand } from "./utils-DhI1qcqR.js";
 
 //#region locales/en-US.json
 var COMMAND = "COMMAND";
@@ -43,7 +43,7 @@ var DefaultTranslation = class {
 	getMessage(locale, key) {
 		const resource = this.getResource(locale);
 		if (resource) return resource[key];
-		return undefined;
+		return void 0;
 	}
 	translate(locale, key, _values = create()) {
 		/**
@@ -61,30 +61,21 @@ var DefaultTranslation = class {
 const BUILT_IN_PREFIX_CODE = BUILT_IN_PREFIX.codePointAt(0);
 async function createCommandContext({ options, values, positionals, command, commandOptions, omitted = false }) {
 	/**
-	* tweak the options and values
+	* normailize the options schema and values, to avoid prototype pollution
 	*/
 	const _options = Object.entries(options).reduce((acc, [key, value]) => {
 		acc[key] = Object.assign(create(), value);
 		return acc;
 	}, create());
-	const _values = Object.assign(create(), values);
-	/**
-	* normalize the usage
-	*/
-	const usage = Object.assign(create(), command.usage);
-	const { help: help$1, version: version$1 } = en_US_default;
-	usage.options = Object.assign(create(), usage.options, {
-		help: help$1,
-		version: version$1
-	});
 	/**
 	* setup the environment
 	*/
 	const env = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, commandOptions);
 	const locale = resolveLocale(commandOptions.locale);
+	const localeStr = locale.toString();
 	const translationAdapterFactory = commandOptions.translationAdapterFactory || createTranslationAdapter;
 	const adapter = translationAdapterFactory({
-		locale: locale.toString(),
+		locale: localeStr,
 		fallbackLocale: DEFAULT_LOCALE
 	});
 	const localeResources = new Map();
@@ -93,9 +84,9 @@ async function createCommandContext({ options, values, positionals, command, com
 	* load the built-in locale resources
 	*/
 	localeResources.set(DEFAULT_LOCALE, mapResourceWithBuiltinKey(en_US_default));
-	if (DEFAULT_LOCALE !== locale.toString()) try {
-		builtInLoadedResources = await import(`../locales/${locale.toString()}.json`, { with: { type: "json" } });
-		localeResources.set(locale.toString(), mapResourceWithBuiltinKey(builtInLoadedResources));
+	if (DEFAULT_LOCALE !== localeStr) try {
+		builtInLoadedResources = await import(`../locales/${localeStr}.json`, { with: { type: "json" } });
+		localeResources.set(localeStr, mapResourceWithBuiltinKey(builtInLoadedResources));
 	} catch {}
 	/**
 	* define the translation function, which is used to {@link CommandContext.translate}.
@@ -104,7 +95,7 @@ async function createCommandContext({ options, values, positionals, command, com
 	function translate(key, values$1 = create()) {
 		const strKey = key;
 		if (strKey.codePointAt(0) === BUILT_IN_PREFIX_CODE) {
-			const resource = localeResources.get(locale.toString()) || localeResources.get(DEFAULT_LOCALE);
+			const resource = localeResources.get(localeStr) || localeResources.get(DEFAULT_LOCALE);
 			return resource[strKey] || strKey;
 		} else return adapter.translate(locale.toString(), strKey, values$1) || "";
 	}
@@ -114,7 +105,7 @@ async function createCommandContext({ options, values, positionals, command, com
 	let cachedCommands;
 	async function loadCommands() {
 		if (cachedCommands) return cachedCommands;
-		const subCommands = [...env.subCommands || []];
+		const subCommands = [...commandOptions.subCommands || []];
 		return cachedCommands = await Promise.all(subCommands.map(async ([name, cmd]) => await resolveLazyCommand(cmd, name)));
 	}
 	/**
@@ -127,25 +118,25 @@ async function createCommandContext({ options, values, positionals, command, com
 		locale,
 		env,
 		options: _options,
-		values: _values,
+		values,
 		positionals,
-		usage,
+		log: commandOptions.usageSilent ? NOOP : log,
 		loadCommands,
 		translate
 	}));
 	/**
 	* load the command resources
 	*/
-	const loadedOptionsResources = Object.entries(usage.options || create()).map(([key, _]) => {
-		const option = usage.options[key];
-		return [key, option];
+	const loadedOptionsResources = Object.entries(options).map(([key, option]) => {
+		const description = option.description || "";
+		return [key, description];
 	});
 	const defaultCommandResource = loadedOptionsResources.reduce((res, [key, value]) => {
 		res[key] = value;
 		return res;
 	}, create());
 	defaultCommandResource.description = command.description || "";
-	defaultCommandResource.examples = usage.examples || "";
+	defaultCommandResource.examples = command.examples || "";
 	adapter.setResource(DEFAULT_LOCALE, defaultCommandResource);
 	const originalResource = await loadCommandResource(ctx, command);
 	if (originalResource) {
@@ -157,7 +148,7 @@ async function createCommandContext({ options, values, positionals, command, com
 			resource.help = builtInLoadedResources.help;
 			resource.version = builtInLoadedResources.version;
 		}
-		adapter.setResource(locale.toString(), resource);
+		adapter.setResource(localeStr, resource);
 	}
 	return ctx;
 }

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-CX4RmDVT.js';
+import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-DTe4N67v.js';
 
 /**
 * Parameters of {@link createCommandContext}
@@ -40,7 +40,7 @@ interface CommandContextParams<
 */
 declare function createCommandContext<
 	Options extends ArgOptions = ArgOptions,
-	Values = ArgValues<Options>
+	Values extends ArgValues<Options> = ArgValues<Options>
 >({ options, values, positionals, command, commandOptions, omitted }: CommandContextParams<Options, Values>): Promise<Readonly<CommandContext<Options, Values>>>;
 
 export { createCommandContext };

package/lib/context.js

@@ -1,4 +1,4 @@
-import { createCommandContext } from "./context-DYokJ5k3.js";
-import "./utils-CU_LSsUg.js";
+import { createCommandContext } from "./context-BeFe0i70.js";
+import "./utils-DhI1qcqR.js";
 
 export { createCommandContext };

package/lib/generator.d.ts

@@ -0,0 +1,13 @@
+import { ArgOptions } from 'args-tokens';
+import { C as Command, c as CommandRunner, a as CommandOptions } from './types.d-DTe4N67v.js';
+
+/**
+* Generate the command usage
+* @param command - usage generate command, if you want to generate the usage of the default command where there are target commands and sub-commands, specify `null`.
+* @param entry - A {@link Command | entry command} or an {@link CommandRunner | inline command runner}
+* @param opts - A {@link CommandOptions | command options}
+* @returns A rendered usage
+*/
+declare function generate<Options extends ArgOptions = ArgOptions>(command: string | null, entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<string>;
+
+export { generate };

package/lib/generator.js

@@ -0,0 +1,17 @@
+import "./context-BeFe0i70.js";
+import { create } from "./utils-DhI1qcqR.js";
+import "./renderer-CZGhbue4.js";
+import { cli } from "./cli-BmK-tBjI.js";
+
+//#region src/generator.ts
+async function generate(command, entry, opts = {}) {
+	const args = ["-h"];
+	if (command != null) args.unshift(command);
+	return await cli(args, entry, Object.assign(create(), opts, {
+		usageSilent: true,
+		__proto__: null
+	})) || "";
+}
+
+//#endregion
+export { generate };

package/lib/index.d.ts

@@ -1,13 +1,14 @@
 import { ArgOptions } from 'args-tokens';
 export { ArgOptionSchema, ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, c as CommandRunner, a as CommandOptions, T as TranslationAdapter, d as TranslationAdapterFactoryOptions } from './types.d-CX4RmDVT.js';
-export { g as CommandBuiltinKeys, e as CommandBuiltinOptionsKeys, f as CommandBuiltinResourceKeys, b as CommandContext, h as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, l as Commandable, G as GenerateNamespacedKey, L as LazyCommand, k as TranslationAdapterFactory } from './types.d-CX4RmDVT.js';
+import { C as Command, c as CommandRunner, a as CommandOptions, T as TranslationAdapter, d as TranslationAdapterFactoryOptions } from './types.d-DTe4N67v.js';
+export { g as CommandBuiltinKeys, e as CommandBuiltinOptionsKeys, f as CommandBuiltinResourceKeys, b as CommandContext, h as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, l as Commandable, G as GenerateNamespacedKey, L as LazyCommand, k as TranslationAdapterFactory } from './types.d-DTe4N67v.js';
 
 /**
 * Run the command
 * @param args - command line arguments
 * @param entry - A {@link Command | entry command} or an {@link CommandRunner | inline command runner}
 * @param opts - A {@link CommandOptions | command options}
+* @returns A rendered usage or undefined. if you will use {@link CommandOptions.usageSilent} option, it will return rendered usage string.
 */
 declare function cli<Options extends ArgOptions = ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<string | undefined>;
 

package/lib/index.js

@@ -1,96 +1,6 @@
-import { DefaultTranslation, createCommandContext } from "./context-DYokJ5k3.js";
-import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, log, resolveLazyCommand } from "./utils-CU_LSsUg.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-KLx2dW-W.js";
-import { parseArgs, resolveArgs } from "args-tokens";
+import { DefaultTranslation } from "./context-BeFe0i70.js";
+import "./utils-DhI1qcqR.js";
+import "./renderer-CZGhbue4.js";
+import { cli } from "./cli-BmK-tBjI.js";
 
-//#region src/cli.ts
-async function cli(args, entry, opts = {}) {
-	const tokens = parseArgs(args);
-	const subCommand = getSubCommand(tokens);
-	const resolvedCommandOptions = resolveCommandOptions(opts, entry);
-	const [name, command] = await resolveCommand(subCommand, entry, resolvedCommandOptions);
-	if (!command) throw new Error(`Command not found: ${name || ""}`);
-	const options = resolveArgOptions(command.options);
-	const { values, positionals, error } = resolveArgs(options, tokens);
-	const omitted = !subCommand;
-	const ctx = await createCommandContext({
-		options,
-		values,
-		positionals,
-		omitted,
-		command,
-		commandOptions: resolvedCommandOptions
-	});
-	if (values.version) {
-		showVersion(ctx);
-		return;
-	}
-	const usageBuffer = [];
-	const header = await showHeader(ctx);
-	if (header) usageBuffer.push(header);
-	if (values.help) {
-		const usage = await showUsage(ctx);
-		if (usage) usageBuffer.push(usage);
-		return usageBuffer.join("\n");
-	}
-	if (error) {
-		await showValidationErrors(ctx, error);
-		return;
-	}
-	await command.run(ctx);
-}
-function resolveArgOptions(options) {
-	return Object.assign(create(), options, COMMON_OPTIONS);
-}
-function resolveCommandOptions(options, entry) {
-	const subCommands = new Map(options.subCommands);
-	if (typeof entry === "object" && entry.name) subCommands.set(entry.name, entry);
-	const resolvedOptions = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, options, { subCommands });
-	return resolvedOptions;
-}
-function getSubCommand(tokens) {
-	const firstToken = tokens[0];
-	return firstToken && firstToken.kind === "positional" && firstToken.index === 0 && firstToken.value ? firstToken.value : "";
-}
-async function showUsage(ctx) {
-	if (ctx.env.renderUsage === null) return;
-	const usage = await (ctx.env.renderUsage || renderUsage)(ctx);
-	if (usage) {
-		log(usage);
-		return usage;
-	}
-}
-function showVersion(ctx) {
-	log(ctx.env.version);
-}
-async function showHeader(ctx) {
-	if (ctx.env.renderHeader === null) return;
-	const header = await (ctx.env.renderHeader || renderHeader)(ctx);
-	if (header) {
-		log(header);
-		log();
-		return header;
-	}
-}
-async function showValidationErrors(ctx, error) {
-	if (ctx.env.renderValidationErrors === null) return;
-	const render = ctx.env.renderValidationErrors || renderValidationErrors;
-	log(await render(ctx, error));
-}
-async function resolveCommand(sub, entry, options) {
-	const omitted = !sub;
-	if (typeof entry === "function") return [undefined, {
-		run: entry,
-		default: true
-	}];
-	else if (omitted) return typeof entry === "object" ? [entry.name, await resolveLazyCommand(entry, undefined, true)] : [undefined, undefined];
-	else {
-		if (options.subCommands == null) return [sub, undefined];
-		const cmd = options.subCommands?.get(sub);
-		if (cmd == null) return [sub, undefined];
-		return [sub, await resolveLazyCommand(cmd, sub)];
-	}
-}
-
-//#endregion
 export { DefaultTranslation, cli };

package/lib/renderer/index.d.ts

@@ -1,5 +1,5 @@
 import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from '../types.d-CX4RmDVT.js';
+import { b as CommandContext } from '../types.d-DTe4N67v.js';
 
 /**
 * Render the header

package/lib/renderer/index.js

@@ -1,4 +1,4 @@
-import "../utils-CU_LSsUg.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-KLx2dW-W.js";
+import "../utils-DhI1qcqR.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-CZGhbue4.js";
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{renderer-KLx2dW-W.js → renderer-CZGhbue4.js}

@@ -1,4 +1,4 @@
-import { create, resolveBuiltInKey } from "./utils-CU_LSsUg.js";
+import { create, resolveBuiltInKey } from "./utils-DhI1qcqR.js";
 
 //#region src/renderer/header.ts
 function renderHeader(ctx) {
@@ -17,7 +17,8 @@ async function renderUsage(ctx) {
 	messages.push(...await renderUsageSection(ctx), "");
 	if (ctx.omitted && await hasCommands(ctx)) messages.push(...await renderCommandsSection(ctx), "");
 	if (hasOptions(ctx)) messages.push(...await renderOptionsSection(ctx), "");
-	if (hasExamples(ctx)) messages.push(...renderExamplesSection(ctx), "");
+	const examples = renderExamplesSection(ctx);
+	if (examples.length > 0) messages.push(...examples, "");
 	return messages.join("\n");
 }
 /**
@@ -38,8 +39,11 @@ async function renderOptionsSection(ctx) {
 */
 function renderExamplesSection(ctx) {
 	const messages = [];
-	const examples = ctx.usage.examples.split("\n").map((example) => example.padStart(ctx.env.leftMargin + example.length));
-	messages.push(`${ctx.translate(resolveBuiltInKey("EXAMPLES"))}:`, ...examples);
+	const resolvedExamples = resolveExamples(ctx);
+	if (resolvedExamples) {
+		const examples = resolvedExamples.split("\n").map((example) => example.padStart(ctx.env.leftMargin + example.length));
+		messages.push(`${ctx.translate(resolveBuiltInKey("EXAMPLES"))}:`, ...examples);
+	}
 	return messages;
 }
 /**
@@ -109,6 +113,17 @@ function resolveDescription(ctx) {
 	return ctx.translate("description") || ctx.description || "";
 }
 /**
+* Resolve the command examples
+* @param ctx A {@link CommandContext | command context}
+* @returns resolved command examples, if not resolved, return empty string
+*/
+function resolveExamples(ctx) {
+	const ret = ctx.translate("examples");
+	if (ret) return ret;
+	const command = ctx.env.subCommands?.get(ctx.name || "");
+	return command?.examples ?? "";
+}
+/**
 * Check if the command has sub commands
 * @param ctx A {@link CommandContext | command context}
 * @returns True if the command has sub commands
@@ -126,14 +141,6 @@ function hasOptions(ctx) {
 	return !!(ctx.options && Object.keys(ctx.options).length > 0);
 }
 /**
-* Check if the command has examples
-* @param ctx A {@link CommandContext | command context}
-* @returns True if the command has examples
-*/
-function hasExamples(ctx) {
-	return !!ctx.usage.examples;
-}
-/**
 * Check if all options have default values
 * @param ctx A {@link CommandContext | command context}
 * @returns True if all options have default values
@@ -147,7 +154,7 @@ function hasAllDefaultOptions(ctx) {
 * @returns Options symbols for usage
 */
 function generateOptionsSymbols(ctx) {
-	return hasOptions(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translate("_:OPTIONS")}]` : `<${ctx.translate("_:OPTIONS")}>` : "";
+	return hasOptions(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translate(resolveBuiltInKey("OPTIONS"))}]` : `<${ctx.translate(resolveBuiltInKey("OPTIONS"))}>` : "";
 }
 /**
 * Get options pairs for usage

package/lib/{types.d-CX4RmDVT.d.ts → types.d-DTe4N67v.d.ts}

@@ -6,14 +6,17 @@ import { ArgOptions, ArgValues } from 'args-tokens';
 declare const DEFAULT_LOCALE = "en-US";
 declare const BUILT_IN_PREFIX = "_";
 declare const BUILT_IN_KEY_SEPARATOR = ":";
+declare const NOOP: () => void;
 type CommonOptionType = {
 	readonly help: {
 		readonly type: "boolean"
 		readonly short: "h"
+		readonly description: string
 	}
 	readonly version: {
 		readonly type: "boolean"
 		readonly short: "v"
+		readonly description: string
 	}
 };
 declare const COMMON_OPTIONS: CommonOptionType;
@@ -26,8 +29,9 @@ declare const __constants_COMMAND_BUILTIN_RESOURCE_KEYS: typeof COMMAND_BUILTIN_
 declare const __constants_COMMAND_OPTIONS_DEFAULT: typeof COMMAND_OPTIONS_DEFAULT;
 declare const __constants_COMMON_OPTIONS: typeof COMMON_OPTIONS;
 declare const __constants_DEFAULT_LOCALE: typeof DEFAULT_LOCALE;
+declare const __constants_NOOP: typeof NOOP;
 declare namespace __constants {
-  export { __constants_BUILT_IN_KEY_SEPARATOR as BUILT_IN_KEY_SEPARATOR, __constants_BUILT_IN_PREFIX as BUILT_IN_PREFIX, __constants_COMMAND_BUILTIN_RESOURCE_KEYS as COMMAND_BUILTIN_RESOURCE_KEYS, __constants_COMMAND_OPTIONS_DEFAULT as COMMAND_OPTIONS_DEFAULT, __constants_COMMON_OPTIONS as COMMON_OPTIONS, __constants_DEFAULT_LOCALE as DEFAULT_LOCALE };
+  export { __constants_BUILT_IN_KEY_SEPARATOR as BUILT_IN_KEY_SEPARATOR, __constants_BUILT_IN_PREFIX as BUILT_IN_PREFIX, __constants_COMMAND_BUILTIN_RESOURCE_KEYS as COMMAND_BUILTIN_RESOURCE_KEYS, __constants_COMMAND_OPTIONS_DEFAULT as COMMAND_OPTIONS_DEFAULT, __constants_COMMON_OPTIONS as COMMON_OPTIONS, __constants_DEFAULT_LOCALE as DEFAULT_LOCALE, __constants_NOOP as NOOP };
 }
 
 /**
@@ -98,6 +102,12 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	*/
 	usageOptionType: boolean;
 	/**
+	* Whether to display the command usage
+	* @default false
+	* @see {@link}
+	*/
+	usageSilent: boolean;
+	/**
 	* Sub commands
 	* @see {@link CommandOptions.subCommands}
 	*/
@@ -157,6 +167,10 @@ interface CommandOptions<Options extends ArgOptions = ArgOptions> {
 	*/
 	usageOptionType?: boolean;
 	/**
+	* Whether to display the command usage
+	*/
+	usageSilent?: boolean;
+	/**
 	* Render function the command usage
 	*/
 	renderUsage?: ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | null;
@@ -200,7 +214,7 @@ interface CommandContext<
 	* Command environment, that is the environment of the command that is executed
 	* @description The command environment is same {@link CommandEnvironment}
 	*/
-	env: CommandEnvironment<Options>;
+	env: Readonly<CommandEnvironment<Options>>;
 	/**
 	* Command options, that is the options of the command that is executed
 	* @description The command options is same {@link Command.options}
@@ -221,10 +235,12 @@ interface CommandContext<
 	*/
 	omitted: boolean;
 	/**
-	* Command usage
-	* @description Usage of the command is same {@link Command.usage}, and more has `--help` and `--version` options
+	* Output a message
+	* @description if {@link CommandEnvironment.usageSilent} is true, the message is not output
+	* @param message an output message, @see {@link console.log}
+	* @param optionalParams an optional parameters, @see {@link console.log}
 	*/
-	usage: CommandUsage<Options>;
+	log: (message?: any, ...optionalParams: any[]) => void;
 	/**
 	* Load sub-commands
 	* @description The loaded commands are cached and returned when called again
@@ -244,19 +260,6 @@ interface CommandContext<
 	>(key: Key, values?: Record<string, unknown>) => string;
 }
 /**
-* Command usage
-*/
-interface CommandUsage<Options extends ArgOptions = ArgOptions> {
-	/**
-	* Options usage
-	*/
-	options?: { [Option in keyof Options] : string };
-	/**
-	* Examples usage
-	*/
-	examples?: string;
-}
-/**
 * Command interface
 */
 interface Command<Options extends ArgOptions = ArgOptions> {
@@ -268,8 +271,7 @@ interface Command<Options extends ArgOptions = ArgOptions> {
 	name?: string;
 	/**
 	* Command description
-	* @description
-	* Command description is used to describe the command in usage, so it's recommended to specify.
+	* @description command description is used to describe the command in usage, so it's recommended to specify.
 	*/
 	description?: string;
 	/**
@@ -279,14 +281,14 @@ interface Command<Options extends ArgOptions = ArgOptions> {
 	default?: boolean;
 	/**
 	* Command options
+	* @description each option can include a description property to describe the option in usage.
 	*/
 	options?: Options;
 	/**
-	* Command usage
-	* @description
-	* Command usage is used to describe the command in usage, so it's recommended to specify.
+	* Command examples
+	* @description examples of how to use the command.
 	*/
-	usage?: CommandUsage<Options>;
+	examples?: string;
 	/**
 	* Command runner, that's the command to be executed
 	*/
@@ -319,7 +321,10 @@ type CommandResource<Options extends ArgOptions = ArgOptions> = {
 * @returns A fetched {@link CommandResource | command resource}
 * @experimental
 */
-type CommandResourceFetcher<Options extends ArgOptions = ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
+type CommandResourceFetcher<
+	Options extends ArgOptions = ArgOptions,
+	Values = ArgValues<Options>
+> = (ctx: Readonly<CommandContext<Options, Values>>) => Promise<CommandResource<Options>>;
 /**
 * Translation adapter factory
 */

package/lib/{utils-CU_LSsUg.js → utils-DhI1qcqR.js}

@@ -3,29 +3,33 @@
 const DEFAULT_LOCALE = "en-US";
 const BUILT_IN_PREFIX = "_";
 const BUILT_IN_KEY_SEPARATOR = ":";
+const NOOP = () => {};
 const COMMON_OPTIONS = {
 	help: {
 		type: "boolean",
-		short: "h"
+		short: "h",
+		description: "Display this help message"
 	},
 	version: {
 		type: "boolean",
-		short: "v"
+		short: "v",
+		description: "Display this version"
 	}
 };
 const COMMAND_OPTIONS_DEFAULT = {
-	name: undefined,
-	description: undefined,
-	version: undefined,
-	cwd: undefined,
-	subCommands: undefined,
+	name: void 0,
+	description: void 0,
+	version: void 0,
+	cwd: void 0,
+	usageSilent: false,
+	subCommands: void 0,
 	leftMargin: 2,
 	middleMargin: 10,
 	usageOptionType: false,
-	renderHeader: undefined,
-	renderUsage: undefined,
-	renderValidationErrors: undefined,
-	translationAdapterFactory: undefined
+	renderHeader: void 0,
+	renderUsage: void 0,
+	renderValidationErrors: void 0,
+	translationAdapterFactory: void 0
 };
 
 //#endregion
@@ -60,4 +64,4 @@ function deepFreeze(obj) {
 }
 
 //#endregion
-export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveBuiltInKey, resolveLazyCommand };
+export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveBuiltInKey, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -54,6 +54,12 @@
       "require": "./lib/renderer/index.js",
       "default": "./lib/renderer/index.js"
     },
+    "./generator": {
+      "types": "./lib/generator.d.ts",
+      "import": "./lib/generator.js",
+      "require": "./lib/generator.js",
+      "default": "./lib/generator.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -67,33 +73,39 @@
     }
   },
   "dependencies": {
-    "args-tokens": "^0.10.2"
+    "args-tokens": "^0.12.0"
   },
   "devDependencies": {
     "@eslint/markdown": "^6.2.2",
     "@intlify/core": "next",
-    "@kazupon/eslint-config": "^0.22.0",
+    "@kazupon/eslint-config": "^0.26.1",
     "@kazupon/prettier-config": "^0.1.1",
     "@types/node": "^22.13.9",
     "@vitest/eslint-plugin": "^1.1.36",
     "bumpp": "^10.0.3",
-    "eslint": "^9.21.0",
+    "eslint": "^9.22.0",
     "eslint-config-prettier": "^10.0.2",
+    "eslint-import-resolver-typescript": "^4.2.2",
+    "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-jsonc": "^2.19.1",
+    "eslint-plugin-module-interop": "^0.3.0",
     "eslint-plugin-promise": "^7.2.1",
     "eslint-plugin-regexp": "^2.7.0",
-    "eslint-plugin-unicorn": "^57.0.0",
+    "eslint-plugin-unicorn": "^58.0.0",
+    "eslint-plugin-unused-imports": "^4.1.4",
     "eslint-plugin-yml": "^1.17.0",
     "gh-changelogen": "^0.2.8",
     "jsr": "^0.13.4",
     "knip": "^5.45.0",
     "lint-staged": "^15.4.3",
-    "messageformat": "4.0.0-9",
+    "messageformat": "4.0.0-10",
     "pkg-pr-new": "^0.0.41",
     "prettier": "^3.5.3",
     "tsdown": "^0.6.4",
     "typescript": "^5.4.2",
     "typescript-eslint": "^8.26.0",
+    "vitepress": "^1.6.3",
+    "vitepress-plugin-group-icons": "^1.3.8",
     "vitest": "^3.0.7"
   },
   "prettier": "@kazupon/prettier-config",
@@ -116,6 +128,9 @@
     "clean": "git clean -df",
     "dev": "pnpx @eslint/config-inspector --config eslint.config.ts",
     "dev:eslint": "pnpx @eslint/config-inspector --config eslint.config.ts",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
     "fix": "pnpm run --stream --color \"/^fix:/\"",
     "fix:eslint": "eslint . --fix",
     "fix:knip": "knip --fix --no-exit-code",