alepha 0.15.0 → 0.15.2

package/dist/command/index.d.ts

@@ -1,10 +1,11 @@
 import * as alepha1 from "alepha";
-import { Alepha, AlephaError, Async, KIND, Primitive, Static, TObject, TSchema, TString } from "alepha";
+import { Alepha, AlephaError, Async, Json, KIND, Primitive, Static, TObject, TSchema, TString } from "alepha";
 import * as node_readline_promises0 from "node:readline/promises";
 import * as alepha_logger0 from "alepha/logger";
 import * as fs from "node:fs/promises";
 import { glob } from "node:fs/promises";
 import { DateTimeProvider, Interval } from "alepha/datetime";
+import { Readable } from "node:stream";
 
 //#region ../../src/command/errors/CommandError.d.ts
 declare class CommandError extends AlephaError {
@@ -14,28 +15,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 +57,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,43 +86,110 @@ 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
+//#region ../../src/system/providers/ShellProvider.d.ts
+interface ShellRunOptions {
+  /**
+   * Working directory for the command.
+   */
+  root?: string;
+  /**
+   * Additional environment variables.
+   */
+  env?: Record<string, string>;
+  /**
+   * Resolve the executable from node_modules/.bin.
+   * Supports local project, pnpm nested, and monorepo structures.
+   * @default false
+   */
+  resolve?: boolean;
+  /**
+   * Capture stdout instead of inheriting stdio.
+   * When true, returns stdout as string.
+   * When false, streams output to terminal.
+   * @default false
+   */
+  capture?: boolean;
+}
+/**
+ * Abstract provider for executing shell commands and binaries.
+ *
+ * Implementations:
+ * - `NodeShellProvider` - Real shell execution using Node.js child_process
+ * - `MemoryShellProvider` - In-memory mock for testing
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   protected readonly shell = $inject(ShellProvider);
+ *
+ *   async build() {
+ *     // Run shell command directly
+ *     await this.shell.run("yarn install");
+ *
+ *     // Run local binary with resolution
+ *     await this.shell.run("vite build", { resolve: true });
+ *
+ *     // Capture output
+ *     const output = await this.shell.run("echo hello", { capture: true });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ShellProvider {
+  /**
+   * Run a shell command or binary.
+   *
+   * @param command - The command to run
+   * @param options - Execution options
+   * @returns stdout if capture is true, empty string otherwise
+   */
+  abstract run(command: string, options?: ShellRunOptions): Promise<string>;
+  /**
+   * Check if a command is installed and available in the system PATH.
+   *
+   * @param command - The command name to check
+   * @returns true if the command is available
+   */
+  abstract isInstalled(command: string): Promise<boolean>;
+}
+//#endregion
 //#region ../../src/command/helpers/Runner.d.ts
 type Task = {
   name: string;
@@ -133,12 +201,12 @@ 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 directory to execute the command in.
+   */
   root?: string;
 }
 interface RunnerMethod {
@@ -152,6 +220,7 @@ declare class Runner {
   protected readonly startTime: number;
   protected readonly prettyPrint: PrettyPrint;
   protected readonly alepha: Alepha;
+  protected readonly shell: ShellProvider;
   readonly run: RunnerMethod;
   protected cliName: string;
   protected commandName: string;
@@ -159,22 +228,22 @@ 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, opts?: {
     root?: string;
   }): Promise<string>;
   /**
-       * Executes one or more tasks.
-       *
-       * @param task - A single task or an array of tasks to run in parallel.
-       */
+   * 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.
-       */
+   * Prints a summary of all executed tasks and their durations.
+   */
   end(): void;
   protected executeTask(task: Task): Promise<string>;
   protected renderTable(data: string[][]): void;
@@ -193,203 +262,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;
   /**
-       * 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>> {
@@ -399,16 +468,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> {
@@ -420,31 +489,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
@@ -505,6 +574,32 @@ declare module "alepha" {
     [cliOptions.key]: CliProviderOptions;
   }
 }
+/**
+ * CLI provider for parsing and executing commands.
+ *
+ * Handles:
+ * - Command resolution (simple, nested, colon-notation)
+ * - Flag and argument parsing
+ * - Environment variable validation
+ * - Help generation
+ * - Pre/post command hooks
+ *
+ * @example
+ * ```typescript
+ * // Define a command
+ * class MyCommands {
+ *   build = $command({
+ *     name: "build",
+ *     description: "Build the project",
+ *     flags: t.object({ watch: t.optional(t.boolean()) }),
+ *     handler: async ({ flags }) => { ... }
+ *   });
+ * }
+ *
+ * // CLI automatically discovers and executes commands
+ * const alepha = Alepha.create().with(MyCommands);
+ * ```
+ */
 declare class CliProvider {
   protected readonly env: {
     CLI_NAME: string;
@@ -524,6 +619,9 @@ declare class CliProvider {
   protected get name(): string;
   protected get description(): string;
   protected get argv(): string[];
+  /**
+   * Global flags available to all commands.
+   */
   protected readonly globalFlags: {
     help: {
       aliases: string[];
@@ -531,115 +629,165 @@ declare class CliProvider {
       schema: alepha1.TBoolean;
     };
   };
+  /**
+   * Main entry point - resolves and executes the command from process.argv.
+   * This is the production execution path with full lifecycle support.
+   */
   protected readonly onReady: alepha1.HookPrimitive<"ready">;
   /**
-       * Execute a command with the given argv.
-       */
+   * Execute a command with full lifecycle support.
+   *
+   * This is the production execution path that includes:
+   * - Mode-based .env file loading
+   * - Pre/post command hooks
+   * - Runner session for pretty CLI output
+   * - Alepha context wrapper for proper scoping
+   *
+   * @see run() for a lightweight test-only alternative
+   */
   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 (keeps flags and remaining args).
+   */
   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[];
   };
+  /**
+   * Get all registered commands in the application.
+   */
   get commands(): CommandPrimitive<any>[];
-  protected findCommand(name: string): CommandPrimitive<TObject> | undefined;
   /**
-       * Find all pre-hooks for a command.
-       */
+   * Execute a command handler with given arguments.
+   *
+   * This is a **lightweight test helper** that directly invokes the command handler
+   * without the full production lifecycle. It intentionally skips:
+   * - Pre/post command hooks
+   * - Runner session (pretty CLI output)
+   * - Alepha context wrapper
+   * - .env.{mode} file loading
+   *
+   * For production execution, the `onReady` hook uses `executeCommand()` which
+   * provides the full lifecycle. Merging them would either make this method too
+   * heavy for simple testing or require many optional parameters to toggle behaviors.
+   *
+   * @example
+   * ```typescript
+   * // In tests
+   * const cli = alepha.inject(CliProvider);
+   * const cmd = alepha.inject(InitCommand);
+   *
+   * await cli.run(cmd.init, "--agent --pm=yarn");
+   * await cli.run(cmd.init, { argv: "--agent", root: "/project" });
+   * ```
+   */
+  run<T extends TObject, A extends TSchema>(command: CommandPrimitive<T, A>, options?: string | string[] | {
+    argv?: string | string[];
+    root?: string;
+  }): Promise<void>;
+  /** Find a command by name or alias */
+  protected findCommand(name: string): CommandPrimitive<TObject> | undefined;
+  /** Find all pre-hooks for a command (commands named `pre{commandName}`) */
   protected findPreHooks(commandName: string): CommandPrimitive<TObject>[];
-  /**
-       * Find all post-hooks for a command.
-       */
+  /** Find all post-hooks for a command (commands named `post{commandName}`) */
   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;
     schema: TSchema;
   }>;
-  protected parseCommandFlags(argv: string[], schema: TObject): Record<string, any>;
+  /** Parse command flags from argv using the command's flag schema */
+  protected parseCommandFlags(argv: string[], schema: TObject, options?: {
+    modeEnabled?: boolean;
+  }): Record<string, any>;
+  /** Parse and validate environment variables using the command's env schema */
   protected parseCommandEnv(schema: TObject, commandName: string): Record<string, any>;
-  /**
-       * Parse --mode or -m flag from argv.
-       */
+  /** Parse --mode or -m flag from argv for environment file loading */
   protected parseModeFlag(argv: string[]): string | undefined;
-  /**
-       * Load environment files based on mode.
-       */
+  /** Load .env and .env.{mode} files into process.env */
   protected loadModeEnv(root: string, mode: string | undefined): Promise<void>;
+  /** Low-level flag parser - extracts flag values from argv based on definitions */
   protected parseFlags(argv: string[], flagDefs: {
     key: string;
     aliases: string[];
     schema: TSchema;
-  }[]): Record<string, any>;
-  /**
-       * Get indices of argv elements that are consumed by flags (including space-separated values).
-       */
+  }[], options?: {
+    strict?: boolean;
+  }): Record<string, any>;
+  /** Get indices of argv elements consumed by flags (for separating args from flags) */
   protected getFlagConsumedIndices(argv: string[], flagDefs: {
     key: string;
     aliases: string[];
     schema: TSchema;
   }[]): Set<number>;
   protected parseCommandArgs(argv: string[], schema?: TSchema, isRootCommand?: boolean, flagSchema?: TObject): any;
+  /** Convert a string argument value to the appropriate type based on schema */
   protected parseArgumentValue(value: string, schema: TSchema): any;
+  /** Generate usage string for command arguments (e.g., "<path>" or "[path]") */
   protected generateArgsUsage(schema?: TSchema): string;
+  /** Get display type name for a schema (e.g., ": number", ": boolean") */
   protected getTypeName(schema: TSchema): string;
-  printHelp(command?: CommandPrimitive<any>): void;
   /**
-       * Generate colored args usage string for help display.
-       */
+   * Print help for a specific command or general CLI help.
+   *
+   * @param command - If provided, shows help for this specific command.
+   *                  If omitted, shows general CLI help with all commands.
+   */
+  printHelp(command?: CommandPrimitive<any>): void;
+  /** Generate colored usage string for command arguments (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 nested command) */
   protected getCommandPath(command: CommandPrimitive<any>): string;
-  /**
-       * Find the parent command of a given command.
-       */
+  /** Find the parent command of a nested 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.
-       */
+  /** Calculate max display length for child commands (for help alignment) */
   protected getMaxChildCmdLength(children: CommandPrimitive<any>[]): number;
+  /** Calculate max display length for commands (for help alignment) */
   protected getMaxCmdLength(commands: CommandPrimitive[]): number;
-  private getMaxFlagLength;
+  /** Calculate max display length for flags (for help alignment) */
+  protected getMaxFlagLength(flags: {
+    aliases: string[];
+  }[]): number;
 }
 //#endregion
 //#region ../../src/command/index.d.ts
 /**
- * This module provides a powerful way to build command-line interfaces
- * directly within your Alepha application, using declarative primitives.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | tooling | rare | stable |
+ *
+ * Declarative CLI command framework.
  *
- * It allows you to define commands using the `$command` primitive.
+ * **Features:**
+ * - CLI command definitions
+ * - Interactive CLI prompts
+ * - Command execution
+ * - Formatted colored output
+ * - Environment variable utilities
+ * - Schema validation for CLI arguments
  *
- * @see {@link $command}
  * @module alepha.command
  */
 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