@h3ravel/musket 2.0.0 → 2.2.0

package/dist/index.cjs

@@ -29,6 +29,232 @@ let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let module$1 = require("module");
 let node_fs_promises = require("node:fs/promises");
+//#region src/SignatureBuilder.ts
+/**
+* A fluent builder for constructing a command's signature programmatically,
+* without authoring the string DSL by hand.
+*
+* ```ts
+* buildSignature (sig: SignatureBuilder) {
+*   return sig
+*     .command('queue:work')
+*     .describe('Process jobs on the queue')
+*     .argument('connection', { description: 'The connection to work', required: false })
+*     .option('queue', { description: 'The queue to process', short: 'Q' })
+*     .option('once', { description: 'Process a single job and exit' })
+* }
+* ```
+*
+* Musket consumes the builder directly (lossless) for normal commands, and can
+* also reconstruct the equivalent signature string via {@link toString} for
+* anything that still expects the DSL.
+*/
+var SignatureBuilder = class {
+	baseName = "";
+	commandDescription;
+	hidden = false;
+	args = [];
+	opts = [];
+	/**
+	* Set the command name, e.g. `make:model` or `queue:work`. A trailing `:`
+	* marks a namespace command.
+	*/
+	command(name) {
+		this.baseName = name.trim();
+		return this;
+	}
+	/** 
+	* Alias for {@link command}. 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	name(name) {
+		return this.command(name);
+	}
+	/** 
+	* Set the command description. 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	describe(description) {
+		this.commandDescription = description;
+		return this;
+	}
+	/** 
+	* Alias for {@link describe}. 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	description(description) {
+		return this.describe(description);
+	}
+	/** 
+	* Mark the command as hidden from help output. 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	hide(hidden = true) {
+		this.hidden = hidden;
+		return this;
+	}
+	/** 
+	* Add a positional argument. 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	argument(name, definition = {}) {
+		this.args.push({
+			name: name.trim(),
+			...definition
+		});
+		return this;
+	}
+	/** 
+	* Add an option/flag. 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	option(name, definition = {}) {
+		this.opts.push({
+			name: name.replace(/^--?/, "").trim(),
+			...definition
+		});
+		return this;
+	}
+	/** 
+	* The configured command name (empty when unset). 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	getName() {
+		return this.baseName;
+	}
+	/** 
+	* The configured description, if any. 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	getDescription() {
+		return this.commandDescription;
+	}
+	/** 
+	* Whether the command is a namespace command (name ends with `:`). 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	isNamespace() {
+		return this.baseName.endsWith(":");
+	}
+	/** 
+	* Whether anything has been configured on this builder. 
+	* 
+	* @param name 
+	* @returns 
+	*/
+	isEmpty() {
+		return this.baseName.length === 0;
+	}
+	/**
+	* Build the structured {@link ParsedCommand} consumed by the kernel. This is
+	* lossless — no string round-trip — and is the path used for normal commands.
+	* 
+	* @param commandClass 
+	* @returns 
+	*/
+	toParsed(commandClass) {
+		const options = [...this.args.map((arg) => this.argumentToOption(arg)), ...this.opts.map((opt) => this.optionToOption(opt))];
+		return {
+			baseCommand: this.baseName,
+			isNamespaceCommand: false,
+			description: this.commandDescription ?? commandClass.getDescription(),
+			commandClass,
+			options,
+			isHidden: this.hidden
+		};
+	}
+	argumentToOption(arg) {
+		const required = arg.required ?? arg.default === void 0;
+		const multiple = arg.multiple ?? false;
+		let placeholder;
+		if (multiple) placeholder = required ? `<${arg.name}...>` : `[${arg.name}...]`;
+		return {
+			name: arg.name,
+			isFlag: false,
+			required,
+			multiple,
+			description: arg.description ?? "",
+			choices: arg.choices ?? [],
+			defaultValue: arg.default,
+			placeholder
+		};
+	}
+	optionToOption(opt) {
+		const long = `--${opt.name}`;
+		const flags = opt.short ? [`-${opt.short}`, long] : [long];
+		const takesValue = opt.default !== void 0 || opt.requiresValue === true || opt.optionalValue === true || (opt.choices?.length ?? 0) > 0;
+		let required = false;
+		let placeholder;
+		if (takesValue) if (opt.requiresValue === true && opt.default === void 0 && opt.optionalValue !== true) required = true;
+		else placeholder = `[${opt.name}]`;
+		return {
+			name: long,
+			flags,
+			isFlag: true,
+			required,
+			placeholder,
+			description: opt.description ?? "",
+			choices: opt.choices ?? [],
+			defaultValue: opt.default ?? (takesValue ? void 0 : false),
+			shared: opt.shared,
+			isHidden: opt.hidden
+		};
+	}
+	/**
+	* Reconstruct the equivalent signature string in musket's DSL. Used by
+	* {@link Command.getSignature} so external consumers (and the namespace path)
+	* keep working unchanged.
+	*/
+	toString() {
+		const tokens = [this.baseName];
+		for (const arg of this.args) tokens.push(this.argumentToken(arg));
+		for (const opt of this.opts) tokens.push(this.optionToken(opt));
+		return tokens.join("\n        ");
+	}
+	argumentToken(arg) {
+		const required = arg.required ?? arg.default === void 0;
+		const multiple = arg.multiple ?? false;
+		let token = arg.name;
+		if (arg.default !== void 0) token += `=${arg.default}`;
+		else if (!required && multiple) token += "?*";
+		else if (multiple) token += "*";
+		else if (!required) token += "?";
+		return this.wrap(token, arg.description, arg.choices);
+	}
+	optionToken(opt) {
+		const takesValue = opt.default !== void 0 || opt.requiresValue === true || opt.optionalValue === true;
+		let token = opt.short ? `--${opt.short}|${opt.name}` : `--${opt.name}`;
+		if (opt.default !== void 0) token += `=${opt.default}`;
+		else if (opt.requiresValue === true && opt.optionalValue !== true) token += "=";
+		else if (opt.optionalValue === true) token += "?";
+		return this.wrap(token, opt.description, opt.choices, takesValue);
+	}
+	wrap(token, description, choices, _value) {
+		let body = token;
+		if (description) body += ` : ${description}`;
+		if (choices?.length) body += ` : [${choices.join(", ")}]`;
+		return `{${body}}`;
+	}
+};
+//#endregion
 //#region src/Core/Command.ts
 var Command = class {
 	app;
@@ -62,6 +288,11 @@ var Command = class {
 	*/
 	description;
 	/**
+	* Memoized result of {@link resolveBuilder}. `undefined` means "not yet
+	* resolved"; `null` means "resolved, no builder in use".
+	*/
+	resolvedBuilder;
+	/**
 	* The console command input.
 	*
 	* @var object
@@ -142,20 +373,70 @@ var Command = class {
 		return this;
 	}
 	/**
-	* Get the command signature
-	* 
-	* @returns 
+	* Define the command signature programmatically.
+	*
+	* Override this instead of (or in addition to) the {@link signature} string
+	* to describe the command, its arguments and its options through the fluent
+	* {@link SignatureBuilder} — no string DSL required. When the `signature`
+	* string is set it always takes precedence and this method is ignored.
+	*
+	* ```ts
+	* buildSignature (sig: SignatureBuilder) {
+	*   return sig
+	*     .command('queue:work')
+	*     .describe('Process jobs on the queue')
+	*     .argument('connection', { required: false })
+	*     .option('queue', { short: 'Q', description: 'The queue to process' })
+	*     .option('once', { description: 'Process a single job and exit' })
+	* }
+	* ```
+	*
+	* @param _builder  A fresh builder to configure.
+	*/
+	buildSignature(_builder) {
+		/** Override to use. */
+	}
+	/**
+	* Resolve (and memoize) the signature builder for this command, or `null`
+	* when the command uses the string {@link signature} (which always wins) or
+	* does not implement {@link buildSignature}.
+	*/
+	resolveBuilder() {
+		if (this.resolvedBuilder !== void 0) return this.resolvedBuilder;
+		if (this.signature) return this.resolvedBuilder = null;
+		const builder = new SignatureBuilder();
+		const result = this.buildSignature(builder);
+		const resolved = result instanceof SignatureBuilder ? result : builder;
+		return this.resolvedBuilder = resolved.isEmpty() ? null : resolved;
+	}
+	/**
+	* Get the command signature. Returns the string {@link signature} when set,
+	* otherwise reconstructs it from {@link buildSignature}.
+	*
+	* @returns
 	*/
 	getSignature() {
-		return this.signature;
+		if (this.signature) return this.signature;
+		return this.resolveBuilder()?.toString() ?? this.signature;
+	}
+	/**
+	* The structured, lossless parsed command when {@link buildSignature} is used
+	* for a non-namespace command; `undefined` otherwise (callers then fall back
+	* to parsing {@link getSignature}). This avoids a lossy string round-trip.
+	*/
+	toParsedSignature() {
+		const builder = this.resolveBuilder();
+		if (!builder || builder.isNamespace()) return;
+		return builder.toParsed(this);
 	}
 	/**
 	* Get the command description
-	* 
-	* @returns 
+	*
+	* @returns
 	*/
 	getDescription() {
-		return this.description;
+		if (this.description) return this.description;
+		return this.resolveBuilder()?.getDescription() ?? this.description;
 	}
 	/**
 	* Get a specific option
@@ -505,11 +786,8 @@ var ListCommand = class ListCommand extends Command {
 			return _h3ravel_shared.Logger.describe(_h3ravel_shared.Logger.log("  " + e.name(), "green", false), e.description(), 25, false).join("");
 		});
 		const list = ListCommand.groupItems(commands);
-		/** Output the modules version */
-		const version = this.kernel.modules.map((e) => {
-			const value = String(e.alias ?? e.name).split("/").pop().replace(/[-_]/g, " ").replace(/cli/gi, (match) => match === "cli" ? "CLI" : match).replace(/^./, (c) => c.toUpperCase());
-			return _h3ravel_shared.Logger.log([[`${value}:`, "white"], [e.version, "green"]], " ", false);
-		}).join(" | ");
+		/** Output the modules version (shared renderer, overridable via config) */
+		const version = this.kernel.getVersionString();
 		this.newLine();
 		console.log(version);
 		this.newLine();
@@ -760,6 +1038,13 @@ var Musket = class Musket {
 	name = "musket";
 	config = {};
 	commands = [];
+	/**
+	* Keys (baseCommand, namespace-aware) of commands already registered, so the
+	* same command surfacing from more than one source — e.g. discovered both as
+	* built `dist/*.js` and as `src/*.ts` via the jiti loader — is only added
+	* once. The first registration wins (base commands before discovered ones).
+	*/
+	registeredKeys = /* @__PURE__ */ new Set();
 	program;
 	constructor(app, kernel, baseCommands = [], resolver, tsDownConfig = {}) {
 		this.app = app;
@@ -808,30 +1093,137 @@ var Musket = class Musket {
 		* CLI Commands auto registration
 		*/
 		for await (const pth of glob.glob.stream(paths)) {
-			const name = node_path.default.basename(pth).replaceAll(/\.ts|\.js|\.mjs/g, "");
+			const file = pth.toString();
+			const name = node_path.default.basename(file).replace(/\.(c|m)?(t|j)s$/, "");
 			try {
-				const cmdClass = (await import(pth))[name];
-				commands.push(new cmdClass(this.app, this.kernel));
-			} catch {}
+				const mod = await this.importCommandModule(file);
+				const CommandClass = this.resolveCommandClass(mod, name);
+				if (!CommandClass) {
+					this.warnDiscovery(`No command class export found in ${file}`);
+					continue;
+				}
+				commands.push(new CommandClass(this.app, this.kernel));
+			} catch (error) {
+				/**
+				* Never swallow load failures silently — a command that throws on
+				* import would otherwise just vanish from the CLI with no clue why.
+				*/
+				this.warnDiscovery(`Failed to load command ${file}: ${error?.message ?? String(error)}`);
+			}
 		}
 		commands.forEach((e) => this.addCommand(e));
 	}
 	/**
-	* Push a new command into the commands stack
-	* 
-	* @param command 
+	* Import a discovered command module with full TypeScript support.
+	*
+	* Native `import()` is attempted first: it loads built `.js`, and works
+	* verbatim in TypeScript-aware runtimes/test loaders (vitest, tsx, Node with
+	* type stripping) — which also keeps their module mocking and single module
+	* registry intact. When native import can't load a TypeScript source (plain
+	* Node throwing on a `.ts`/`.mts`/`.cts` file), it is transpiled on the fly
+	* via jiti (`@h3ravel/shared`'s `importFile`) so commands are discovered
+	* without a prior build. Consumers can bypass all of this with
+	* {@link KernelConfig.importModule}.
+	*
+	* @param file  Absolute or cwd-relative path to the command module.
+	*/
+	async importCommandModule(file) {
+		if (this.config.importModule) return await this.config.importModule(file);
+		try {
+			return await import(file);
+		} catch (error) {
+			if (/\.(c|m)?ts$/.test(file)) return await (0, _h3ravel_shared.importFile)(file);
+			throw error;
+		}
+	}
+	/**
+	* Resolve the command class out of an imported module. Prefers the export
+	* named after the file, then a `default` export, then the first exported
+	* constructor — because a file's name and its exported class name do not
+	* always match.
+	*
+	* @param mod   The imported module namespace.
+	* @param name  The file name without extension.
+	*/
+	resolveCommandClass(mod, name) {
+		const named = mod[name];
+		if (this.isCommandClass(named)) return named;
+		if (this.isCommandClass(mod.default)) return mod.default;
+		return Object.values(mod).find((value) => this.isCommandClass(value));
+	}
+	/**
+	* Whether a value is a Command class (constructor), as opposed to any other
+	* exported function/class.
+	*
+	* The check is structural — it looks for `getSignature` on the prototype
+	* rather than using `instanceof Command` — so it stays correct when the
+	* discovered command extends a Command from a different copy/version of
+	* musket. Crucially, it rejects non-command exports such as the shared
+	* bundler chunks tools like tsdown can emit alongside built commands (e.g. a
+	* `Rebuilder` helper), which would otherwise be `new`-ed and then crash when
+	* `getSignature()` is called on them.
+	*
+	* @param value  The candidate export.
+	*/
+	isCommandClass(value) {
+		return typeof value === "function" && typeof value.prototype?.getSignature === "function";
+	}
+	/**
+	* Emit a non-fatal command-discovery warning.
+	*
+	* @param message
+	*/
+	warnDiscovery(message) {
+		_h3ravel_shared.Logger.log([["[musket]", "yellow"], [message, "white"]], " ");
+	}
+	/**
+	* Push a new command into the commands stack.
+	*
+	* Resolution prefers a command's structured signature (built via
+	* {@link Command.buildSignature}) and falls back to parsing its signature
+	* string. Commands that expose no usable signature are skipped with a warning
+	* rather than crashing the CLI, and a command whose key was already
+	* registered is ignored (de-duplication — see {@link registeredKeys}).
+	*
+	* @param command
 	*/
 	addCommand(command) {
-		this.commands.push(Signature.parseSignature(command.getSignature(), command));
+		if (!command || typeof command.getSignature !== "function") {
+			this.warnDiscovery(`Skipping ${this.describeCommand(command)}: not a valid command (no getSignature()).`);
+			return this;
+		}
+		let parsed;
+		try {
+			parsed = command.toParsedSignature?.() ?? Signature.parseSignature(command.getSignature(), command);
+		} catch (error) {
+			this.warnDiscovery(`Skipping ${this.describeCommand(command)}: ${error?.message ?? String(error)}`);
+			return this;
+		}
+		if (!parsed || !parsed.baseCommand) {
+			this.warnDiscovery(`Skipping ${this.describeCommand(command)}: empty or unparsable signature.`);
+			return this;
+		}
+		const key = parsed.isNamespaceCommand ? `${parsed.baseCommand}:` : parsed.baseCommand;
+		if (this.registeredKeys.has(key)) return this;
+		this.registeredKeys.add(key);
+		this.commands.push(parsed);
 		return this;
 	}
 	/**
+	* A best-effort human label for a command, for diagnostics.
+	*
+	* @param command
+	*/
+	describeCommand(command) {
+		return command?.constructor?.name ?? "command";
+	}
+	/**
 	* Push a list of new commands to commands stack
-	* 
-	* @param command 
+	*
+	* @param command
 	*/
 	registerCommands(commands) {
-		commands.forEach(this.addCommand);
+		commands.forEach((e) => this.addCommand(e));
 		return this;
 	}
 	/**
@@ -842,13 +1234,11 @@ var Musket = class Musket {
 	}
 	async initialize() {
 		if (process.argv.includes("--help") || process.argv.includes("-h")) await this.rebuild("help");
-		/** 
-		* Get the provided packages versions
+		/**
+		* Render the provided packages versions (single source of truth shared
+		* with ListCommand, fully overridable via KernelConfig).
 		*/
-		const moduleVersions = this.kernel.modules.map((e) => {
-			const value = String(e.alias ?? e.name).split("/").pop().replace(/[-_]/g, " ").replace(/cli/gi, (match) => match === "cli" ? "CLI" : match).replace(/^./, (c) => c.toUpperCase());
-			return _h3ravel_shared.Logger.parse([[`${value}:`, "white"], [e.version, "green"]], " ", false);
-		}).join(" | ");
+		const moduleVersions = this.kernel.getVersionString();
 		const additional = {
 			quiet: ["-q, --quiet", "Do not output any message except errors and warnings"],
 			silent: ["--silent", "Do not output any message"],
@@ -875,7 +1265,7 @@ var Musket = class Musket {
 			* Load the root command here
 			*/
 			const root = new this.config.rootCommand(this.app, this.kernel);
-			const sign = Signature.parseSignature(root.getSignature(), root);
+			const sign = root.toParsedSignature?.() ?? Signature.parseSignature(root.getSignature(), root);
 			const cmd = this.program.name(sign.baseCommand).description(sign.description ?? sign.baseCommand).configureHelp({ showGlobalOptions: true }).action(async () => {
 				root.setInput(this.program.opts(), this.program.args, this.program.registeredArguments, {}, this.program);
 				await this.handle(root);
@@ -1177,13 +1567,18 @@ var Kernel = class Kernel {
 		for (let i = 0; i < this.packages.length; i++) try {
 			const item = this.packages[i];
 			const name = typeof item === "string" ? item : item.name;
-			const alias = typeof item === "string" ? item : item.alias;
+			const alias = typeof item === "string" ? item : item.alias ?? item.name;
 			const base = typeof item === "string" ? false : item.base;
+			const label = typeof item === "string" ? void 0 : item.label;
+			const versionOverride = typeof item === "string" ? void 0 : item.version;
 			const modulePath = _h3ravel_shared.FileSystem.findModulePkg(name, this.cwd) ?? "";
 			const pkg = require(node_path.default.join(modulePath, "package.json"));
 			pkg.alias = alias;
 			pkg.base = base;
-			if (base === true && version) pkg.version = version;
+			if (label) pkg.label = label;
+			/** A per-package version wins, then the base-package override. */
+			if (versionOverride) pkg.version = versionOverride;
+			else if (base === true && version) pkg.version = version;
 			this.modules.push(pkg);
 		} catch {
 			this.modules.push({
@@ -1200,9 +1595,48 @@ var Kernel = class Kernel {
 		}
 		return this;
 	}
+	/**
+	* Format a module's display label: strip the package scope, turn `-`/`_`
+	* into spaces, normalise "cli" casing and capitalise. A module's explicit
+	* `label` short-circuits all of this.
+	*
+	* @param module
+	*/
+	formatModuleLabel(module) {
+		if (module.label) return module.label;
+		return String(module.alias ?? module.name).split("/").pop().replace(/[-_]/g, " ").replace(/cli/gi, (match) => match === "cli" ? "CLI" : match).replace(/^./, (c) => c.toUpperCase());
+	}
+	/**
+	* Render a single module as a colored `Label: version` segment, honoring
+	* {@link KernelConfig.versionColors}.
+	*
+	* @param module
+	*/
+	renderModuleVersion(module) {
+		const colors = this.config.versionColors ?? {};
+		return _h3ravel_shared.Logger.parse([[`${this.formatModuleLabel(module)}:`, colors.label ?? "white"], [String(module.version), colors.version ?? "green"]], " ", false);
+	}
+	/**
+	* Build the full version line shown for `--version` and atop the command
+	* list. A single source of truth for both render sites.
+	*
+	* Honors {@link KernelConfig.versionFormatter} for complete control,
+	* otherwise joins each module with {@link KernelConfig.versionSeparator}.
+	*/
+	getVersionString() {
+		const modules = this.modules;
+		const separator = this.config.versionSeparator ?? " | ";
+		if (this.config.versionFormatter) return this.config.versionFormatter(modules, {
+			format: (module) => this.renderModuleVersion(module),
+			label: (module) => this.formatModuleLabel(module),
+			separator
+		});
+		return modules.map((module) => this.renderModuleVersion(module)).join(separator);
+	}
 };
 //#endregion
 exports.Command = Command;
 exports.Kernel = Kernel;
 exports.Musket = Musket;
 exports.Signature = Signature;
+exports.SignatureBuilder = SignatureBuilder;