@optique/discover 1.2.0-dev.2330 → 1.2.0-dev.2333

package/dist/cli.cjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 const require_chunk = require('./chunk-CUT6urMc.cjs');
 require('./command-C-NgG0KJ.cjs');
-require('./src-CPtrcNkd.cjs');
-const require_generator = require('./generator-Dc9I4tTs.cjs');
+require('./src-Bb2ONs5m.cjs');
+const require_generator = require('./generator-4mV9w1F0.cjs');
 const require_main_check = require('./main-check-CwunSNpK.cjs');
 const __optique_core_constructs = require_chunk.__toESM(require("@optique/core/constructs"));
 const __optique_core_message = require_chunk.__toESM(require("@optique/core/message"));
@@ -15,7 +15,7 @@ const node_process = require_chunk.__toESM(require("node:process"));
 
 //#region deno.json
 var name = "@optique/discover";
-var version = "1.2.0-dev.2330+6776ce17";
+var version = "1.2.0-dev.2333+f7f47e8b";
 var license = "MIT";
 var exports$1 = {
 	".": "./src/index.ts",

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import "./command-9sgrJtwh.js";
-import "./src-CCeOMJRj.js";
-import { watchCommandsModule, writeCommandsModule } from "./generator-wZHULCZH.js";
+import "./src-Ddp18zFp.js";
+import { watchCommandsModule, writeCommandsModule } from "./generator-CJiusCJb.js";
 import { isMainModuleUrl } from "./main-check-mMnKfUZs.js";
 import { object } from "@optique/core/constructs";
 import { message } from "@optique/core/message";
@@ -14,7 +14,7 @@ import process from "node:process";
 
 //#region deno.json
 var name = "@optique/discover";
-var version = "1.2.0-dev.2330+6776ce17";
+var version = "1.2.0-dev.2333+f7f47e8b";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",

package/dist/{command-Dvg452tU.d.cts → command-BaFBKA4c.d.ts}

@@ -30,14 +30,15 @@ type CommandPath = readonly string[];
  * {@link ProgramHooks.afterEach} and {@link ProgramHooks.onError} hooks.  This
  * threads handler-time resources without global state.
  *
+ * @template R The caller-defined resource stored in the context.
  * @since 1.2.0
  */
-interface ProgramHookContext {
+interface ProgramHookContext<R = unknown> {
   /**
    * Caller-defined resource.  Common shapes include a database pool, a logger
    * scope, or a tracing span.
    */
-  readonly resource?: unknown;
+  readonly resource?: R;
 }
 /**
  * The parsed command selected by a discovered command parser.
@@ -94,9 +95,10 @@ interface ProgramInvocation {
  * program.onError    ← command.onError    ← on failure
  * ```
  *
+ * @template R The resource returned by `beforeEach` and passed to later hooks.
  * @since 1.2.0
  */
-interface ProgramHooks {
+interface ProgramHooks<R = unknown> {
   /**
    * Called before the command handler runs, receiving the matched command, its
    * resolved {@link ProgramInvocation.path}, the parsed value, and the handler
@@ -112,7 +114,7 @@ interface ProgramHooks {
    * 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>;
+  readonly beforeEach?: (invocation: ProgramInvocation) => ProgramHookContext<R> | null | void | Promise<ProgramHookContext<R> | null | void>;
   /**
    * Called after the handler returns successfully, receiving the context from
    * {@link beforeEach} (or an empty object when no `beforeEach` ran) and the
@@ -122,7 +124,7 @@ interface ProgramHooks {
    * 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>;
+  readonly afterEach?: (context: ProgramHookContext<R>, 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)
@@ -135,16 +137,33 @@ interface ProgramHooks {
    *
    * Returning a promise is supported; the dispatcher awaits it.
    */
-  readonly onError?: (context: ProgramHookContext, error: unknown) => void | Promise<void>;
+  readonly onError?: (context: ProgramHookContext<R>, error: unknown) => void | Promise<void>;
 }
+/**
+ * Lifecycle hooks that always create their own command context.
+ *
+ * @internal
+ */
+type ProgramHooksWithBeforeEach<R> = ProgramHooks<R> & {
+  readonly beforeEach: NonNullable<ProgramHooks<R>["beforeEach"]>;
+};
+/**
+ * Lifecycle hooks that do not replace the program-level command context.
+ *
+ * @internal
+ */
+type ProgramHooksWithoutBeforeEach<R> = Omit<ProgramHooks<R>, "beforeEach"> & {
+  readonly beforeEach?: undefined;
+};
 /**
  * Input accepted by {@link defineCommand}.
  *
  * @template M The mode of the command parser.
  * @template T The parsed value passed to the command handler.
+ * @template R The resource made available to lifecycle hooks and the handler.
  * @since 1.1.0
  */
-interface CommandDefinition<M extends Mode, T> {
+interface CommandDefinition<M extends Mode, T, R = unknown> {
   /**
    * Command path used when commands are passed directly to `runProgram()`.
    * Use an empty path (`[]`) to register the root command.
@@ -172,7 +191,7 @@ interface CommandDefinition<M extends Mode, T> {
    *
    * @since 1.2.0
    */
-  readonly hooks?: ProgramHooks;
+  readonly hooks?: ProgramHooks<R>;
   /**
    * Handles the parsed command value.
    *
@@ -185,16 +204,17 @@ interface CommandDefinition<M extends Mode, T> {
    * @returns Nothing, or a promise that resolves when command handling
    *          completes.
    */
-  readonly handler: (value: T, context?: ProgramHookContext) => void | Promise<void>;
+  readonly handler: (value: T, context?: ProgramHookContext<R>) => 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.
+ * @template R The resource made available to lifecycle hooks and the handler.
  * @since 1.1.0
  */
-interface Command<M extends Mode, T> extends CommandDefinition<M, T> {
+interface Command<M extends Mode, T, R = unknown> extends CommandDefinition<M, T, R> {
   /**
    * Internal marker used to validate discovered modules.
    *
@@ -209,14 +229,61 @@ interface Command<M extends Mode, T> extends CommandDefinition<M, T> {
  *
  * @template M The mode of the command parser.
  * @template T The parsed value passed to the command handler.
+ * @template R The resource made available to lifecycle hooks and the handler.
  * @since 1.1.0
  */
-interface StaticCommand<M extends Mode, T> extends Command<M, T> {
+interface StaticCommand<M extends Mode, T, R = unknown> extends Command<M, T, R> {
   /**
    * Command path used by static command registration.
    */
   readonly path: CommandPath;
 }
+/**
+ * A command whose hooks always create their own command context.
+ *
+ * @internal
+ */
+type CommandWithBeforeEach<M extends Mode, T, R> = Command<M, T, R> & {
+  readonly hooks: ProgramHooksWithBeforeEach<R>;
+};
+/**
+ * A static command whose hooks always create their own command context.
+ *
+ * @internal
+ */
+type StaticCommandWithBeforeEach<M extends Mode, T, R> = StaticCommand<M, T, R> & CommandWithBeforeEach<M, T, R>;
+/**
+ * A command that does not create its own command context.
+ *
+ * @internal
+ */
+type CommandWithoutBeforeEach<M extends Mode, T, R> = Omit<Command<M, T, R>, "hooks"> & {
+  readonly hooks?: ProgramHooksWithoutBeforeEach<R>;
+};
+/**
+ * A static command that does not create its own command context.
+ *
+ * @internal
+ */
+type StaticCommandWithoutBeforeEach<M extends Mode, T, R> = Omit<StaticCommand<M, T, R>, "hooks"> & CommandWithoutBeforeEach<M, T, R>;
+/**
+ * Lifecycle hooks whose caller-defined resource type has been erased.
+ *
+ * @internal
+ */
+interface ErasedProgramHooks {
+  readonly beforeEach?: ProgramHooks<unknown>["beforeEach"];
+  readonly afterEach?: ProgramHooks<never>["afterEach"];
+  readonly onError?: ProgramHooks<never>["onError"];
+}
+/**
+ * Erased lifecycle hooks that always create their own command context.
+ *
+ * @internal
+ */
+interface ErasedProgramHooksWithBeforeEach extends ErasedProgramHooks {
+  readonly beforeEach: NonNullable<ErasedProgramHooks["beforeEach"]>;
+}
 /**
  * A command with its handler value type erased.
  *
@@ -226,23 +293,87 @@ interface StaticCommand<M extends Mode, T> extends Command<M, T> {
  *
  * @since 1.1.0
  */
-type AnyCommand = Omit<Command<Mode, unknown>, "handler"> & {
+type AnyCommand = Omit<Command<Mode, unknown>, "handler" | "hooks"> & {
+  /**
+   * Lifecycle hooks with their caller-defined resource type erased.
+   */
+  readonly hooks?: ErasedProgramHooks;
   /**
    * Erased command handler.
    */
-  readonly handler: (value: never, context?: ProgramHookContext) => void | Promise<void>;
+  readonly handler: (value: never, context?: ProgramHookContext<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"> & {
+type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler" | "hooks"> & {
+  /**
+   * Lifecycle hooks with their caller-defined resource type erased.
+   */
+  readonly hooks?: ErasedProgramHooks;
   /**
    * Erased command handler.
    */
-  readonly handler: (value: never, context?: ProgramHookContext) => void | Promise<void>;
+  readonly handler: (value: never, context?: ProgramHookContext<never>) => void | Promise<void>;
+};
+/**
+ * A type-erased command whose handler consumes a program-level resource.
+ *
+ * @internal
+ */
+type ProgramResourceCommand<R> = Omit<Command<Mode, unknown, R>, "handler"> & {
+  readonly handler: (value: never, context?: ProgramHookContext<R>) => void | Promise<void>;
 };
+/**
+ * A type-erased command that always creates its own command context.
+ *
+ * @internal
+ */
+type OwnResourceCommand = Omit<AnyCommand, "hooks"> & {
+  readonly hooks: ErasedProgramHooksWithBeforeEach;
+};
+/**
+ * A type-erased static command whose handler consumes a program-level
+ * resource.
+ *
+ * @internal
+ */
+type ProgramResourceStaticCommand<R> = Omit<StaticCommand<Mode, unknown, R>, "handler"> & {
+  readonly handler: (value: never, context?: ProgramHookContext<R>) => void | Promise<void>;
+};
+/**
+ * A type-erased static command that always creates its own command context.
+ *
+ * @internal
+ */
+type OwnResourceStaticCommand = Omit<AnyStaticCommand, "hooks"> & {
+  readonly hooks: ErasedProgramHooksWithBeforeEach;
+};
+/**
+ * A command accepted by `runProgram()` with a program-level resource type.
+ *
+ * Commands without a command-level `beforeEach` must consume `R`.  A command
+ * that always creates its own context may use a different resource type.
+ * Untyped calls retain the fully erased command shape for compatibility.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @since 1.2.0
+ */
+type RunProgramCommand<R = unknown> = unknown extends R ? AnyCommand : ProgramResourceCommand<R> | OwnResourceCommand;
+/**
+ * A static command accepted by `runProgram()` with a program-level resource
+ * type.
+ *
+ * Commands without a command-level `beforeEach` must consume `R`.  A command
+ * that always creates its own context may use a different resource type.
+ * Untyped calls retain the fully erased command shape for compatibility.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @since 1.2.0
+ */
+type RunProgramStaticCommand<R = unknown> = unknown extends R ? AnyStaticCommand : ProgramResourceStaticCommand<R> | OwnResourceStaticCommand;
 /**
  * Defines a command module for `@optique/discover`.
  *
@@ -251,16 +382,33 @@ type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler"> & {
  *
  * @template M The mode of the command parser.
  * @template T The parsed value passed to the command handler.
+ * @template R The resource made available to lifecycle hooks and the 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> & {
+declare function defineCommand<M extends Mode, T, R = unknown>(command: CommandDefinition<M, T, R> & {
+  readonly path: CommandPath;
+} & {
+  readonly hooks: ProgramHooksWithBeforeEach<R>;
+}): StaticCommandWithBeforeEach<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: Omit<CommandDefinition<M, T, R>, "hooks"> & {
+  readonly path: CommandPath;
+} & {
+  readonly hooks?: ProgramHooksWithoutBeforeEach<R>;
+}): StaticCommandWithoutBeforeEach<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: CommandDefinition<M, T, R> & {
+  readonly hooks: ProgramHooksWithBeforeEach<R>;
+}): CommandWithBeforeEach<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: Omit<CommandDefinition<M, T, R>, "hooks"> & {
+  readonly hooks?: ProgramHooksWithoutBeforeEach<R>;
+}): CommandWithoutBeforeEach<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: CommandDefinition<M, T, R> & {
   readonly path: CommandPath;
-}): StaticCommand<M, T>;
-declare function defineCommand<M extends Mode, T>(command: CommandDefinition<M, T>): Command<M, T>;
+}): StaticCommand<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: CommandDefinition<M, T, R>): Command<M, T, R>;
 /**
  * Returns whether a value is a command created by {@link defineCommand}.
  *
@@ -282,4 +430,4 @@ declare function isCommand(value: unknown): value is AnyCommand;
  */
 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 };
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, RunProgramCommand, RunProgramStaticCommand, StaticCommand, defineCommand, isCommand, validateHooks };

package/dist/{command-egqHCvDL.d.ts → command-BtjFShKT.d.cts}

@@ -30,14 +30,15 @@ type CommandPath = readonly string[];
  * {@link ProgramHooks.afterEach} and {@link ProgramHooks.onError} hooks.  This
  * threads handler-time resources without global state.
  *
+ * @template R The caller-defined resource stored in the context.
  * @since 1.2.0
  */
-interface ProgramHookContext {
+interface ProgramHookContext<R = unknown> {
   /**
    * Caller-defined resource.  Common shapes include a database pool, a logger
    * scope, or a tracing span.
    */
-  readonly resource?: unknown;
+  readonly resource?: R;
 }
 /**
  * The parsed command selected by a discovered command parser.
@@ -94,9 +95,10 @@ interface ProgramInvocation {
  * program.onError    ← command.onError    ← on failure
  * ```
  *
+ * @template R The resource returned by `beforeEach` and passed to later hooks.
  * @since 1.2.0
  */
-interface ProgramHooks {
+interface ProgramHooks<R = unknown> {
   /**
    * Called before the command handler runs, receiving the matched command, its
    * resolved {@link ProgramInvocation.path}, the parsed value, and the handler
@@ -112,7 +114,7 @@ interface ProgramHooks {
    * 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>;
+  readonly beforeEach?: (invocation: ProgramInvocation) => ProgramHookContext<R> | null | void | Promise<ProgramHookContext<R> | null | void>;
   /**
    * Called after the handler returns successfully, receiving the context from
    * {@link beforeEach} (or an empty object when no `beforeEach` ran) and the
@@ -122,7 +124,7 @@ interface ProgramHooks {
    * 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>;
+  readonly afterEach?: (context: ProgramHookContext<R>, 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)
@@ -135,16 +137,33 @@ interface ProgramHooks {
    *
    * Returning a promise is supported; the dispatcher awaits it.
    */
-  readonly onError?: (context: ProgramHookContext, error: unknown) => void | Promise<void>;
+  readonly onError?: (context: ProgramHookContext<R>, error: unknown) => void | Promise<void>;
 }
+/**
+ * Lifecycle hooks that always create their own command context.
+ *
+ * @internal
+ */
+type ProgramHooksWithBeforeEach<R> = ProgramHooks<R> & {
+  readonly beforeEach: NonNullable<ProgramHooks<R>["beforeEach"]>;
+};
+/**
+ * Lifecycle hooks that do not replace the program-level command context.
+ *
+ * @internal
+ */
+type ProgramHooksWithoutBeforeEach<R> = Omit<ProgramHooks<R>, "beforeEach"> & {
+  readonly beforeEach?: undefined;
+};
 /**
  * Input accepted by {@link defineCommand}.
  *
  * @template M The mode of the command parser.
  * @template T The parsed value passed to the command handler.
+ * @template R The resource made available to lifecycle hooks and the handler.
  * @since 1.1.0
  */
-interface CommandDefinition<M extends Mode, T> {
+interface CommandDefinition<M extends Mode, T, R = unknown> {
   /**
    * Command path used when commands are passed directly to `runProgram()`.
    * Use an empty path (`[]`) to register the root command.
@@ -172,7 +191,7 @@ interface CommandDefinition<M extends Mode, T> {
    *
    * @since 1.2.0
    */
-  readonly hooks?: ProgramHooks;
+  readonly hooks?: ProgramHooks<R>;
   /**
    * Handles the parsed command value.
    *
@@ -185,16 +204,17 @@ interface CommandDefinition<M extends Mode, T> {
    * @returns Nothing, or a promise that resolves when command handling
    *          completes.
    */
-  readonly handler: (value: T, context?: ProgramHookContext) => void | Promise<void>;
+  readonly handler: (value: T, context?: ProgramHookContext<R>) => 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.
+ * @template R The resource made available to lifecycle hooks and the handler.
  * @since 1.1.0
  */
-interface Command<M extends Mode, T> extends CommandDefinition<M, T> {
+interface Command<M extends Mode, T, R = unknown> extends CommandDefinition<M, T, R> {
   /**
    * Internal marker used to validate discovered modules.
    *
@@ -209,14 +229,61 @@ interface Command<M extends Mode, T> extends CommandDefinition<M, T> {
  *
  * @template M The mode of the command parser.
  * @template T The parsed value passed to the command handler.
+ * @template R The resource made available to lifecycle hooks and the handler.
  * @since 1.1.0
  */
-interface StaticCommand<M extends Mode, T> extends Command<M, T> {
+interface StaticCommand<M extends Mode, T, R = unknown> extends Command<M, T, R> {
   /**
    * Command path used by static command registration.
    */
   readonly path: CommandPath;
 }
+/**
+ * A command whose hooks always create their own command context.
+ *
+ * @internal
+ */
+type CommandWithBeforeEach<M extends Mode, T, R> = Command<M, T, R> & {
+  readonly hooks: ProgramHooksWithBeforeEach<R>;
+};
+/**
+ * A static command whose hooks always create their own command context.
+ *
+ * @internal
+ */
+type StaticCommandWithBeforeEach<M extends Mode, T, R> = StaticCommand<M, T, R> & CommandWithBeforeEach<M, T, R>;
+/**
+ * A command that does not create its own command context.
+ *
+ * @internal
+ */
+type CommandWithoutBeforeEach<M extends Mode, T, R> = Omit<Command<M, T, R>, "hooks"> & {
+  readonly hooks?: ProgramHooksWithoutBeforeEach<R>;
+};
+/**
+ * A static command that does not create its own command context.
+ *
+ * @internal
+ */
+type StaticCommandWithoutBeforeEach<M extends Mode, T, R> = Omit<StaticCommand<M, T, R>, "hooks"> & CommandWithoutBeforeEach<M, T, R>;
+/**
+ * Lifecycle hooks whose caller-defined resource type has been erased.
+ *
+ * @internal
+ */
+interface ErasedProgramHooks {
+  readonly beforeEach?: ProgramHooks<unknown>["beforeEach"];
+  readonly afterEach?: ProgramHooks<never>["afterEach"];
+  readonly onError?: ProgramHooks<never>["onError"];
+}
+/**
+ * Erased lifecycle hooks that always create their own command context.
+ *
+ * @internal
+ */
+interface ErasedProgramHooksWithBeforeEach extends ErasedProgramHooks {
+  readonly beforeEach: NonNullable<ErasedProgramHooks["beforeEach"]>;
+}
 /**
  * A command with its handler value type erased.
  *
@@ -226,23 +293,87 @@ interface StaticCommand<M extends Mode, T> extends Command<M, T> {
  *
  * @since 1.1.0
  */
-type AnyCommand = Omit<Command<Mode, unknown>, "handler"> & {
+type AnyCommand = Omit<Command<Mode, unknown>, "handler" | "hooks"> & {
+  /**
+   * Lifecycle hooks with their caller-defined resource type erased.
+   */
+  readonly hooks?: ErasedProgramHooks;
   /**
    * Erased command handler.
    */
-  readonly handler: (value: never, context?: ProgramHookContext) => void | Promise<void>;
+  readonly handler: (value: never, context?: ProgramHookContext<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"> & {
+type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler" | "hooks"> & {
+  /**
+   * Lifecycle hooks with their caller-defined resource type erased.
+   */
+  readonly hooks?: ErasedProgramHooks;
   /**
    * Erased command handler.
    */
-  readonly handler: (value: never, context?: ProgramHookContext) => void | Promise<void>;
+  readonly handler: (value: never, context?: ProgramHookContext<never>) => void | Promise<void>;
+};
+/**
+ * A type-erased command whose handler consumes a program-level resource.
+ *
+ * @internal
+ */
+type ProgramResourceCommand<R> = Omit<Command<Mode, unknown, R>, "handler"> & {
+  readonly handler: (value: never, context?: ProgramHookContext<R>) => void | Promise<void>;
 };
+/**
+ * A type-erased command that always creates its own command context.
+ *
+ * @internal
+ */
+type OwnResourceCommand = Omit<AnyCommand, "hooks"> & {
+  readonly hooks: ErasedProgramHooksWithBeforeEach;
+};
+/**
+ * A type-erased static command whose handler consumes a program-level
+ * resource.
+ *
+ * @internal
+ */
+type ProgramResourceStaticCommand<R> = Omit<StaticCommand<Mode, unknown, R>, "handler"> & {
+  readonly handler: (value: never, context?: ProgramHookContext<R>) => void | Promise<void>;
+};
+/**
+ * A type-erased static command that always creates its own command context.
+ *
+ * @internal
+ */
+type OwnResourceStaticCommand = Omit<AnyStaticCommand, "hooks"> & {
+  readonly hooks: ErasedProgramHooksWithBeforeEach;
+};
+/**
+ * A command accepted by `runProgram()` with a program-level resource type.
+ *
+ * Commands without a command-level `beforeEach` must consume `R`.  A command
+ * that always creates its own context may use a different resource type.
+ * Untyped calls retain the fully erased command shape for compatibility.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @since 1.2.0
+ */
+type RunProgramCommand<R = unknown> = unknown extends R ? AnyCommand : ProgramResourceCommand<R> | OwnResourceCommand;
+/**
+ * A static command accepted by `runProgram()` with a program-level resource
+ * type.
+ *
+ * Commands without a command-level `beforeEach` must consume `R`.  A command
+ * that always creates its own context may use a different resource type.
+ * Untyped calls retain the fully erased command shape for compatibility.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @since 1.2.0
+ */
+type RunProgramStaticCommand<R = unknown> = unknown extends R ? AnyStaticCommand : ProgramResourceStaticCommand<R> | OwnResourceStaticCommand;
 /**
  * Defines a command module for `@optique/discover`.
  *
@@ -251,16 +382,33 @@ type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler"> & {
  *
  * @template M The mode of the command parser.
  * @template T The parsed value passed to the command handler.
+ * @template R The resource made available to lifecycle hooks and the 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> & {
+declare function defineCommand<M extends Mode, T, R = unknown>(command: CommandDefinition<M, T, R> & {
+  readonly path: CommandPath;
+} & {
+  readonly hooks: ProgramHooksWithBeforeEach<R>;
+}): StaticCommandWithBeforeEach<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: Omit<CommandDefinition<M, T, R>, "hooks"> & {
+  readonly path: CommandPath;
+} & {
+  readonly hooks?: ProgramHooksWithoutBeforeEach<R>;
+}): StaticCommandWithoutBeforeEach<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: CommandDefinition<M, T, R> & {
+  readonly hooks: ProgramHooksWithBeforeEach<R>;
+}): CommandWithBeforeEach<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: Omit<CommandDefinition<M, T, R>, "hooks"> & {
+  readonly hooks?: ProgramHooksWithoutBeforeEach<R>;
+}): CommandWithoutBeforeEach<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: CommandDefinition<M, T, R> & {
   readonly path: CommandPath;
-}): StaticCommand<M, T>;
-declare function defineCommand<M extends Mode, T>(command: CommandDefinition<M, T>): Command<M, T>;
+}): StaticCommand<M, T, R>;
+declare function defineCommand<M extends Mode, T, R = unknown>(command: CommandDefinition<M, T, R>): Command<M, T, R>;
 /**
  * Returns whether a value is a command created by {@link defineCommand}.
  *
@@ -282,4 +430,4 @@ declare function isCommand(value: unknown): value is AnyCommand;
  */
 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 };
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, RunProgramCommand, RunProgramStaticCommand, StaticCommand, defineCommand, isCommand, validateHooks };

package/dist/command.d.cts

@@ -1,2 +1,2 @@
-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 };
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, RunProgramCommand, RunProgramStaticCommand, StaticCommand, defineCommand, isCommand, validateHooks } from "./command-BtjFShKT.cjs";
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, RunProgramCommand, RunProgramStaticCommand, StaticCommand, defineCommand, isCommand, validateHooks };

package/dist/command.d.ts

@@ -1,2 +1,2 @@
-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 };
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, RunProgramCommand, RunProgramStaticCommand, StaticCommand, defineCommand, isCommand, validateHooks } from "./command-BaFBKA4c.js";
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, RunProgramCommand, RunProgramStaticCommand, StaticCommand, defineCommand, isCommand, validateHooks };

package/dist/{generator-Dc9I4tTs.cjs → generator-4mV9w1F0.cjs}

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

@@ -1,4 +1,4 @@
-import { getDefaultExtensions } from "./src-CCeOMJRj.js";
+import { getDefaultExtensions } from "./src-Ddp18zFp.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-C-NgG0KJ.cjs');
-require('./src-CPtrcNkd.cjs');
-const require_generator = require('./generator-Dc9I4tTs.cjs');
+require('./src-Bb2ONs5m.cjs');
+const require_generator = require('./generator-4mV9w1F0.cjs');
 
 exports.generateCommandsModule = require_generator.generateCommandsModule;
 exports.watchCommandsModule = require_generator.watchCommandsModule;

package/dist/generator.js

@@ -1,5 +1,5 @@
 import "./command-9sgrJtwh.js";
-import "./src-CCeOMJRj.js";
-import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-wZHULCZH.js";
+import "./src-Ddp18zFp.js";
+import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-CJiusCJb.js";
 
 export { generateCommandsModule, watchCommandsModule, writeCommandsModule };

package/dist/index.cjs

@@ -1,5 +1,5 @@
 const require_command = require('./command-C-NgG0KJ.cjs');
-const require_src = require('./src-CPtrcNkd.cjs');
+const require_src = require('./src-Bb2ONs5m.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, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand } from "./command-Dvg452tU.cjs";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, RunProgramCommand, RunProgramStaticCommand, StaticCommand, defineCommand, isCommand } from "./command-BtjFShKT.cjs";
 import { Mode } from "@optique/core/parser";
 import { FluentParser } from "@optique/core/fluent";
 import { Message } from "@optique/core/message";
@@ -26,6 +26,20 @@ interface CommandEntry {
    */
   readonly command: AnyCommand;
 }
+/**
+ * A command entry accepted by `runProgram()` with a program-level resource
+ * type.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @since 1.2.0
+ */
+type RunProgramCommandEntry<R = unknown> = Omit<CommandEntry, "command"> & {
+  /**
+   * A command compatible with the program-level resource, or one that
+   * always creates its own command context.
+   */
+  readonly command: RunProgramCommand<R>;
+};
 /**
  * A command found on disk.
  *
@@ -48,9 +62,15 @@ interface DiscoveredCommand extends CommandEntry {
 /**
  * A command loaded from a static module map.
  *
+ * @template R The program-level resource used by commands without their own
+ *              `beforeEach` hook.
  * @since 1.2.0
  */
-interface ModuleCommand extends CommandEntry {
+interface ModuleCommand<R = unknown> extends CommandEntry {
+  /**
+   * The command definition.
+   */
+  readonly command: RunProgramCommand<R>;
   /**
    * Module map key used to derive the command path.
    */
@@ -146,7 +166,7 @@ interface RuntimeExtensionOptions {
    */
   readonly nodeTypeScriptSupport?: boolean;
 }
-interface RunProgramBaseOptions extends Omit<RunOptions, "help" | "version" | "completion" | "programName"> {
+interface RunProgramBaseOptions<R = unknown> extends Omit<RunOptions, "help" | "version" | "completion" | "programName"> {
   /**
    * Root program metadata.
    */
@@ -187,14 +207,15 @@ interface RunProgramBaseOptions extends Omit<RunOptions, "help" | "version" | "c
    *
    * @since 1.2.0
    */
-  readonly hooks?: ProgramHooks;
+  readonly hooks?: ProgramHooks<R>;
 }
 /**
  * Options for {@link runProgram} when discovering commands from files.
  *
+ * @template R The resource made available by program-level lifecycle hooks.
  * @since 1.1.0
  */
-interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
+interface RunProgramDiscoveryOptions<R = unknown> extends RunProgramBaseOptions<R> {
   /**
    * Directory containing command modules.
    */
@@ -219,16 +240,17 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
 /**
  * Options for {@link runProgram} when commands are imported manually.
  *
+ * @template R The resource made available by program-level lifecycle hooks.
  * @since 1.1.0
  */
-interface RunProgramStaticOptions extends RunProgramBaseOptions {
+interface RunProgramStaticOptions<R = unknown> extends RunProgramBaseOptions<R> {
   /**
    * Commands to compose without file-system discovery.
    *
    * Pass commands that declare their own `path`, or command entries returned
    * by {@link commandsFromModules}.
    */
-  readonly commands: readonly (AnyStaticCommand | CommandEntry)[];
+  readonly commands: readonly (RunProgramStaticCommand<NoInfer<R>> | RunProgramCommandEntry<NoInfer<R>>)[];
   /**
    * File-system discovery cannot be used together with `commands`.
    */
@@ -245,9 +267,10 @@ interface RunProgramStaticOptions extends RunProgramBaseOptions {
 /**
  * Options for {@link runProgram}.
  *
+ * @template R The resource made available by program-level lifecycle hooks.
  * @since 1.1.0
  */
-type RunProgramOptions = RunProgramDiscoveryOptions | RunProgramStaticOptions;
+type RunProgramOptions<R = unknown> = RunProgramDiscoveryOptions<R> | RunProgramStaticOptions<R>;
 /**
  * Returns runtime-aware command module suffixes.
  *
@@ -274,6 +297,8 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  * see module maps, such as `import.meta.glob(..., { eager: true })`, while
  * still deriving command paths from file-like module keys.
  *
+ * @template R The program-level resource used by commands without their own
+ *             `beforeEach` hook.
  * @param modules Static module map keyed by module path.
  * @param options Module path derivation options.
  * @returns Command entries sorted by command path.
@@ -283,7 +308,7 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  *         `path` does not match the module-derived path.
  * @since 1.2.0
  */
-declare function commandsFromModules(modules: ModuleMap, options?: CommandsFromModulesOptions): readonly ModuleCommand[];
+declare function commandsFromModules<R = unknown>(modules: ModuleMap, options?: CommandsFromModulesOptions): readonly ModuleCommand<R>[];
 /**
  * Builds a parser that dispatches to discovered command handlers.
  *
@@ -298,6 +323,7 @@ declare function createProgramParser(commands: readonly CommandEntry[], options?
 /**
  * Discovers and runs a command program.
  *
+ * @template R The resource made available by program-level lifecycle hooks.
  * @param options Program options.
  * @returns A promise that resolves after the selected command handler
  *          completes.
@@ -305,7 +331,7 @@ declare function createProgramParser(commands: readonly CommandEntry[], options?
  *         malformed.
  * @since 1.1.0
  */
-declare function runProgram(options: RunProgramOptions): Promise<void>;
+declare function runProgram<R = unknown>(options: RunProgramOptions<R>): Promise<void>;
 /**
  * Root help metadata for {@link createProgramParser}.
  *
@@ -339,4 +365,4 @@ interface CreateProgramParserOptions extends ProgramHelpMetadata {
   readonly commandList?: RunOptions["commandList"];
 }
 //#endregion
-export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, CreateProgramParserOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type 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, CreateProgramParserOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type ProgramInvocation, type RunProgramCommand, RunProgramCommandEntry, RunProgramDiscoveryOptions, RunProgramOptions, type RunProgramStaticCommand, 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, ProgramHookContext, ProgramHooks, ProgramInvocation, StaticCommand, defineCommand, isCommand } from "./command-egqHCvDL.js";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, ProgramHookContext, ProgramHooks, ProgramInvocation, RunProgramCommand, RunProgramStaticCommand, StaticCommand, defineCommand, isCommand } from "./command-BaFBKA4c.js";
 import { Message } from "@optique/core/message";
 import { ProgramMetadata } from "@optique/core/program";
 import { RunOptions } from "@optique/run";
@@ -26,6 +26,20 @@ interface CommandEntry {
    */
   readonly command: AnyCommand;
 }
+/**
+ * A command entry accepted by `runProgram()` with a program-level resource
+ * type.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @since 1.2.0
+ */
+type RunProgramCommandEntry<R = unknown> = Omit<CommandEntry, "command"> & {
+  /**
+   * A command compatible with the program-level resource, or one that
+   * always creates its own command context.
+   */
+  readonly command: RunProgramCommand<R>;
+};
 /**
  * A command found on disk.
  *
@@ -48,9 +62,15 @@ interface DiscoveredCommand extends CommandEntry {
 /**
  * A command loaded from a static module map.
  *
+ * @template R The program-level resource used by commands without their own
+ *              `beforeEach` hook.
  * @since 1.2.0
  */
-interface ModuleCommand extends CommandEntry {
+interface ModuleCommand<R = unknown> extends CommandEntry {
+  /**
+   * The command definition.
+   */
+  readonly command: RunProgramCommand<R>;
   /**
    * Module map key used to derive the command path.
    */
@@ -146,7 +166,7 @@ interface RuntimeExtensionOptions {
    */
   readonly nodeTypeScriptSupport?: boolean;
 }
-interface RunProgramBaseOptions extends Omit<RunOptions, "help" | "version" | "completion" | "programName"> {
+interface RunProgramBaseOptions<R = unknown> extends Omit<RunOptions, "help" | "version" | "completion" | "programName"> {
   /**
    * Root program metadata.
    */
@@ -187,14 +207,15 @@ interface RunProgramBaseOptions extends Omit<RunOptions, "help" | "version" | "c
    *
    * @since 1.2.0
    */
-  readonly hooks?: ProgramHooks;
+  readonly hooks?: ProgramHooks<R>;
 }
 /**
  * Options for {@link runProgram} when discovering commands from files.
  *
+ * @template R The resource made available by program-level lifecycle hooks.
  * @since 1.1.0
  */
-interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
+interface RunProgramDiscoveryOptions<R = unknown> extends RunProgramBaseOptions<R> {
   /**
    * Directory containing command modules.
    */
@@ -219,16 +240,17 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
 /**
  * Options for {@link runProgram} when commands are imported manually.
  *
+ * @template R The resource made available by program-level lifecycle hooks.
  * @since 1.1.0
  */
-interface RunProgramStaticOptions extends RunProgramBaseOptions {
+interface RunProgramStaticOptions<R = unknown> extends RunProgramBaseOptions<R> {
   /**
    * Commands to compose without file-system discovery.
    *
    * Pass commands that declare their own `path`, or command entries returned
    * by {@link commandsFromModules}.
    */
-  readonly commands: readonly (AnyStaticCommand | CommandEntry)[];
+  readonly commands: readonly (RunProgramStaticCommand<NoInfer<R>> | RunProgramCommandEntry<NoInfer<R>>)[];
   /**
    * File-system discovery cannot be used together with `commands`.
    */
@@ -245,9 +267,10 @@ interface RunProgramStaticOptions extends RunProgramBaseOptions {
 /**
  * Options for {@link runProgram}.
  *
+ * @template R The resource made available by program-level lifecycle hooks.
  * @since 1.1.0
  */
-type RunProgramOptions = RunProgramDiscoveryOptions | RunProgramStaticOptions;
+type RunProgramOptions<R = unknown> = RunProgramDiscoveryOptions<R> | RunProgramStaticOptions<R>;
 /**
  * Returns runtime-aware command module suffixes.
  *
@@ -274,6 +297,8 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  * see module maps, such as `import.meta.glob(..., { eager: true })`, while
  * still deriving command paths from file-like module keys.
  *
+ * @template R The program-level resource used by commands without their own
+ *             `beforeEach` hook.
  * @param modules Static module map keyed by module path.
  * @param options Module path derivation options.
  * @returns Command entries sorted by command path.
@@ -283,7 +308,7 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  *         `path` does not match the module-derived path.
  * @since 1.2.0
  */
-declare function commandsFromModules(modules: ModuleMap, options?: CommandsFromModulesOptions): readonly ModuleCommand[];
+declare function commandsFromModules<R = unknown>(modules: ModuleMap, options?: CommandsFromModulesOptions): readonly ModuleCommand<R>[];
 /**
  * Builds a parser that dispatches to discovered command handlers.
  *
@@ -298,6 +323,7 @@ declare function createProgramParser(commands: readonly CommandEntry[], options?
 /**
  * Discovers and runs a command program.
  *
+ * @template R The resource made available by program-level lifecycle hooks.
  * @param options Program options.
  * @returns A promise that resolves after the selected command handler
  *          completes.
@@ -305,7 +331,7 @@ declare function createProgramParser(commands: readonly CommandEntry[], options?
  *         malformed.
  * @since 1.1.0
  */
-declare function runProgram(options: RunProgramOptions): Promise<void>;
+declare function runProgram<R = unknown>(options: RunProgramOptions<R>): Promise<void>;
 /**
  * Root help metadata for {@link createProgramParser}.
  *
@@ -339,4 +365,4 @@ interface CreateProgramParserOptions extends ProgramHelpMetadata {
   readonly commandList?: RunOptions["commandList"];
 }
 //#endregion
-export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, CreateProgramParserOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type 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, CreateProgramParserOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, type ProgramHookContext, type ProgramHooks, type ProgramInvocation, type RunProgramCommand, RunProgramCommandEntry, RunProgramDiscoveryOptions, RunProgramOptions, type RunProgramStaticCommand, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.js

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

package/dist/{src-CPtrcNkd.cjs → src-Bb2ONs5m.cjs}

@@ -81,6 +81,8 @@ async function discoverCommands(options) {
 * see module maps, such as `import.meta.glob(..., { eager: true })`, while
 * still deriving command paths from file-like module keys.
 *
+* @template R The program-level resource used by commands without their own
+*             `beforeEach` hook.
 * @param modules Static module map keyed by module path.
 * @param options Module path derivation options.
 * @returns Command entries sorted by command path.
@@ -144,6 +146,7 @@ function createProgramParser(commands, options = {}) {
 /**
 * Discovers and runs a command program.
 *
+* @template R The resource made available by program-level lifecycle hooks.
 * @param options Program options.
 * @returns A promise that resolves after the selected command handler
 *          completes.

package/dist/{src-CCeOMJRj.js → src-Ddp18zFp.js}

@@ -80,6 +80,8 @@ async function discoverCommands(options) {
 * see module maps, such as `import.meta.glob(..., { eager: true })`, while
 * still deriving command paths from file-like module keys.
 *
+* @template R The program-level resource used by commands without their own
+*             `beforeEach` hook.
 * @param modules Static module map keyed by module path.
 * @param options Module path derivation options.
 * @returns Command entries sorted by command path.
@@ -143,6 +145,7 @@ function createProgramParser(commands, options = {}) {
 /**
 * Discovers and runs a command program.
 *
+* @template R The resource made available by program-level lifecycle hooks.
 * @param options Program options.
 * @returns A promise that resolves after the selected command handler
 *          completes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/discover",
-  "version": "1.2.0-dev.2330",
+  "version": "1.2.0-dev.2333",
   "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.2330+6776ce17",
-    "@optique/run": "1.2.0-dev.2330+6776ce17"
+    "@optique/core": "1.2.0-dev.2333+f7f47e8b",
+    "@optique/run": "1.2.0-dev.2333+f7f47e8b"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",