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

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

package/dist/{command-Dvg452tU.d.cts → command-CYwk-AJC.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,17 @@ 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>;
 }
 /**
  * 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 +175,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 +188,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 +213,25 @@ 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;
 }
+/**
+ * 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"];
+}
 /**
  * A command with its handler value type erased.
  *
@@ -226,22 +241,30 @@ 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>;
 };
 /**
  * Defines a command module for `@optique/discover`.
@@ -251,16 +274,17 @@ 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;
-}): 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}.
  *

package/dist/{command-egqHCvDL.d.ts → command-ChWCwb3x.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,17 @@ 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>;
 }
 /**
  * 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 +175,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 +188,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 +213,25 @@ 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;
 }
+/**
+ * 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"];
+}
 /**
  * A command with its handler value type erased.
  *
@@ -226,22 +241,30 @@ 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>;
 };
 /**
  * Defines a command module for `@optique/discover`.
@@ -251,16 +274,17 @@ 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;
-}): 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}.
  *

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";
+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 };

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";
+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 };

package/dist/{generator-Dc9I4tTs.cjs → generator-DX58yLaB.cjs}

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

@@ -1,4 +1,4 @@
-import { getDefaultExtensions } from "./src-CCeOMJRj.js";
+import { getDefaultExtensions } from "./src-Bxt-nAIP.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-BAFFLASv.cjs');
+const require_generator = require('./generator-DX58yLaB.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-Bxt-nAIP.js";
+import { generateCommandsModule, watchCommandsModule, writeCommandsModule } from "./generator-wG1l1zon.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-BAFFLASv.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, StaticCommand, defineCommand, isCommand } from "./command-ChWCwb3x.cjs";
 import { Mode } from "@optique/core/parser";
 import { FluentParser } from "@optique/core/fluent";
 import { Message } from "@optique/core/message";
@@ -146,7 +146,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 +187,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,9 +220,10 @@ 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.
    *
@@ -245,9 +247,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.
  *
@@ -298,6 +301,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 +309,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}.
  *

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, StaticCommand, defineCommand, isCommand } from "./command-CYwk-AJC.js";
 import { Message } from "@optique/core/message";
 import { ProgramMetadata } from "@optique/core/program";
 import { RunOptions } from "@optique/run";
@@ -146,7 +146,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 +187,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,9 +220,10 @@ 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.
    *
@@ -245,9 +247,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.
  *
@@ -298,6 +301,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 +309,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}.
  *

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-Bxt-nAIP.js";
 
 export { commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

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

@@ -144,6 +144,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-Bxt-nAIP.js}

@@ -143,6 +143,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.2331",
   "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.2331+0f3b5a2e",
+    "@optique/run": "1.2.0-dev.2331+0f3b5a2e"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",