@breadc/core 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -1,8 +1,18 @@
-# @breadc/core
+# 🥪 Breadc
 
-[![version](https://img.shields.io/npm/v/breadc?label=Breadc)](https://www.npmjs.com/package/breadc) [![CI](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml/badge.svg)](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/yjl9903/Breadc/branch/main/graph/badge.svg?token=F7PGOG62EF)](https://codecov.io/gh/yjl9903/Breadc)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/yjl9903/Breadc)
+[![version](https://img.shields.io/npm/v/breadc?label=Breadc)](https://www.npmjs.com/package/breadc)
+[![CI](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml/badge.svg)](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/yjl9903/Breadc/branch/main/graph/badge.svg?token=F7PGOG62EF)](https://codecov.io/gh/yjl9903/Breadc)
 
-Yet another Command Line Application Framework with fully strong **[TypeScript](https://www.typescriptlang.org/) support**.
+Yet another **Command Line Application Framework** desgined for **[TypeScript](https://www.typescriptlang.org/)**.
+
+- **TypeScript Infer**: infer command arguments, option values, and action signatures in IDE automatically
+- **Command**: support default command, command alias, and nested sub-commands like `git remote add <name> <url>`
+- **Group**: organize commands by modules and build large multi-command CLI applications with clear structure
+- **Option**: support boolean, required, optional, spread options, `--no-*` negation, and `--` passthrough arguments
+- **Middleware**: support middleware pipeline and unknown option handling
+- **Builtin CLI Features**: provide common help / version options and i18n support out of the box
 
 ![vscode](https://raw.githubusercontent.com/yjl9903/Breadc/v1.0.0-beta.1/assets/typescript.png)
 
@@ -39,8 +49,9 @@ If you are using IDEs that support TypeScript (like [Visual Studio Code](https:/
 
 ## Inspiration
 
-+ [cac](https://github.com/cacjs/cac): Simple yet powerful framework for building command-line apps.
-+ [TypeScript: Documentation - Template Literal Types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)
+- [cac](https://github.com/cacjs/cac): Simple yet powerful framework for building command-line apps.
+- [Commander.js](https://github.com/tj/commander.js): Node.js command-line interfaces made easy.
+- [TypeScript: Documentation - Template Literal Types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)
 
 ## License
 

package/dist/index.d.mts

@@ -321,7 +321,7 @@ type InternalCommand = Command & {
   /**
    * @internal
    */
-  _actionFn?: Function;
+  _actionFn?: (...args: any[]) => unknown;
 };
 type OptionType = 'boolean' | 'required' | 'optional' | 'spread';
 type InternalOption = Option & {
@@ -529,9 +529,9 @@ type Breadc<Data extends {} = {}, Options extends Record<never, never> = {}> = {
    */
   use<Middleware extends ActionMiddleware<Data, ActionMiddlewareNextFn>>(middleware: Middleware): Breadc<InferMiddlewareData<Middleware>, Options>;
   /**
-   * Allow unknown option middleware
+   * Unknown command middleware
    */
-  onUnknownCommand(middleware?: boolean | UnknownCommandMiddleware<Data>): Breadc<Data, Options>;
+  onUnknownCommand(middleware?: UnknownCommandMiddleware<Data>): Breadc<Data, Options>;
   /**
    * Allow unknown option middleware
    */
@@ -567,7 +567,7 @@ type Group<Spec extends string = string, Init extends GroupInit<Spec> = GroupIni
   option<OS extends string, Initial extends NonTrueNullable<InferOptionInitialType<OS>>, OI extends NonNullableOptionInit<OS, Initial>>(spec: OS, description: string, init: OI): Group<Spec, Init, Data, Options & InferOption<OS, Initial, OI>>;
   option<OS extends string, Initial extends InferOptionInitialType<OS>, OI extends OptionInit<OS, Initial>>(spec: OS, description?: string, init?: OI): Group<Spec, Init, Data, Options & InferOption<OS, Initial, OI>>;
   command<S extends string, I extends CommandInit<S>>(spec: S, description?: string, init?: I): Command<S, I, Data, Options, InferArgumentsType<S>, unknown>;
-  command<S extends string, I extends CommandInit<S>>(command: Command<S, I, Options>): Command<S, I, Data, Options, InferArgumentsType<S>, unknown>;
+  command<S extends string, I extends CommandInit<S>>(command: Command<S, I, Data, Options>): Command<S, I, Data, Options, InferArgumentsType<S>, unknown>;
   /**
    * Action middleware
    */
@@ -577,7 +577,7 @@ type Group<Spec extends string = string, Init extends GroupInit<Spec> = GroupIni
    */
   allowUnknownOption(middleware?: UnknownOptionMiddleware<Data>): Group<Spec, Init, Data, Options>;
 };
-type Command<Spec extends string = string, Init extends CommandInit<Spec> = CommandInit<Spec>, Data extends {} = {}, Options extends Record<never, never> = {}, Arguments extends unknown[] = InferArgumentsType<Spec>, Return extends unknown = unknown> = {
+type Command<Spec extends string = string, Init extends CommandInit<Spec> = CommandInit<Spec>, Data extends {} = {}, Options extends Record<never, never> = Record<never, never>, Arguments extends unknown[] = InferArgumentsType<Spec>, Return extends unknown = unknown> = {
   spec: Spec;
   init: Init | undefined;
   /**
@@ -657,6 +657,7 @@ declare function printVersion(context: Context): string;
 //#region src/error.d.ts
 declare abstract class BreadcError extends Error {}
 type BreadcAppErrorCause = {
+  group?: InternalGroup;
   command?: InternalCommand;
   commands?: (InternalCommand | InternalGroup)[];
 };
@@ -665,6 +666,7 @@ type BreadcAppErrorInput = BreadcAppErrorCause & {
 };
 declare class BreadcAppError extends BreadcError {
   static DUPLICATED_DEFAULT_COMMAND: string;
+  static DUPLICATED_DEFAULT_GROUP_COMMAND: string;
   static DUPLICATED_GROUP: string;
   static DUPLICATED_COMMAND: string;
   static NO_ACTION_BOUND: string;

package/dist/index.mjs

@@ -38,6 +38,7 @@ function rawOption(spec, type, long, short, init) {
 //#region src/error.ts
 var BreadcError = class extends Error {};
 var RuntimeError = class extends BreadcError {
+	static UNEXPECTED_ARGUMENTS = "Detect unexpected redundant arguments";
 	static REQUIRED_ARGUMENT_MISSING = "Missing required argument";
 	static OPTIONAL_ARGUMENT_ACCEPT_ONCE = "Optional argument can only be assigned once";
 	static REQUIRED_ARGUMENT_ACCEPT_ONCE = "Required argument can only be assigned once";
@@ -60,6 +61,7 @@ var RuntimeError = class extends BreadcError {
 };
 var BreadcAppError = class extends BreadcError {
 	static DUPLICATED_DEFAULT_COMMAND = `Find duplicated default commands`;
+	static DUPLICATED_DEFAULT_GROUP_COMMAND = `Find duplicated default group commands`;
 	static DUPLICATED_GROUP = `Find duplicated groups`;
 	static DUPLICATED_COMMAND = `Find duplicated commands`;
 	static NO_ACTION_BOUND = `There is no action function bound in this command`;
@@ -112,6 +114,16 @@ var ResolveOptionError = class extends BreadcError {
 	}
 };
 
+//#endregion
+//#region src/breadc/shared.ts
+function resolveOptionInput(spec, description, init) {
+	return typeof spec === "string" ? option(spec, description, init) : spec;
+}
+const defaultUnknownOptionMiddleware = (_ctx, key, value) => ({
+	name: key,
+	value
+});
+
 //#endregion
 //#region src/breadc/command.ts
 function command(spec, init) {
@@ -134,8 +146,7 @@ function command(spec, init) {
 		return run;
 	};
 	run.option = (spec, description, init) => {
-		const option$5 = typeof spec === "string" ? option(spec, description, init) : spec;
-		options.push(option$5);
+		options.push(resolveOptionInput(spec, description, init));
 		return run;
 	};
 	run.use = (middleware) => {
@@ -146,10 +157,7 @@ function command(spec, init) {
 	run.allowUnknownOption = (middleware) => {
 		if (!run._unknownOptionMiddlewares) run._unknownOptionMiddlewares = [];
 		if (typeof middleware === "function") run._unknownOptionMiddlewares.push(middleware);
-		else run._unknownOptionMiddlewares.push((_ctx, key, value) => ({
-			name: key,
-			value
-		}));
+		else run._unknownOptionMiddlewares.push(defaultUnknownOptionMiddleware);
 		return run;
 	};
 	run.action = (fn) => {
@@ -799,9 +807,9 @@ function buildVersionOption(context) {
 	const { breadc } = context;
 	if (breadc._version) return breadc._version;
 	const spec = typeof breadc._init.builtin?.version === "object" ? breadc._init.builtin.version.spec : void 0;
-	const option$4 = spec ? resolveOption(option(spec, "Print version")) : rawOption("-v, --version", "boolean", "version", "v", { description: "Print version" });
-	breadc._version = option$4;
-	return option$4;
+	const option$2 = spec ? resolveOption(option(spec, "Print version")) : rawOption("-v, --version", "boolean", "version", "v", { description: "Print version" });
+	breadc._version = option$2;
+	return option$2;
 }
 function printVersion(context) {
 	const { breadc } = context;
@@ -849,7 +857,7 @@ function formatCommand(command) {
 	const args = formatArgument(command).join(" ");
 	return pieces && args ? `${pieces} ${args}` : pieces;
 }
-function commandMatched(command, prefix) {
+function commandStartsWith(command, prefix) {
 	if (prefix.length === 0) return true;
 	for (const pieces of command._pieces) {
 		if (pieces.length < prefix.length) continue;
@@ -862,6 +870,18 @@ function commandMatched(command, prefix) {
 	}
 	return false;
 }
+function commandIncludes(command, prefix) {
+	for (const pieces of command._pieces) {
+		if (pieces.length > prefix.length) continue;
+		let ok = true;
+		for (let i = 0; i < pieces.length; i++) if (pieces[i] !== prefix[i]) {
+			ok = false;
+			break;
+		}
+		if (ok) return true;
+	}
+	return false;
+}
 function collect(context, pieces) {
 	const allCommands = [];
 	const commands = [];
@@ -876,17 +896,17 @@ function collect(context, pieces) {
 		resolveGroup(group);
 		buildGroup(group);
 		allCommands.push(...group._commands);
-		if (commandMatched(group, pieces)) for (const option of group._options) append(option);
-		for (const command of group._commands) if (commandMatched(command, pieces)) {
+		if (commandIncludes(group, pieces)) for (const option of group._options) append(option);
+		for (const command of group._commands) if (commandStartsWith(command, pieces)) {
 			commands.push(command);
-			for (const option of command._options) append(option);
+			if (commandIncludes(command, pieces)) for (const option of command._options) append(option);
 		}
 	} else {
 		resolveCommand(command);
 		allCommands.push(command);
-		if (commandMatched(command, pieces)) {
+		if (commandStartsWith(command, pieces)) {
 			commands.push(command);
-			for (const option of command._options) append(option);
+			if (commandIncludes(command, pieces)) for (const option of command._options) append(option);
 		}
 	}
 	if (context.breadc._init.builtin?.help !== false) append(buildHelpOption(context));
@@ -901,9 +921,9 @@ function buildHelpOption(context) {
 	const { breadc } = context;
 	if (breadc._help) return breadc._help;
 	const spec = typeof breadc._init.builtin?.help === "object" ? breadc._init.builtin.help.spec : void 0;
-	const option$3 = spec ? resolveOption(option(spec, "Print help")) : rawOption("-h, --help", "boolean", "help", "h", { description: "Print help" });
-	breadc._help = option$3;
-	return option$3;
+	const option$1 = spec ? resolveOption(option(spec, "Print help")) : rawOption("-h, --help", "boolean", "help", "h", { description: "Print help" });
+	breadc._help = option$1;
+	return option$1;
 }
 function printHelp(context) {
 	const { breadc, pieces } = context;
@@ -950,10 +970,14 @@ function parse(app, argv) {
 		commands: defaultCommands
 	});
 	const defaultCommand = defaultCommands[0];
-	doParse(context$1, defaultCommand !== void 0 && context$1.breadc._commands.length === 1 ? defaultCommand : void 0);
-	if (context$1.command || isVersion(context$1) || isHelp(context$1)) {} else if (defaultCommand) {
+	doParse(context$1, void 0, defaultCommand !== void 0 && context$1.breadc._commands.length === 1 ? defaultCommand : void 0);
+	if (context$1.command || isVersion(context$1) || isHelp(context$1)) {} else if (context$1.group) {
+		const matchedGroup = context$1.group;
+		reset(context$1);
+		doParse(context$1, matchedGroup, void 0);
+	} else if (defaultCommand) {
 		reset(context$1);
-		doParse(context$1, defaultCommand);
+		doParse(context$1, void 0, defaultCommand);
 	}
 	return context$1;
 }
@@ -973,7 +997,7 @@ function isVersion(context) {
 	if (version && context.options.get(version.long)?.value()) return true;
 	else return false;
 }
-function doParse(context, defaultCommand) {
+function doParse(context, defaultGroup, defaultCommand) {
 	const { breadc, tokens, options: matchedOptions } = context;
 	let index = 0;
 	let matchedGroup = void 0;
@@ -1010,10 +1034,8 @@ function doParse(context, defaultCommand) {
 	}
 	if (defaultCommand) {
 		matchedCommand = defaultCommand;
-		for (const command of breadc._commands) if (command._default) {
-			buildCommand(command);
-			addPendingOptions(command._options);
-		}
+		buildCommand(defaultCommand);
+		addPendingOptions(defaultCommand._options);
 	} else for (const command of breadc._commands) if (!command._default) for (let alias = 0; alias < command._pieces.length; alias++) addPendingCommand(command, alias);
 	while (!tokens.isEnd) {
 		const token = tokens.next();
@@ -1035,7 +1057,22 @@ function doParse(context, defaultCommand) {
 					});
 					buildGroup(group);
 					addPendingOptions(group._options);
-					for (const command of group._commands) for (let alias = 0; alias < command._pieces.length; alias++) addPendingCommand(command, alias);
+					if (matchedGroup && matchedGroup === defaultGroup) {
+						const defaultCommands = matchedGroup._commands.filter((command) => command._pieces.some((p) => p.length === index));
+						if (defaultCommands.length === 1) {
+							const defaultCommand = defaultCommands[0];
+							matchedCommand = defaultCommand;
+							buildCommand(defaultCommand);
+							addPendingOptions(defaultCommand._options);
+						} else if (defaultCommands.length > 1) throw new BreadcAppError(BreadcAppError.DUPLICATED_DEFAULT_GROUP_COMMAND, {
+							context,
+							group: matchedGroup,
+							commands: defaultCommands
+						});
+					} else for (const command of group._commands) for (let alias = 0; alias < command._pieces.length; alias++) {
+						if (command._pieces[alias].length === index) continue;
+						addPendingCommand(command, alias);
+					}
 				} else {
 					if (!matchedCommand || matchedCommand === command) matchedCommand = command;
 					else throw new BreadcAppError(BreadcAppError.DUPLICATED_COMMAND, {
@@ -1075,6 +1112,7 @@ function doParse(context, defaultCommand) {
 	context.group = matchedGroup;
 	context.command = matchedCommand;
 	if (matchedCommand) {
+		if (unknown.length > 0) throw new RuntimeError(RuntimeError.UNEXPECTED_ARGUMENTS, { context });
 		let i = 0;
 		for (; i < matchedCommand._arguments.length; i++) {
 			const argument = matchedCommand._arguments[i];
@@ -1169,12 +1207,14 @@ function group(spec, init) {
 		_actionMiddlewares: actionMiddlewares,
 		_unknownOptionMiddlewares: unknownOptionMiddlewares,
 		option(spec, description, init) {
-			const option$2 = typeof spec === "string" ? option(spec, description, init) : spec;
-			options.push(option$2);
+			options.push(resolveOptionInput(spec, description, init));
 			return group;
 		},
-		command(spec, init) {
-			const command$2 = typeof spec === "string" ? command(spec, init) : spec;
+		command(spec, description, init) {
+			const command$2 = typeof spec === "string" ? command(spec, description || init ? {
+				description,
+				...init
+			} : void 0) : spec;
 			command$2._group = group;
 			commands.push(command$2);
 			return command$2;
@@ -1185,10 +1225,7 @@ function group(spec, init) {
 		},
 		allowUnknownOption(middleware) {
 			if (typeof middleware === "function") unknownOptionMiddlewares.push(middleware);
-			else unknownOptionMiddlewares.push((_ctx, key, value) => ({
-				name: key,
-				value
-			}));
+			else unknownOptionMiddlewares.push(defaultUnknownOptionMiddleware);
 			return group;
 		}
 	};
@@ -1213,8 +1250,7 @@ function breadc(name, init = {}) {
 		_unknownOptionMiddlewares: unknownOptionMiddlewares,
 		_unknownCommandMiddlewares: unknownCommandMiddlewares,
 		option(spec, description, init) {
-			const option$1 = typeof spec === "string" ? option(spec, description, init) : spec;
-			options.push(option$1);
+			options.push(resolveOptionInput(spec, description, init));
 			return app;
 		},
 		group(spec, init) {
@@ -1240,10 +1276,7 @@ function breadc(name, init = {}) {
 		},
 		allowUnknownOption(middleware) {
 			if (typeof middleware === "function") unknownOptionMiddlewares.push(middleware);
-			else unknownOptionMiddlewares.push((_ctx, key, value) => ({
-				name: key,
-				value
-			}));
+			else unknownOptionMiddlewares.push(defaultUnknownOptionMiddleware);
 			return app;
 		},
 		parse(argv) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadc/core",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "description": "Yet another Command Line Application Framework with fully strong TypeScript support",
   "keywords": [
     "breadc",
@@ -33,7 +33,7 @@
     "dist"
   ],
   "dependencies": {
-    "@breadc/color": "1.0.0-beta.2"
+    "@breadc/color": "1.0.0-beta.4"
   },
   "size-limit": [
     {