gunshi 0.11.0 → 0.12.0

package/lib/{context-ZNBQwQKN.js → cli-C-y15OeH.js}

@@ -1,4 +1,5 @@
-import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveLazyCommand } from "./utils-zZSVaYTy.js";
+import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, renderHeader, renderUsage, renderValidationErrors, resolveLazyCommand } from "./renderer-DAUAIZxV.js";
+import { parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/locales/en-US.json
 var COMMAND = "COMMAND";
@@ -29,10 +30,11 @@ function createTranslationAdapter(options) {
 }
 var DefaultTranslation = class {
 	#resources = new Map();
-	options;
+	#options;
 	constructor(options) {
-		this.options = options;
-		this.#resources = new Map();
+		this.#options = options;
+		this.#resources.set(options.locale, create());
+		if (options.locale !== options.fallbackLocale) this.#resources.set(options.fallbackLocale, create());
 	}
 	getResource(locale) {
 		return this.#resources.get(locale);
@@ -45,14 +47,13 @@ var DefaultTranslation = class {
 		if (resource) return resource[key];
 		return void 0;
 	}
-	translate(locale, key, _values = create()) {
-		/**
-		* NOTE:
-		* DefaultTranslation support static message only
-		* If you want to resolve message with values and use the complex message format,
-		* you should inherit this class or implement your own translation adapter.
-		*/
-		return this.getMessage(locale, key) || this.getMessage(this.options.fallbackLocale, key);
+	translate(locale, key, values = create()) {
+		let message = this.getMessage(locale, key);
+		if (message === void 0 && locale !== this.#options.fallbackLocale) message = this.getMessage(this.#options.fallbackLocale, key);
+		if (message === void 0) return;
+		return message.replaceAll(/\{\{(\w+)\}\}/g, (_, name) => {
+			return values[name] == null ? "" : values[name].toString();
+		});
 	}
 };
 
@@ -164,4 +165,91 @@ async function loadCommandResource(ctx, command) {
 }
 
 //#endregion
-export { DefaultTranslation, createCommandContext };
+//#region src/cli.ts
+async function cli(args, entry, opts = {}) {
+	const tokens = parseArgs(args);
+	const subCommand = getSubCommand(tokens);
+	const resolvedCommandOptions = resolveCommandOptions(opts, entry);
+	const [name, command] = await resolveCommand(subCommand, entry, resolvedCommandOptions);
+	if (!command) throw new Error(`Command not found: ${name || ""}`);
+	const options = resolveArgOptions(command.options);
+	const { values, positionals, error } = resolveArgs(options, tokens);
+	const omitted = !subCommand;
+	const ctx = await createCommandContext({
+		options,
+		values,
+		positionals,
+		omitted,
+		command,
+		commandOptions: resolvedCommandOptions
+	});
+	if (values.version) {
+		showVersion(ctx);
+		return;
+	}
+	const usageBuffer = [];
+	const header = await showHeader(ctx);
+	if (header) usageBuffer.push(header);
+	if (values.help) {
+		const usage = await showUsage(ctx);
+		if (usage) usageBuffer.push(usage);
+		return usageBuffer.join("\n");
+	}
+	if (error) {
+		await showValidationErrors(ctx, error);
+		return;
+	}
+	await command.run(ctx);
+}
+function resolveArgOptions(options) {
+	return Object.assign(create(), options, COMMON_OPTIONS);
+}
+function resolveCommandOptions(options, entry) {
+	const subCommands = new Map(options.subCommands);
+	if (typeof entry === "object" && entry.name) subCommands.set(entry.name, entry);
+	const resolvedOptions = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, options, { subCommands });
+	return resolvedOptions;
+}
+function getSubCommand(tokens) {
+	const firstToken = tokens[0];
+	return firstToken && firstToken.kind === "positional" && firstToken.index === 0 && firstToken.value ? firstToken.value : "";
+}
+async function showUsage(ctx) {
+	if (ctx.env.renderUsage === null) return;
+	const usage = await (ctx.env.renderUsage || renderUsage)(ctx);
+	if (usage) {
+		ctx.log(usage);
+		return usage;
+	}
+}
+function showVersion(ctx) {
+	ctx.log(ctx.env.version);
+}
+async function showHeader(ctx) {
+	if (ctx.env.renderHeader === null) return;
+	const header = await (ctx.env.renderHeader || renderHeader)(ctx);
+	if (header) {
+		ctx.log(header);
+		ctx.log();
+		return header;
+	}
+}
+async function showValidationErrors(ctx, error) {
+	if (ctx.env.renderValidationErrors === null) return;
+	const render = ctx.env.renderValidationErrors || renderValidationErrors;
+	ctx.log(await render(ctx, error));
+}
+async function resolveCommand(sub, entry, options) {
+	const omitted = !sub;
+	if (typeof entry === "function") return [void 0, { run: entry }];
+	else if (omitted) return typeof entry === "object" ? [entry.name, await resolveLazyCommand(entry)] : [void 0, void 0];
+	else {
+		if (options.subCommands == null) return [sub, void 0];
+		const cmd = options.subCommands?.get(sub);
+		if (cmd == null) return [sub, void 0];
+		return [sub, await resolveLazyCommand(cmd, sub)];
+	}
+}
+
+//#endregion
+export { DefaultTranslation, cli };

package/lib/generator.d.ts

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

package/lib/generator.js

@@ -1,7 +1,5 @@
-import { create } from "./utils-zZSVaYTy.js";
-import "./context-ZNBQwQKN.js";
-import "./renderer-Dm_6iF2f.js";
-import { cli } from "./cli-CKcZ5eWi.js";
+import { create } from "./renderer-DAUAIZxV.js";
+import { cli } from "./cli-C-y15OeH.js";
 
 //#region src/generator.ts
 async function generate(command, entry, opts = {}) {

package/lib/index.d.ts

@@ -1,25 +1,24 @@
 import { ArgOptions } from 'args-tokens';
 export { ArgOptionSchema, ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, c as CommandRunner, a as CommandOptions, T as TranslationAdapter, d as TranslationAdapterFactoryOptions } from './types.d-VymWn7vz.js';
-export { g as CommandBuiltinKeys, e as CommandBuiltinOptionsKeys, f as CommandBuiltinResourceKeys, b as CommandContext, h as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, l as Commandable, G as GenerateNamespacedKey, L as LazyCommand, k as TranslationAdapterFactory } from './types.d-VymWn7vz.js';
+import { C as Command, b as CommandRunner, a as CommandOptions, T as TranslationAdapter, c as TranslationAdapterFactoryOptions } from './types.d-DIY9YbHU.js';
+export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, h as CommandContext, g as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, l as Commandable, D as DEFAULT_LOCALE, G as GenerateNamespacedKey, L as LazyCommand, k as TranslationAdapterFactory } from './types.d-DIY9YbHU.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}
+* Run the command.
+* @param args Command line arguments
+* @param entry A {@link Command | entry command} or an {@link CommandRunner | inline command runner}
+* @param opts A {@link CommandOptions | command options}
 * @returns A rendered usage or undefined. if you will use {@link CommandOptions.usageSilent} option, it will return rendered usage string.
 */
 declare function cli<Options extends ArgOptions = ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<string | undefined>;
 
 declare class DefaultTranslation implements TranslationAdapter {
 	#private;
-	options: TranslationAdapterFactoryOptions;
 	constructor(options: TranslationAdapterFactoryOptions);
 	getResource(locale: string): Record<string, string> | undefined;
 	setResource(locale: string, resource: Record<string, string>): void;
 	getMessage(locale: string, key: string): string | undefined;
-	translate(locale: string, key: string, _values?: Record<string, unknown>): string | undefined;
+	translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
 }
 
 export { Command, CommandOptions, CommandRunner, DefaultTranslation, TranslationAdapter, TranslationAdapterFactoryOptions, cli };

package/lib/index.js

@@ -1,6 +1,4 @@
-import "./utils-zZSVaYTy.js";
-import { DefaultTranslation } from "./context-ZNBQwQKN.js";
-import "./renderer-Dm_6iF2f.js";
-import { cli } from "./cli-CKcZ5eWi.js";
+import { DEFAULT_LOCALE } from "./renderer-DAUAIZxV.js";
+import { DefaultTranslation, cli } from "./cli-C-y15OeH.js";
 
-export { DefaultTranslation, cli };
+export { DEFAULT_LOCALE, DefaultTranslation, cli };

package/lib/renderer/index.d.ts

@@ -1,25 +1,25 @@
 import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from '../types.d-VymWn7vz.js';
+import { h as CommandContext } from '../types.d-DIY9YbHU.js';
 
 /**
-* Render the header
+* Render the header.
 * @param ctx A {@link CommandContext | command context}
-* @returns A rendered header
+* @returns A rendered header.
 */
 declare function renderHeader<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
 
 /**
-* Render the usage
+* Render the usage.
 * @param ctx A {@link CommandContext | command context}
-* @returns A rendered usage
+* @returns A rendered usage.
 */
 declare function renderUsage<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
 
 /**
-* Render the validation errors
+* 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
+* @returns A rendered validation error.
 */
 declare function renderValidationErrors<Options extends ArgOptions = ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
 

package/lib/renderer/index.js

@@ -1,4 +1,3 @@
-import "../utils-zZSVaYTy.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-Dm_6iF2f.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-DAUAIZxV.js";
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{renderer-Dm_6iF2f.js → renderer-DAUAIZxV.js}

@@ -1,5 +1,69 @@
-import { create, resolveBuiltInKey } from "./utils-zZSVaYTy.js";
 
+//#region src/constants.ts
+const DEFAULT_LOCALE = "en-US";
+const BUILT_IN_PREFIX = "_";
+const BUILT_IN_KEY_SEPARATOR = ":";
+const NOOP = () => {};
+const COMMON_OPTIONS = {
+	help: {
+		type: "boolean",
+		short: "h",
+		description: "Display this help message"
+	},
+	version: {
+		type: "boolean",
+		short: "v",
+		description: "Display this version"
+	}
+};
+const COMMAND_OPTIONS_DEFAULT = {
+	name: void 0,
+	description: void 0,
+	version: void 0,
+	cwd: void 0,
+	usageSilent: false,
+	subCommands: void 0,
+	leftMargin: 2,
+	middleMargin: 10,
+	usageOptionType: false,
+	renderHeader: void 0,
+	renderUsage: void 0,
+	renderValidationErrors: void 0,
+	translationAdapterFactory: void 0
+};
+
+//#endregion
+//#region src/utils.ts
+async function resolveLazyCommand(cmd, name) {
+	const resolved = Object.assign(create(), typeof cmd == "function" ? await cmd() : cmd);
+	if (resolved.name == null && name) resolved.name = name;
+	return deepFreeze(resolved);
+}
+function resolveBuiltInKey(key) {
+	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+function mapResourceWithBuiltinKey(resource) {
+	return Object.entries(resource).reduce((acc, [key, value]) => {
+		acc[resolveBuiltInKey(key)] = value;
+		return acc;
+	}, create());
+}
+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/renderer/header.ts
 function renderHeader(ctx) {
 	const title = ctx.env.description || ctx.env.name || "";
@@ -198,4 +262,4 @@ function renderValidationErrors(_ctx, error) {
 }
 
 //#endregion
-export { renderHeader, renderUsage, renderValidationErrors };
+export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, renderHeader, renderUsage, renderValidationErrors, resolveLazyCommand };

package/lib/{types.d-VymWn7vz.d.ts → types.d-DIY9YbHU.d.ts}

@@ -1,7 +1,7 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
 
 /**
-* The default locale string, which format is BCP 47 language tag
+* The default locale string, which format is BCP 47 language tag.
 */
 declare const DEFAULT_LOCALE = "en-US";
 declare const BUILT_IN_PREFIX = "_";
@@ -43,7 +43,7 @@ declare namespace __constants_ts {
 }
 
 /**
-* Define a promise type that can be await from T
+* Define a promise type that can be await from T.
 */
 type Awaitable<T> = T | Promise<T>;
 type GenerateNamespacedKey<
@@ -51,216 +51,211 @@ type GenerateNamespacedKey<
 	Prefixed extends string = typeof BUILT_IN_PREFIX
 > = `${Prefixed}${typeof BUILT_IN_KEY_SEPARATOR}${Key}`;
 /**
-* Command i18n built-in options keys
-* @experimental
+* Command i18n built-in options keys.
 */
 type CommandBuiltinOptionsKeys = keyof (typeof __constants_ts)["COMMON_OPTIONS"];
 /**
-* Command i18n built-in resource keys
-* @experimental
+* Command i18n built-in resource keys.
 */
 type CommandBuiltinResourceKeys = (typeof __constants_ts)["COMMAND_BUILTIN_RESOURCE_KEYS"][number];
 /**
-* Command i18n built-in keys
-* @description The command i18n built-in keys are used to {@link CommandContext.translate | translate} function
-* @experimental
+* Command i18n built-in keys.
+* The command i18n built-in keys are used to {@link CommandContext.translate | translate} function.
 */
 type CommandBuiltinKeys = GenerateNamespacedKey<CommandBuiltinOptionsKeys> | GenerateNamespacedKey<CommandBuiltinResourceKeys> | "description" | "examples";
 /**
-* Command environment
+* Command environment.
 */
 interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	/**
-	* Current working directory
+	* Current working directory.
 	* @see {@link CommandOptions.cwd}
 	*/
 	cwd: string | undefined;
 	/**
-	* Command name
+	* Command name.
 	* @see {@link CommandOptions.name}
 	*/
 	name: string | undefined;
 	/**
-	* Command description
+	* Command description.
 	* @see {@link CommandOptions.description}
 	*
 	*/
 	description: string | undefined;
 	/**
-	* Command version
+	* Command version.
 	* @see {@link CommandOptions.version}
 	*/
 	version: string | undefined;
 	/**
-	* Left margin of the command output
+	* Left margin of the command output.
 	* @default 2
 	* @see {@link CommandOptions.leftMargin}
 	*/
 	leftMargin: number;
 	/**
-	* Middle margin of the command output
+	* Middle margin of the command output.
 	* @default 10
 	* @see {@link CommandOptions.middleMargin}
 	*/
 	middleMargin: number;
 	/**
-	* Whether to display the usage option type
+	* Whether to display the usage option type.
 	* @default false
 	* @see {@link CommandOptions.usageOptionType}
 	*/
 	usageOptionType: boolean;
 	/**
-	* Whether to display the command usage
+	* Whether to display the command usage.
 	* @default false
 	* @see {@link}
 	*/
 	usageSilent: boolean;
 	/**
-	* Sub commands
+	* Sub commands.
 	* @see {@link CommandOptions.subCommands}
 	*/
 	subCommands: Map<string, Command<any> | LazyCommand<any>> | undefined;
 	/**
-	* Render function the command usage
+	* Render function the command usage.
 	*/
 	renderUsage: ((ctx: CommandContext<Options>) => Promise<string>) | null | undefined;
 	/**
-	* Render function the header section in the command usage
+	* Render function the header section in the command usage.
 	*/
 	renderHeader: ((ctx: CommandContext<Options>) => Promise<string>) | null | undefined;
 	/**
-	* Render function the validation errors
+	* Render function the validation errors.
 	*/
 	renderValidationErrors: ((ctx: CommandContext<Options>, error: AggregateError) => Promise<string>) | null | undefined;
 }
 /**
-* Command options
+* Command options.
 */
 interface CommandOptions<Options extends ArgOptions = ArgOptions> {
 	/**
-	* Current working directory
+	* Current working directory.
 	*/
 	cwd?: string;
 	/**
-	* Command program name
+	* Command program name.
 	*/
 	name?: string;
 	/**
-	* Command program description
+	* Command program description.
 	*
 	*/
 	description?: string;
 	/**
-	* Command program version
+	* Command program version.
 	*/
 	version?: string;
 	/**
-	* Command program locale
+	* Command program locale.
 	*/
 	locale?: string | Intl.Locale;
 	/**
-	* Sub commands
+	* Sub commands.
 	*/
 	subCommands?: Map<string, Command<any> | LazyCommand<any>>;
 	/**
-	* Left margin of the command output
+	* Left margin of the command output.
 	*/
 	leftMargin?: number;
 	/**
-	* Middle margin of the command output
+	* Middle margin of the command output.
 	*/
 	middleMargin?: number;
 	/**
-	* Whether to display the usage option type
+	* Whether to display the usage option type.
 	*/
 	usageOptionType?: boolean;
 	/**
-	* Whether to display the command usage
+	* Whether to display the command usage.
 	*/
 	usageSilent?: boolean;
 	/**
-	* Render function the command usage
+	* Render function the command usage.
 	*/
 	renderUsage?: ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | null;
 	/**
-	* Render function the header section in the command usage
+	* Render function the header section in the command usage.
 	*/
 	renderHeader?: ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | null;
 	/**
-	* Render function the validation errors
+	* Render function the validation errors.
 	*/
 	renderValidationErrors?: ((ctx: Readonly<CommandContext<Options>>, error: AggregateError) => Promise<string>) | null;
 	/**
-	* Translation adapter factory
-	* @experimental
+	* Translation adapter factory.
 	*/
 	translationAdapterFactory?: TranslationAdapterFactory;
 }
 /**
-* Command context
-* @description Command context is the context of the command execution
+* Command context.
+* Command context is the context of the command execution.
 */
 interface CommandContext<
 	Options extends ArgOptions = ArgOptions,
 	Values = ArgValues<Options>
 > {
 	/**
-	* Command name, that is the command that is executed
-	* @description The command name is same {@link CommandEnvironment.name}
+	* Command name, that is the command that is executed.
+	* The command name is same {@link CommandEnvironment.name}.
 	*/
 	name: string | undefined;
 	/**
-	* Command description, that is the description of the command that is executed
-	* @description The command description is same {@link CommandEnvironment.description}
+	* Command description, that is the description of the command that is executed.
+	* The command description is same {@link CommandEnvironment.description}.
 	*/
 	description: string | undefined;
 	/**
-	* 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;
 	/**
-	* Command environment, that is the environment of the command that is executed
-	* @description The command environment is same {@link CommandEnvironment}
+	* Command environment, that is the environment of the command that is executed.
+	* The command environment is same {@link CommandEnvironment}.
 	*/
 	env: Readonly<CommandEnvironment<Options>>;
 	/**
-	* Command options, that is the options of the command that is executed
-	* @description The command options is same {@link Command.options}
+	* Command options, that is the options of the command that is executed.
+	* The command options is same {@link Command.options}.
 	*/
 	options: Options;
 	/**
-	* Command values, that is the values of the command that is executed
-	* @description Resolve values with `resolveArgs` from command arguments and {@link Command.options}
+	* Command values, that is the values of the command that is executed.
+	* Resolve values with `resolveArgs` from command arguments and {@link Command.options}.
 	*/
 	values: Values;
 	/**
-	* Command positionals arguments, that is the positionals of the command that is executed
-	* @description Resolve positionals with `resolveArgs` from command arguments
+	* Command positionals arguments, that is the positionals of the command that is executed.
+	* Resolve positionals with `resolveArgs` from command arguments.
 	*/
 	positionals: string[];
 	/**
-	* Whether the currently executing command has been executed with the sub-command name omitted
+	* Whether the currently executing command has been executed with the sub-command name omitted.
 	*/
 	omitted: boolean;
 	/**
-	* Output a message
-	* @description if {@link CommandEnvironment.usageSilent} is true, the message is not output
+	* Output a message.
+	* If {@link CommandEnvironment.usageSilent} is true, the message is not output.
 	* @param message an output message, @see {@link console.log}
 	* @param optionalParams an optional parameters, @see {@link console.log}
 	*/
 	log: (message?: any, ...optionalParams: any[]) => void;
 	/**
-	* Load sub-commands
-	* @description The loaded commands are cached and returned when called again
-	* @returns loaded commands
+	* Load sub-commands.
+	* The loaded commands are cached and returned when called again.
+	* @returns loaded commands.
 	*/
 	loadCommands: () => Promise<Command<Options>[]>;
 	/**
-	* Translate function
+	* Translate function.
 	* @param key the key to be translated
 	* @param values the values to be formatted
-	* @returns A translated string
-	* @experimental
+	* @returns A translated string.
 	*/
 	translate: <
 		T extends string = CommandBuiltinKeys,
@@ -268,137 +263,127 @@ interface CommandContext<
 	>(key: Key, values?: Record<string, unknown>) => string;
 }
 /**
-* Command interface
+* Command interface.
 */
 interface Command<Options extends ArgOptions = ArgOptions> {
 	/**
-	* Command name
-	* @description
-	* Command name is used to find command line arguments to execute from sub commands, so it's recommended to specify.
+	* Command name.
+	* It's used to find command line arguments to execute from sub commands, and it's recommended to specify.
 	*/
 	name?: string;
 	/**
-	* Command description
-	* @description command description is used to describe the command in usage, so it's recommended to specify.
+	* Command description.
+	* It's used to describe the command in usage and 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;
-	/**
-	* Command options
-	* @description each option can include a description property to describe the option in usage.
+	* Command options.
+	* Each option can include a description property to describe the option in usage.
 	*/
 	options?: Options;
 	/**
-	* Command examples
-	* @description examples of how to use the command.
+	* Command examples.
+	* examples of how to use the command.
 	*/
 	examples?: string;
 	/**
-	* Command runner, that's the command to be executed
+	* Command runner. it's the command to be executed
 	*/
 	run: CommandRunner<Options>;
 	/**
-	* Command resource fetcher
-	* @experimental
+	* Command resource fetcher.
 	*/
 	resource?: CommandResourceFetcher<Options>;
 }
 /**
-* Command resource
-* @experimental
+* Command resource.
 */
 type CommandResource<Options extends ArgOptions = ArgOptions> = {
 	/**
-	* Command description
+	* Command description.
 	*/
 	description: string
 	/**
-	* Examples usage
+	* Examples usage.
 	*/
 	examples: string
 } & { [Option in keyof Options] : string } & {
 	[key: string]: string
 };
 /**
-* Command resource fetcher
+* Command resource fetcher.
 * @param ctx A {@link CommandContext | command context}
-* @returns A fetched {@link CommandResource | command resource}
-* @experimental
+* @returns A fetched {@link CommandResource | command resource}.
 */
 type CommandResourceFetcher<
 	Options extends ArgOptions = ArgOptions,
 	Values = ArgValues<Options>
 > = (ctx: Readonly<CommandContext<Options, Values>>) => Promise<CommandResource<Options>>;
 /**
-* Translation adapter factory
+* Translation adapter factory.
 */
 type TranslationAdapterFactory = (options: TranslationAdapterFactoryOptions) => TranslationAdapter;
 /**
-* Translation adapter factory options
+* Translation adapter factory options.
 */
 interface TranslationAdapterFactoryOptions {
 	/**
-	* A locale
+	* A locale.
 	*/
 	locale: string;
 	/**
-	* A fallback locale
+	* A fallback locale.
 	*/
 	fallbackLocale: string;
 }
 /**
-* Translation adapter
-*
-* @description
+* Translation adapter.
 * This adapter is used to custom message formatter like {@link https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf | Intlify message format}, {@link https://github.com/tc39/proposal-intl-messageformat | `Intl.MessageFormat` (MF2)}, and etc.
-* This adapter will support localization with your preferred message format
+* This adapter will support localization with your preferred message format.
 */
 interface TranslationAdapter<MessageResource = string> {
 	/**
-	* Get a resource of locale
+	* Get a resource of locale.
 	* @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
-	* @returns A resource of locale. if resource not found, return `undefined`
+	* @returns A resource of locale. if resource not found, return `undefined`.
 	*/
 	getResource(locale: string): Record<string, string> | undefined;
 	/**
-	* Set a resource of locale
+	* Set a resource of locale.
 	* @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
 	* @param resource A resource of locale
 	*/
 	setResource(locale: string, resource: Record<string, string>): void;
 	/**
-	* Get a message of locale
+	* Get a message of locale.
 	* @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
 	* @param key A key of message resource
-	* @returns A message of locale. if message not found, return `undefined`
+	* @returns A message of locale. if message not found, return `undefined`.
 	*/
 	getMessage(locale: string, key: string): MessageResource | undefined;
 	/**
-	* Translate a message
+	* Translate a message.
 	* @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
 	* @param key A key of message resource
 	* @param values A values to be resolved in the message
-	* @returns A translated message, if message is not translated, return `undefined`
+	* @returns A translated message, if message is not translated, return `undefined`.
 	*/
 	translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
 }
 /**
-* Command runner
+* Command runner.
 * @param ctx A {@link CommandContext | command context}
 */
 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
+* Lazy command interface.
+* Lazy command that's not loaded until it is executed.
 */
 type LazyCommand<Options extends ArgOptions = ArgOptions> = () => Awaitable<Command<Options>>;
 /**
-* Define a command type
+* Define a command type.
 */
 type Commandable<Options extends ArgOptions> = Command<Options> | LazyCommand<Options>;
 
-export type { Command as C, GenerateNamespacedKey as G, LazyCommand as L, TranslationAdapter as T, CommandOptions as a, CommandContext as b, CommandRunner as c, TranslationAdapterFactoryOptions as d, CommandBuiltinOptionsKeys as e, CommandBuiltinResourceKeys as f, CommandBuiltinKeys as g, CommandEnvironment as h, CommandResource as i, CommandResourceFetcher as j, TranslationAdapterFactory as k, Commandable as l };
+export { DEFAULT_LOCALE as D };
+export type { Command as C, GenerateNamespacedKey as G, LazyCommand as L, TranslationAdapter as T, CommandOptions as a, CommandRunner as b, TranslationAdapterFactoryOptions as c, CommandBuiltinOptionsKeys as d, CommandBuiltinResourceKeys as e, CommandBuiltinKeys as f, CommandEnvironment as g, CommandContext as h, CommandResource as i, CommandResourceFetcher as j, TranslationAdapterFactory as k, Commandable as l };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -41,12 +41,6 @@
       "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/index.d.ts",
       "import": "./lib/renderer/index.js",
@@ -72,7 +66,7 @@
     }
   },
   "dependencies": {
-    "args-tokens": "^0.12.0"
+    "args-tokens": "^0.14.0"
   },
   "devDependencies": {
     "@eslint/markdown": "^6.3.0",
@@ -102,10 +96,14 @@
     "pkg-pr-new": "^0.0.41",
     "prettier": "^3.5.3",
     "tsdown": "^0.6.10",
+    "typedoc": "^0.28.1",
+    "typedoc-plugin-markdown": "^4.6.0",
+    "typedoc-vitepress-theme": "^1.1.2",
     "typescript": "^5.8.2",
     "typescript-eslint": "^8.28.0",
     "vitepress": "^1.6.3",
     "vitepress-plugin-group-icons": "^1.3.8",
+    "vitepress-plugin-llms": "^0.0.21",
     "vitest": "^3.0.9"
   },
   "prettier": "@kazupon/prettier-config",
@@ -128,8 +126,12 @@
     "clean": "git clean -df",
     "dev": "pnpx @eslint/config-inspector --config eslint.config.ts",
     "dev:eslint": "pnpx @eslint/config-inspector --config eslint.config.ts",
-    "docs:build": "vitepress build docs",
-    "docs:dev": "vitepress dev docs",
+    "dev:typedoc": "typedoc --watch --preserveWatchOutput",
+    "docs:build": "pnpm run docs:build:typedoc && pnpm docs:build:vitepress",
+    "docs:build:typedoc": "typedoc",
+    "docs:build:vitepress": "vitepress build docs",
+    "docs:dev": "pnpm run docs:build:typedoc && pnpm docs:dev:vitepress",
+    "docs:dev:vitepress": "vitepress dev docs",
     "docs:preview": "vitepress preview docs",
     "fix": "pnpm run --stream --color \"/^fix:/\"",
     "fix:eslint": "eslint . --fix",

package/lib/cli-CKcZ5eWi.js

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

package/lib/context.d.ts

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

package/lib/context.js

@@ -1,4 +0,0 @@
-import "./utils-zZSVaYTy.js";
-import { createCommandContext } from "./context-ZNBQwQKN.js";
-
-export { createCommandContext };

package/lib/utils-zZSVaYTy.js

@@ -1,67 +0,0 @@
-
-//#region src/constants.ts
-const DEFAULT_LOCALE = "en-US";
-const BUILT_IN_PREFIX = "_";
-const BUILT_IN_KEY_SEPARATOR = ":";
-const NOOP = () => {};
-const COMMON_OPTIONS = {
-	help: {
-		type: "boolean",
-		short: "h",
-		description: "Display this help message"
-	},
-	version: {
-		type: "boolean",
-		short: "v",
-		description: "Display this version"
-	}
-};
-const COMMAND_OPTIONS_DEFAULT = {
-	name: void 0,
-	description: void 0,
-	version: void 0,
-	cwd: void 0,
-	usageSilent: false,
-	subCommands: void 0,
-	leftMargin: 2,
-	middleMargin: 10,
-	usageOptionType: false,
-	renderHeader: void 0,
-	renderUsage: void 0,
-	renderValidationErrors: void 0,
-	translationAdapterFactory: void 0
-};
-
-//#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 resolveBuiltInKey(key) {
-	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
-}
-function mapResourceWithBuiltinKey(resource) {
-	return Object.entries(resource).reduce((acc, [key, value]) => {
-		acc[resolveBuiltInKey(key)] = value;
-		return acc;
-	}, create());
-}
-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 { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveBuiltInKey, resolveLazyCommand };