@h3ravel/musket 2.0.0 → 2.1.0

package/dist/index.cjs

@@ -505,11 +505,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();
@@ -808,15 +805,73 @@ 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));
 	}
 	/**
+	* 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 (typeof named === "function") return named;
+		if (typeof mod.default === "function") return mod.default;
+		return Object.values(mod).find((value) => typeof value === "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
 	* 
 	* @param command 
@@ -842,13 +897,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"],
@@ -1177,13 +1230,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,6 +1258,44 @@ 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;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ChoiceOrSeparatorArray, Choices, Spinner } from "@h3ravel/shared";
+import { ChoiceOrSeparatorArray, Choices, LoggerChalk, Spinner } from "@h3ravel/shared";
 import { Argument, Command as Command$1 } from "commander";
 import { UserConfig } from "tsdown";
 
@@ -52,9 +52,45 @@ type ParsedCommand<A extends Application = Application> = {
   options?: CommandOption[];
 };
 type PackageMeta = string | {
+  /**
+   * The package name to resolve version info from (its `package.json`).
+   */
   name: string;
-  alias: string;
+  /**
+   * Display alias; defaults to `name`. Still passes through label formatting.
+   */
+  alias?: string;
+  /**
+   * Mark as the base package whose version `KernelConfig.version` overrides.
+   */
   base?: boolean;
