@optique/discover 1.2.0-dev.2254 → 1.2.0-dev.2259

package/dist/command-egqHCvDL.d.ts

@@ -0,0 +1,285 @@
+import { CommandOptions } from "@optique/core/primitives";
+import { Mode, Parser } from "@optique/core/parser";
+
+//#region src/command.d.ts
+declare const commandBrand: unique symbol;
+/**
+ * Metadata shown for a discovered command.
+ *
+ * This uses the same shape as Optique's `command()` options so discovered
+ * commands can provide descriptions, usage overrides, visibility, and custom
+ * command-level errors.
+ *
+ * @since 1.1.0
+ */
+type CommandMetadata = CommandOptions;
+/**
+ * Command path used by static command registration.
+ *
+ * An empty path represents the root command.
+ *
+ * @since 1.1.0
+ */
+type CommandPath = readonly string[];
+/**
+ * Resource bundle threaded through {@link ProgramHooks} for a single command
+ * run.
+ *
+ * A {@link ProgramHooks.beforeEach} hook returns this object; the dispatcher
+ * forwards it to the command handler's second parameter and to the matching
+ * {@link ProgramHooks.afterEach} and {@link ProgramHooks.onError} hooks.  This
+ * threads handler-time resources without global state.
+ *
+ * @since 1.2.0
+ */
+interface ProgramHookContext {
+  /**
+   * Caller-defined resource.  Common shapes include a database pool, a logger
+   * scope, or a tracing span.
+   */
+  readonly resource?: unknown;
+}
+/**
+ * The parsed command selected by a discovered command parser.
+ *
+ * Most applications receive this only indirectly through `runProgram()`, which
+ * calls the handler automatically.
+ *
+ * @since 1.1.0
+ */
+interface ProgramInvocation {
+  /**
+   * The command definition that matched the input.
+   */
+  readonly command: AnyCommand;
+  /**
+   * The resolved command path that matched the input.
+   *
+   * Unlike {@link CommandDefinition.path}, this is always populated: for
+   * file-based discovery it is the path derived from the module's location even
+   * when the command definition omits an explicit `path`.  The root command
+   * uses an empty array.  Lifecycle hooks can use this to identify which
+   * command is running.
+   */
+  readonly path: CommandPath;
+  /**
+   * Parsed value produced by the command parser.
+   */
+  readonly value: unknown;
+  /**
+   * Handler to call with {@link ProgramInvocation.value} and, when a
+   * {@link ProgramHooks} `beforeEach` produced one, a {@link ProgramHookContext}.
+   *
+   * The context is optional: `runProgram()` supplies it only when a program-level
+   * or command-level `beforeEach` ran, and callers that dispatch invocations
+   * directly can keep passing only the value.
+   */
+  readonly handler: (value: unknown, context?: ProgramHookContext) => void | Promise<void>;
+}
+/**
+ * Lifecycle hooks invoked around a command handler.
+ *
+ * Hooks let cross-cutting concerns — log scopes, tracing spans, lazy resource
+ * setup, structured timing, error reporting — live in a single place instead
+ * of being duplicated inside every command handler.  Pass them to
+ * `runProgram({ hooks })` to wrap every command, or to
+ * {@link CommandDefinition.hooks} to wrap a single command.
+ *
+ * When both program-level and command-level hooks are present, they nest:
+ *
+ * ```
+ * program.beforeEach → command.beforeEach → handler
+ *                                             ↓
+ * program.afterEach  ← command.afterEach  ←─┘
+ * program.onError    ← command.onError    ← on failure
+ * ```
+ *
+ * @since 1.2.0
+ */
+interface ProgramHooks {
+  /**
+   * Called before the command handler runs, receiving the matched command, its
+   * resolved {@link ProgramInvocation.path}, the parsed value, and the handler
+   * via {@link ProgramInvocation}.
+   *
+   * The returned {@link ProgramHookContext} is threaded forward as the second
+   * argument to the command handler (when this is the most specific hook scope)
+   * and to {@link afterEach} and {@link onError}.  Returning a context is
+   * optional: omit the return or return `null`, and an empty context is
+   * threaded forward instead.
+   *
+   * Returning a promise is supported; the dispatcher awaits it.  A rejected
+   * promise (or a thrown error) aborts the command before the handler runs and
+   * invokes {@link onError}.
+   */
+  readonly beforeEach?: (invocation: ProgramInvocation) => ProgramHookContext | null | void | Promise<ProgramHookContext | null | void>;
+  /**
+   * Called after the handler returns successfully, receiving the context from
+   * {@link beforeEach} (or an empty object when no `beforeEach` ran) and the
+   * handler's return value.
+   *
+   * Returning a promise is supported; the dispatcher awaits it.  If this hook
+   * throws or rejects, the dispatcher treats it as a handler failure and
+   * invokes {@link onError} with the thrown error.
+   */
+  readonly afterEach?: (context: ProgramHookContext, result: unknown) => void | Promise<void>;
+  /**
+   * Called when the handler (or {@link beforeEach}/{@link afterEach}) throws or
+   * rejects, receiving the context from {@link beforeEach} (or an empty object)
+   * and the thrown error.
+   *
+   * The dispatcher re-throws the original error after this hook resolves, so
+   * process exit-code behavior is unchanged; the hook is for observation and
+   * cleanup, not for swallowing the error.  An error thrown by this hook itself
+   * is suppressed so it cannot mask the original failure.
+   *
+   * Returning a promise is supported; the dispatcher awaits it.
+   */
+  readonly onError?: (context: ProgramHookContext, error: unknown) => void | Promise<void>;
+}
+/**
+ * Input accepted by {@link defineCommand}.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @since 1.1.0
+ */
+interface CommandDefinition<M extends Mode, T> {
+  /**
+   * Command path used when commands are passed directly to `runProgram()`.
+   * Use an empty path (`[]`) to register the root command.
+   *
+   * File-based discovery derives the command path from the file name and uses
+   * this field only to validate that the declared path matches.
+   */
+  readonly path?: CommandPath;
+  /**
+   * Parser for this command's command-specific arguments and options.
+   */
+  readonly parser: Parser<M, T, unknown>;
+  /**
+   * Metadata used in help output and shell completion.
+   */
+  readonly metadata?: CommandMetadata;
+  /**
+   * Lifecycle hooks scoped to this command.
+   *
+   * These run inside any program-level hooks passed to `runProgram({ hooks })`:
+   * the program-level `beforeEach` runs first, then this command's
+   * `beforeEach`, then the handler; teardown unwinds in reverse.  Use this when
+   * a single command needs its own preflight, such as a `deploy` command that
+   * always refreshes an auth token, instead of program-wide logic.
+   *
+   * @since 1.2.0
+   */
+  readonly hooks?: ProgramHooks;
+  /**
+   * Handles the parsed command value.
+   *
+   * @param value Parsed command value.
+   * @param context Resource bundle from the most specific {@link ProgramHooks}
+   *                `beforeEach` that ran.  It is omitted when no program-level
+   *                or command-level `beforeEach` ran, so a plain command
+   *                without hooks receives only the value, exactly as before.
+   *                Existing single-argument handlers can ignore it.
+   * @returns Nothing, or a promise that resolves when command handling
+   *          completes.
+   */
+  readonly handler: (value: T, context?: ProgramHookContext) => void | Promise<void>;
+}
+/**
+ * A discovered command module definition.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @since 1.1.0
+ */
+interface Command<M extends Mode, T> extends CommandDefinition<M, T> {
+  /**
+   * Internal marker used to validate discovered modules.
+   *
+   * @internal
+   */
+  readonly [commandBrand]: true;
+}
+/**
+ * A command that declares its own command path.
+ *
+ * Static `runProgram({ commands })` registration accepts this shape.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @since 1.1.0
+ */
+interface StaticCommand<M extends Mode, T> extends Command<M, T> {
+  /**
+   * Command path used by static command registration.
+   */
+  readonly path: CommandPath;
+}
+/**
+ * A command with its handler value type erased.
+ *
+ * This type is used by discovery APIs that collect commands with different
+ * parsed value types.  The handler cannot be called directly without first
+ * recovering the parser's value type.
+ *
+ * @since 1.1.0
+ */
+type AnyCommand = Omit<Command<Mode, unknown>, "handler"> & {
+  /**
+   * Erased command handler.
+   */
+  readonly handler: (value: never, context?: ProgramHookContext) => void | Promise<void>;
+};
+/**
+ * A statically registered command with its handler value type erased.
+ *
+ * @since 1.1.0
+ */
+type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler"> & {
+  /**
+   * Erased command handler.
+   */
+  readonly handler: (value: never, context?: ProgramHookContext) => void | Promise<void>;
+};
+/**
+ * Defines a command module for `@optique/discover`.
+ *
+ * This helper returns its argument unchanged while preserving parser value
+ * inference for the handler callback.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @param command The command definition.
+ * @returns The same command definition with inferred types.
+ * @throws {TypeError} If the parser, path, handler, or hooks are missing or
+ *         malformed.
+ * @since 1.1.0
+ */
+declare function defineCommand<M extends Mode, T>(command: CommandDefinition<M, T> & {
+  readonly path: CommandPath;
+}): StaticCommand<M, T>;
+declare function defineCommand<M extends Mode, T>(command: CommandDefinition<M, T>): Command<M, T>;
+/**
+ * Returns whether a value is a command created by {@link defineCommand}.
+ *
+ * @param value The value to inspect.
+ * @returns `true` when the value is a discovered command definition.
+ * @since 1.1.0
+ */
+declare function isCommand(value: unknown): value is AnyCommand;
+/**
+ * Validates a {@link ProgramHooks} value, throwing a descriptive error when it
+ * is malformed.
+ *
+ * @param hooks The value to validate.
+ * @param scope Label used in error messages: `"Command"` for command-level
+ *              hooks and `"Program"` for program-level hooks.
+ * @throws {TypeError} If `hooks` is not an object, or a hook is neither
+ *         nullish nor a function.
+ * @internal
+ */
+declare function validateHooks(hooks: unknown, scope: "Command" | "Program"): asserts hooks is ProgramHooks;
+//#endregion
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand, validateHooks };

