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

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;
   /**

package/dist/index.mjs

@@ -112,6 +112,18 @@ 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;
+}
+function defaultUnknownOptionMiddleware() {
+	return (_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;
@@ -1169,8 +1189,7 @@ 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) {
@@ -1185,10 +1204,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 +1229,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 +1255,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.3",
   "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.3"
   },
   "size-limit": [
     {