gunshi 0.8.0 → 0.9.0

package/README.md

@@ -10,7 +10,7 @@
 
 Gunshi is a modern javascript command-line library
 
-> [!TIP]
+> [!TIP] <!-- eslint-disable-line markdown/no-missing-label-refs -->
 > gunshi (軍師) is a position in ancient Japanese samurai battle in which a samurai devised strategies and gave orders. That name is inspired by the word "command".
 
 ## ✨ Features
@@ -64,7 +64,7 @@ import { cli } from 'gunshi'
 
 const args = process.argv.slice(2)
 // run a simple command
-cli(args, () => {
+await cli(args, () => {
   // something logic ...
   console.log('Hello from Gunshi!', args)
 })
@@ -103,7 +103,7 @@ const command = {
 
 // run a command that is defined above
 // (the 3rd argument of `cli` is the command option)
-cli(process.argv.slice(2), command, {
+await cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0',
   description: 'My CLI application'
@@ -201,7 +201,7 @@ const mainCommand = {
 }
 
 // run the CLI with composable sub-commands
-cli(process.argv.slice(2), mainCommand, {
+await cli(process.argv.slice(2), mainCommand, {
   name: 'my-app',
   version: '1.0.0',
   subCommands
@@ -239,7 +239,7 @@ const subCommands = new Map()
 subCommands.set('lazy', lazyCommand)
 
 // run the CLI with lazy-loaded commands
-cli(
+await cli(
   process.argv.slice(2),
   { name: 'main', run: () => {} },
   {
@@ -281,7 +281,7 @@ const command = {
 }
 
 // run with --help to see the automatically generated usage information
-cli(process.argv.slice(2), command, {
+await cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0'
 })
@@ -324,7 +324,7 @@ const customUsageRenderer = ctx => {
 }
 
 // run with custom renderers
-cli(
+await cli(
   process.argv.slice(2),
   { name: 'app', run: () => {} },
   {
@@ -371,7 +371,7 @@ const command = {
 }
 
 // run with locale support
-cli(process.argv.slice(2), command, {
+await cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0',
   // set the locale via an environment variable
@@ -394,7 +394,8 @@ If you are interested in contributing to `gunshi`, I highly recommend checking o
 
 This project is inspired and powered by:
 
-- [`citty`](https://github.com/unjs/citty), created by UnJS team and contributors
+- [`citty`](https://github.com/unjs/citty), created by [UnJS team](https://github.com/unjs) and contributors
+- [`ordana`](https://github.com/sapphi-red/ordana), createdy by [sapphi-red](https://github.com/sapphi-red), inspired documentation generation
 - cline and claude 3.7 sonnet, examples and docs is generated
 
 Thank you!

package/lib/{context-DYokJ5k3.js → context-DeTM_Qpg.js}

@@ -1,4 +1,4 @@
-import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE, create, deepFreeze, mapResourceWithBuiltinKey, resolveLazyCommand } from "./utils-CU_LSsUg.js";
+import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveLazyCommand } from "./utils-jm146hfy.js";
 
 //#region locales/en-US.json
 var COMMAND = "COMMAND";
@@ -43,7 +43,7 @@ var DefaultTranslation = class {
 	getMessage(locale, key) {
 		const resource = this.getResource(locale);
 		if (resource) return resource[key];
-		return undefined;
+		return void 0;
 	}
 	translate(locale, key, _values = create()) {
 		/**
@@ -130,6 +130,7 @@ async function createCommandContext({ options, values, positionals, command, com
 		values: _values,
 		positionals,
 		usage,
+		log: commandOptions.usageSilent ? NOOP : log,
 		loadCommands,
 		translate
 	}));

package/lib/context.d.ts

@@ -1,5 +1,5 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-CX4RmDVT.js';
+import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-Dp0YJQNw.js';
 
 /**
 * Parameters of {@link createCommandContext}

package/lib/context.js

@@ -1,4 +1,4 @@
-import { createCommandContext } from "./context-DYokJ5k3.js";
-import "./utils-CU_LSsUg.js";
+import { createCommandContext } from "./context-DeTM_Qpg.js";
+import "./utils-jm146hfy.js";
 
 export { createCommandContext };

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import { ArgOptions } from 'args-tokens';
 export { ArgOptionSchema, ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, c as CommandRunner, a as CommandOptions, T as TranslationAdapter, d as TranslationAdapterFactoryOptions } from './types.d-CX4RmDVT.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-CX4RmDVT.js';
+import { C as Command, c as CommandRunner, a as CommandOptions, T as TranslationAdapter, d as TranslationAdapterFactoryOptions } from './types.d-Dp0YJQNw.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-Dp0YJQNw.js';
 
 /**
 * Run the command

package/lib/index.js

@@ -1,6 +1,6 @@
-import { DefaultTranslation, createCommandContext } from "./context-DYokJ5k3.js";
-import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, log, resolveLazyCommand } from "./utils-CU_LSsUg.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-KLx2dW-W.js";
+import { DefaultTranslation, createCommandContext } from "./context-DeTM_Qpg.js";
+import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, resolveLazyCommand } from "./utils-jm146hfy.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-DIRwkoRd.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/cli.ts
@@ -56,38 +56,38 @@ async function showUsage(ctx) {
 	if (ctx.env.renderUsage === null) return;
 	const usage = await (ctx.env.renderUsage || renderUsage)(ctx);
 	if (usage) {
-		log(usage);
+		ctx.log(usage);
 		return usage;
 	}
 }
 function showVersion(ctx) {
-	log(ctx.env.version);
+	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();
+		ctx.log(header);
+		ctx.log();
 		return header;
 	}
 }
 async function showValidationErrors(ctx, error) {
 	if (ctx.env.renderValidationErrors === null) return;
 	const render = ctx.env.renderValidationErrors || renderValidationErrors;
-	log(await render(ctx, error));
+	ctx.log(await render(ctx, error));
 }
 async function resolveCommand(sub, entry, options) {
 	const omitted = !sub;
-	if (typeof entry === "function") return [undefined, {
+	if (typeof entry === "function") return [void 0, {
 		run: entry,
 		default: true
 	}];
-	else if (omitted) return typeof entry === "object" ? [entry.name, await resolveLazyCommand(entry, undefined, true)] : [undefined, undefined];
+	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, undefined];
+		if (options.subCommands == null) return [sub, void 0];
 		const cmd = options.subCommands?.get(sub);
-		if (cmd == null) return [sub, undefined];
+		if (cmd == null) return [sub, void 0];
 		return [sub, await resolveLazyCommand(cmd, sub)];
 	}
 }

package/lib/renderer/index.d.ts

@@ -1,5 +1,5 @@
 import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from '../types.d-CX4RmDVT.js';
+import { b as CommandContext } from '../types.d-Dp0YJQNw.js';
 
 /**
 * Render the header

package/lib/renderer/index.js

@@ -1,4 +1,4 @@
-import "../utils-CU_LSsUg.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-KLx2dW-W.js";
+import "../utils-jm146hfy.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-DIRwkoRd.js";
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{renderer-KLx2dW-W.js → renderer-DIRwkoRd.js}

@@ -1,4 +1,4 @@
-import { create, resolveBuiltInKey } from "./utils-CU_LSsUg.js";
+import { create, resolveBuiltInKey } from "./utils-jm146hfy.js";
 
 //#region src/renderer/header.ts
 function renderHeader(ctx) {

package/lib/{types.d-CX4RmDVT.d.ts → types.d-Dp0YJQNw.d.ts}

@@ -6,6 +6,7 @@ import { ArgOptions, ArgValues } from 'args-tokens';
 declare const DEFAULT_LOCALE = "en-US";
 declare const BUILT_IN_PREFIX = "_";
 declare const BUILT_IN_KEY_SEPARATOR = ":";
+declare const NOOP: () => void;
 type CommonOptionType = {
 	readonly help: {
 		readonly type: "boolean"
@@ -26,8 +27,9 @@ declare const __constants_COMMAND_BUILTIN_RESOURCE_KEYS: typeof COMMAND_BUILTIN_
 declare const __constants_COMMAND_OPTIONS_DEFAULT: typeof COMMAND_OPTIONS_DEFAULT;
 declare const __constants_COMMON_OPTIONS: typeof COMMON_OPTIONS;
 declare const __constants_DEFAULT_LOCALE: typeof DEFAULT_LOCALE;
+declare const __constants_NOOP: typeof NOOP;
 declare namespace __constants {
-  export { __constants_BUILT_IN_KEY_SEPARATOR as BUILT_IN_KEY_SEPARATOR, __constants_BUILT_IN_PREFIX as BUILT_IN_PREFIX, __constants_COMMAND_BUILTIN_RESOURCE_KEYS as COMMAND_BUILTIN_RESOURCE_KEYS, __constants_COMMAND_OPTIONS_DEFAULT as COMMAND_OPTIONS_DEFAULT, __constants_COMMON_OPTIONS as COMMON_OPTIONS, __constants_DEFAULT_LOCALE as DEFAULT_LOCALE };
+  export { __constants_BUILT_IN_KEY_SEPARATOR as BUILT_IN_KEY_SEPARATOR, __constants_BUILT_IN_PREFIX as BUILT_IN_PREFIX, __constants_COMMAND_BUILTIN_RESOURCE_KEYS as COMMAND_BUILTIN_RESOURCE_KEYS, __constants_COMMAND_OPTIONS_DEFAULT as COMMAND_OPTIONS_DEFAULT, __constants_COMMON_OPTIONS as COMMON_OPTIONS, __constants_DEFAULT_LOCALE as DEFAULT_LOCALE, __constants_NOOP as NOOP };
 }
 
 /**
@@ -98,6 +100,12 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	*/
 	usageOptionType: boolean;
 	/**
+	* Whether to display the command usage
+	* @default false
+	* @see {@link}
+	*/
+	usageSilent: boolean;
+	/**
 	* Sub commands
 	* @see {@link CommandOptions.subCommands}
 	*/
@@ -157,6 +165,10 @@ interface CommandOptions<Options extends ArgOptions = ArgOptions> {
 	*/
 	usageOptionType?: boolean;
 	/**
+	* Whether to display the command usage
+	*/
+	usageSilent?: boolean;
+	/**
 	* Render function the command usage
 	*/
 	renderUsage?: ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | null;
@@ -226,6 +238,13 @@ interface CommandContext<
 	*/
 	usage: CommandUsage<Options>;
 	/**
+	* Output a message
+	* @description 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

package/lib/{utils-CU_LSsUg.js → utils-jm146hfy.js}

@@ -3,6 +3,7 @@
 const DEFAULT_LOCALE = "en-US";
 const BUILT_IN_PREFIX = "_";
 const BUILT_IN_KEY_SEPARATOR = ":";
+const NOOP = () => {};
 const COMMON_OPTIONS = {
 	help: {
 		type: "boolean",
@@ -14,18 +15,19 @@ const COMMON_OPTIONS = {
 	}
 };
 const COMMAND_OPTIONS_DEFAULT = {
-	name: undefined,
-	description: undefined,
-	version: undefined,
-	cwd: undefined,
-	subCommands: undefined,
+	name: void 0,
+	description: void 0,
+	version: void 0,
+	cwd: void 0,
+	usageSilent: false,
+	subCommands: void 0,
 	leftMargin: 2,
 	middleMargin: 10,
 	usageOptionType: false,
-	renderHeader: undefined,
-	renderUsage: undefined,
-	renderValidationErrors: undefined,
-	translationAdapterFactory: undefined
+	renderHeader: void 0,
+	renderUsage: void 0,
+	renderValidationErrors: void 0,
+	translationAdapterFactory: void 0
 };
 
 //#endregion
@@ -60,4 +62,4 @@ function deepFreeze(obj) {
 }
 
 //#endregion
-export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveBuiltInKey, resolveLazyCommand };
+export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveBuiltInKey, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -72,28 +72,33 @@
   "devDependencies": {
     "@eslint/markdown": "^6.2.2",
     "@intlify/core": "next",
-    "@kazupon/eslint-config": "^0.22.0",
+    "@kazupon/eslint-config": "^0.26.1",
     "@kazupon/prettier-config": "^0.1.1",
     "@types/node": "^22.13.9",
     "@vitest/eslint-plugin": "^1.1.36",
     "bumpp": "^10.0.3",
-    "eslint": "^9.21.0",
+    "eslint": "^9.22.0",
     "eslint-config-prettier": "^10.0.2",
+    "eslint-import-resolver-typescript": "^4.2.2",
+    "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-jsonc": "^2.19.1",
+    "eslint-plugin-module-interop": "^0.3.0",
     "eslint-plugin-promise": "^7.2.1",
     "eslint-plugin-regexp": "^2.7.0",
     "eslint-plugin-unicorn": "^57.0.0",
+    "eslint-plugin-unused-imports": "^4.1.4",
     "eslint-plugin-yml": "^1.17.0",
     "gh-changelogen": "^0.2.8",
     "jsr": "^0.13.4",
     "knip": "^5.45.0",
     "lint-staged": "^15.4.3",
-    "messageformat": "4.0.0-9",
+    "messageformat": "4.0.0-10",
     "pkg-pr-new": "^0.0.41",
     "prettier": "^3.5.3",
     "tsdown": "^0.6.4",
     "typescript": "^5.4.2",
     "typescript-eslint": "^8.26.0",
+    "vitepress": "^1.6.3",
     "vitest": "^3.0.7"
   },
   "prettier": "@kazupon/prettier-config",
@@ -116,6 +121,9 @@
     "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",
+    "docs:preview": "vitepress preview docs",
     "fix": "pnpm run --stream --color \"/^fix:/\"",
     "fix:eslint": "eslint . --fix",
     "fix:knip": "knip --fix --no-exit-code",