alepha 0.14.3 → 0.15.0

package/dist/command/index.d.ts

@@ -14,28 +14,28 @@ declare class CommandError extends AlephaError {
 //#region ../../src/command/helpers/Asker.d.ts
 interface AskOptions<T extends TSchema = TString> {
   /**
-   * Response schema expected.
-   *
-   * Recommended schemas:
-   * - t.text() - for free text input
-   * - t.number() - for numeric input
-   * - t.boolean() - for yes/no input (accepts "true", "false", "1", "0")
-   * - t.enum(["option1", "option2"]) - for predefined options
-   *
-   * You can use schema.default to provide a default value.
-   *
-   * @example
-   * ```ts
-   * ask("What is your name?", { schema: t.text({ default: "John Doe" }) })
-   * ```
-   *
-   * @default TString
-   */
+       * Response schema expected.
+       *
+       * Recommended schemas:
+       * - t.text() - for free text input
+       * - t.number() - for numeric input
+       * - t.boolean() - for yes/no input (accepts "true", "false", "1", "0")
+       * - t.enum(["option1", "option2"]) - for predefined options
+       *
+       * You can use schema.default to provide a default value.
+       *
+       * @example
+       * ```ts
+       * ask("What is your name?", { schema: t.text({ default: "John Doe" }) })
+       * ```
+       *
+       * @default TString
+       */
   schema?: T;
   /**
-   * Custom validation function.
-   * Throws an AlephaError in case of validation failure.
-   */
+       * Custom validation function.
+       * Throws an AlephaError in case of validation failure.
+       */
   validate?: (value: Static<T>) => void;
 }
 interface AskMethod {
@@ -56,10 +56,10 @@ declare class Asker {
 declare class EnvUtils {
   protected readonly log: alepha_logger0.Logger;
   /**
-   * Load environment variables from .env files into process.env.
-   * By default, it loads from ".env" and ".env.local".
-   * You can specify additional files to load, e.g. [".env", ".env.production"].
-   */
+       * Load environment variables from .env files into process.env.
+       * By default, it loads from ".env" and ".env.local".
+       * You can specify additional files to load, e.g. [".env", ".env.production"].
+       */
   loadEnv(root: string, files?: string[]): Promise<void>;
 }
 //#endregion
@@ -85,40 +85,40 @@ declare class PrettyPrint {
     dim: string;
   };
   /**
-   * Start a new command session with header
-   */
+       * Start a new command session with header
+       */
   startCommand(cliName: string, commandName: string): void;
   /**
-   * End the command session with footer
-   */
+       * End the command session with footer
+       */
   endCommand(): void;
   /**
-   * Start an animated spinner with a task name
-   */
+       * Start an animated spinner with a task name
+       */
   startSpinner(id: string, taskName: string): void;
   /**
-   * Stop the spinner and show success with a tick
-   */
+       * Stop the spinner and show success with a tick
+       */
   success(id: string, taskName?: string, duration?: string): void;
   /**
-   * Stop the spinner and show error with a cross
-   */
+       * Stop the spinner and show error with a cross
+       */
   error(id: string, taskName?: string): void;
   /**
-   * Update the display for all tasks
-   */
+       * Update the display for all tasks
+       */
   protected updateDisplay(): void;
   /**
-   * Check if all tasks are done and stop the interval
-   */
+       * Check if all tasks are done and stop the interval
+       */
   protected checkIfAllDone(): void;
   /**
-   * Stop the spinner without showing any symbol
-   */
+       * Stop the spinner without showing any symbol
+       */
   stopSpinner(): void;
   /**
-   * Clear all tasks
-   */
+       * Clear all tasks
+       */
   clear(): void;
 }
 //#endregion
@@ -133,9 +133,13 @@ interface Timer {
 }
 interface RunOptions {
   /**
-   * Rename the command for logging purposes.
-   */
+       * Rename the command for logging purposes.
+       */
   alias?: string;
+  /**
+       * Root directory to execute the command in.
+       */
+  root?: string;
 }
 interface RunnerMethod {
   (cmd: string | Task | Array<string | Task>, options?: RunOptions | (() => any)): Promise<string>;
@@ -155,21 +159,23 @@ declare class Runner {
   constructor();
   protected get useDynamicLogger(): boolean;
   /**
-   * Start a new command session with header (for pretty print mode)
-   */
+       * Start a new command session with header (for pretty print mode)
+       */
   startCommand(cliName: string, commandName: string): void;
   protected createRunMethod(): RunnerMethod;
-  protected exec(cmd: string): Promise<string>;
-  /**
-   * Executes one or more tasks.
-   *
-   * @param task - A single task or an array of tasks to run in parallel.
-   */
+  protected exec(cmd: string, opts?: {
+    root?: string;
+  }): Promise<string>;
+  /**
+       * Executes one or more tasks.
+       *
+       * @param task - A single task or an array of tasks to run in parallel.
+       */
   protected execute(task: Task | Task[]): Promise<string>;
   /**
-   * Prints a summary of all executed tasks and their durations.
-   */
-  summary(): void;
+       * Prints a summary of all executed tasks and their durations.
+       */
+  end(): void;
   protected executeTask(task: Task): Promise<string>;
   protected renderTable(data: string[][]): void;
 }
@@ -187,208 +193,203 @@ declare const $command: {
 };
 interface CommandPrimitiveOptions<T extends TObject, A extends TSchema, E extends TObject = TObject> {
   /**
-   * The handler function to execute when the command is matched.
-   *
-   * For parent commands with children, the handler is called when:
-   * - The parent command is invoked without a subcommand
-   * - The parent command is invoked with --help (to show available subcommands)
-   */
+       * The handler function to execute when the command is matched.
+       *
+       * For parent commands with children, the handler is called when:
+       * - The parent command is invoked without a subcommand
+       * - The parent command is invoked with --help (to show available subcommands)
+       */
   handler: (args: CommandHandlerArgs<T, A, E>) => Async<void>;
   /**
-   * The name of the command. If omitted, the property key is used.
-   *
-   * An empty string "" denotes the root command.
-   */
+       * The name of the command. If omitted, the property key is used.
+       *
+       * An empty string "" denotes the root command.
+       */
   name?: string;
   /**
-   * A short description of the command, shown in the help message.
-   */
+       * A short description of the command, shown in the help message.
+       */
   description?: string;
   /**
-   * An array of alternative names for the command.
-   */
+       * An array of alternative names for the command.
+       */
   aliases?: string[];
   /**
-   * A TypeBox object schema defining the flags for the command.
-   */
+       * A TypeBox object schema defining the flags for the command.
+       */
   flags?: T;
   /**
-   * A TypeBox object schema defining required environment variables.
-   *
-   * Environment variables are validated before the handler runs (fail fast).
-   * They are displayed in the help output under "Env:" section.
-   *
-   * @example
-   * ```ts
-   * $command({
-   *   env: t.object({
-   *     VERCEL_TOKEN: t.text({ description: "Vercel API token" }),
-   *     VERCEL_ORG_ID: t.optional(t.text({ description: "Organization ID" })),
-   *   }),
-   *   handler: async ({ env }) => {
-   *     // env.VERCEL_TOKEN is typed & guaranteed to exist
-   *     console.log(env.VERCEL_TOKEN);
-   *   }
-   * })
-   * ```
-   */
+       * A TypeBox object schema defining required environment variables.
+       *
+       * Environment variables are validated before the handler runs (fail fast).
+       * They are displayed in the help output under "Env:" section.
+       *
+       * @example
+       * ```ts
+       * $command({
+       *   env: t.object({
+       *     VERCEL_TOKEN: t.text({ description: "Vercel API token" }),
+       *     VERCEL_ORG_ID: t.optional(t.text({ description: "Organization ID" })),
+       *   }),
+       *   handler: async ({ env }) => {
+       *     // env.VERCEL_TOKEN is typed & guaranteed to exist
+       *     console.log(env.VERCEL_TOKEN);
+       *   }
+       * })
+       * ```
+       */
   env?: E;
   /**
-   * An optional TypeBox schema defining the arguments for the command.
-   *
-   * @example
-   * args: t.text()
-   * my-cli command <arg1: string>
-   *
-   * args: t.optional(t.text())
-   * my-cli command [arg1: string]
-   *
-   * args: t.tuple([t.text(), t.number()])
-   * my-cli command <arg1: string> <arg2: number>
-   *
-   * args: t.tuple([t.text(), t.optional(t.number())])
-   * my-cli command <arg1: string> [arg2: number]
-   */
+       * An optional TypeBox schema defining the arguments for the command.
+       *
+       * @example
+       * args: t.text()
+       * my-cli command <arg1: string>
+       *
+       * args: t.optional(t.text())
+       * my-cli command [arg1: string]
+       *
+       * args: t.tuple([t.text(), t.number()])
+       * my-cli command <arg1: string> <arg2: number>
+       *
+       * args: t.tuple([t.text(), t.optional(t.number())])
+       * my-cli command <arg1: string> [arg2: number]
+       */
   args?: A;
   /**
-   * If false, skip summary message at the end of the command execution.
-   * Summary will display only if ({ run }) method calls were made.
-   */
-  summary?: boolean;
-  /**
-   * Marks this command as the root command.
-   * Equivalent to setting name to an empty string "".
-   */
+       * Marks this command as the root command.
+       * Equivalent to setting name to an empty string "".
+       */
   root?: boolean;
   /**
-   * Run this command's handler BEFORE the specified target command.
-   *
-   * Pre-hooks are not listed in help and cannot be called directly.
-   * They receive the same parsed flags and args as the target command.
-   *
-   * @example
-   * ```ts
-   * class BuildCommands {
-   *   prebuild = $command({
-   *     pre: "build",
-   *     handler: async ({ run }) => {
-   *       await run("cleaning dist folder...", () => fs.rm("dist"));
-   *     }
-   *   });
-   *
-   *   build = $command({
-   *     name: "build",
-   *     handler: async () => { ... }
-   *   });
-   * }
-   * ```
-   */
+       * Run this command's handler BEFORE the specified target command.
+       *
+       * Pre-hooks are not listed in help and cannot be called directly.
+       * They receive the same parsed flags and args as the target command.
+       *
+       * @example
+       * ```ts
+       * class BuildCommands {
+       *   prebuild = $command({
+       *     pre: "build",
+       *     handler: async ({ run }) => {
+       *       await run("cleaning dist folder...", () => fs.rm("dist"));
+       *     }
+       *   });
+       *
+       *   build = $command({
+       *     name: "build",
+       *     handler: async () => { ... }
+       *   });
+       * }
+       * ```
+       */
   pre?: string;
   /**
-   * Run this command's handler AFTER the specified target command.
-   *
-   * Post-hooks are not listed in help and cannot be called directly.
-   * They receive the same parsed flags and args as the target command.
-   *
-   * @example
-   * ```ts
-   * class BuildCommands {
-   *   build = $command({
-   *     name: "build",
-   *     handler: async () => { ... }
-   *   });
-   *
-   *   postbuild = $command({
-   *     post: "build",
-   *     handler: async ({ run }) => {
-   *       await run("generating checksums...", generateChecksums);
-   *     }
-   *   });
-   * }
-   * ```
-   */
+       * Run this command's handler AFTER the specified target command.
+       *
+       * Post-hooks are not listed in help and cannot be called directly.
+       * They receive the same parsed flags and args as the target command.
+       *
+       * @example
+       * ```ts
+       * class BuildCommands {
+       *   build = $command({
+       *     name: "build",
+       *     handler: async () => { ... }
+       *   });
+       *
+       *   postbuild = $command({
+       *     post: "build",
+       *     handler: async ({ run }) => {
+       *       await run("generating checksums...", generateChecksums);
+       *     }
+       *   });
+       * }
+       * ```
+       */
   post?: string;
   /**
-   * If true, this command will be hidden from the help output.
-   */
+       * If true, this command will be hidden from the help output.
+       */
   hide?: boolean;
   /**
-   * Adds a `--mode, -m` flag to load environment files.
-   *
-   * When enabled:
-   * - Loads `.env` and `.env.local` by default
-   * - With `--mode production`, also loads `.env.production` and `.env.production.local`
-   * - The mode value is exposed in the handler as `mode: string | undefined`
-   *
-   * Set to `true` to enable with no default, or a string to set a default mode.
-   *
-   * This follows Vite's environment loading convention.
-   * @see https://vite.dev/guide/env-and-mode
-   *
-   * @example
-   * ```ts
-   * // No default mode
-   * build = $command({
-   *   mode: true,
-   *   handler: async ({ mode }) => {
-   *     console.log(`Building for ${mode ?? 'development'}...`);
-   *   }
-   * });
-   *
-   * // Default mode "production"
-   * deploy = $command({
-   *   mode: "production",
-   *   handler: async ({ mode }) => {
-   *     console.log(`Deploying for ${mode}...`); // always defined
-   *   }
-   * });
-   * ```
-   *
-   * Usage:
-   * - `cli build` - loads .env (mode = undefined)
-   * - `cli build --mode production` - loads .env and .env.production
-   * - `cli deploy` - loads .env and .env.production (default mode)
-   * - `cli deploy --mode staging` - loads .env and .env.staging
-   */
+       * Adds a `--mode, -m` flag to load environment files.
+       *
+       * When enabled:
+       * - Loads `.env` and `.env.local` by default
+       * - With `--mode production`, also loads `.env.production` and `.env.production.local`
+       * - The mode value is exposed in the handler as `mode: string | undefined`
+       *
+       * Set to `true` to enable with no default, or a string to set a default mode.
+       *
+       * This follows Vite's environment loading convention.
+       * @see https://vite.dev/guide/env-and-mode
+       *
+       * @example
+       * ```ts
+       * // No default mode
+       * build = $command({
+       *   mode: true,
+       *   handler: async ({ mode }) => {
+       *     console.log(`Building for ${mode ?? 'development'}...`);
+       *   }
+       * });
+       *
+       * // Default mode "production"
+       * deploy = $command({
+       *   mode: "production",
+       *   handler: async ({ mode }) => {
+       *     console.log(`Deploying for ${mode}...`); // always defined
+       *   }
+       * });
+       * ```
+       *
+       * Usage:
+       * - `cli build` - loads .env (mode = undefined)
+       * - `cli build --mode production` - loads .env and .env.production
+       * - `cli deploy` - loads .env and .env.production (default mode)
+       * - `cli deploy --mode staging` - loads .env and .env.staging
+       */
   mode?: boolean | string;
   /**
-   * Child commands (subcommands) for this command.
-   *
-   * When children are defined, the command becomes a parent command that
-   * can be invoked with space-separated subcommands:
-   *
-   * @example
-   * ```ts
-   * class DeployCommands {
-   *   // Subcommands
-   *   vercel = $command({
-   *     description: "Deploy to Vercel",
-   *     handler: async () => { ... }
-   *   });
-   *
-   *   cloudflare = $command({
-   *     description: "Deploy to Cloudflare",
-   *     handler: async () => { ... }
-   *   });
-   *
-   *   // Parent command with children
-   *   deploy = $command({
-   *     description: "Deploy the application",
-   *     children: [this.vercel, this.cloudflare],
-   *     handler: async () => {
-   *       // Called when "deploy" is invoked without subcommand
-   *       console.log("Available: deploy vercel, deploy cloudflare");
-   *     }
-   *   });
-   * }
-   * ```
-   *
-   * This allows CLI usage like:
-   * - `cli deploy vercel` - runs the vercel subcommand
-   * - `cli deploy cloudflare` - runs the cloudflare subcommand
-   * - `cli deploy` - runs the parent handler (shows available subcommands)
-   * - `cli deploy --help` - shows help with all available subcommands
-   */
+       * Child commands (subcommands) for this command.
+       *
+       * When children are defined, the command becomes a parent command that
+       * can be invoked with space-separated subcommands:
+       *
+       * @example
+       * ```ts
+       * class DeployCommands {
+       *   // Subcommands
+       *   vercel = $command({
+       *     description: "Deploy to Vercel",
+       *     handler: async () => { ... }
+       *   });
+       *
+       *   cloudflare = $command({
+       *     description: "Deploy to Cloudflare",
+       *     handler: async () => { ... }
+       *   });
+       *
+       *   // Parent command with children
+       *   deploy = $command({
+       *     description: "Deploy the application",
+       *     children: [this.vercel, this.cloudflare],
+       *     handler: async () => {
+       *       // Called when "deploy" is invoked without subcommand
+       *       console.log("Available: deploy vercel, deploy cloudflare");
+       *     }
+       *   });
+       * }
+       * ```
+       *
+       * This allows CLI usage like:
+       * - `cli deploy vercel` - runs the vercel subcommand
+       * - `cli deploy cloudflare` - runs the cloudflare subcommand
+       * - `cli deploy` - runs the parent handler (shows available subcommands)
+       * - `cli deploy --help` - shows help with all available subcommands
+       */
   children?: CommandPrimitive<any, any>[];
 }
 declare class CommandPrimitive<T extends TObject = TObject, A extends TSchema = TSchema, E extends TObject = TObject> extends Primitive<CommandPrimitiveOptions<T, A, E>> {
@@ -398,16 +399,16 @@ declare class CommandPrimitive<T extends TObject = TObject, A extends TSchema =
   protected onInit(): void;
   get name(): string;
   /**
-   * Get the child commands (subcommands) for this command.
-   */
+       * Get the child commands (subcommands) for this command.
+       */
   get children(): CommandPrimitive<any, any>[];
   /**
-   * Check if this command has child commands (is a parent command).
-   */
+       * Check if this command has child commands (is a parent command).
+       */
   get hasChildren(): boolean;
   /**
-   * Find a child command by name or alias.
-   */
+       * Find a child command by name or alias.
+       */
   findChild(name: string): CommandPrimitive<any, any> | undefined;
 }
 interface CommandHandlerArgs<T extends TObject, A extends TSchema = TSchema, E extends TObject = TObject> {
@@ -419,31 +420,31 @@ interface CommandHandlerArgs<T extends TObject, A extends TSchema = TSchema, E e
   glob: typeof glob;
   fs: typeof fs;
   /**
-   * The root directory where the command is executed.
-   */
+       * The root directory where the command is executed.
+       */
   root: string;
   /**
-   * Display help for the current command.
-   *
-   * Useful for parent commands with children to show available subcommands
-   * when invoked without a specific subcommand.
-   *
-   * @example
-   * ```ts
-   * deploy = $command({
-   *   children: [this.vercel, this.cloudflare],
-   *   handler: async ({ help }) => {
-   *     help(); // Shows available subcommands
-   *   }
-   * });
-   * ```
-   */
+       * Display help for the current command.
+       *
+       * Useful for parent commands with children to show available subcommands
+       * when invoked without a specific subcommand.
+       *
+       * @example
+       * ```ts
+       * deploy = $command({
+       *   children: [this.vercel, this.cloudflare],
+       *   handler: async ({ help }) => {
+       *     help(); // Shows available subcommands
+       *   }
+       * });
+       * ```
+       */
   help: () => void;
   /**
-   * The current execution mode (e.g., "development", "production", "staging").
-   *
-   * Use --mode flag to set this value when running the command.
-   */
+       * The current execution mode (e.g., "development", "production", "staging").
+       *
+       * Use --mode flag to set this value when running the command.
+       */
   mode?: string;
 }
 //#endregion
@@ -532,21 +533,21 @@ declare class CliProvider {
   };
   protected readonly onReady: alepha1.HookPrimitive<"ready">;
   /**
-   * Execute a command with the given argv.
-   */
+       * Execute a command with the given argv.
+       */
   protected executeCommand(command: CommandPrimitive<TObject>, argv: string[], isRootCommand: boolean): Promise<void>;
   /**
-   * Remove consumed command path arguments from argv.
-   */
+       * Remove consumed command path arguments from argv.
+       */
   protected removeConsumedArgs(argv: string[], consumedArgs: string[]): string[];
   /**
-   * Resolve a command from positional arguments.
-   *
-   * Supports:
-   * 1. Space-separated subcommands: `deploy vercel` -> finds deploy command, then vercel child
-   * 2. Colon notation (backwards compat): `deploy:vercel` -> finds command with name "deploy:vercel"
-   * 3. Simple commands: `build` -> finds command with name "build"
-   */
+       * Resolve a command from positional arguments.
+       *
+       * Supports:
+       * 1. Space-separated subcommands: `deploy vercel` -> finds deploy command, then vercel child
+       * 2. Colon notation (backwards compat): `deploy:vercel` -> finds command with name "deploy:vercel"
+       * 3. Simple commands: `build` -> finds command with name "build"
+       */
   protected resolveCommand(positionalArgs: string[]): {
     command: CommandPrimitive<TObject> | undefined;
     consumedArgs: string[];
@@ -554,16 +555,16 @@ declare class CliProvider {
   get commands(): CommandPrimitive<any>[];
   protected findCommand(name: string): CommandPrimitive<TObject> | undefined;
   /**
-   * Find all pre-hooks for a command.
-   */
+       * Find all pre-hooks for a command.
+       */
   protected findPreHooks(commandName: string): CommandPrimitive<TObject>[];
   /**
-   * Find all post-hooks for a command.
-   */
+       * Find all post-hooks for a command.
+       */
   protected findPostHooks(commandName: string): CommandPrimitive<TObject>[];
   /**
-   * Get global flags (help only, root command flags are NOT global).
-   */
+       * Get global flags (help only, root command flags are NOT global).
+       */
   protected getAllGlobalFlags(): Record<string, {
     aliases: string[];
     description?: string;
@@ -572,12 +573,12 @@ declare class CliProvider {
   protected parseCommandFlags(argv: string[], schema: TObject): Record<string, any>;
   protected parseCommandEnv(schema: TObject, commandName: string): Record<string, any>;
   /**
-   * Parse --mode or -m flag from argv.
-   */
+       * Parse --mode or -m flag from argv.
+       */
   protected parseModeFlag(argv: string[]): string | undefined;
   /**
-   * Load environment files based on mode.
-   */
+       * Load environment files based on mode.
+       */
   protected loadModeEnv(root: string, mode: string | undefined): Promise<void>;
   protected parseFlags(argv: string[], flagDefs: {
     key: string;
@@ -585,8 +586,8 @@ declare class CliProvider {
     schema: TSchema;
   }[]): Record<string, any>;
   /**
-   * Get indices of argv elements that are consumed by flags (including space-separated values).
-   */
+       * Get indices of argv elements that are consumed by flags (including space-separated values).
+       */
   protected getFlagConsumedIndices(argv: string[], flagDefs: {
     key: string;
     aliases: string[];
@@ -598,24 +599,24 @@ declare class CliProvider {
   protected getTypeName(schema: TSchema): string;
   printHelp(command?: CommandPrimitive<any>): void;
   /**
-   * Generate colored args usage string for help display.
-   */
+       * Generate colored args usage string for help display.
+       */
   protected generateColoredArgsUsage(schema?: TSchema): string;
   /**
-   * Get the full command path (e.g., "deploy vercel" for a child command).
-   */
+       * Get the full command path (e.g., "deploy vercel" for a child command).
+       */
   protected getCommandPath(command: CommandPrimitive<any>): string;
   /**
-   * Find the parent command of a given command.
-   */
+       * Find the parent command of a given command.
+       */
   protected findParentCommand(command: CommandPrimitive<any>): CommandPrimitive<any> | undefined;
   /**
-   * Get top-level commands (commands that are not children of other commands).
-   */
+       * Get top-level commands (commands that are not children of other commands).
+       */
   protected getTopLevelCommands(): CommandPrimitive<any>[];
   /**
-   * Get max length for child command display.
-   */
+       * Get max length for child command display.
+       */
   protected getMaxChildCmdLength(children: CommandPrimitive<any>[]): number;
   protected getMaxCmdLength(commands: CommandPrimitive[]): number;
   private getMaxFlagLength;
@@ -635,15 +636,13 @@ declare const AlephaCommand: alepha1.Service<alepha1.Module>;
 declare module "typebox" {
   interface StringOptions {
     /**
-     * Additional aliases for the flags.
-     *
-     * @module alepha.command
-     */
+             * Additional aliases for the flags.
+             *
+             * @module alepha.command
+             */
     aliases?: string[];
   }
-}
-//# sourceMappingURL=index.d.ts.map
-
+} //# sourceMappingURL=index.d.ts.map
 //#endregion
 export { $command, AlephaCommand, AskMethod, AskOptions, Asker, CliProvider, CliProviderOptions, CommandError, CommandHandlerArgs, CommandPrimitive, CommandPrimitiveOptions, EnvUtils, PrettyPrint, RunOptions, Runner, RunnerMethod, Task, cliOptions };
 //# sourceMappingURL=index.d.ts.map