gunshi 0.2.1 → 0.3.0

package/README.md

@@ -5,22 +5,22 @@
 
 [![Version][npm-version-src]][npm-version-href]
 [![CI][ci-src]][ci-href]
+[![InstallSize][install-size-src]][install-size-src]
 
 <!--
 [![JSR][jsr-src]][jsr-href]
-[![InstallSize][install-size-src]][install-size-src]
 -->
 
 Gunshi is a modern javascript command-line library
 
 > [!TIP]
-> gunshi (軍師) is a position in ancient Japanese samurai battle in which a amurai devised strategies and gave orders. That name is inspired by the word "command.”
+> gunshi (軍師) is a position in ancient Japanese samurai battle in which a amurai devised strategies and gave orders. That name is inspired by the word "command".
 
 ## ✨ Features
 
 Gunshi is designed to simplify the creation of modern command-line interfaces:
 
-- 📏 **Minimal**: Run the commands with a minimum API.
+- 📏 **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.
 - 🧩 **Composable**: Sub-commands that can be composed with modularized commands.
@@ -40,13 +40,338 @@ pnpm add gunshi
 
 ## yarn
 yarn add gunshi
+```
+
+## 🚀 Usage
+
+### Simple API
+
+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!')
+})
+```
+
+### 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:
+
+```js
+import { cli } from 'gunshi'
+
+// Define a command with declarative configuration
+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)'
+    }
+  },
+  run: ctx => {
+    const { name = 'World', greeting, times } = ctx.values
+    for (let i = 0; i < times; i++) {
+      console.log(`${greeting}, ${name}!`)
+    }
+  }
+}
+
+cli(process.argv.slice(2), command, {
+  name: 'my-app',
+  version: '1.0.0',
+  description: 'My CLI application'
+})
 ```
 
