gunshi 0.0.0 → 0.2.0

package/README.md

@@ -1,13 +1,67 @@
 <p align="center">
-	<img width="110" src="./assets/logo.webp">
+	<img width="196" src="./assets/logo.webp">
 </p>
-<h1 align="center">🏯 gunshi</h1>
+<h1 align="center">🏯 Gunshi</h1>
 
-Modern command-line interfaces composer
+[![Version][npm-version-src]][npm-version-href]
+[![CI][ci-src]][ci-href]
 
-> [!WARNING]
-> WIP
+<!--
+[![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.”
+
+## ✨ Features
+
+Gunshi is designed to simplify the creation of modern command-line interfaces:
+
+- 📏 **Minimal**: Run the commands with a minimum 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.
+- ⏳ **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.
+
+## 💿 Installation
+
+```sh
+# npm
+npm install --save gunshi
+
+## pnpm
+pnpm add gunshi
+
+## yarn
+yarn add gunshi
+
+```
+
+## 🙌 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.
 
 ## ©️ License
 
 [MIT](http://opensource.org/licenses/MIT)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/gunshi?style=flat
+[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
+-->
+
+[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/cli.d.ts

@@ -0,0 +1,9 @@
+import type { ArgOptions } from "args-tokens";
+import type { Command, CommandOptions, CommandRunner } from "./types.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}
+*/
+export declare function cli<Options extends ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<void>;

package/lib/constants.d.ts

@@ -0,0 +1,14 @@
+import type { ArgOptions } from "args-tokens";
+import type { CommandOptions } from "./types.js";
+export declare const COMMON_OPTIONS: {
+	readonly help: {
+		readonly type: "boolean"
+		readonly short: "h"
+	}
+	readonly version: {
+		readonly type: "boolean"
+		readonly short: "v"
+	}
+};
+export declare const COMMAND_OPTIONS_DEFAULT: CommandOptions<ArgOptions>;
+export declare const COMMAND_I18N_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "OPTIONS", "EXAMPLES", "FORMORE"];

package/lib/context.d.ts

@@ -0,0 +1,14 @@
+import type { ArgOptions, ArgValues } from "args-tokens";
+import type { Command, CommandContext, CommandOptions } from "./types.js";
+export declare const DEFAULT_LOCALE = "en-US";
+export 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>>>;

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./cli.js";
+export type * from "./types.js";

package/lib/index.js

@@ -1,2 +1,723 @@
-"use strict";
-console.log('Hello, world!');
+
+//#region node_modules/.pnpm/args-tokens@0.10.2/node_modules/args-tokens/lib/parser.js
+const HYPHEN_CHAR = "-";
+const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
+const EQUAL_CHAR = "=";
+const EQUAL_CODE = EQUAL_CHAR.codePointAt(0);
+const TERMINATOR = "--";
+const SHORT_OPTION_PREFIX = HYPHEN_CHAR;
+const LONG_OPTION_PREFIX = "--";
+function parseArgs(args, options = {}) {
+	const { allowCompatible = false } = options;
+	const tokens = [];
+	const remainings = [...args];
+	let index = -1;
+	let groupCount = 0;
+	let hasShortValueSeparator = false;
+	while (remainings.length > 0) {
+		const arg = remainings.shift();
+		if (arg == undefined) break;
+		const nextArg = remainings[0];
+		if (groupCount > 0) groupCount--;
+		else index++;
+		if (arg === TERMINATOR) {
+			tokens.push({
+				kind: "option-terminator",
+				index
+			});
+			const mapped = remainings.map((arg$1) => {
+				return {
+					kind: "positional",
+					index: ++index,
+					value: arg$1
+				};
+			});
+			tokens.push(...mapped);
+			break;
+		}
+		if (isShortOption(arg)) {
+			const shortOption = arg.charAt(1);
+			let value;
+			let inlineValue;
+			if (groupCount) {
+				tokens.push({
+					kind: "option",
+					name: shortOption,
+					rawName: arg,
+					index,
+					value,
+					inlineValue
+				});
+				if (groupCount === 1 && hasOptionValue(nextArg)) {
+					value = remainings.shift();
+					if (hasShortValueSeparator) {
+						inlineValue = true;
+						hasShortValueSeparator = false;
+					}
+					tokens.push({
+						kind: "option",
+						index,
+						value,
+						inlineValue
+					});
+				}
+			} else tokens.push({
+				kind: "option",
+				name: shortOption,
+				rawName: arg,
+				index,
+				value,
+				inlineValue
+			});
+			if (value != null) ++index;
+			continue;
+		}
+		if (isShortOptionGroup(arg)) {
+			const expanded = [];
+			let shortValue = "";
+			for (let i = 1; i < arg.length; i++) {
+				const shortableOption = arg.charAt(i);
+				if (hasShortValueSeparator) shortValue += shortableOption;
+				else if (!allowCompatible && shortableOption.codePointAt(0) === EQUAL_CODE) hasShortValueSeparator = true;
+				else expanded.push(`${SHORT_OPTION_PREFIX}${shortableOption}`);
+			}
+			if (shortValue) expanded.push(shortValue);
+			remainings.unshift(...expanded);
+			groupCount = expanded.length;
+			continue;
+		}
+		if (isLongOption(arg)) {
+			const longOption = arg.slice(2);
+			tokens.push({
+				kind: "option",
+				name: longOption,
+				rawName: arg,
+				index,
+				value: undefined,
+				inlineValue: undefined
+			});
+			continue;
+		}
+		if (isLongOptionAndValue(arg)) {
+			const equalIndex = arg.indexOf(EQUAL_CHAR);
+			const longOption = arg.slice(2, equalIndex);
+			const value = arg.slice(equalIndex + 1);
+			tokens.push({
+				kind: "option",
+				name: longOption,
+				rawName: `${LONG_OPTION_PREFIX}${longOption}`,
+				index,
+				value,
+				inlineValue: true
+			});
+			continue;
+		}
+		tokens.push({
+			kind: "positional",
+			index,
+			value: arg
+		});
+	}
+	return tokens;
+}
+function isShortOption(arg) {
+	return arg.length === 2 && arg.codePointAt(0) === HYPHEN_CODE && arg.codePointAt(1) !== HYPHEN_CODE;
+}
+/**
+* Check if `arg` is a short option group (e.g. `-abc`)
+* @param arg the argument to check
+* @returns whether `arg` is a short option group
+*/
+function isShortOptionGroup(arg) {
+	if (arg.length <= 2) return false;
+	if (arg.codePointAt(0) !== HYPHEN_CODE) return false;
+	if (arg.codePointAt(1) === HYPHEN_CODE) return false;
+	return true;
+}
+/**
+* Check if `arg` is a long option (e.g. `--foo`)
+* @param arg the argument to check
+* @returns whether `arg` is a long option
+*/
+function isLongOption(arg) {
+	return hasLongOptionPrefix(arg) && !arg.includes(EQUAL_CHAR, 3);
+}
+/**
+* Check if `arg` is a long option with value (e.g. `--foo=bar`)
+* @param arg the argument to check
+* @returns whether `arg` is a long option
+*/
+function isLongOptionAndValue(arg) {
+	return hasLongOptionPrefix(arg) && arg.includes(EQUAL_CHAR, 3);
+}
+function hasLongOptionPrefix(arg) {
+	return arg.length > 2 && ~arg.indexOf(LONG_OPTION_PREFIX);
+}
+/**
+* Check if a `value` is an option value
+* @param value a value to check
+* @returns whether a `value` is an option value
+*/
+function hasOptionValue(value) {
+	return !(value == null) && value.codePointAt(0) !== HYPHEN_CODE;
+}
+
+//#endregion
+//#region node_modules/.pnpm/args-tokens@0.10.2/node_modules/args-tokens/lib/resolver.js
+function resolveArgs(options, tokens) {
+	const positionals = [];
+	const longOptionTokens = [];
+	const shortOptionTokens = [];
+	let currentLongOption;
+	let currentShortOption;
+	const expandableShortOptions = [];
+	function toShortValue() {
+		if (expandableShortOptions.length === 0) return undefined;
+		else {
+			const value = expandableShortOptions.map((token) => token.name).join("");
+			expandableShortOptions.length = 0;
+			return value;
+		}
+	}
+	function applyLongOptionValue(value = undefined) {
+		if (currentLongOption) {
+			currentLongOption.value = value;
+			longOptionTokens.push({ ...currentLongOption });
+			currentLongOption = undefined;
+		}
+	}
+	function applyShortOptionValue(value = undefined) {
+		if (currentShortOption) {
+			currentShortOption.value = value || toShortValue();
+			shortOptionTokens.push({ ...currentShortOption });
+			currentShortOption = undefined;
+		}
+	}
+	/**
+	* analyze phase to resolve value
+	* separate tokens into positionals, long and short options, after that resolve values
+	*/
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token.kind === "positional") {
+			positionals.push(token.value);
+			applyLongOptionValue(token.value);
+			applyShortOptionValue(token.value);
+		} else if (token.kind === "option") if (token.rawName) {
+			if (hasLongOptionPrefix(token.rawName)) {
+				if (token.inlineValue) longOptionTokens.push({ ...token });
+				else currentLongOption = { ...token };
+				applyShortOptionValue();
+			} else if (isShortOption(token.rawName)) if (currentShortOption) {
+				if (currentShortOption.index === token.index) expandableShortOptions.push({ ...token });
+				else {
+					currentShortOption.value = toShortValue();
+					shortOptionTokens.push({ ...currentShortOption });
+					currentShortOption = { ...token };
+				}
+				applyLongOptionValue();
+			} else {
+				currentShortOption = { ...token };
+				applyLongOptionValue();
+			}
+		} else {
+			if (currentShortOption && currentShortOption.index == token.index && token.inlineValue) {
+				currentShortOption.value = token.value;
+				shortOptionTokens.push({ ...currentShortOption });
+				currentShortOption = undefined;
+			}
+			applyLongOptionValue();
+		}
+		else {
+			applyLongOptionValue();
+			applyShortOptionValue();
+		}
+	}
+	/**
+	* check if the last long or short option is not resolved
+	*/
+	applyLongOptionValue();
+	applyShortOptionValue();
+	/**
+	* resolve values
+	*/
+	const values = Object.create(null);
+	const errors = [];
+	for (const [option, schema] of Object.entries(options)) {
+		if (schema.required) {
+			const found = longOptionTokens.find((token) => token.name === option) || schema.short && shortOptionTokens.find((token) => token.name === schema.short);
+			if (!found) {
+				errors.push(createRequireError(option, schema));
+				continue;
+			}
+		}
+		for (let i = 0; i < longOptionTokens.length; i++) {
+			const token = longOptionTokens[i];
+			if (option === token.name && token.rawName != null && hasLongOptionPrefix(token.rawName)) {
+				const invalid = validateRequire(token, option, schema);
+				if (invalid) {
+					errors.push(invalid);
+					continue;
+				}
+				if (schema.type === "boolean") token.value = undefined;
+				else {
+					const invalid$1 = validateValue(token, option, schema);
+					if (invalid$1) {
+						errors.push(invalid$1);
+						continue;
+					}
+				}
+				values[option] = resolveOptionValue(token, schema);
+				continue;
+			}
+		}
+		for (let i = 0; i < shortOptionTokens.length; i++) {
+			const token = shortOptionTokens[i];
+			if (schema.short === token.name && token.rawName != null && isShortOption(token.rawName)) {
+				const invalid = validateRequire(token, option, schema);
+				if (invalid) {
+					errors.push(invalid);
+					continue;
+				}
+				if (schema.type === "boolean") token.value = undefined;
+				else {
+					const invalid$1 = validateValue(token, option, schema);
+					if (invalid$1) {
+						errors.push(invalid$1);
+						continue;
+					}
+				}
+				values[option] = resolveOptionValue(token, schema);
+				continue;
+			}
+		}
+		if (values[option] == null && schema.default != null) values[option] = schema.default;
+	}
+	return {
+		values,
+		positionals,
+		error: errors.length > 0 ? new AggregateError(errors) : undefined
+	};
+}
+function createRequireError(option, schema) {
+	return new Error(`Option '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}is required`);
+}
+function validateRequire(token, option, schema) {
+	if (schema.required && schema.type !== "boolean" && !token.value) return createRequireError(option, schema);
+}
+function validateValue(token, option, schema) {
+	switch (schema.type) {
+		case "number": {
+			if (!isNumeric(token.value)) return createTypeError(option, schema);
+			break;
+		}
+		case "string": {
+			if (typeof token.value !== "string") return createTypeError(option, schema);
+			break;
+		}
+	}
+}
+function isNumeric(str) {
+	return str.trim() !== "" && !isNaN(str);
+}
+function createTypeError(option, schema) {
+	return new TypeError(`Option '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be '${schema.type}'`);
+}
+function resolveOptionValue(token, schema) {
+	if (token.value) return schema.type === "number" ? +token.value : token.value;
+	if (schema.type === "boolean") return true;
+	return schema.type === "number" ? +(schema.default || "") : schema.default;
+}
+
+//#endregion
+//#region src/constants.ts
+const COMMON_OPTIONS = {
+	help: {
+		type: "boolean",
+		short: "h"
+	},
+	version: {
+		type: "boolean",
+		short: "v"
+	}
+};
+const COMMAND_OPTIONS_DEFAULT = {
+	name: undefined,
+	description: undefined,
+	version: undefined,
+	cwd: undefined,
+	subCommands: undefined,
+	leftMargin: 2,
+	middleMargin: 10,
+	usageOptionType: false,
+	renderHeader: undefined,
+	renderUsage: undefined,
+	renderValidationErrors: undefined
+};
+const COMMAND_I18N_RESOURCE_KEYS = [
+	"USAGE",
+	"COMMAND",
+	"SUBCOMMAND",
+	"COMMANDS",
+	"OPTIONS",
+	"EXAMPLES",
+	"FORMORE"
+];
+
+//#endregion
+//#region locales/en-US.json
+var COMMAND = "COMMAND";
+var COMMANDS = "COMMANDS";
+var SUBCOMMAND = "SUBCOMMAND";
+var USAGE = "USAGE";
+var OPTIONS = "OPTIONS";
+var EXAMPLES = "EXAMPLES";
+var FORMORE = "For more info, run any command with the `--help` flag:";
+var help = "Display this help message";
+var version = "Display this version";
+var en_US_default = {
+	COMMAND,
+	COMMANDS,
+	SUBCOMMAND,
+	USAGE,
+	OPTIONS,
+	EXAMPLES,
+	FORMORE,
+	help,
+	version
+};
+
+//#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";
+async function createCommandContext({ options, values, positionals, command, commandOptions, omitted = false }) {
+	/**
+	* tweak the options and values
+	*/
+	const _options = options == null ? undefined : 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 localeResources = new Map();
+	const commandResources = new Map();
+	let builtInLoadedResources;
+	/**
+	* load the built-in locale resources
+	*/
+	localeResources.set(DEFAULT_LOCALE, en_US_default);
+	if (DEFAULT_LOCALE !== locale.toString()) try {
+		builtInLoadedResources = await import(`../locales/${locale.toString()}.json`, { with: { type: "json" } });
+		localeResources.set(locale.toString(), builtInLoadedResources);
+	} catch {}
+	/**
+	* define the translation function
+	*/
+	function translation(key) {
+		if (COMMAND_I18N_RESOURCE_KEYS.includes(key)) {
+			const resource = localeResources.get(locale.toString()) || localeResources.get(DEFAULT_LOCALE);
+			return resource[key] || key;
+		} else {
+			const resource = commandResources.get(locale.toString()) || commandResources.get(DEFAULT_LOCALE);
+			return resource[key] || "";
+		}
+	}
+	/**
+	* load the sub commands
+	*/
+	let cachedCommands;
+	async function loadCommands() {
+		if (cachedCommands) return cachedCommands;
+		const subCommands = [...env.subCommands || []];
+		return cachedCommands = await Promise.all(subCommands.map(async ([name, cmd]) => await resolveLazyCommand(cmd, name)));
+	}
+	/**
+	* create the context
+	*/
+	const ctx = deepFreeze(Object.assign(create(), {
+		name: command.name,
+		description: command.description,
+		omitted,
+		locale,
+		env,
+		options: _options,
+		values: _values,
+		positionals,
+		usage,
+		loadCommands,
+		translation
+	}));
+	/**
+	* load the command resources
+	*/
+	const loadedOptionsResources = Object.entries(usage.options || create()).map(([key, _]) => {
+		const option = usage.options[key];
+		return [key, option];
+	});
+	const defaultCommandResource = loadedOptionsResources.reduce((res, [key, value]) => {
+		res[key] = value;
+		return res;
+	}, create());
+	defaultCommandResource.description = command.description || "";
+	defaultCommandResource.examples = usage.examples || "";
+	commandResources.set(DEFAULT_LOCALE, defaultCommandResource);
+	const originalResource = await loadCommandResource(ctx, command);
+	if (originalResource) {
+		const resource = Object.entries(originalResource.options).reduce((res, [key, value]) => {
+			res[key] = value;
+			return res;
+		}, Object.assign(create(), {
+			description: originalResource.description,
+			examples: originalResource.examples
+		}));
+		if (builtInLoadedResources) {
+			resource.help = builtInLoadedResources.help;
+			resource.version = builtInLoadedResources.version;
+		}
+		commandResources.set(locale.toString(), resource);
+	}
+	return ctx;
+}
+function resolveLocale(locale) {
+	return locale instanceof Intl.Locale ? locale : typeof locale === "string" ? new Intl.Locale(locale) : new Intl.Locale(DEFAULT_LOCALE);
+}
+async function loadCommandResource(ctx, command) {
+	let resource;
+	try {
+		resource = await command.resource?.(ctx);
+	} catch {}
+	return resource;
+}
+
+//#endregion
+//#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
+//#region src/cli.ts
+async function cli(args, entry, opts = {}) {
+	const tokens = parseArgs(args);
+	const subCommand = getSubCommand(tokens);
+	const resolvedCommandOptions = resolveCommandOptions(opts);
+	const [name, command] = await resolveCommand(subCommand, entry, resolvedCommandOptions);
+	if (!command) throw new Error(`Command not found: ${name || ""}`);
+	if (command.name && !resolvedCommandOptions.subCommands.has(command.name)) resolvedCommandOptions.subCommands.set(command.name, command);
+	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: opts
+	});
+	if (values.version) {
+		showVersion(ctx);
+		return;
+	}
+	await showHeader(ctx);
+	if (values.help) {
+		await showUsage(ctx);
+		return;
+	}
+	if (error) {
+		await showValidationErrors(ctx, error);
+		throw error;
+	}
+	await command.run(ctx);
+}
+function resolveArgOptions(options) {
+	return Object.assign(create(), options, COMMON_OPTIONS);
+}
+function resolveCommandOptions(options) {
+	const subCommands = new Map(options.subCommands);
+	return Object.assign(create(), COMMAND_OPTIONS_DEFAULT, { subCommands }, options);
+}
+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 render = ctx.env.renderUsage || renderUsage;
+	log(await render(ctx));
+}
+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();
+	}
+}
+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 { cli };

