cli: add pre/post hooks

Author: feunard

packages/alepha/src/command/primitives/$command.ts

@@ -82,6 +82,61 @@ export interface CommandPrimitiveOptions<T extends TObject, A extends TSchema> {
    * 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 () => { ... }
+   *   });
+   * }
+   * ```
+   */
+  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);
+   *     }
+   *   });
+   * }
+   * ```
+   */
+  post?: string;
+
+  /**
+   * If true, this command will be hidden from the help output.
+   */
+  hide?: boolean;
 }
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -93,10 +148,22 @@ export class CommandPrimitive<
   public readonly flags = this.options.flags ?? t.object({});
   public readonly aliases = this.options.aliases ?? [];
 
+  protected onInit() {
+    if (this.options.pre || this.options.post) {
+      this.options.hide ??= true;
+    }
+  }
+
   public get name(): string {
     if (this.options.root) {
       return "";
     }
+    if (this.options.pre) {
+      return `pre${this.options.pre}`;
+    }
+    if (this.options.post) {
+      return `post${this.options.post}`;
+    }
     return this.options.name ?? `${this.config.propertyKey}`;
   }
 }

packages/alepha/src/command/providers/CliProvider.ts

@@ -169,8 +169,23 @@ export class CliProvider {
           root: process.cwd(),
         };
 
+        // Execute pre-hooks
+        const preHooks = this.findPreHooks(command.name);
+        for (const hook of preHooks) {
+          this.log.debug(`Executing pre-hook for '${command.name}'...`);
+          await hook.options.handler(args as CommandHandlerArgs<TObject>);
+        }
+
+        // Execute main command
         await command.options.handler(args as CommandHandlerArgs<TObject>);
 
+        // Execute post-hooks
+        const postHooks = this.findPostHooks(command.name);
+        for (const hook of postHooks) {
+          this.log.debug(`Executing post-hook for '${command.name}'...`);
+          await hook.options.handler(args as CommandHandlerArgs<TObject>);
+        }
+
         if (command.options.summary !== false) {
           runner.summary();
         }
@@ -190,6 +205,20 @@ export class CliProvider {
     );
   }
 
+  /**
+   * Find all pre-hooks for a command.
+   */
+  protected findPreHooks(commandName: string): CommandPrimitive<TObject>[] {
+    return this.commands.filter((cmd) => cmd.name === `pre${commandName}`);
+  }
+
+  /**
+   * Find all post-hooks for a command.
+   */
+  protected findPostHooks(commandName: string): CommandPrimitive<TObject>[] {
+    return this.commands.filter((cmd) => cmd.name === `post${commandName}`);
+  }
+
   /**
    * Get all global flags including those from the root command (name === "")
    */
@@ -464,8 +493,8 @@ export class CliProvider {
       const maxCmdLength = this.getMaxCmdLength(this.commands);
 
       for (const command of this.commands) {
-        // skip root command in list
-        if (command.name === "") {
+        // skip root command and hooks in list
+        if (command.name === "" || command.options.hide) {
           continue;
         }
 
@@ -495,11 +524,13 @@ export class CliProvider {
 
   private getMaxCmdLength(commands: CommandPrimitive[]): number {
     return Math.max(
-      ...commands.map((c) => {
-        const cmdStr = [c.name, ...c.aliases].join(", ");
-        const argsUsage = this.generateArgsUsage(c.options.args);
-        return `${cmdStr}${argsUsage}`.length;
-      }),
+      ...commands
+        .filter((c) => !c.options.hide && c.name !== "")
+        .map((c) => {
+          const cmdStr = [c.name, ...c.aliases].join(", ");
+          const argsUsage = this.generateArgsUsage(c.options.args);
+          return `${cmdStr}${argsUsage}`.length;
+        }),
     );
   }