+For more detailed examples, check out the [playground/declarative](https://github.com/kazupon/gunshi/tree/main/playground/declarative) in the repository.
+
+### Composable Sub-commands
+
+Create a CLI with composable sub-commands:
+
+```js
+import { cli } from 'gunshi'
+
+// Define sub-commands
+const createCommand = {
+  name: 'create',
+  description: 'Create a new resource',
+  options: {
+    name: { type: 'string', short: 'n' }
+  },
+  run: ctx => {
+    console.log(`Creating resource: ${ctx.values.name}`)
+  }
+}
+
+const listCommand = {
+  name: 'list',
+  description: 'List all resources',
+  run: () => {
+    console.log('Listing all resources...')
+  }
+}
+
+// Create a Map of sub-commands
+const subCommands = new Map()
+subCommands.set('create', createCommand)
+subCommands.set('list', listCommand)
+
+// Define the main command
+const mainCommand = {
+  name: 'resource-manager',
+  description: 'Manage resources',
+  run: () => {
+    console.log('Use one of the sub-commands: create, list')
+  }
+}
+
+// Run the CLI with composable sub-commands
+cli(process.argv.slice(2), mainCommand, {
+  name: 'my-app',
+  version: '1.0.0',
+  subCommands
+})
+```
+
+For more detailed examples, check out the [playground/composable](https://github.com/kazupon/gunshi/tree/main/playground/composable) in the repository.
+
+### Lazy & Async Command Loading
+
+Load commands lazily and execute them asynchronously:
+
+```js
+import { cli } from 'gunshi'
+
+// Define a command that will be loaded lazily
+const lazyCommand = async () => {
+  // Simulate async loading
+  await new Promise(resolve => setTimeout(resolve, 1000))
+
+  // Return the actual command
+  return {
+    name: 'lazy',
+    description: 'A command that is loaded lazily',
+    run: async ctx => {
+      // Async execution
+      await new Promise(resolve => setTimeout(resolve, 500))
+      console.log('Command executed!')
+    }
+  }
+}
+
+// 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
+cli(
+  process.argv.slice(2),
+  { name: 'main', run: () => {} },
+  {
+    name: 'my-app',
+    subCommands
+  }
+)
+```
+
+For more detailed examples, check out the [playground/lazy-async](https://github.com/kazupon/gunshi/tree/main/playground/lazy-async) in the repository.
+
+### Auto Usage Generation
+
+Gunshi automatically generates usage information:
+
+```js
+import { cli } from 'gunshi'
+
+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 }
+  },
+  usage: {
+    options: {
+      path: 'File or directory path',
+      recursive: 'Operate recursively on directories',
+      operation: 'Operation to perform (list, copy, move, delete)'
+    },
+    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, {
+  name: 'my-app',
+  version: '1.0.0'
+})
+```
+
+For more detailed examples, check out the [playground/auto-usage](https://github.com/kazupon/gunshi/tree/main/playground/auto-usage) in the repository.
+
+### Custom Usage Generation
+
+Customize the usage message generation:
+
+```js
+import { cli } from 'gunshi'
+
+// Custom header renderer
+const customHeaderRenderer = ctx => {
+  return Promise.resolve(`
+╔═══════════════════════╗
+║      ${ctx.env.name.toUpperCase()}      ║
+╚═══════════════════════╝
+${ctx.env.description}
+Version: ${ctx.env.version}
+`)
+}
+
+// Custom usage renderer
+const customUsageRenderer = ctx => {
+  const lines = []
+  lines.push('USAGE:')
+  lines.push(`  $ ${ctx.env.name} [options]`)
+  lines.push('')
+  lines.push('OPTIONS:')
+
+  for (const [key, option] of Object.entries(ctx.options || {})) {
+    const shortFlag = option.short ? `-${option.short}, ` : '    '
+    lines.push(`  ${shortFlag}--${key.padEnd(10)} ${ctx.translation(key)}`)
+  }
+
+  return Promise.resolve(lines.join('\n'))
+}
+
+// Run with custom renderers
+cli(
+  process.argv.slice(2),
+  { name: 'app', run: () => {} },
+  {
+    name: 'my-app',
+    version: '1.0.0',
+    description: 'My application',
+    renderHeader: customHeaderRenderer,
+    renderUsage: customUsageRenderer
+  }
+)
+```
+
+For more detailed examples, check out the [playground/custom-usage](https://github.com/kazupon/gunshi/tree/main/playground/custom-usage) in the repository.
+
+### Internationalization
+
+Support internationalization:
+
+```js
+import { cli } from 'gunshi'
+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' }
+  },
+  // 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
+    return enUS
+  },
+  run: ctx => {
+    const { name = 'World', formal } = ctx.values
+    const greeting = formal ? ctx.translation('formal') : ctx.translation('informal')
+    console.log(`${greeting}, ${name}!`)
+  }
+}
+
+// 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)
+  locale: new Intl.Locale(process.env.MY_LOCALE || 'en-US')
+})
+```
+
+For more detailed examples, check out the [playground/i18n](https://github.com/kazupon/gunshi/tree/main/playground/i18n) in the repository.
+
 ## 🙌 Contributing guidelines
 
 If you are interested in contributing to `gunshi`, I highly recommend checking out [the contributing guidelines](/CONTRIBUTING.md) here. You'll find all the relevant information such as [how to make a PR](/CONTRIBUTING.md#pull-request-guidelines), [how to setup development](/CONTRIBUTING.md#development-setup)) etc., there.
 
+## 💖 Credits
+
+This project is inspired by:
+
+- [`citty`](https://github.com/unjs/citty), created by UnJS team and contributors
+- cline and claude 3.7 sonnet, examples and docs is generated
+
+Thank you!
+
 ## ©️ License
 
 [MIT](http://opensource.org/licenses/MIT)
@@ -57,11 +382,7 @@ If you are interested in contributing to `gunshi`, I highly recommend checking o
 [npm-version-href]: https://npmjs.com/package/gunshi
 [jsr-src]: https://jsr.io/badges/@kazupon/gunishi
 [jsr-href]: https://jsr.io/@kazupon/gunshi
-
-<!--
-[install-size-src]: https://pkg-size.dev/badge/install/35082
-[install-size-href]: https://pkg-size.dev/gunishi
--->
-
+[install-size-src]: https://pkg-size.dev/badge/install/72346
+[install-size-href]: https://pkg-size.dev/gunshi
 [ci-src]: https://github.com/kazupon/gunshi/actions/workflows/ci.yml/badge.svg
 [ci-href]: https://github.com/kazupon/gunshi/actions/workflows/ci.yml

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

@@ -1,4 +1,3 @@
-import { create, deepFreeze, resolveLazyCommand } from "./utils-NHs5DuHk.js";
 
 //#region locales/en-US.json
 var COMMAND = "COMMAND";
@@ -57,6 +56,28 @@ 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";
@@ -95,7 +116,8 @@ async function createCommandContext({ options, values, positionals, command, com
 		localeResources.set(locale.toString(), builtInLoadedResources);
 	} catch {}
 	/**
-	* define the translation function
+	* define the translation function, which is used to {@link CommandContext.translation}.
+	*
 	*/
 	function translation(key) {
 		if (COMMAND_I18N_RESOURCE_KEYS.includes(key)) {
@@ -174,4 +196,4 @@ async function loadCommandResource(ctx, command) {
 }
 
 //#endregion
-export { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, createCommandContext };
+export { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, create, createCommandContext, log, resolveLazyCommand };

package/lib/context.d.ts

@@ -1,17 +1,50 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-B3YGxDV6.js';
+import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-00BVt8hZ.js';
 
+/**
+* The default locale string, which format is BCP 47 language tag
+*/
 declare const DEFAULT_LOCALE = "en-US";
+/**
+* Parameters of {@link createCommandContext}
+*/
+interface CommandContextParams<
+	Options extends ArgOptions,
+	Values
+> {
+	/**
+	* An options of target command
+	*/
+	options: Options | undefined;
+	/**
+	* A values of target command
+	*/
+	values: Values;
+	/**
+	* A positionals arguments, which passed to the target command
+	*/
+	positionals: string[];
+	/**
+	* Whether the command is omitted
+	*/
+	omitted: boolean;
+	/**
+	* A target {@link Command | command}
+	*/
+	command: Command<Options>;
+	/**
+	* A command options, which is spicialized from `cli` function
+	*/
+	commandOptions: CommandOptions<Options>;
+}
+/**
+* Create a {@link CommandContext | command context}
+* @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
+* @returns A {@link CommandContext | command context}, which is readonly
+*/
 declare function createCommandContext<
 	Options extends ArgOptions,
 	Values = ArgValues<Options>
->({ options, values, positionals, command, commandOptions, omitted }: {
-	options: Options | undefined
-	values: Values
-	positionals: string[]
-	omitted: boolean
-	command: Command<Options>
-	commandOptions: CommandOptions<Options>
-}): Promise<Readonly<CommandContext<Options, Values>>>;
+>({ options, values, positionals, command, commandOptions, omitted }: CommandContextParams<Options, Values>): Promise<Readonly<CommandContext<Options, Values>>>;
 
 export { DEFAULT_LOCALE, createCommandContext };

package/lib/context.js

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

package/lib/index.d.ts

@@ -1,13 +1,13 @@
 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-B3YGxDV6.js';
-export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, b as CommandContext, g as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, h as CommandUsageRender, L as LazyCommand } from './types.d-B3YGxDV6.js';
+import { C as Command, c as CommandRunner, a as CommandOptions } from './types.d-00BVt8hZ.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-00BVt8hZ.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}
+* @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>;
 

package/lib/index.js

@@ -1,8 +1,195 @@
-import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, createCommandContext } from "./context-BQKZW5bg.js";
-import { create, log, resolveLazyCommand } from "./utils-NHs5DuHk.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-Bo0DibAK.js";
+import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, createCommandContext, log, resolveLazyCommand } from "./context-B5z7lnoV.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);
@@ -33,7 +220,7 @@ async function cli(args, entry, opts = {}) {
 	}
 	if (error) {
 		await showValidationErrors(ctx, error);
-		throw error;
+		return;
 	}
 	await command.run(ctx);
 }

package/lib/{types.d-B3YGxDV6.d.ts → types.d-00BVt8hZ.d.ts}

@@ -25,54 +25,54 @@ declare namespace __constants {
 */
 type Awaitable<T> = T | Promise<T>;
 /**
-* The command i18n built-in options keys
+* Command i18n built-in options keys
 * @experimental
 */
 type CommandBuiltinOptionsKeys = keyof (typeof __constants)["COMMON_OPTIONS"];
 /**
-* The command i18n built-in resource keys
+* Command i18n built-in resource keys
 * @experimental
 */
 type CommandBuiltinResourceKeys = (typeof __constants)["COMMAND_I18N_RESOURCE_KEYS"][number];
 /**
-* The command i18n built-in keys
+* Command i18n built-in keys
 * @description The command i18n built-in keys are used to {@link CommandContext.translation | translate} function
 * @experimental
 */
 type CommandBuiltinKeys = CommandBuiltinOptionsKeys | CommandBuiltinResourceKeys | "description" | "examples";
 /**
-* The command environment
+* Command environment
 */
 interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	/**
-	* The current working directory
+	* Current working directory
 	* @see {@link CommandOptions.cwd}
 	*/
 	cwd: string | undefined;
 	/**
-	* The command name
+	* Command name
 	* @see {@link CommandOptions.name}
 	*/
 	name: string | undefined;
 	/**
-	* The command description
+	* Command description
 	* @see {@link CommandOptions.description}
 	*
 	*/
 	description: string | undefined;
 	/**
-	* The command version
+	* Command version
 	* @see {@link CommandOptions.version}
 	*/
 	version: string | undefined;
 	/**
-	* The left margin of the command output
+	* Left margin of the command output
 	* @default 2
 	* @see {@link CommandOptions.leftMargin}
 	*/
 	leftMargin: number;
 	/**
-	* The middle margin of the command output
+	* Middle margin of the command output
 	* @default 10
 	* @see {@link CommandOptions.middleMargin}
 	*/
@@ -84,7 +84,7 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	*/
 	usageOptionType: boolean;
 	/**
-	* The sub commands
+	* Sub commands
 	* @see {@link CommandOptions.subCommands}
 	*/
 	subCommands: Map<string, Command<Options> | LazyCommand<Options>> | undefined;
@@ -102,45 +102,40 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	renderValidationErrors: ((ctx: CommandContext<Options>, error: AggregateError) => Promise<string>) | null | undefined;
 }
 /**
-* The command options
+* Command options
 */
 interface CommandOptions<Options extends ArgOptions> {
 	/**
-	* The current working directory
-	* @description This is the current working directory path passed in the context of the run command. This is useful if you need your command about the current execution directory.
+	* Current working directory
 	*/
 	cwd?: string;
 	/**
-	* The command name
-	* @description Please specify the name of the command that was executed. If you would specify it, gunshi will be displayed in the usage.
+	* Command program name
 	*/
 	name?: string;
 	/**
-	* The command description
-	* @description Please specify the description (summary) of the command that was executed. If you would specify it, gunshi will be displayed in the usage.
+	* Command program description
 	*
 	*/
 	description?: string;
 	/**
-	* The command version
-	* @description Please specify the version of the command that was executed. If you would specify it, gunshi will be displayed in the usage.
+	* Command program version
 	*/
 	version?: string;
 	/**
-	* The locale of the command
-	* @description The locale of the command that was executed. If you would specify it, gunshi command usage will be localized.
+	* Command program locale
 	*/
 	locale?: string | Intl.Locale;
 	/**
-	* The sub commands
+	* Sub commands
 	*/
 	subCommands?: Map<string, Command<Options> | LazyCommand<Options>>;
 	/**
-	* The left margin of the command output
+	* Left margin of the command output
 	*/
 	leftMargin?: number;
 	/**
-	* The middle margin of the command output
+	* Middle margin of the command output
 	*/
 	middleMargin?: number;
 	/**
@@ -161,44 +156,44 @@ interface CommandOptions<Options extends ArgOptions> {
 	renderValidationErrors?: ((ctx: Readonly<CommandContext<Options>>, error: AggregateError) => Promise<string>) | null;
 }
 /**
-* The command context
-* @description The command context is the context of the command execution
+* Command context
+* @description Command context is the context of the command execution
 */
 interface CommandContext<
 	Options extends ArgOptions,
 	Values = ArgValues<Options>
 > {
 	/**
-	* The command name, that is the command that is executed
+	* Command name, that is the command that is executed
 	* @description The command name is same {@link CommandEnvironment.name}
 	*/
 	name: string | undefined;
 	/**
-	* The command description, that is the description of the command that is executed
+	* Command description, that is the description of the command that is executed
 	* @description The command description is same {@link CommandEnvironment.description}
 	*/
 	description: string | undefined;
 	/**
-	* The command locale, that is the locale of the command that is executed
+	* Command locale, that is the locale of the command that is executed
 	*/
 	locale: Intl.Locale;
 	/**
-	* The command environment, that is the environment of the command that is executed
+	* Command environment, that is the environment of the command that is executed
 	* @description The command environment is same {@link CommandEnvironment}
 	*/
 	env: CommandEnvironment<Options>;
 	/**
-	* The command options, that is the options of the command that is executed
+	* Command options, that is the options of the command that is executed
 	* @description The command options is same {@link Command.options}
 	*/
 	options: Options | undefined;
 	/**
-	* The command values, that is the values of the command that is executed
+	* Command values, that is the values of the command that is executed
 	* @description Resolve values with `resolveArgs` from command arguments and {@link Command.options}
 	*/
 	values: Values;
 	/**
-	* The command positionals, that is the positionals of the command that is executed
+	* Command positionals arguments, that is the positionals of the command that is executed
 	* @description Resolve positionals with `resolveArgs` from command arguments
 	*/
 	positionals: string[];
@@ -207,20 +202,20 @@ interface CommandContext<
 	*/
 	omitted: boolean;
 	/**
-	* The usage of the command
-	* @description The usage of the command is same {@link Command.usage}, and more has `--help` and `--version` options
+	* Command usage
+	* @description Usage of the command is same {@link Command.usage}, and more has `--help` and `--version` options
 	*/
 	usage: CommandUsage<Options>;
 	/**
-	* Load the sub-commands
+	* Load sub-commands
 	* @description The loaded commands are cached and returned when called again
 	* @returns loaded commands
 	*/
 	loadCommands: () => Promise<Command<Options>[]>;
 	/**
-	* The translation function
-	* @param key {CommandBuiltinKeys | T} - The key to be translated
-	* @returns The translated string, if the key is not found, the key itself is returned
+	* Translation function
+	* @param key the key to be translated
+	* @returns A translated string
 	* @experimental
 	*/
 	translation: <
@@ -229,37 +224,32 @@ interface CommandContext<
 	>(key: Key) => string;
 }
 /**
-* The command usage render
-* @description if the render function is async, it should return a promise
-*/
-type CommandUsageRender<Options extends ArgOptions> = ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | string;
-/**
-* The command usage
+* Command usage
 */
 interface CommandUsage<Options extends ArgOptions> {
 	/**
-	* The options usage
+	* Options usage
 	*/
 	options?: { [Option in keyof Options] : string };
 	/**
-	* The examples usage
+	* Examples usage
 	*/
 	examples?: string;
 }
 /**
-* The command interface
+* Command interface
 */
 interface Command<Options extends ArgOptions> {
 	/**
-	* The command name
+	* Command name
 	* @description
-	* The command name is used to find command line arguments to execute from sub commands, so it's recommended to specify.
+	* Command name is used to find command line arguments to execute from sub commands, so it's recommended to specify.
 	*/
 	name?: string;
 	/**
-	* The command description
+	* Command description
 	* @description
-	* The command description is used to describe the command in usage, so it's recommended to specify.
+	* Command description is used to describe the command in usage, so it's recommended to specify.
 	*/
 	description?: string;
 	/**
@@ -268,57 +258,59 @@ interface Command<Options extends ArgOptions> {
 	*/
 	default?: boolean;
 	/**
-	* The command options
+	* Command options
 	*/
 	options?: Options;
 	/**
-	* The command usage
+	* Command usage
 	* @description
-	* The command usage is used to describe the command in usage, so it's recommended to specify.
+	* Command usage is used to describe the command in usage, so it's recommended to specify.
 	*/
 	usage?: CommandUsage<Options>;
 	/**
-	* The command runner, that's the command to be executed
+	* Command runner, that's the command to be executed
 	*/
 	run: CommandRunner<Options>;
 	/**
-	* The command resource fetcher
+	* Command resource fetcher
 	* @experimental
 	*/
 	resource?: CommandResourceFetcher<Options>;
 }
 /**
-* The command resource
+* Command resource
 * @experimental
 */
 interface CommandResource<Options extends ArgOptions> {
 	/**
-	* The command description resource
+	* Command description
 	*/
 	description: string;
 	/**
-	* The options usage resources
+	* Options usage
 	*/
 	options: { [Option in keyof Options] : string };
 	/**
-	* The examples usage resources
+	* Examples usage
 	*/
 	examples: string;
 }
 /**
-* The command resource fetcher
+* Command resource fetcher
+* @param ctx A {@link CommandContext | command context}
+* @returns A fetched {@link CommandResource | command resource}
 * @experimental
 */
 type CommandResourceFetcher<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
 /**
-* The command runner interface
-* @param ctx - The {@link CommandContext | command context}
+* Command runner
+* @param ctx A {@link CommandContext | command context}
 */
 type CommandRunner<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Awaitable<void>;
 /**
-* The lazy command interface
-* @description The lazy command that's not loaded until it is executed
+* Lazy command interface
+* @description lazy command that's not loaded until it is executed
 */
 type LazyCommand<Options extends ArgOptions> = () => Awaitable<Command<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, CommandUsageRender as h, CommandResource as i, CommandResourceFetcher as j };
+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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -86,10 +86,10 @@
     "gh-changelogen": "^0.2.8",
     "knip": "^5.45.0",
     "lint-staged": "^15.4.3",
-    "pkg-pr-new": "^0.0.40",
+    "pkg-pr-new": "^0.0.41",
     "prettier": "^3.5.3",
     "tsdown": "^0.6.4",
-    "typescript": "^5.8.2",
+    "typescript": "^5.4.2",
     "typescript-eslint": "^8.26.0",
     "vitest": "^3.0.7"
   },
@@ -113,11 +113,11 @@
     "clean": "git clean -df",
     "dev": "pnpx @eslint/config-inspector --config eslint.config.ts",
     "dev:eslint": "pnpx @eslint/config-inspector --config eslint.config.ts",
-    "fix": "pnpm run --parallel --color \"/^fix:/\"",
+    "fix": "pnpm run --stream --color \"/^fix:/\"",
     "fix:eslint": "eslint . --fix",
     "fix:knip": "knip --fix --no-exit-code",
     "fix:prettier": "prettier . --write",
-    "lint": "pnpm run --parallel --color \"/^lint:/\"",
+    "lint": "pnpm run --stream --color \"/^lint:/\"",
     "lint:eslint": "eslint .",
     "lint:knip": "knip",
     "lint:prettier": "prettier . --check",

package/lib/renderer-Bo0DibAK.js

@@ -1,115 +0,0 @@
-import { create } from "./utils-NHs5DuHk.js";
-
-//#region src/renderer.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);
-}
-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");
-}
-function renderValidationErrors(_ctx, error) {
-	const messages = [];
-	for (const err of error.errors) messages.push(err.message);
-	return Promise.resolve(messages.join("\n"));
-}
-async function renderOptionsSection(ctx) {
-	const messages = [];
-	messages.push(`${ctx.translation("OPTIONS")}:`);
-	const optionsPairs = getOptionsPairs(ctx);
-	messages.push(await generateOptionsUsage(ctx, optionsPairs));
-	return messages;
-}
-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;
-}
-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;
-}
-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;
-}
-function resolveEntry(ctx) {
-	return ctx.env.name || ctx.translation("COMMAND");
-}
-function resolveSubCommand(ctx) {
-	return ctx.name || ctx.translation("SUBCOMMAND");
-}
-function hasDescription(ctx) {
-	return !!ctx.description;
-}
-async function hasCommands(ctx) {
-	const loadedCommands = await ctx.loadCommands();
-	return loadedCommands.length > 1;
-}
-function hasOptions(ctx) {
-	return !!(ctx.options && Object.keys(ctx.options).length > 0);
-}
-function hasExamples(ctx) {
-	return !!ctx.usage.examples;
-}
-function hasAllDefaultOptions(ctx) {
-	return !!(ctx.options && Object.values(ctx.options).every((opt) => opt.default));
-}
-function generateOptionsSymbols(ctx) {
-	return hasOptions(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translation("OPTIONS")}]` : `<${ctx.translation("OPTIONS")}>` : "";
-}
-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());
-}
-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
-export { renderHeader, renderUsage, renderValidationErrors };

package/lib/renderer.d.ts

@@ -1,8 +0,0 @@
-import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from './types.d-B3YGxDV6.js';
-
-declare function renderHeader<Options extends ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
-declare function renderUsage<Options extends ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
-declare function renderValidationErrors<Options extends ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
-
-export { renderHeader, renderUsage, renderValidationErrors };

package/lib/renderer.js

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

package/lib/utils-NHs5DuHk.js

@@ -1,24 +0,0 @@
-
-//#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 };