package/dist/command.cjs

@@ -1,4 +1,5 @@
-const require_command = require('./command-CUn2_NIA.cjs');
+const require_command = require('./command-C-NgG0KJ.cjs');
 
 exports.defineCommand = require_command.defineCommand;
-exports.isCommand = require_command.isCommand;
+exports.isCommand = require_command.isCommand;
+exports.validateHooks = require_command.validateHooks;

package/dist/command.d.cts

@@ -1,2 +1,2 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DSHBTa5c.cjs";
-export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand, validateHooks } from "./command-Dvg452tU.cjs";
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand, validateHooks };

package/dist/command.d.ts

@@ -1,2 +1,2 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DrmNW0HO.js";
-export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand, validateHooks } from "./command-egqHCvDL.js";
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand, validateHooks };

package/dist/command.js

@@ -1,3 +1,3 @@
-import { defineCommand, isCommand } from "./command-DO5zgkvS.js";
+import { defineCommand, isCommand, validateHooks } from "./command-9sgrJtwh.js";
 
-export { defineCommand, isCommand };
+export { defineCommand, isCommand, validateHooks };

package/dist/{generator-B81thoIS.js → generator-B8UY7n7b.js}

@@ -1,4 +1,4 @@
-import { getDefaultExtensions } from "./src-kBDpUW2H.js";
+import { getDefaultExtensions } from "./src-wHLRsXWK.js";
 import { mkdir, readdir, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, posix, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/{generator-BV1QDOot.cjs → generator-CkGpilfc.cjs}

@@ -1,5 +1,5 @@
 const require_chunk = require('./chunk-CUT6urMc.cjs');
-const require_src = require('./src-BDObn4mj.cjs');
+const require_src = require('./src-C3_a7SFM.cjs');
 const node_fs_promises = require_chunk.__toESM(require("node:fs/promises"));
 const node_path = require_chunk.__toESM(require("node:path"));
 const node_url = require_chunk.__toESM(require("node:url"));

package/dist/generator.cjs

@@ -1,6 +1,6 @@
-require('./command-CUn2_NIA.cjs');
-require('./src-BDObn4mj.cjs');
-const require_generator = require('./generator-BV1QDOot.cjs');
+require('./command-C-NgG0KJ.cjs');
+require('./src-C3_a7SFM.cjs');
+const require_generator = require('./generator-CkGpilfc.cjs');
 
 exports.generateCommandsModule = require_generator.generateCommandsModule;
 exports.watchCommandsModule = require_generator.watchCommandsModule;

package/dist/generator.js

@@ -1,5 +1,5 @@
-import "./command-DO5zgkvS.js";
-import "./src-kBDpUW2H.js";
-import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-B81thoIS.js";
+import "./command-9sgrJtwh.js";
+import "./src-wHLRsXWK.js";
+import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-B8UY7n7b.js";
 
 export { generateCommandsModule, watchCommandsModule, writeCommandsModule };

package/dist/index.cjs

@@ -1,5 +1,5 @@
-const require_command = require('./command-CUn2_NIA.cjs');
-const require_src = require('./src-BDObn4mj.cjs');
+const require_command = require('./command-C-NgG0KJ.cjs');
+const require_src = require('./src-C3_a7SFM.cjs');
 
 exports.commandsFromModules = require_src.commandsFromModules;
 exports.createProgramParser = require_src.createProgramParser;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DSHBTa5c.cjs";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand } from "./command-Dvg452tU.cjs";
 import { Mode } from "@optique/core/parser";
 import { FluentParser } from "@optique/core/fluent";
 import { Message } from "@optique/core/message";
@@ -7,28 +7,6 @@ import { RunOptions } from "@optique/run";
 
 //#region src/index.d.ts
 
-/**
- * The parsed command selected by a discovered command parser.
- *
- * Most applications receive this only indirectly through {@link runProgram},
- * which calls the handler automatically.
- *
- * @since 1.1.0
- */
-interface ProgramInvocation {
-  /**
-   * The command definition that matched the input.
-   */
-  readonly command: AnyCommand;
-  /**
-   * Parsed value produced by the command parser.
-   */
-  readonly value: unknown;
-  /**
-   * Handler to call with {@link ProgramInvocation.value}.
-   */
-  readonly handler: (value: unknown) => void | Promise<void>;
-}
 /**
  * A command paired with its command path.
  *
@@ -198,6 +176,18 @@ interface RunProgramBaseOptions extends Omit<RunOptions, "help" | "version" | "c
    * @default `"both"`
    */
   readonly completion?: RunOptions["completion"] | false;
+  /**
+   * Lifecycle hooks invoked around each command handler.
+   *
+   * Use these for cross-cutting concerns such as opening a log scope, starting
+   * a tracing span, or reporting handler failures, without duplicating the
+   * logic in every command.  Hooks are opt-in: omitting this field keeps the
+   * exact behavior of a plain `runProgram()` call.  Command-level hooks defined
+   * on {@link CommandDefinition.hooks} nest inside these.
+   *
+   * @since 1.2.0
+   */
+  readonly hooks?: ProgramHooks;
 }
 /**
  * Options for {@link runProgram} when discovering commands from files.
@@ -311,7 +301,8 @@ declare function createProgramParser(commands: readonly CommandEntry[], metadata
  * @param options Program options.
  * @returns A promise that resolves after the selected command handler
  *          completes.
- * @throws {TypeError} If discovery or command loading fails.
+ * @throws {TypeError} If discovery or command loading fails, or `hooks` is
+ *         malformed.
  * @since 1.1.0
  */
 declare function runProgram(options: RunProgramOptions): Promise<void>;