package/lib/renderer.d.ts

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

package/lib/types.d.ts

@@ -0,0 +1,302 @@
+import type { ArgOptions, ArgValues } from "args-tokens";
+/**
+* Define a promise type that can be await from T
+*/
+type Awaitable<T> = T | Promise<T>;
+/**
+* The command i18n built-in options keys
+* @experimental
+*/
+export type CommandBuiltinOptionsKeys = keyof (typeof import("./constants"))["COMMON_OPTIONS"];
+/**
+* The command i18n built-in resource keys
+* @experimental
+*/
+export type CommandBuiltinResourceKeys = (typeof import("./constants"))["COMMAND_I18N_RESOURCE_KEYS"][number];
+/**
+* The command i18n built-in keys
+* @description The command i18n built-in keys are used to {@link CommandContext.translation | translate} function
+* @experimental
+*/
+export type CommandBuiltinKeys = CommandBuiltinOptionsKeys | CommandBuiltinResourceKeys | "description" | "examples";
+/**
+* The command environment
+*/
+export interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
+	/**
+	* The current working directory
+	* @see {@link CommandOptions.cwd}
+	*/
+	cwd: string | undefined;
+	/**
+	* The command name
+	* @see {@link CommandOptions.name}
+	*/
+	name: string | undefined;
+	/**
+	* The command description
+	* @see {@link CommandOptions.description}
+	*
+	*/
+	description: string | undefined;
+	/**
+	* The command version
+	* @see {@link CommandOptions.version}
+	*/
+	version: string | undefined;
+	/**
+	* The left margin of the command output
+	* @default 2
+	* @see {@link CommandOptions.leftMargin}
+	*/
+	leftMargin: number;
+	/**
+	* The middle margin of the command output
+	* @default 10
+	* @see {@link CommandOptions.middleMargin}
+	*/
+	middleMargin: number;
+	/**
+	* Whether to display the usage option type
+	* @default false
+	* @see {@link CommandOptions.usageOptionType}
+	*/
+	usageOptionType: boolean;
+	/**
+	* The sub commands
+	* @see {@link CommandOptions.subCommands}
+	*/
+	subCommands: Map<string, Command<Options> | LazyCommand<Options>> | undefined;
+	/**
+	* Render function the command usage
+	*/
+	renderUsage: ((ctx: CommandContext<Options>) => Promise<string>) | null | undefined;
+	/**
+	* Render function the header section in the command usage
+	*/
+	renderHeader: ((ctx: CommandContext<Options>) => Promise<string>) | null | undefined;
+	/**
+	* Render function the validation errors
+	*/
+	renderValidationErrors: ((ctx: CommandContext<Options>, error: AggregateError) => Promise<string>) | null | undefined;
+}
+/**
+* The command options
+*/
+export 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.
+	*/
+	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.
+	*/
+	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.
+	*
+	*/
+	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.
+	*/
+	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.
+	*/
+	locale?: string | Intl.Locale;
+	/**
+	* The sub commands
+	*/
+	subCommands?: Map<string, Command<Options> | LazyCommand<Options>>;
+	/**
+	* The left margin of the command output
+	*/
+	leftMargin?: number;
+	/**
+	* The middle margin of the command output
+	*/
+	middleMargin?: number;
+	/**
+	* Whether to display the usage option type
+	*/
+	usageOptionType?: boolean;
+	/**
+	* Render function the command usage
+	*/
+	renderUsage?: ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | null;
+	/**
+	* Render function the header section in the command usage
+	*/
+	renderHeader?: ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | null;
+	/**
+	* Render function the validation errors
+	*/
+	renderValidationErrors?: ((ctx: Readonly<CommandContext<Options>>, error: AggregateError) => Promise<string>) | null;
+}
+/**
+* The command context
+* @description The command context is the context of the command execution
+*/
+export interface CommandContext<
+	Options extends ArgOptions,
+	Values = ArgValues<Options>
+> {
+	/**
+	* The 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
+	* @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
+	*/
+	locale: Intl.Locale;
+	/**
+	* The 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
+	* @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
+	* @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
+	* @description Resolve positionals with `resolveArgs` from command arguments
+	*/
+	positionals: string[];
+	/**
+	* Whether the currently executing command has been executed with the sub-command name omitted
+	*/
+	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
+	*/
+	usage: CommandUsage<Options>;
+	/**
+	* Load the 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
+	* @experimental
+	*/
+	translation: <
+		T = CommandBuiltinKeys,
+		Key = CommandBuiltinKeys | T
+	>(key: Key) => string;
+}
+/**
+* The command usage render
+* @description if the render function is async, it should return a promise
+*/
+export type CommandUsageRender<Options extends ArgOptions> = ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | string;
+/**
+* The command usage
+*/
+interface CommandUsage<Options extends ArgOptions> {
+	/**
+	* The options usage
+	*/
+	options?: { [Option in keyof Options] : string };
+	/**
+	* The examples usage
+	*/
+	examples?: string;
+}
+/**
+* The command interface
+*/
+export interface Command<Options extends ArgOptions> {
+	/**
+	* The command name
+	* @description
+	* The 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
+	* @description
+	* The command description is used to describe the command in usage, so it's recommended to specify.
+	*/
+	description?: string;
+	/**
+	* whether the command is default or not
+	* @description if the command is default, it is executed when no sub-command is specified
+	*/
+	default?: boolean;
+	/**
+	* The command options
+	*/
+	options?: Options;
+	/**
+	* The command usage
+	* @description
+	* The 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
+	*/
+	run: CommandRunner<Options>;
+	/**
+	* The command resource fetcher
+	* @experimental
+	*/
+	resource?: CommandResourceFetcher<Options>;
+}
+/**
+* The command resource
+* @experimental
+*/
+export interface CommandResource<Options extends ArgOptions> {
+	/**
+	* The command description resource
+	*/
+	description: string;
+	/**
+	* The options usage resources
+	*/
+	options: { [Option in keyof Options] : string };
+	/**
+	* The examples usage resources
+	*/
+	examples: string;
+}
+/**
+* The command resource fetcher
+* @experimental
+*/
+export type CommandResourceFetcher<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
+/**
+* The command runner interface
+* @param ctx - The {@link CommandContext | command context}
+*/
+export 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
+*/
+export type LazyCommand<Options extends ArgOptions> = () => Awaitable<Command<Options>>;
+export {};

