@optique/discover 1.2.0-dev.2252 → 1.2.0-dev.2255

package/dist/command.cjs

@@ -1,4 +1,5 @@
-const require_command = require('./command-CUn2_NIA.cjs');
+const require_command = require('./command-C9u5sJZS.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-DIfnalpt.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-s80EaEXl.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-DSHIV50v.js";
 
-export { defineCommand, isCommand };
+export { defineCommand, isCommand, validateHooks };

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

@@ -1,5 +1,5 @@
 const require_chunk = require('./chunk-CUT6urMc.cjs');
-const require_src = require('./src-BDObn4mj.cjs');
+const require_src = require('./src-CzbbFDmi.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-B81thoIS.js → generator-HNXr5Vz2.js}

@@ -1,4 +1,4 @@
-import { getDefaultExtensions } from "./src-kBDpUW2H.js";
+import { getDefaultExtensions } from "./src-CVATvqru.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.cjs

@@ -1,6 +1,6 @@
-require('./command-CUn2_NIA.cjs');
-require('./src-BDObn4mj.cjs');
-const require_generator = require('./generator-BV1QDOot.cjs');
+require('./command-C9u5sJZS.cjs');
+require('./src-CzbbFDmi.cjs');
+const require_generator = require('./generator-DW4rrPD2.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-DSHIV50v.js";
+import "./src-CVATvqru.js";
+import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-HNXr5Vz2.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-C9u5sJZS.cjs');
+const require_src = require('./src-CzbbFDmi.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-DIfnalpt.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-s80EaEXl.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-DSHIV50v.js";
+import { commandsFromModules, createProgramParser, discoverCommands, getDefaultExtensions, runProgram } from "./src-CVATvqru.js";
 
 export { commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/{src-kBDpUW2H.js → src-CVATvqru.js}

@@ -1,4 +1,4 @@
-import { isCommand } from "./command-DO5zgkvS.js";
+import { isCommand, validateHooks } from "./command-DSHIV50v.js";
 import { longestMatch, or } from "@optique/core/constructs";
 import { map } from "@optique/core/modifiers";
 import { command } from "@optique/core/primitives";
@@ -145,10 +145,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) validateHooks(options.hooks, "Program");
 	let commands;
 	if (isStaticRunProgramOptions(options)) commands = staticCommandsToEntries(options.commands);
 	else commands = await discoverCommands({
@@ -158,7 +160,55 @@ async function runProgram(options) {
 	});
 	const parser = createProgramParser(commands, options.metadata);
 	const invocation = await 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";
@@ -336,18 +386,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 = longestMatch(childParser, leafParser);
 	const phase2SeedHook = findPhase2SeedHook(parser);
@@ -386,16 +437,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 = 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 = inheritAnnotations(state, activeState.result.next.state);
 			return getExecutableNodeBranchSuggestRuntimeNodes(branchParser, branchState, branchPath);
 		},
@@ -647,9 +698,10 @@ function commandMetadataWithInheritedHidden(metadata, inheritedHidden) {
 		...hidden != null && { hidden }
 	};
 }
-function createLeafParser(commandDefinition, includeMetadata = false) {
+function createLeafParser(commandDefinition, path, includeMetadata = false) {
 	const parser = map(commandDefinition.parser, (value) => ({
 		command: commandDefinition,
+		path,
 		value,
 		handler: commandDefinition.handler
 	}));
@@ -702,7 +754,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),

package/dist/{src-BDObn4mj.cjs → src-CzbbFDmi.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-C9u5sJZS.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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/discover",
-  "version": "1.2.0-dev.2252",
+  "version": "1.2.0-dev.2255",
   "description": "Runtime-aware command discovery for Optique CLI programs",
   "keywords": [
     "CLI",
@@ -83,8 +83,8 @@
     "optique-discover": "./dist/cli.js"
   },
   "dependencies": {
-    "@optique/core": "1.2.0-dev.2252+23a526b7",
-    "@optique/run": "1.2.0-dev.2252+23a526b7"
+    "@optique/core": "1.2.0-dev.2255+a902c666",
+    "@optique/run": "1.2.0-dev.2255+a902c666"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",