@@ -335,4 +326,4 @@ interface ProgramHelpMetadata {
   readonly footer?: Message;
 }
 //#endregion
-export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DrmNW0HO.js";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand } from "./command-egqHCvDL.js";
 import { Message } from "@optique/core/message";
 import { ProgramMetadata } from "@optique/core/program";
 import { RunOptions } from "@optique/run";
@@ -7,28 +7,6 @@ import { Mode } from "@optique/core/parser";
 
 //#region src/index.d.ts
 
-/**
- * The parsed command selected by a discovered command parser.
- *
- * Most applications receive this only indirectly through {@link runProgram},
- * which calls the handler automatically.
- *
- * @since 1.1.0
- */
-interface ProgramInvocation {
-  /**
-   * The command definition that matched the input.
-   */
-  readonly command: AnyCommand;
-  /**
-   * Parsed value produced by the command parser.
-   */
-  readonly value: unknown;
-  /**
-   * Handler to call with {@link ProgramInvocation.value}.
-   */
-  readonly handler: (value: unknown) => void | Promise<void>;
-}
 /**
  * A command paired with its command path.
  *
@@ -198,6 +176,18 @@ interface RunProgramBaseOptions extends Omit<RunOptions, "help" | "version" | "c
    * @default `"both"`
    */
   readonly completion?: RunOptions["completion"] | false;
