gunshi 0.2.0 → 0.2.2

package/lib/renderer-Bo0DibAK.js

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

package/lib/renderer.js

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

package/lib/types.d-00BVt8hZ.d.ts

@@ -0,0 +1,316 @@
+import { ArgOptions, ArgValues } from 'args-tokens';
+
+declare const COMMON_OPTIONS: {
+	readonly help: {
+		readonly type: "boolean"
+		readonly short: "h"
+	}
+	readonly version: {
+		readonly type: "boolean"
+		readonly short: "v"
+	}
+};
+declare const COMMAND_OPTIONS_DEFAULT: CommandOptions<ArgOptions>;
+declare const COMMAND_I18N_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "OPTIONS", "EXAMPLES", "FORMORE"];
+
+declare const __constants_COMMAND_I18N_RESOURCE_KEYS: typeof COMMAND_I18N_RESOURCE_KEYS;
+declare const __constants_COMMAND_OPTIONS_DEFAULT: typeof COMMAND_OPTIONS_DEFAULT;
+declare const __constants_COMMON_OPTIONS: typeof COMMON_OPTIONS;
+declare namespace __constants {
+  export { __constants_COMMAND_I18N_RESOURCE_KEYS as COMMAND_I18N_RESOURCE_KEYS, __constants_COMMAND_OPTIONS_DEFAULT as COMMAND_OPTIONS_DEFAULT, __constants_COMMON_OPTIONS as COMMON_OPTIONS };
+}
+
+/**
+* Define a promise type that can be await from T
+*/
+type Awaitable<T> = T | Promise<T>;
+/**
+* Command i18n built-in options keys
+* @experimental
+*/
+type CommandBuiltinOptionsKeys = keyof (typeof __constants)["COMMON_OPTIONS"];
+/**
+* Command i18n built-in resource keys
+* @experimental
+*/
+type CommandBuiltinResourceKeys = (typeof __constants)["COMMAND_I18N_RESOURCE_KEYS"][number];
+/**
+* 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";
+/**
+* Command environment
+*/
+interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
+	/**
+	* Current working directory
+	* @see {@link CommandOptions.cwd}
+	*/
+	cwd: string | undefined;
+	/**
+	* Command name
+	* @see {@link CommandOptions.name}
+	*/
+	name: string | undefined;
+	/**
+	* Command description
+	* @see {@link CommandOptions.description}
+	*
+	*/
+	description: string | undefined;
+	/**
+	* Command version
+	* @see {@link CommandOptions.version}
+	*/
+	version: string | undefined;
+	/**
+	* Left margin of the command output
+	* @default 2
+	* @see {@link CommandOptions.leftMargin}
+	*/
+	leftMargin: number;
+	/**
+	* 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;
+	/**
+	* 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;
+}
+/**
+* Command options
+*/
+interface CommandOptions<Options extends ArgOptions> {
+	/**
+	* Current working directory
+	*/
+	cwd?: string;
+	/**
+	* Command program name
+	*/
+	name?: string;
+	/**
+	* Command program description
+	*
+	*/
+	description?: string;
+	/**
+	* Command program version
+	*/
+	version?: string;
+	/**
+	* Command program locale
+	*/
+	locale?: string | Intl.Locale;
+	/**
+	* Sub commands
+	*/
+	subCommands?: Map<string, Command<Options> | LazyCommand<Options>>;
+	/**
+	* Left margin of the command output
+	*/
+	leftMargin?: number;
+	/**
+	* 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;
+}
+/**
+* Command context
+* @description Command context is the context of the command execution
+*/
+interface CommandContext<
+	Options extends ArgOptions,
+	Values = ArgValues<Options>
+> {
+	/**
+	* Command name, that is the command that is executed
+	* @description 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}
+	*/
+	description: string | undefined;
+	/**
+	* 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}
+	*/
+	env: CommandEnvironment<Options>;
+	/**
+	* Command options, that is the options of the command that is executed
+	* @description The command options is same {@link Command.options}
+	*/
+	options: Options | undefined;
+	/**
+	* 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;
+	/**
+	* Command positionals arguments, 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;
+	/**
+	* Command usage
+	* @description Usage of the command is same {@link Command.usage}, and more has `--help` and `--version` options
+	*/
+	usage: CommandUsage<Options>;
+	/**
+	* Load sub-commands
+	* @description The loaded commands are cached and returned when called again
+	* @returns loaded commands
+	*/
+	loadCommands: () => Promise<Command<Options>[]>;
+	/**
+	* Translation function
+	* @param key the key to be translated
+	* @returns A translated string
+	* @experimental
+	*/
+	translation: <
+		T = CommandBuiltinKeys,
+		Key = CommandBuiltinKeys | T
+	>(key: Key) => string;
+}
+/**
+* Command usage
+*/
+interface CommandUsage<Options extends ArgOptions> {
+	/**
+	* Options usage
+	*/
+	options?: { [Option in keyof Options] : string };
+	/**
+	* Examples usage
+	*/
+	examples?: string;
+}
+/**
+* Command interface
+*/
+interface Command<Options extends ArgOptions> {
+	/**
+	* Command name
+	* @description
+	* Command name is used to find command line arguments to execute from sub commands, so 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.
+	*/
+	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
+	*/
+	options?: Options;
+	/**
+	* Command usage
+	* @description
+	* Command usage is used to describe the command in usage, so it's recommended to specify.
+	*/
+	usage?: CommandUsage<Options>;
+	/**
+	* Command runner, that's the command to be executed
+	*/
+	run: CommandRunner<Options>;
+	/**
+	* Command resource fetcher
+	* @experimental
+	*/
+	resource?: CommandResourceFetcher<Options>;
+}
+/**
+* Command resource
+* @experimental
+*/
+interface CommandResource<Options extends ArgOptions> {
+	/**
+	* Command description
+	*/
+	description: string;
+	/**
+	* Options usage
+	*/
+	options: { [Option in keyof Options] : string };
+	/**
+	* Examples usage
+	*/
+	examples: string;
+}
+/**
+* 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>>;
+/**
+* Command runner
+* @param ctx A {@link CommandContext | command context}
+*/
+type CommandRunner<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Awaitable<void>;
+/**
+* Lazy command interface
+* @description lazy command that's not loaded until it is executed
+*/
+type LazyCommand<Options extends ArgOptions> = () => Awaitable<Command<Options>>;
+
+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/lib/utils-NHs5DuHk.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -88,10 +88,9 @@
     "lint-staged": "^15.4.3",
     "pkg-pr-new": "^0.0.40",
     "prettier": "^3.5.3",
-    "rolldown": "1.0.0-beta.3",
+    "tsdown": "^0.6.4",
     "typescript": "^5.8.2",
     "typescript-eslint": "^8.26.0",
-    "unplugin-isolated-decl": "^0.13.1",
     "vitest": "^3.0.7"
   },
   "prettier": "@kazupon/prettier-config",
@@ -109,7 +108,7 @@
     ]
   },
   "scripts": {
-    "build": "rolldown -c rolldown.config.ts",
+    "build": "tsdown",
     "changelog": "gh-changelogen --repo=kazupon/gunshi",
     "clean": "git clean -df",
     "dev": "pnpx @eslint/config-inspector --config eslint.config.ts",

package/lib/cli.d.ts

@@ -1,9 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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"];