@optique/discover 1.2.0-dev.2331 → 1.2.0-dev.2335

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-BAFFLASv.cjs');
-const require_generator = require('./generator-DX58yLaB.cjs');
+require('./src-DL9BHbjo.cjs');
+const require_generator = require('./generator-B0OvR99S.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.2331+0f3b5a2e";
+var version = "1.2.0-dev.2335+26079d6b";
 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-Bxt-nAIP.js";
-import { watchCommandsModule, writeCommandsModule } from "./generator-wG1l1zon.js";
+import "./src-BT2FzGqZ.js";
+import { watchCommandsModule, writeCommandsModule } from "./generator-BY2Tdodb.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.2331+0f3b5a2e";
+var version = "1.2.0-dev.2335+26079d6b";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",

package/dist/{command-CYwk-AJC.d.ts → command-BaFBKA4c.d.ts}

@@ -139,6 +139,22 @@ interface ProgramHooks<R = unknown> {
    */
   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}.
  *
@@ -222,6 +238,34 @@ interface StaticCommand<M extends Mode, T, R = unknown> extends Command<M, T, R>
    */
   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.
  *
@@ -232,6 +276,14 @@ interface ErasedProgramHooks {
   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.
  *
@@ -266,6 +318,62 @@ type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler" | "hooks">
    */
   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`.
  *
@@ -281,6 +389,22 @@ type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler" | "hooks">
  *         malformed.
  * @since 1.1.0
  */
+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, R>;
@@ -306,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-ChWCwb3x.d.cts → command-BtjFShKT.d.cts}

@@ -139,6 +139,22 @@ interface ProgramHooks<R = unknown> {
    */
   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}.
  *
@@ -222,6 +238,34 @@ interface StaticCommand<M extends Mode, T, R = unknown> extends Command<M, T, R>
    */
   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.
  *
@@ -232,6 +276,14 @@ interface ErasedProgramHooks {
   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.
  *
@@ -266,6 +318,62 @@ type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler" | "hooks">
    */
   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`.
  *
@@ -281,6 +389,22 @@ type AnyStaticCommand = Omit<StaticCommand<Mode, unknown>, "handler" | "hooks">
  *         malformed.
  * @since 1.1.0
  */
+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, R>;
@@ -306,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-ChWCwb3x.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-CYwk-AJC.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-DX58yLaB.cjs → generator-B0OvR99S.cjs}

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

@@ -1,4 +1,4 @@
-import { getDefaultExtensions } from "./src-Bxt-nAIP.js";
+import { getDefaultExtensions } from "./src-BT2FzGqZ.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-BAFFLASv.cjs');
-const require_generator = require('./generator-DX58yLaB.cjs');
+require('./src-DL9BHbjo.cjs');
+const require_generator = require('./generator-B0OvR99S.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-Bxt-nAIP.js";
-import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-wG1l1zon.js";
+import "./src-BT2FzGqZ.js";
+import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-BY2Tdodb.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-BAFFLASv.cjs');
+const require_src = require('./src-DL9BHbjo.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-ChWCwb3x.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.
    */
@@ -230,7 +250,7 @@ interface RunProgramStaticOptions<R = unknown> extends RunProgramBaseOptions<R>
    * 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`.
    */
@@ -277,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.
@@ -286,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.
  *
@@ -343,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-CYwk-AJC.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.
    */
@@ -230,7 +250,7 @@ interface RunProgramStaticOptions<R = unknown> extends RunProgramBaseOptions<R>
    * 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`.
    */
@@ -277,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.
@@ -286,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.
  *
@@ -343,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-Bxt-nAIP.js";
+import { commandsFromModules, createProgramParser, discoverCommands, getDefaultExtensions, runProgram } from "./src-BT2FzGqZ.js";
 
 export { commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/{src-Bxt-nAIP.js → src-BT2FzGqZ.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.
@@ -188,7 +190,7 @@ async function dispatchInvocation(invocation, programHooks) {
 		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);
-	}));
+	}, programContext));
 }
 /**
 * Runs an inner step wrapped in a single set of lifecycle hooks.
@@ -196,13 +198,14 @@ async function dispatchInvocation(invocation, programHooks) {
 * @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`.
+* @param fallbackContext The context used when `beforeEach` is absent.
 * @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 = {};
+async function runHookScope(hooks, invocation, inner, fallbackContext = {}) {
+	let context = fallbackContext;
 	try {
 		if (hooks?.beforeEach != null) context = await hooks.beforeEach(invocation) ?? {};
 		const result = await inner(context);

package/dist/{src-BAFFLASv.cjs → src-DL9BHbjo.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.
@@ -189,7 +191,7 @@ async function dispatchInvocation(invocation, programHooks) {
 		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);
-	}));
+	}, programContext));
 }
 /**
 * Runs an inner step wrapped in a single set of lifecycle hooks.
@@ -197,13 +199,14 @@ async function dispatchInvocation(invocation, programHooks) {
 * @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`.
+* @param fallbackContext The context used when `beforeEach` is absent.
 * @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 = {};
+async function runHookScope(hooks, invocation, inner, fallbackContext = {}) {
+	let context = fallbackContext;
 	try {
 		if (hooks?.beforeEach != null) context = await hooks.beforeEach(invocation) ?? {};
 		const result = await inner(context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/discover",
-  "version": "1.2.0-dev.2331",
+  "version": "1.2.0-dev.2335",
   "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.2331+0f3b5a2e",
-    "@optique/run": "1.2.0-dev.2331+0f3b5a2e"
+    "@optique/run": "1.2.0-dev.2335+26079d6b",
+    "@optique/core": "1.2.0-dev.2335+26079d6b"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",