gunshi 0.5.4 → 0.6.1

package/README.md

@@ -62,9 +62,11 @@ Gunshi has a simple API that is a facade:
 ```js
 import { cli } from 'gunshi'
 
+const args = process.argv.slice(2)
 // run a simple command
-cli(process.argv.slice(2), () => {
-  console.log('Hello from Gunshi!')
+cli(args, () => {
+  // something logic ...
+  console.log('Hello from Gunshi!', args)
 })
 ```
 
@@ -75,7 +77,7 @@ Configure commands declaratively:
 ```js
 import { cli } from 'gunshi'
 
-// define a command with declarative configuration
+// define a command with declarative configuration, using commandable object
 const command = {
   name: 'greet',
   description: 'A greeting command',
@@ -99,6 +101,8 @@ const command = {
   }
 }
 
+// run a command that is defined above
+// (the 3rd argument of `cli` is the command option)
 cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0',
@@ -119,7 +123,7 @@ import type { ArgOptions, Command, CommandContext } from 'gunshi'
 // type-safe arguments parsing example
 // this demonstrates how to define and use typed command options with `satisfies`
 
-// define options with types
+// define 'type-safe' command options with types
 const options = {
   // define string option with short alias
   name: {
@@ -139,7 +143,7 @@ const options = {
   }
 } satisfies ArgOptions
 
-// create a type-safe command
+// define 'type-safe' command
 const command = {
   name: 'type-safe',
   options,
@@ -156,12 +160,12 @@ For more detailed examples, check out the [playground/type-safe](https://github.
 
 ### 🧩 Composable Sub-commands
 
-Create a CLI with composable sub-commands:
+Run a CLI with composable sub-commands:
 
 ```js
 import { cli } from 'gunshi'
 
-// define sub-commands
+// define 'create' command
 const createCommand = {
   name: 'create',
   description: 'Create a new resource',
@@ -173,6 +177,7 @@ const createCommand = {
   }
 }
 
+// define 'list' command
 const listCommand = {
   name: 'list',
   description: 'List all resources',
@@ -181,12 +186,12 @@ const listCommand = {
   }
 }
 
-// create a Map of sub-commands
+// prepare a Map of sub-commands
 const subCommands = new Map()
 subCommands.set('create', createCommand)
 subCommands.set('list', listCommand)
 
-// define the main command
+// define the main ('resource-manager') command
 const mainCommand = {
   name: 'resource-manager',
   description: 'Manage resources',
@@ -229,7 +234,7 @@ const lazyCommand = async () => {
   }
 }
 
-// create a Map of sub-commands with lazy-loaded commands
+// prepare a Map of sub-commands with lazy-loaded commands
 const subCommands = new Map()
 subCommands.set('lazy', lazyCommand)
 
@@ -261,6 +266,7 @@ const command = {
     recursive: { type: 'boolean', short: 'r' },
     operation: { type: 'string', short: 'o', required: true }
   },
+  // define usage with object
   usage: {
     options: {
       path: 'File or directory path',
@@ -290,7 +296,7 @@ Customize the usage message generation:
 ```js
 import { cli } from 'gunshi'
 
-// custom header renderer
+// define custom header renderer
 const customHeaderRenderer = ctx => {
   return Promise.resolve(`
 ╔═══════════════════════╗
@@ -301,7 +307,7 @@ Version: ${ctx.env.version}
 `)
 }
 
-// custom usage renderer
+// define custom usage renderer
 const customUsageRenderer = ctx => {
   const lines = []
   lines.push('USAGE:')
@@ -386,7 +392,7 @@ If you are interested in contributing to `gunshi`, I highly recommend checking o
 
 ## 💖 Credits
 
-This project is inspired by:
+This project is inspired and powered by:
 
 - [`citty`](https://github.com/unjs/citty), created by UnJS team and contributors
 - cline and claude 3.7 sonnet, examples and docs is generated

package/lib/index.d.ts

@@ -9,6 +9,6 @@ export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBu
 * @param entry - A {@link Command | entry command} or an {@link CommandRunner | inline command runner}
 * @param opts - A {@link CommandOptions | command options}
 */
-declare function cli<Options extends ArgOptions = ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<void>;
+declare function cli<Options extends ArgOptions = ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<string | undefined>;
 
 export { Command, CommandOptions, CommandRunner, cli };

package/lib/index.js

@@ -1,6 +1,6 @@
 import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, createCommandContext } from "./context-DmZAeiph.js";
 import { create, log, resolveLazyCommand } from "./utils-NHs5DuHk.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-MpQ9U28q.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-v5Uq0km9.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/cli.ts
@@ -26,10 +26,13 @@ async function cli(args, entry, opts = {}) {
 		showVersion(ctx);
 		return;
 	}
-	await showHeader(ctx);
+	const usageBuffer = [];
+	const header = await showHeader(ctx);
+	if (header) usageBuffer.push(header);
 	if (values.help) {
-		await showUsage(ctx);
-		return;
+		const usage = await showUsage(ctx);
+		if (usage) usageBuffer.push(usage);
+		return usageBuffer.join("\n");
 	}
 	if (error) {
 		await showValidationErrors(ctx, error);
@@ -50,8 +53,11 @@ function getSubCommand(tokens) {
 }
 async function showUsage(ctx) {
 	if (ctx.env.renderUsage === null) return;
-	const render = ctx.env.renderUsage || renderUsage;
-	log(await render(ctx));
+	const usage = await (ctx.env.renderUsage || renderUsage)(ctx);
+	if (usage) {
+		log(usage);
+		return usage;
+	}
 }
 function showVersion(ctx) {
 	log(ctx.env.version);
@@ -62,6 +68,7 @@ async function showHeader(ctx) {
 	if (header) {
 		log(header);
 		log();
+		return header;
 	}
 }
 async function showValidationErrors(ctx, error) {

package/lib/renderer/index.js

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

package/lib/{renderer-MpQ9U28q.js → renderer-v5Uq0km9.js}

@@ -10,7 +10,10 @@ function renderHeader(ctx) {
 //#region src/renderer/usage.ts
 async function renderUsage(ctx) {
 	const messages = [];
-	if (!ctx.omitted && hasDescription(ctx)) messages.push(ctx.description, "");
+	if (!ctx.omitted) {
+		const description = resolveDescription(ctx);
+		if (description) messages.push(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), "");
@@ -99,12 +102,12 @@ function resolveSubCommand(ctx) {
 	return ctx.name || ctx.translation("SUBCOMMAND");
 }
 /**
-* Check if the command has a description
+* Resolve the command description
 * @param ctx A {@link CommandContext | command context}
-* @returns True if the command has a description
+* @returns resolved command description
 */
-function hasDescription(ctx) {
-	return !!ctx.description;
+function resolveDescription(ctx) {
+	return ctx.translation("description") || ctx.description || "";
 }
 /**
 * Check if the command has sub commands

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"