@h3ravel/musket 2.1.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
@@ -757,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;
@@ -859,9 +1147,26 @@ var Musket = class Musket {
 	*/
 	resolveCommandClass(mod, name) {
 		const named = mod[name];
-		if (typeof named === "function") return named;
-		if (typeof mod.default === "function") return mod.default;
-		return Object.values(mod).find((value) => typeof value === "function");
+		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.
@@ -872,21 +1177,53 @@ var Musket = class Musket {
 		_h3ravel_shared.Logger.log([["[musket]", "yellow"], [message, "white"]], " ");
 	}
 	/**
-	* Push a new command into the commands stack
-	* 
-	* @param command 
+	* 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;
 	}
 	/**
@@ -928,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);
@@ -1302,3 +1639,4 @@ exports.Command = Command;
 exports.Kernel = Kernel;
 exports.Musket = Musket;
 exports.Signature = Signature;
+exports.SignatureBuilder = SignatureBuilder;

package/dist/index.d.ts

@@ -327,6 +327,168 @@ declare class Kernel<A extends Application = Application> {
   getVersionString(): string;
 }
 //#endregion
+//#region src/SignatureBuilder.d.ts
+type SignatureValue = string | number | boolean | string[] | undefined;
+/**
+ * Definition of a positional argument added via {@link SignatureBuilder.argument}.
+ */
+interface ArgumentDefinition {
+  /** Human readable description. */
+  description?: string;
+  /** Whether the argument must be provided. Defaults to `true`. */
+  required?: boolean;
+  /** A default value. Implies the argument is optional. */
+  default?: SignatureValue;
+  /** Whether the argument accepts multiple (variadic) values. */
+  multiple?: boolean;
+  /** Restrict the accepted values to this list. */
+  choices?: string[];
+}
+/**
+ * Definition of an option/flag added via {@link SignatureBuilder.option}.
+ *
+ * By default an option is a boolean flag. Give it a `default`, set
+ * `requiresValue`, or set `optionalValue` to make it take a value.
+ */
+interface OptionDefinition {
+  /** Human readable description. */
+  description?: string;
+  /** A single character short alias, e.g. `Q` for `-Q`. */
+  short?: string;
+  /** A default value. Implies the option takes an optional value. */
+  default?: SignatureValue;
+  /** The option requires a value (`--queue <value>`). */
+  requiresValue?: boolean;
+  /** The option takes an optional value (`--queue [value]`). */
+  optionalValue?: boolean;
+  /** Restrict the accepted values to this list. */
+  choices?: string[];
+  /** Share this option with sub-commands of a namespace command. */
+  shared?: boolean;
+  /** Hide this option from help output. */
+  hidden?: boolean;
+}
+/**
+ * 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.
+ */
+declare class SignatureBuilder {
+  private baseName;
+  private commandDescription?;
+  private hidden;
+  private args;
+  private opts;
+  /**
+   * Set the command name, e.g. `make:model` or `queue:work`. A trailing `:`
+   * marks a namespace command.
+   */
+  command(name: string): this;
+  /**
+   * Alias for {@link command}.
+   *
+   * @param name
+   * @returns
+   */
+  name(name: string): this;
+  /**
+   * Set the command description.
+   *
+   * @param name
+   * @returns
+   */
+  describe(description: string): this;
+  /**
+   * Alias for {@link describe}.
+   *
+   * @param name
+   * @returns
+   */
+  description(description: string): this;
+  /**
+   * Mark the command as hidden from help output.
+   *
+   * @param name
+   * @returns
+   */
+  hide(hidden?: boolean): this;
+  /**
+   * Add a positional argument.
+   *
+   * @param name
+   * @returns
+   */
+  argument(name: string, definition?: ArgumentDefinition): this;
+  /**
+   * Add an option/flag.
+    *
+    * @param name
+    * @returns
+    */
+  option(name: string, definition?: OptionDefinition): this;
+  /**
+   * The configured command name (empty when unset).
+   *
+   * @param name
+   * @returns
+   */
+  getName(): string;
+  /**
+   * The configured description, if any.
+   *
+   * @param name
+   * @returns
+   */
+  getDescription(): string | undefined;
+  /**
+   * Whether the command is a namespace command (name ends with `:`).
+   *
+   * @param name
+   * @returns
+   */
+  isNamespace(): boolean;
+  /**
+   * Whether anything has been configured on this builder.
+   *
+   * @param name
+   * @returns
+   */
+  isEmpty(): boolean;
+  /**
+   * 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<A extends Application = Application>(commandClass: Command<A>): ParsedCommand<A>;
+  private argumentToOption;
+  private optionToOption;
+  /**
+   * 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(): string;
+  private argumentToken;
+  private optionToken;
+  private wrap;
+}
+//#endregion
 //#region src/Core/Command.d.ts
 declare class Command<A extends Application = Application> {
   protected app: A;
@@ -356,6 +518,11 @@ declare class Command<A extends Application = Application> {
    * @var string
    */
   protected description?: string;
+  /**
+   * Memoized result of {@link resolveBuilder}. `undefined` means "not yet
+   * resolved"; `null` means "resolved, no builder in use".
+   */
+  private resolvedBuilder?;
   /**
    * The console command input.
    *
@@ -409,11 +576,46 @@ declare class Command<A extends Application = Application> {
    */
   setProgram(program: Command$1): this;
   /**
-   * Get the command signature
+   * 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.
+   */
+  protected buildSignature(_builder: SignatureBuilder): SignatureBuilder | void;
+  /**
+   * 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}.
+   */
+  private resolveBuilder;
+  /**
+   * Get the command signature. Returns the string {@link signature} when set,
+   * otherwise reconstructs it from {@link buildSignature}.
    *
    * @returns
    */
   getSignature(): string;
+  /**
+   * 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(): ParsedCommand<A> | undefined;
   /**
    * Get the command description
    *
@@ -626,6 +828,13 @@ declare class Musket<A extends Application = Application> {
   name: string;
   private config;
   private 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).
+   */
+  private registeredKeys;
   private program;
   constructor(app: A, kernel: Kernel<A>, baseCommands?: Command<A>[], resolver?: CommandMethodResolver | undefined, tsDownConfig?: UserConfig);
   build(): Promise<Command$1>;
@@ -674,6 +883,21 @@ declare class Musket<A extends Application = Application> {
    * @param name  The file name without extension.
    */
   private resolveCommandClass;
+  /**
+   * 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.
+   */
+  private isCommandClass;
   /**
    * Emit a non-fatal command-discovery warning.
    *
@@ -681,11 +905,23 @@ declare class Musket<A extends Application = Application> {
    */
   private warnDiscovery;
   /**
-   * Push a new command into the commands stack
+   * 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: Command<A>): this;
+  /**
+   * A best-effort human label for a command, for diagnostics.
+   *
+   * @param command
+   */
+  private describeCommand;
   /**
    * Push a list of new commands to commands stack
    *
@@ -736,4 +972,4 @@ declare class Signature {
   static parseSignature<A extends Application = Application>(signature: string, commandClass: Command<A>): ParsedCommand<A>;
 }
 //#endregion
-export { Application, Command, CommandMethodResolver, CommandOption, Kernel, KernelConfig, ModuleMeta, Musket, PackageMeta, ParsedCommand, Signature, TGeneric, VersionRenderHelpers, XGeneric };
+export { Application, ArgumentDefinition, Command, CommandMethodResolver, CommandOption, Kernel, KernelConfig, ModuleMeta, Musket, OptionDefinition, PackageMeta, ParsedCommand, Signature, SignatureBuilder, SignatureValue, TGeneric, VersionRenderHelpers, XGeneric };

package/dist/index.js

@@ -5,6 +5,232 @@ import { glob } from "glob";
 import path from "node:path";
 import { createRequire } from "module";
 import { mkdir } from "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;
@@ -38,6 +264,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
@@ -118,20 +349,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
@@ -733,6 +1014,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;
@@ -835,9 +1123,26 @@ var Musket = class Musket {
 	*/
 	resolveCommandClass(mod, name) {
 		const named = mod[name];
-		if (typeof named === "function") return named;
-		if (typeof mod.default === "function") return mod.default;
-		return Object.values(mod).find((value) => typeof value === "function");
+		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.
@@ -848,21 +1153,53 @@ var Musket = class Musket {
 		Logger.log([["[musket]", "yellow"], [message, "white"]], " ");
 	}
 	/**
-	* Push a new command into the commands stack
-	* 
-	* @param command 
+	* 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;
 	}
 	/**
@@ -904,7 +1241,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);
@@ -1274,4 +1611,4 @@ var Kernel = class Kernel {
 	}
 };
 //#endregion
-export { Command, Kernel, Musket, Signature };
+export { Command, Kernel, Musket, Signature, SignatureBuilder };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h3ravel/musket",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Musket CLI is a framework-agnostic CLI framework designed to allow you build artisan-like CLI apps and for use in the H3ravel framework.",
   "type": "module",
   "main": "./dist/index.cjs",