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

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

@@ -1,4 +1,4 @@
-import { isCommand } from "./command-DO5zgkvS.js";
+import { isCommand, validateHooks } from "./command-9sgrJtwh.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/discover",
-  "version": "1.2.0-dev.2254",
+  "version": "1.2.0-dev.2259",
   "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.2254+22b59099",
-    "@optique/run": "1.2.0-dev.2254+22b59099"
+    "@optique/core": "1.2.0-dev.2259+0b30260e",
+    "@optique/run": "1.2.0-dev.2259+0b30260e"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/dist/command-DSHBTa5c.d.cts

@@ -1,139 +0,0 @@
-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[];
-/**
- * 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;
-  /**
-   * Handles the parsed command value.
-   *
-   * @param value Parsed command value.
-   * @returns Nothing, or a promise that resolves when command handling
-   *          completes.
-   */
-  readonly handler: (value: T) => 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) => 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) => 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, or handler is 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;
-//#endregion
-export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };

package/dist/command-DrmNW0HO.d.ts

@@ -1,139 +0,0 @@
-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[];
-/**
- * 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;
-  /**
-   * Handles the parsed command value.
-   *
-   * @param value Parsed command value.
-   * @returns Nothing, or a promise that resolves when command handling
-   *          completes.
-   */
-  readonly handler: (value: T) => 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) => 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) => 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, or handler is 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;
-//#endregion
-export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };