gunshi 0.5.2 → 0.5.4

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,12 @@ Gunshi has a simple API that is a facade:
 ```js
 import { cli } from 'gunshi'
 
-// Run a simple command
+// run a simple command
 cli(process.argv.slice(2), () => {
   console.log('Hello from Gunshi!')
 })
 ```
 
-### 🛡️ 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 +75,7 @@ Configure commands declaratively:
 ```js
 import { cli } from 'gunshi'
 
-// Define a command with declarative configuration
+// define a command with declarative configuration
 const command = {
   name: 'greet',
   description: 'A greeting command',
@@ -148,6 +108,52 @@ 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 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
+
+// create a 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:
@@ -155,7 +161,7 @@ Create a CLI with composable sub-commands:
 ```js
 import { cli } from 'gunshi'
 
-// Define sub-commands
+// define sub-commands
 const createCommand = {
   name: 'create',
   description: 'Create a new resource',
@@ -175,12 +181,12 @@ const listCommand = {
   }
 }
 
-// Create a Map of sub-commands
+// create a Map of sub-commands
 const subCommands = new Map()
 subCommands.set('create', createCommand)
 subCommands.set('list', listCommand)
 
-// Define the main command
+// define the main command
 const mainCommand = {
   name: 'resource-manager',
   description: 'Manage resources',
@@ -189,7 +195,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 +212,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
+// create 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: () => {} },
@@ -264,11 +270,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 +290,7 @@ Customize the usage message generation:
 ```js
 import { cli } from 'gunshi'
 
-// Custom header renderer
+// custom header renderer
 const customHeaderRenderer = ctx => {
   return Promise.resolve(`
 ╔═══════════════════════╗
@@ -295,7 +301,7 @@ Version: ${ctx.env.version}
 `)
 }
 
-// Custom usage renderer
+// custom usage renderer
 const customUsageRenderer = ctx => {
   const lines = []
   lines.push('USAGE:')
@@ -303,7 +309,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 +317,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 +347,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 +364,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')
 })
 ```

package/lib/{context-B5z7lnoV.js → context-DmZAeiph.js}

@@ -1,3 +1,4 @@
+import { create, deepFreeze, resolveLazyCommand } from "./utils-NHs5DuHk.js";
 
 //#region locales/en-US.json
 var COMMAND = "COMMAND";
@@ -56,28 +57,6 @@ const COMMAND_I18N_RESOURCE_KEYS = [
 	"FORMORE"
 ];
 
-//#endregion
-//#region src/utils.ts
-async function resolveLazyCommand(cmd, name, entry = false) {
-	const resolved = Object.assign(create(), typeof cmd == "function" ? await cmd() : cmd, { default: entry });
-	if (resolved.name == null && name) resolved.name = name;
-	return deepFreeze(resolved);
-}
-function create(obj = null) {
-	return Object.create(obj);
-}
-function log(...args) {
-	console.log(...args);
-}
-function deepFreeze(obj) {
-	if (obj === null || typeof obj !== "object") return obj;
-	for (const key of Object.keys(obj)) {
-		const value = obj[key];
-		if (typeof value === "object" && value !== null) deepFreeze(value);
-	}
-	return Object.freeze(obj);
-}
-
 //#endregion
 //#region src/context.ts
 const DEFAULT_LOCALE = "en-US";
@@ -196,4 +175,4 @@ async function loadCommandResource(ctx, command) {
 }
 
 //#endregion
-export { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, create, createCommandContext, log, resolveLazyCommand };
+export { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, createCommandContext };

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/context.js

@@ -1,3 +1,4 @@
-import { DEFAULT_LOCALE, createCommandContext } from "./context-B5z7lnoV.js";
+import { DEFAULT_LOCALE, createCommandContext } from "./context-DmZAeiph.js";
+import "./utils-NHs5DuHk.js";
 
 export { DEFAULT_LOCALE, createCommandContext };

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<void>;
 
 export { Command, CommandOptions, CommandRunner, cli };

package/lib/index.js

@@ -1,195 +1,8 @@
-import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, createCommandContext, log, resolveLazyCommand } from "./context-B5z7lnoV.js";
+import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, createCommandContext } from "./context-DmZAeiph.js";
+import { create, log, resolveLazyCommand } from "./utils-NHs5DuHk.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-MpQ9U28q.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
-//#region src/renderer/header.ts
-function renderHeader(ctx) {
-	const title = ctx.env.description || ctx.env.name || "";
-	return Promise.resolve(title ? `${title} (${ctx.env.name || ""}${ctx.env.version ? ` v${ctx.env.version}` : ""})` : title);
-}
-
-//#endregion
-//#region src/renderer/usage.ts
-async function renderUsage(ctx) {
-	const messages = [];
-	if (!ctx.omitted && hasDescription(ctx)) messages.push(ctx.description, "");
-	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), "");
-	return messages.join("\n");
-}
-/**
-* Render the options section
-* @param ctx A {@link CommandContext | command context}
-* @returns A rendered options section
-*/
-async function renderOptionsSection(ctx) {
-	const messages = [];
-	messages.push(`${ctx.translation("OPTIONS")}:`);
-	const optionsPairs = getOptionsPairs(ctx);
-	messages.push(await generateOptionsUsage(ctx, optionsPairs));
-	return messages;
-}
-/**
-* Render the examples section
-* @param ctx A {@link CommandContext | command context}
-* @returns A rendered examples section
-*/
-function renderExamplesSection(ctx) {
-	const messages = [];
-	const examples = ctx.usage.examples.split("\n").map((example) => example.padStart(ctx.env.leftMargin + example.length));
-	messages.push(`${ctx.translation("EXAMPLES")}:`, ...examples);
-	return messages;
-}
-/**
-* Render the usage section
-* @param ctx A {@link CommandContext | command context}
-* @returns A rendered usage section
-*/
-async function renderUsageSection(ctx) {
-	const messages = [`${ctx.translation("USAGE")}:`];
-	if (ctx.omitted) {
-		const defaultCommand = `${resolveEntry(ctx)}${await hasCommands(ctx) ? ` [${resolveSubCommand(ctx)}]` : ""} ${hasOptions(ctx) ? `<${ctx.translation("OPTIONS")}>` : ""} `;
-		messages.push(defaultCommand.padStart(ctx.env.leftMargin + defaultCommand.length));
-		if (await hasCommands(ctx)) {
-			const commandsUsage = `${resolveEntry(ctx)} <${ctx.translation("COMMANDS")}>`;
-			messages.push(commandsUsage.padStart(ctx.env.leftMargin + commandsUsage.length));
-		}
-	} else {
-		const usageStr = `${resolveEntry(ctx)} ${resolveSubCommand(ctx)} ${generateOptionsSymbols(ctx)}`;
-		messages.push(usageStr.padStart(ctx.env.leftMargin + usageStr.length));
-	}
-	return messages;
-}
-/**
-* Render the commands section
-* @param ctx A {@link CommandContext | command context}
-* @returns A rendered commands section
-*/
-async function renderCommandsSection(ctx) {
-	const messages = [`${ctx.translation("COMMANDS")}:`];
-	const loadedCommands = await ctx.loadCommands();
-	const commandMaxLength = Math.max(...loadedCommands.map((cmd) => (cmd.name || "").length));
-	const commandsStr = await Promise.all(loadedCommands.map((cmd) => {
-		const key = cmd.name || "";
-		const desc = cmd.description || "";
-		const command = `${key.padEnd(commandMaxLength + ctx.env.middleMargin)}${desc} `;
-		return `${command.padStart(ctx.env.leftMargin + command.length)} `;
-	}));
-	messages.push(...commandsStr, "", ctx.translation("FORMORE"));
-	messages.push(...loadedCommands.map((cmd) => {
-		const commandHelp = `${ctx.env.name} ${cmd.name} --help`;
-		return `${commandHelp.padStart(ctx.env.leftMargin + commandHelp.length)}`;
-	}));
-	return messages;
-}
-/**
-* Resolve the entry command name
-* @param ctx A {@link CommandContext | command context}
-* @returns The entry command name
-*/
-function resolveEntry(ctx) {
-	return ctx.env.name || ctx.translation("COMMAND");
-}
-/**
-* Resolve the sub command name
-* @param ctx A {@link CommandContext | command context}
-* @returns The sub command name
-*/
-function resolveSubCommand(ctx) {
-	return ctx.name || ctx.translation("SUBCOMMAND");
-}
-/**
-* Check if the command has a description
-* @param ctx A {@link CommandContext | command context}
-* @returns True if the command has a description
-*/
-function hasDescription(ctx) {
-	return !!ctx.description;
-}
-/**
-* Check if the command has sub commands
-* @param ctx A {@link CommandContext | command context}
-* @returns True if the command has sub commands
-*/
-async function hasCommands(ctx) {
-	const loadedCommands = await ctx.loadCommands();
-	return loadedCommands.length > 1;
-}
-/**
-* Check if the command has options
-* @param ctx A {@link CommandContext | command context}
-* @returns True if the command has options
-*/
-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
-*/
-function hasAllDefaultOptions(ctx) {
-	return !!(ctx.options && Object.values(ctx.options).every((opt) => opt.default));
-}
-/**
-* Generate options symbols for usage
-* @param ctx A {@link CommandContext | command context}
-* @returns Options symbols for usage
-*/
-function generateOptionsSymbols(ctx) {
-	return hasOptions(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translation("OPTIONS")}]` : `<${ctx.translation("OPTIONS")}>` : "";
-}
-/**
-* Get options pairs for usage
-* @param ctx A {@link CommandContext | command context}
-* @returns Options pairs for usage
-*/
-function getOptionsPairs(ctx) {
-	return Object.entries(ctx.options).reduce((acc, [name, value]) => {
-		let key = `--${name}`;
-		if (value.short) key = `-${value.short}, ${key}`;
-		if (value.type !== "boolean") key = value.default ? `${key} [${name}]` : `${key} <${name}>`;
-		acc[name] = key;
-		return acc;
-	}, create());
-}
-/**
-* Generate options usage
-* @param ctx A {@link CommandContext | command context}
-* @param optionsPairs Options pairs for usage
-* @returns Generated options usage
-*/
-async function generateOptionsUsage(ctx, optionsPairs) {
-	const optionsMaxLength = Math.max(...Object.entries(optionsPairs).map(([_, value]) => value.length));
-	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...Object.entries(optionsPairs).map(([key, _]) => ctx.options[key].type.length)) : 0;
-	const usages = await Promise.all(Object.entries(optionsPairs).map(([key, value]) => {
-		const rawDesc = ctx.translation(key);
-		const optionsSchema = ctx.env.usageOptionType ? `[${ctx.options[key].type}] ` : "";
-		const desc = `${optionsSchema ? optionsSchema.padEnd(optionSchemaMaxLength + 3) : ""}${rawDesc}`;
-		const option = `${value.padEnd(optionsMaxLength + ctx.env.middleMargin)}${desc}`;
-		return `${option.padStart(ctx.env.leftMargin + option.length)}`;
-	}));
-	return usages.join("\n");
-}
-
-//#endregion
-//#region src/renderer/validation.ts
-function renderValidationErrors(_ctx, error) {
-	const messages = [];
-	for (const err of error.errors) messages.push(err.message);
-	return Promise.resolve(messages.join("\n"));
-}
-
-//#endregion
 //#region src/cli.ts
 async function cli(args, entry, opts = {}) {
 	const tokens = parseArgs(args);

package/lib/renderer/index.d.ts

@@ -0,0 +1,26 @@
+import { ArgOptions } from 'args-tokens';
+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 = 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 = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
+
+/**
+* Render the validation errors
+* @param ctx A {@link CommandContext | command context}
+* @param error An {@link AggregateError} of option in `args-token` validation
+* @returns A rendered validation error
+*/
+declare function renderValidationErrors<Options extends ArgOptions = ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
+
+export { renderHeader, renderUsage, renderValidationErrors };

package/lib/renderer/index.js

@@ -0,0 +1,4 @@
+import "../utils-NHs5DuHk.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-MpQ9U28q.js";
+
+export { renderHeader, renderUsage, renderValidationErrors };

package/lib/renderer-MpQ9U28q.js

@@ -0,0 +1,192 @@
+import { create } from "./utils-NHs5DuHk.js";
+
+//#region src/renderer/header.ts
+function renderHeader(ctx) {
+	const title = ctx.env.description || ctx.env.name || "";
+	return Promise.resolve(title ? `${title} (${ctx.env.name || ""}${ctx.env.version ? ` v${ctx.env.version}` : ""})` : title);
+}
+
+//#endregion
+//#region src/renderer/usage.ts
+async function renderUsage(ctx) {
+	const messages = [];
+	if (!ctx.omitted && hasDescription(ctx)) messages.push(ctx.description, "");
+	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), "");
+	return messages.join("\n");
+}
+/**
+* Render the options section
+* @param ctx A {@link CommandContext | command context}
+* @returns A rendered options section
+*/
+async function renderOptionsSection(ctx) {
+	const messages = [];
+	messages.push(`${ctx.translation("OPTIONS")}:`);
+	const optionsPairs = getOptionsPairs(ctx);
+	messages.push(await generateOptionsUsage(ctx, optionsPairs));
+	return messages;
+}
+/**
+* Render the examples section
+* @param ctx A {@link CommandContext | command context}
+* @returns A rendered examples section
+*/
+function renderExamplesSection(ctx) {
+	const messages = [];
+	const examples = ctx.usage.examples.split("\n").map((example) => example.padStart(ctx.env.leftMargin + example.length));
+	messages.push(`${ctx.translation("EXAMPLES")}:`, ...examples);
+	return messages;
+}
+/**
+* Render the usage section
+* @param ctx A {@link CommandContext | command context}
+* @returns A rendered usage section
+*/
+async function renderUsageSection(ctx) {
+	const messages = [`${ctx.translation("USAGE")}:`];
+	if (ctx.omitted) {
+		const defaultCommand = `${resolveEntry(ctx)}${await hasCommands(ctx) ? ` [${resolveSubCommand(ctx)}]` : ""} ${hasOptions(ctx) ? `<${ctx.translation("OPTIONS")}>` : ""} `;
+		messages.push(defaultCommand.padStart(ctx.env.leftMargin + defaultCommand.length));
+		if (await hasCommands(ctx)) {
+			const commandsUsage = `${resolveEntry(ctx)} <${ctx.translation("COMMANDS")}>`;
+			messages.push(commandsUsage.padStart(ctx.env.leftMargin + commandsUsage.length));
+		}
+	} else {
+		const usageStr = `${resolveEntry(ctx)} ${resolveSubCommand(ctx)} ${generateOptionsSymbols(ctx)}`;
+		messages.push(usageStr.padStart(ctx.env.leftMargin + usageStr.length));
+	}
+	return messages;
+}
+/**
+* Render the commands section
+* @param ctx A {@link CommandContext | command context}
+* @returns A rendered commands section
+*/
+async function renderCommandsSection(ctx) {
+	const messages = [`${ctx.translation("COMMANDS")}:`];
+	const loadedCommands = await ctx.loadCommands();
+	const commandMaxLength = Math.max(...loadedCommands.map((cmd) => (cmd.name || "").length));
+	const commandsStr = await Promise.all(loadedCommands.map((cmd) => {
+		const key = cmd.name || "";
+		const desc = cmd.description || "";
+		const command = `${key.padEnd(commandMaxLength + ctx.env.middleMargin)}${desc} `;
+		return `${command.padStart(ctx.env.leftMargin + command.length)} `;
+	}));
+	messages.push(...commandsStr, "", ctx.translation("FORMORE"));
+	messages.push(...loadedCommands.map((cmd) => {
+		const commandHelp = `${ctx.env.name} ${cmd.name} --help`;
+		return `${commandHelp.padStart(ctx.env.leftMargin + commandHelp.length)}`;
+	}));
+	return messages;
+}
+/**
+* Resolve the entry command name
+* @param ctx A {@link CommandContext | command context}
+* @returns The entry command name
+*/
+function resolveEntry(ctx) {
+	return ctx.env.name || ctx.translation("COMMAND");
+}
+/**
+* Resolve the sub command name
+* @param ctx A {@link CommandContext | command context}
+* @returns The sub command name
+*/
+function resolveSubCommand(ctx) {
+	return ctx.name || ctx.translation("SUBCOMMAND");
+}
+/**
+* Check if the command has a description
+* @param ctx A {@link CommandContext | command context}
+* @returns True if the command has a description
+*/
+function hasDescription(ctx) {
+	return !!ctx.description;
+}
+/**
+* Check if the command has sub commands
+* @param ctx A {@link CommandContext | command context}
+* @returns True if the command has sub commands
+*/
+async function hasCommands(ctx) {
+	const loadedCommands = await ctx.loadCommands();
+	return loadedCommands.length > 1;
+}
+/**
+* Check if the command has options
+* @param ctx A {@link CommandContext | command context}
+* @returns True if the command has options
+*/
+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
+*/
+function hasAllDefaultOptions(ctx) {
+	return !!(ctx.options && Object.values(ctx.options).every((opt) => opt.default));
+}
+/**
+* Generate options symbols for usage
+* @param ctx A {@link CommandContext | command context}
+* @returns Options symbols for usage
+*/
+function generateOptionsSymbols(ctx) {
+	return hasOptions(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translation("OPTIONS")}]` : `<${ctx.translation("OPTIONS")}>` : "";
+}
+/**
+* Get options pairs for usage
+* @param ctx A {@link CommandContext | command context}
+* @returns Options pairs for usage
+*/
+function getOptionsPairs(ctx) {
+	return Object.entries(ctx.options).reduce((acc, [name, value]) => {
+		let key = `--${name}`;
+		if (value.short) key = `-${value.short}, ${key}`;
+		if (value.type !== "boolean") key = value.default ? `${key} [${name}]` : `${key} <${name}>`;
+		acc[name] = key;
+		return acc;
+	}, create());
+}
+/**
+* Generate options usage
+* @param ctx A {@link CommandContext | command context}
+* @param optionsPairs Options pairs for usage
+* @returns Generated options usage
+*/
+async function generateOptionsUsage(ctx, optionsPairs) {
+	const optionsMaxLength = Math.max(...Object.entries(optionsPairs).map(([_, value]) => value.length));
+	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...Object.entries(optionsPairs).map(([key, _]) => ctx.options[key].type.length)) : 0;
+	const usages = await Promise.all(Object.entries(optionsPairs).map(([key, value]) => {
+		const rawDesc = ctx.translation(key);
+		const optionsSchema = ctx.env.usageOptionType ? `[${ctx.options[key].type}] ` : "";
+		const desc = `${optionsSchema ? optionsSchema.padEnd(optionSchemaMaxLength + 3) : ""}${rawDesc}`;
+		const option = `${value.padEnd(optionsMaxLength + ctx.env.middleMargin)}${desc}`;
+		return `${option.padStart(ctx.env.leftMargin + option.length)}`;
+	}));
+	return usages.join("\n");
+}
+
+//#endregion
+//#region src/renderer/validation.ts
+function renderValidationErrors(_ctx, error) {
+	const messages = [];
+	for (const err of error.errors) messages.push(err.message);
+	return Promise.resolve(messages.join("\n"));
+}
+
+//#endregion
+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/lib/utils-NHs5DuHk.js

@@ -0,0 +1,24 @@
+
+//#region src/utils.ts
+async function resolveLazyCommand(cmd, name, entry = false) {
+	const resolved = Object.assign(create(), typeof cmd == "function" ? await cmd() : cmd, { default: entry });
+	if (resolved.name == null && name) resolved.name = name;
+	return deepFreeze(resolved);
+}
+function create(obj = null) {
+	return Object.create(obj);
+}
+function log(...args) {
+	console.log(...args);
+}
+function deepFreeze(obj) {
+	if (obj === null || typeof obj !== "object") return obj;
+	for (const key of Object.keys(obj)) {
+		const value = obj[key];
+		if (typeof value === "object" && value !== null) deepFreeze(value);
+	}
+	return Object.freeze(obj);
+}
+
+//#endregion
+export { create, deepFreeze, log, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -49,10 +49,10 @@
       "default": "./lib/context.js"
     },
     "./renderer": {
-      "types": "./lib/renderer.d.ts",
-      "import": "./lib/renderer.js",
-      "require": "./lib/renderer.js",
-      "default": "./lib/renderer.js"
+      "types": "./lib/renderer/index.d.ts",
+      "import": "./lib/renderer/index.js",
+      "require": "./lib/renderer/index.js",
+      "default": "./lib/renderer/index.js"
     },
     "./package.json": "./package.json",
     "./*": "./*"