package/lib/utils.d.ts

@@ -0,0 +1,6 @@
+import type { ArgOptions } from "args-tokens";
+import type { Command, LazyCommand } from "./types.js";
+export declare function resolveLazyCommand<Options extends ArgOptions>(cmd: Command<Options> | LazyCommand<Options>, name: string | undefined, entry?: boolean): Promise<Command<Options>>;
+export declare function create<T>(obj?: object | null): T;
+export declare function log(...args: unknown[]): void;
+export declare function deepFreeze<T extends Record<string, any>>(obj: T): Readonly<T>;

package/locales/en-US.json

@@ -0,0 +1,11 @@
+{
+  "COMMAND": "COMMAND",
+  "COMMANDS": "COMMANDS",
+  "SUBCOMMAND": "SUBCOMMAND",
+  "USAGE": "USAGE",
+  "OPTIONS": "OPTIONS",
+  "EXAMPLES": "EXAMPLES",
+  "FORMORE": "For more info, run any command with the `--help` flag:",
+  "help": "Display this help message",
+  "version": "Display this version"
+}

package/locales/ja-JP.json

@@ -0,0 +1,11 @@
+{
+  "COMMAND": "コマンド",
+  "COMMANDS": "コマンド",
+  "SUBCOMMAND": "サブコマンド",
+  "USAGE": "使い方",
+  "OPTIONS": "オプション",
+  "EXAMPLES": "例",
+  "FORMORE": "詳細は、コマンドと`--help`フラグを実行してください:",
+  "help": "このヘルプメッセージを表示",
+  "version": "このバージョンを表示"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
-  "description": "Modern command-line interfaces composer",
-  "version": "0.0.0",
+  "description": "Modern javascript command-line library",
+  "version": "0.2.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -31,7 +31,8 @@
   },
   "type": "module",
   "files": [
-    "lib"
+    "lib",
+    "locales"
   ],
   "module": "lib/index.js",
   "exports": {
@@ -41,6 +42,18 @@
       "require": "./lib/index.js",
       "default": "./lib/index.js"
     },