+  /**
+   * Lifecycle hooks invoked around each command handler.
+   *
+   * Use these for cross-cutting concerns such as opening a log scope, starting
+   * a tracing span, or reporting handler failures, without duplicating the
+   * logic in every command.  Hooks are opt-in: omitting this field keeps the
+   * exact behavior of a plain `runProgram()` call.  Command-level hooks defined
+   * on {@link CommandDefinition.hooks} nest inside these.
+   *
+   * @since 1.2.0
+   */
+  readonly hooks?: ProgramHooks;
 }
 /**
  * Options for {@link runProgram} when discovering commands from files.
@@ -311,7 +301,8 @@ declare function createProgramParser(commands: readonly CommandEntry[], metadata
  * @param options Program options.
  * @returns A promise that resolves after the selected command handler
  *          completes.
- * @throws {TypeError} If discovery or command loading fails.
+ * @throws {TypeError} If discovery or command loading fails, or `hooks` is
+ *         malformed.
  * @since 1.1.0
  */
 declare function runProgram(options: RunProgramOptions): Promise<void>;
@@ -335,4 +326,4 @@ interface ProgramHelpMetadata {
   readonly footer?: Message;
 }
 //#endregion
-export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { defineCommand, isCommand } from "./command-DO5zgkvS.js";
-import { commandsFromModules, createProgramParser, discoverCommands, getDefaultExtensions, runProgram } from "./src-kBDpUW2H.js";
+import { defineCommand, isCommand } from "./command-9sgrJtwh.js";
+import { commandsFromModules, createProgramParser, discoverCommands, getDefaultExtensions, runProgram } from "./src-wHLRsXWK.js";
 
 export { commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/{src-BDObn4mj.cjs → src-C3_a7SFM.cjs}

@@ -1,5 +1,5 @@
 const require_chunk = require('./chunk-CUT6urMc.cjs');
-const require_command = require('./command-CUn2_NIA.cjs');
+const require_command = require('./command-C-NgG0KJ.cjs');
 const __optique_core_constructs = require_chunk.__toESM(require("@optique/core/constructs"));
 const __optique_core_modifiers = require_chunk.__toESM(require("@optique/core/modifiers"));
 const __optique_core_primitives = require_chunk.__toESM(require("@optique/core/primitives"));
@@ -146,10 +146,12 @@ function createProgramParser(commands, metadata = {}) {
 * @param options Program options.
 * @returns A promise that resolves after the selected command handler
 *          completes.
-* @throws {TypeError} If discovery or command loading fails.
+* @throws {TypeError} If discovery or command loading fails, or `hooks` is
+*         malformed.
 * @since 1.1.0
 */
 async function runProgram(options) {
+	if (options.hooks != null) require_command.validateHooks(options.hooks, "Program");
 	let commands;
 	if (isStaticRunProgramOptions(options)) commands = staticCommandsToEntries(options.commands);
 	else commands = await discoverCommands({
@@ -159,7 +161,55 @@ async function runProgram(options) {
 	});
 	const parser = createProgramParser(commands, options.metadata);
 	const invocation = await (0, __optique_run.runAsync)(parser, buildRunOptions(options));
-	await invocation.handler(invocation.value);
+	await dispatchInvocation(invocation, options.hooks);
+}
+/**
+* Runs a command handler wrapped in the program-level and command-level
+* lifecycle hooks.
+*
+* The hooks nest: the program-level `beforeEach` runs first, then the command's
+* `beforeEach`, then the handler; `afterEach` and `onError` unwind in reverse,
+* with the command-level hook running before the program-level one.
+*
+* @param invocation The selected command invocation.
+* @param programHooks Program-level hooks, if any.
+* @returns A promise that resolves after the handler and matching hooks
+*          complete.
+* @throws The original error thrown by `beforeEach`, the handler, or
+*         `afterEach`, re-thrown after the `onError` hooks run.
+*/
+async function dispatchInvocation(invocation, programHooks) {
+	const commandHooks = invocation.command.hooks;
+	await runHookScope(programHooks, invocation, (programContext) => runHookScope(commandHooks, invocation, (commandContext) => {
+		if (commandHooks?.beforeEach != null) return invocation.handler(invocation.value, commandContext);
+		if (programHooks?.beforeEach != null) return invocation.handler(invocation.value, programContext);
+		return invocation.handler(invocation.value);
+	}));
+}
+/**
+* Runs an inner step wrapped in a single set of lifecycle hooks.
+*
+* @param hooks The hooks for this scope, if any.
+* @param invocation The selected command invocation passed to `beforeEach`.
+* @param inner The step to wrap; receives the context from `beforeEach`.
+* @returns The value returned by `inner`.
+* @throws The original error thrown by `beforeEach`, `inner`, or `afterEach`,
+*         re-thrown after `onError` runs.  An error thrown by `onError` itself
+*         is suppressed so it cannot mask the original failure.
+*/
+async function runHookScope(hooks, invocation, inner) {
+	let context = {};
+	try {
+		if (hooks?.beforeEach != null) context = await hooks.beforeEach(invocation) ?? {};
+		const result = await inner(context);
+		if (hooks?.afterEach != null) await hooks.afterEach(context, result);
+		return result;
+	} catch (error) {
+		if (hooks?.onError != null) try {
+			await hooks.onError(context, error);
+		} catch {}
+		throw error;
+	}
 }
 function getRuntime() {
 	if ("Deno" in globalThis) return "deno";
@@ -337,18 +387,19 @@ function buildCommandTree(commands) {
 			current = child;
 		}
 		current.command = entry.command;
+		current.path = entry.path;
 	}
 	return root;
 }
 function buildNodeParser(node, inheritedHidden) {
 	const childParser = buildChildrenParser(node, inheritedHidden);
-	if (childParser != null && node.command != null) return createExecutableNodeParser(childParser, node.command);
+	if (childParser != null && node.command != null) return createExecutableNodeParser(childParser, node.command, node.path ?? []);
 	if (childParser != null) return childParser;
-	if (node.command != null) return createLeafParser(node.command);
+	if (node.command != null) return createLeafParser(node.command, node.path ?? []);
 	throw new TypeError("Command tree node must contain a command.");
 }
-function createExecutableNodeParser(childParser, commandDefinition) {
-	const leafParser = createLeafParser(commandDefinition, true);
+function createExecutableNodeParser(childParser, commandDefinition, path) {
+	const leafParser = createLeafParser(commandDefinition, path, true);
 	const branchParsers = [childParser, leafParser];
 	const parser = (0, __optique_core_constructs.longestMatch)(childParser, leafParser);
 	const phase2SeedHook = findPhase2SeedHook(parser);
@@ -387,16 +438,16 @@ function createExecutableNodeParser(childParser, commandDefinition) {
 				state: toExclusiveState(activeState, context.state)
 			}, prefix);
 		},
-		getSuggestRuntimeNodes(state, path) {
+		getSuggestRuntimeNodes(state, path$1) {
 			const activeState = normalizeExecutableNodeState(state);
 			if (activeState == null) {
-				const branchPath$1 = [...path, 1];
+				const branchPath$1 = [...path$1, 1];
 				const branchState$1 = (0, __optique_core_extension.inheritAnnotations)(state, leafParser.initialState);
 				return getExecutableNodeBranchSuggestRuntimeNodes(leafParser, branchState$1, branchPath$1);
 			}
-			if (activeState?.result.success !== true) return parser.getSuggestRuntimeNodes?.(toExclusiveState(activeState, state), path) ?? [];
+			if (activeState?.result.success !== true) return parser.getSuggestRuntimeNodes?.(toExclusiveState(activeState, state), path$1) ?? [];
 			const branchParser = branchParsers[activeState.branch];
-			const branchPath = [...path, activeState.branch];
+			const branchPath = [...path$1, activeState.branch];
 			const branchState = (0, __optique_core_extension.inheritAnnotations)(state, activeState.result.next.state);
 			return getExecutableNodeBranchSuggestRuntimeNodes(branchParser, branchState, branchPath);
 		},
@@ -648,9 +699,10 @@ function commandMetadataWithInheritedHidden(metadata, inheritedHidden) {
 		...hidden != null && { hidden }
 	};
 }
-function createLeafParser(commandDefinition, includeMetadata = false) {
+function createLeafParser(commandDefinition, path, includeMetadata = false) {
 	const parser = (0, __optique_core_modifiers.map)(commandDefinition.parser, (value) => ({
 		command: commandDefinition,
+		path,
 		value,
 		handler: commandDefinition.handler
 	}));
@@ -703,7 +755,7 @@ function commandPathHidden(path, commandsByPath) {
 }
 function buildRunOptions(options) {
 	const metadata = options.metadata;
-	const { dir: _dir, commands: _commands, extensions: _extensions, entryFileName: _entryFileName, metadata: _metadata, help, version, completion,...rest } = options;
+	const { dir: _dir, commands: _commands, extensions: _extensions, entryFileName: _entryFileName, metadata: _metadata, hooks: _hooks, help, version, completion,...rest } = options;
 	const runOptions = {
 		...rest,
 		contexts: unwrapProgramContexts(rest.contexts),