@h3ravel/musket 2.0.0 → 2.2.0

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,10 +52,46 @@ type ParsedCommand<A extends Application = Application> = {
   options?: CommandOption[];
 };
 type PackageMeta = string | {
+  /**
+   * The package name to resolve version info from (its `package.json`).
+   */
+  name: 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;
-  alias: 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,191 @@ 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/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
@@ -255,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.
    *
@@ -308,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
    *
@@ -525,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>;
@@ -549,11 +859,69 @@ declare class Musket<A extends Application = Application> {
   discoverCommandsFrom(paths: string | string[]): this;
   private loadDiscoveredCommands;
   /**
-   * Push a new command into the commands stack
+   * 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;
+  /**
+   * 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.
+   *
+   * @param message
+   */
+  private warnDiscovery;
+  /**
+   * 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
    *
@@ -604,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, Musket, PackageMeta, ParsedCommand, Signature, TGeneric, XGeneric };
+export { Application, ArgumentDefinition, Command, CommandMethodResolver, CommandOption, Kernel, KernelConfig, ModuleMeta, Musket, OptionDefinition, PackageMeta, ParsedCommand, Signature, SignatureBuilder, SignatureValue, TGeneric, VersionRenderHelpers, XGeneric };