+    "./context": {
+      "types": "./lib/context.d.ts",
+      "import": "./lib/context.js",
+      "require": "./lib/context.js",
+      "default": "./lib/context.js"
+    },
+    "./renderer": {
+      "types": "./lib/renderer.d.ts",
+      "import": "./lib/renderer.js",
+      "require": "./lib/renderer.js",
+      "default": "./lib/renderer.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -53,28 +66,33 @@
       ]
     }
   },
+  "dependencies": {
+    "args-tokens": "^0.10.2"
+  },
   "devDependencies": {
     "@eslint/markdown": "^6.2.2",
     "@kazupon/eslint-config": "^0.22.0",
     "@kazupon/prettier-config": "^0.1.1",
-    "@types/node": "^22.13.5",
-    "@vitest/eslint-plugin": "^1.1.31",
+    "@types/node": "^22.13.9",
+    "@vitest/eslint-plugin": "^1.1.36",
     "bumpp": "^10.0.3",
     "eslint": "^9.21.0",
-    "eslint-config-prettier": "^10.0.1",
+    "eslint-config-prettier": "^10.0.2",
     "eslint-plugin-jsonc": "^2.19.1",
     "eslint-plugin-promise": "^7.2.1",
     "eslint-plugin-regexp": "^2.7.0",
     "eslint-plugin-unicorn": "^57.0.0",
     "eslint-plugin-yml": "^1.17.0",
     "gh-changelogen": "^0.2.8",
-    "knip": "^5.44.4",
+    "knip": "^5.45.0",
     "lint-staged": "^15.4.3",
-    "pkg-pr-new": "^0.0.39",
-    "prettier": "^3.5.2",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.24.1",
-    "vitest": "^3.0.6"
+    "pkg-pr-new": "^0.0.40",
+    "prettier": "^3.5.3",
+    "rolldown": "1.0.0-beta.3",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.26.0",
+    "unplugin-isolated-decl": "^0.13.1",
+    "vitest": "^3.0.7"
   },
   "prettier": "@kazupon/prettier-config",
   "lint-staged": {
@@ -91,8 +109,9 @@
     ]
   },
   "scripts": {
-    "build": "tsc -p ./tsconfig.build.json",
+    "build": "rolldown -c rolldown.config.ts",
     "changelog": "gh-changelogen --repo=kazupon/gunshi",
+    "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:/\"",