+  /**
+   * Exact display label, bypassing the default name formatting entirely.
+   */
+  label?: string;
+  /**
+   * Hardcoded version string, bypassing `package.json` resolution.
+   */
+  version?: string;
+};
+/**
+ * Resolved metadata for a single module shown in the CLI version line.
+ */
+type ModuleMeta = {
+  name: string;
+  version: string;
+  alias?: string;
+  label?: string;
+  base?: boolean;
+};
+/**
+ * Helpers handed to {@link KernelConfig.versionFormatter} so a custom renderer
+ * can reuse the default per-module formatting while controlling the layout.
+ */
+type VersionRenderHelpers = {
+  /** Default per-module renderer: the colored `Label: version` segment. */format: (module: ModuleMeta) => string; /** Default label formatter (scope-stripped, spaced, capitalized). */
+  label: (module: ModuleMeta) => string; /** The separator that would be used between modules. */
+  separator: string;
 };
 type CommandMethodResolver = <X extends Command>(cmd: X, met: any) => Promise<X>;
 interface KernelConfig<A extends Application = Application> {
@@ -74,6 +110,42 @@ interface KernelConfig<A extends Application = Application> {
    * @default musket
    */
   version?: string;
+  /**
+   * Separator rendered between modules in the version line.
+   *
+   * @default ' | '
+   */
+  versionSeparator?: string;
+  /**
+   * Colors used by the default version renderer. Ignored when
+   * {@link versionFormatter} is supplied.
+   */
+  versionColors?: {
+    /**
+     * Color of each module's label.
+     *
+     * @default 'white'
+     */
+    label?: LoggerChalk;
+    /**
+     * Color of each module's version.
+     *
+     * @default 'green'
+     */
+    version?: LoggerChalk;
+  };
+  /**
+   * Fully override how the version line is rendered. Receives the resolved
+   * modules plus helpers (default per-module formatter, label formatter and
+   * separator) and must return the final string shown for `--version` and
+   * atop the command list. When omitted, modules are joined with
+   * {@link versionSeparator} using the default colored `Label: version`
+   * layout.
+   *
+   * @param modules  The resolved module metadata.
+   * @param helpers  Default formatters so layout can be customized cheaply.
+   */
+  versionFormatter?: (modules: ModuleMeta[], helpers: VersionRenderHelpers) => string;
   /**
    * Don't parse the command, usefull for testing or manual control
    */
@@ -124,6 +196,17 @@ interface KernelConfig<A extends Application = Application> {
    * @example ['Console/Commands/*.js', 'src/app/Commands/*.js']
    */
   discoveryPaths?: string | string[];
+  /**
+   * Optional override for how discovered command modules are imported.
+   * Receives the matched file path and must resolve the module namespace.
+   *
+   * When omitted, musket loads TypeScript sources via jiti (`@h3ravel/shared`'s
+   * `importFile`) and JavaScript natively, so `.ts` commands are discovered
+   * without a prior build.
+   *
+   * @param filePath  The matched command file path.
+   */
+  importModule?: (filePath: string) => Promise<Record<string, unknown>>;
 }
 //#endregion
 //#region src/Contracts/Utils.d.ts
@@ -140,12 +223,7 @@ declare class Kernel<A extends Application = Application> {
    */
   private cwd;
   output: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
-  modules: XGeneric<{
-    version: string;
-    name: string;
-    base?: boolean;
-    alias?: string;
-  }>[];
+  modules: XGeneric<ModuleMeta>[];
   /**
    * The base path for the CLI app
    */
@@ -224,6 +302,29 @@ declare class Kernel<A extends Application = Application> {
    * Prepares the CLI for execution
    */
   bootstrap(): 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: ModuleMeta): string;
+  /**
+   * Render a single module as a colored `Label: version` segment, honoring
+   * {@link KernelConfig.versionColors}.
+   *
+   * @param module
+   */
+  renderModuleVersion(module: ModuleMeta): string;
+  /**
+   * 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(): string;
 }
 //#endregion
 //#region src/Core/Command.d.ts
@@ -548,6 +649,37 @@ declare class Musket<A extends Application = Application> {
    */
   discoverCommandsFrom(paths: string | string[]): this;
   private loadDiscoveredCommands;
+  /**
+   * 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.
+   */
+  private importCommandModule;
+  /**
+   * 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.
+   */
+  private resolveCommandClass;
+  /**
+   * Emit a non-fatal command-discovery warning.
+   *
+   * @param message
+   */
+  private warnDiscovery;
   /**
    * Push a new command into the commands stack
    *
@@ -604,4 +736,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, Musket, PackageMeta, ParsedCommand, Signature, TGeneric, XGeneric };
+export { Application, Command, CommandMethodResolver, CommandOption, Kernel, KernelConfig, ModuleMeta, Musket, PackageMeta, ParsedCommand, Signature, TGeneric, VersionRenderHelpers, XGeneric };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { FileSystem, Logger, Prompts } from "@h3ravel/shared";
+import { FileSystem, Logger, Prompts, importFile } from "@h3ravel/shared";
 import { Argument, Command as Command$1, Option } from "commander";
 import { build } from "tsdown";
 import { glob } from "glob";
@@ -481,11 +481,8 @@ var ListCommand = class ListCommand extends Command {
 			return Logger.describe(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 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();
@@ -784,15 +781,73 @@ var Musket = class Musket {
 		* CLI Commands auto registration
 		*/
 		for await (const pth of glob.stream(paths)) {
-			const name = path.basename(pth).replaceAll(/\.ts|\.js|\.mjs/g, "");
+			const file = pth.toString();
+			const name = path.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));
 	}
 	/**
+	* 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 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 (typeof named === "function") return named;
+		if (typeof mod.default === "function") return mod.default;
+		return Object.values(mod).find((value) => typeof value === "function");
+	}
+	/**
+	* Emit a non-fatal command-discovery warning.
+	*
+	* @param message
+	*/
+	warnDiscovery(message) {
+		Logger.log([["[musket]", "yellow"], [message, "white"]], " ");
+	}
+	/**
 	* Push a new command into the commands stack
 	* 
 	* @param command 
@@ -818,13 +873,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 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"],
@@ -1153,13 +1206,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 = FileSystem.findModulePkg(name, this.cwd) ?? "";
 			const pkg = require(path.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({
@@ -1176,6 +1234,44 @@ 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 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
 export { Command, Kernel, Musket, Signature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h3ravel/musket",
-  "version": "2.0.0",
+  "version": "2.1.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",