@optique/discover 1.2.0-dev.2167 → 1.2.0-dev.2169

package/README.md

@@ -14,7 +14,8 @@ handler.
 > *@optique/discover* reads command files and imports them dynamically at
 > runtime.  It is a poor fit for CLIs that rely on aggressive tree shaking,
 > static bundling, or single-file executable packaging.  In those cases, use
-> manually imported commands with `runProgram({ commands })`.
+> `commandsFromModules()` with a static module map, or manually imported
+> commands with `runProgram({ commands })`.
 
 
 Installation
@@ -79,32 +80,23 @@ admin --help
 admin completion bash
 ~~~~
 
-For bundlers and single-file packagers, import commands manually and declare
-their paths in the command definitions:
+For bundlers and single-file packagers, turn a static module map into command
+entries:
 
 ~~~~ typescript
 // cli.ts
-import { defineCommand, runProgram } from "@optique/discover";
-import { object } from "@optique/core/constructs";
+import { commandsFromModules, runProgram } from "@optique/discover";
 import { message } from "@optique/core/message";
-import { option } from "@optique/core/primitives";
-import { string } from "@optique/core/valueparser";
 
-const addUser = defineCommand({
-  path: ["user", "add"],
-  parser: object({
-    name: option("--name", string()),
-  }),
-  metadata: {
-    brief: message`Add a user.`,
-  },
-  handler(value) {
-    console.log(`Adding ${value.name}.`);
-  },
+const modules = import.meta.glob("./commands/**/*.ts", {
+  eager: true,
 });
 
 await runProgram({
-  commands: [addUser],
+  commands: commandsFromModules(modules, {
+    base: "./commands",
+    extensions: [".ts"],
+  }),
   metadata: {
     name: "admin",
     version: "1.0.0",
@@ -113,6 +105,11 @@ await runProgram({
 });
 ~~~~
 
+`commandsFromModules()` preserves the file-based command layout while making
+the module list visible to bundlers.  For smaller registries, you can also
+import commands manually, declare `path` in each `defineCommand()` call, and
+pass those commands to `runProgram({ commands })`.
+
 By default, Deno and Bun discover `.ts`, `.mts`, `.js`, and `.mjs` files.
 Node.js discovers `.js`, `.mjs`, and `.cjs` files, plus `.ts`, `.mts`, and
 `.cts` when it reports native TypeScript support or runs with a recognized
@@ -120,7 +117,8 @@ TypeScript loader.  TypeScript declaration files such as `.d.ts` are ignored.
 Entry files named `index` map to their containing command path, so
 `commands/index.ts` defines the root command and `commands/user/index.ts`
 defines `user`.  Use `entryFileName` to choose another entry name or disable
-this rule.
+this rule.  `commandsFromModules()` applies the same path rules to module map
+keys after stripping its `base` option.
 
 For more resources, see the [docs] and the [*examples/*](/examples/)
 directory.

package/dist/index.cjs

@@ -85,9 +85,8 @@ async function discoverCommands(options) {
 		}
 		seen.set(key, filePath);
 		const mod = await import((0, node_url.pathToFileURL)(filePath).href);
-		const commandDefinition = unwrapCommandExport(mod.default);
-		if (commandDefinition == null) throw new TypeError(`Module ${filePath} default export must be created with defineCommand().`);
-		if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${filePath} declares command path "${displayCommandPath(commandDefinition.path)}" but file path defines "${displayCommandPath(path)}".`);
+		const commandDefinition = commandFromModuleExport(filePath, mod.default);
+		validateDeclaredCommandPath(commandDefinition, path, filePath, "file path");
 		discovered.push({
 			path,
 			filePath,
@@ -97,6 +96,51 @@ async function discoverCommands(options) {
 	return sortCommands(discovered);
 }
 /**
+* Converts a static module map into command entries.
+*
+* This is useful for bundlers and single-file packagers that can statically
+* see module maps, such as `import.meta.glob(..., { eager: true })`, while
+* still deriving command paths from file-like module keys.
+*
+* @param modules Static module map keyed by module path.
+* @param options Module path derivation options.
+* @returns Command entries sorted by command path.
+* @throws {TypeError} If options are invalid, no command modules are found,
+*         command paths are duplicated, a module does not default-export a
+*         command created with `defineCommand()`, or an explicit command
+*         `path` does not match the module-derived path.
+* @since 1.2.0
+*/
+function commandsFromModules(modules, options = {}) {
+	if (modules == null || typeof modules !== "object") throw new TypeError("commandsFromModules() requires a module map object.");
+	const base = normalizeModuleBase(options.base);
+	const extensions = normalizeExtensions(options.extensions ?? getDefaultExtensions());
+	const entryFileName = normalizeEntryFileName(options.entryFileName);
+	const modulePaths = Object.keys(modules).toSorted((a, b) => a.localeCompare(b));
+	const seen = /* @__PURE__ */ new Map();
+	const discovered = [];
+	for (const modulePath of modulePaths) {
+		if (isDeclarationFile(node_path.posix.basename(modulePath)) || !extensions.some((ext) => modulePath.endsWith(ext))) continue;
+		const path = commandPathFromModulePath(base, modulePath, extensions, entryFileName);
+		const key = commandPathKey(path);
+		const previous = seen.get(key);
+		if (previous != null) {
+			const displayPath = displayCommandPath(path);
+			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${modulePath}.`);
+		}
+		seen.set(key, modulePath);
+		const commandDefinition = commandFromModuleExport(modulePath, modules[modulePath]);
+		validateDeclaredCommandPath(commandDefinition, path, modulePath, "module path");
+		discovered.push({
+			path,
+			modulePath,
+			command: commandDefinition
+		});
+	}
+	if (discovered.length < 1) throw new TypeError("No command modules found in module map.");
+	return sortCommands(discovered);
+}
+/**
 * Builds a parser that dispatches to discovered command handlers.
 *
 * @param commands Commands to compose.
@@ -171,6 +215,11 @@ function normalizeEntryFileName(entryFileName) {
 	if (normalized.length < 1 || normalized.includes("/") || normalized.includes("\\")) throw new TypeError(`Command entry file name must be a non-empty file name: ${normalized}`);
 	return normalized;
 }
+function normalizeModuleBase(base) {
+	if (base === void 0) return ".";
+	if (typeof base !== "string" || base.length < 1) throw new TypeError(`Module base path must be a non-empty string: ${base}`);
+	return normalizeModulePath(base);
+}
 async function collectCommandFiles(dir, extensions, activeDirs = /* @__PURE__ */ new Set()) {
 	const canonicalDir = await (0, node_fs_promises.realpath)(dir);
 	if (activeDirs.has(canonicalDir)) return [];
@@ -203,12 +252,33 @@ function isDeclarationFile(fileName) {
 	return /\.d\.[cm]?ts$/.test(fileName);
 }
 function commandPathFromFile(rootDir, filePath, extensions, entryFileName) {
-	const matchedExtension = extensions.find((ext) => filePath.endsWith(ext));
-	if (matchedExtension == null) throw new TypeError(`No configured extension matches ${filePath}.`);
-	const withoutExtension = filePath.slice(0, -matchedExtension.length);
+	const withoutExtension = stripCommandExtension(filePath, extensions);
 	const relativePath = (0, node_path.relative)(rootDir, withoutExtension);
 	const path = relativePath.split(node_path.sep).filter((segment) => segment.length > 0);
-	if (path.length < 1) throw new TypeError(`Command file ${filePath} does not define a path.`);
+	return commandPathFromSegments(path, filePath, entryFileName);
+}
+function commandPathFromModulePath(base, modulePath, extensions, entryFileName) {
+	const withoutExtension = stripCommandExtension(modulePath, extensions);
+	const relativePath = relativeModulePath(base, withoutExtension, modulePath);
+	const path = relativePath.split("/").filter((segment) => segment.length > 0);
+	return commandPathFromSegments(path, modulePath, entryFileName);
+}
+function stripCommandExtension(path, extensions) {
+	const matchedExtension = extensions.find((ext) => path.endsWith(ext));
+	if (matchedExtension == null) throw new TypeError(`No configured extension matches ${path}.`);
+	return path.slice(0, -matchedExtension.length);
+}
+function relativeModulePath(base, modulePath, originalModulePath) {
+	const normalizedPath = normalizeModulePath(modulePath);
+	const relativePath = node_path.posix.relative(base, normalizedPath);
+	if (relativePath.length < 1 || relativePath === ".." || relativePath.startsWith("../") || node_path.posix.isAbsolute(relativePath)) throw new TypeError(`Module path ${originalModulePath} is not under base path ${base}.`);
+	return relativePath;
+}
+function normalizeModulePath(path) {
+	return node_path.posix.normalize(path.replaceAll("\\", "/"));
+}
+function commandPathFromSegments(path, source, entryFileName) {
+	if (path.length < 1) throw new TypeError(`Command module ${source} does not define a path.`);
 	if (entryFileName !== false && path[path.length - 1] === entryFileName) return path.slice(0, -1);
 	return path;
 }
@@ -243,23 +313,38 @@ function isStaticRunProgramOptions(options) {
 	return hasCommands;
 }
 function staticCommandsToEntries(commands) {
-	return commands.map((command$1) => {
-		if (!require_command.isCommand(command$1)) throw new TypeError("Static command entries must be created with defineCommand().");
-		if (!isCommandPath(command$1.path)) throw new TypeError("Static command entries must declare a path.");
+	return commands.map((entry) => {
+		if (isCommandEntry(entry)) return entry;
+		if (!require_command.isCommand(entry)) throw new TypeError("Static command entries must be created with defineCommand().");
+		if (!isCommandPath(entry.path)) throw new TypeError("Static command entries must declare a path.");
 		return {
-			path: command$1.path,
-			command: command$1
+			path: entry.path,
+			command: entry
 		};
 	});
 }
+function isCommandEntry(value) {
+	return value != null && typeof value === "object" && isCommandPath(value.path) && require_command.isCommand(value.command);
+}
 function unwrapCommandExport(value) {
-	if (require_command.isCommand(value)) return value;
-	if (value != null && typeof value === "object") {
-		const nestedDefault = value.default;
-		if (require_command.isCommand(nestedDefault)) return nestedDefault;
+	let current = value;
+	for (let depth = 0; depth < 3; depth++) {
+		if (require_command.isCommand(current)) return current;
+		if (current == null || typeof current !== "object") return void 0;
+		const nestedDefault = current.default;
+		if (Object.is(nestedDefault, current)) return void 0;
+		current = nestedDefault;
 	}
 	return void 0;
 }
+function commandFromModuleExport(source, value) {
+	const commandDefinition = unwrapCommandExport(value);
+	if (commandDefinition == null) throw new TypeError(`Module ${source} default export must be created with defineCommand().`);
+	return commandDefinition;
+}
+function validateDeclaredCommandPath(commandDefinition, path, source, sourcePathLabel) {
+	if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${source} declares command path "${displayCommandPath(commandDefinition.path)}" but ${sourcePathLabel} defines "${displayCommandPath(path)}".`);
+}
 function buildCommandTree(commands) {
 	const root = { children: /* @__PURE__ */ new Map() };
 	for (const entry of commands) {
@@ -689,6 +774,7 @@ function isProgramInvocation(value) {
 }
 
 //#endregion
+exports.commandsFromModules = commandsFromModules;
 exports.createProgramParser = createProgramParser;
 exports.defineCommand = require_command.defineCommand;
 exports.discoverCommands = discoverCommands;

package/dist/index.d.cts

@@ -28,12 +28,31 @@ interface ProgramInvocation {
    */
   readonly handler: (value: unknown) => void | Promise<void>;
 }
+/**
+ * A command paired with its command path.
+ *
+ * `createProgramParser()` accepts command entries directly, and
+ * `runProgram({ commands })` accepts them alongside commands that declare
+ * their own `path` field.
+ *
+ * @since 1.2.0
+ */
+interface CommandEntry {
+  /**
+   * Command path used to place the command in the program tree.
+   */
+  readonly path: CommandPath;
+  /**
+   * The command definition.
+   */
+  readonly command: AnyCommand;
+}
 /**
  * A command found on disk.
  *
  * @since 1.1.0
  */
-interface DiscoveredCommand {
+interface DiscoveredCommand extends CommandEntry {
   /**
    * Command path derived from the module's relative path.
    */
@@ -47,6 +66,26 @@ interface DiscoveredCommand {
    */
   readonly command: AnyCommand;
 }
+/**
+ * A command loaded from a static module map.
+ *
+ * @since 1.2.0
+ */
+interface ModuleCommand extends CommandEntry {
+  /**
+   * Module map key used to derive the command path.
+   */
+  readonly modulePath: string;
+}
+/**
+ * Static module map accepted by {@link commandsFromModules}.
+ *
+ * This matches eager glob import APIs such as Vite's
+ * `import.meta.glob(..., { eager: true })`.
+ *
+ * @since 1.2.0
+ */
+type ModuleMap = Readonly<Record<string, unknown>>;
 /**
  * Options for {@link discoverCommands}.
  *
@@ -75,6 +114,35 @@ interface DiscoverCommandsOptions {
    */
   readonly entryFileName?: string | false;
 }
+/**
+ * Options for {@link commandsFromModules}.
+ *
+ * @since 1.2.0
+ */
+interface CommandsFromModulesOptions {
+  /**
+   * Base module path to strip before deriving command paths.
+   *
+   * @default `"."`
+   */
+  readonly base?: string;
+  /**
+   * Module suffixes to include.  Compound suffixes such as `.cmd.ts` are
+   * supported.
+   *
+   * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.  For example, `stash/index.ts` maps to `stash`, and root
+   * `index.ts` maps to the root command.  Pass `false` to treat matching files
+   * as ordinary command names.
+   *
+   * @default `"index"`
+   */
+  readonly entryFileName?: string | false;
+}
 /**
  * Runtime hint for {@link getDefaultExtensions}.
  *
@@ -165,8 +233,11 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
 interface RunProgramStaticOptions extends RunProgramBaseOptions {
   /**
    * 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[];
+  readonly commands: readonly (AnyStaticCommand | CommandEntry)[];
   /**
    * File-system discovery cannot be used together with `commands`.
    */
@@ -205,6 +276,23 @@ declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readon
  * @since 1.1.0
  */
 declare function discoverCommands(options: DiscoverCommandsOptions): Promise<readonly DiscoveredCommand[]>;
+/**
+ * Converts a static module map into command entries.
+ *
+ * This is useful for bundlers and single-file packagers that can statically
+ * see module maps, such as `import.meta.glob(..., { eager: true })`, while
+ * still deriving command paths from file-like module keys.
+ *
+ * @param modules Static module map keyed by module path.
+ * @param options Module path derivation options.
+ * @returns Command entries sorted by command path.
+ * @throws {TypeError} If options are invalid, no command modules are found,
+ *         command paths are duplicated, a module does not default-export a
+ *         command created with `defineCommand()`, or an explicit command
+ *         `path` does not match the module-derived path.
+ * @since 1.2.0
+ */
+declare function commandsFromModules(modules: ModuleMap, options?: CommandsFromModulesOptions): readonly ModuleCommand[];
 /**
  * Builds a parser that dispatches to discovered command handlers.
  *
@@ -215,7 +303,7 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  *         duplicated.
  * @since 1.1.0
  */
-declare function createProgramParser(commands: readonly Pick<DiscoveredCommand, "path" | "command">[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
+declare function createProgramParser(commands: readonly CommandEntry[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
 /**
  * Discovers and runs a command program.
  *
@@ -246,4 +334,4 @@ interface ProgramHelpMetadata {
   readonly footer?: Message;
 }
 //#endregion
-export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, type CommandMetadata, type CommandPath, DiscoverCommandsOptions, DiscoveredCommand, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.d.ts

@@ -28,12 +28,31 @@ interface ProgramInvocation {
    */
   readonly handler: (value: unknown) => void | Promise<void>;
 }
+/**
+ * A command paired with its command path.
+ *
+ * `createProgramParser()` accepts command entries directly, and
+ * `runProgram({ commands })` accepts them alongside commands that declare
+ * their own `path` field.
+ *
+ * @since 1.2.0
+ */
+interface CommandEntry {
+  /**
+   * Command path used to place the command in the program tree.
+   */
+  readonly path: CommandPath;
+  /**
+   * The command definition.
+   */
+  readonly command: AnyCommand;
+}
 /**
  * A command found on disk.
  *
  * @since 1.1.0
  */
-interface DiscoveredCommand {
+interface DiscoveredCommand extends CommandEntry {
   /**
    * Command path derived from the module's relative path.
    */
@@ -47,6 +66,26 @@ interface DiscoveredCommand {
    */
   readonly command: AnyCommand;
 }
+/**
+ * A command loaded from a static module map.
+ *
+ * @since 1.2.0
+ */
+interface ModuleCommand extends CommandEntry {
+  /**
+   * Module map key used to derive the command path.
+   */
+  readonly modulePath: string;
+}
+/**
+ * Static module map accepted by {@link commandsFromModules}.
+ *
+ * This matches eager glob import APIs such as Vite's
+ * `import.meta.glob(..., { eager: true })`.
+ *
+ * @since 1.2.0
+ */
+type ModuleMap = Readonly<Record<string, unknown>>;
 /**
  * Options for {@link discoverCommands}.
  *
@@ -75,6 +114,35 @@ interface DiscoverCommandsOptions {
    */
   readonly entryFileName?: string | false;
 }
+/**
+ * Options for {@link commandsFromModules}.
+ *
+ * @since 1.2.0
+ */
+interface CommandsFromModulesOptions {
+  /**
+   * Base module path to strip before deriving command paths.
+   *
+   * @default `"."`
+   */
+  readonly base?: string;
+  /**
+   * Module suffixes to include.  Compound suffixes such as `.cmd.ts` are
+   * supported.
+   *
+   * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.  For example, `stash/index.ts` maps to `stash`, and root
+   * `index.ts` maps to the root command.  Pass `false` to treat matching files
+   * as ordinary command names.
+   *
+   * @default `"index"`
+   */
+  readonly entryFileName?: string | false;
+}
 /**
  * Runtime hint for {@link getDefaultExtensions}.
  *
@@ -165,8 +233,11 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
 interface RunProgramStaticOptions extends RunProgramBaseOptions {
   /**
    * 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[];
+  readonly commands: readonly (AnyStaticCommand | CommandEntry)[];
   /**
    * File-system discovery cannot be used together with `commands`.
    */
@@ -205,6 +276,23 @@ declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readon
  * @since 1.1.0
  */
 declare function discoverCommands(options: DiscoverCommandsOptions): Promise<readonly DiscoveredCommand[]>;
+/**
+ * Converts a static module map into command entries.
+ *
+ * This is useful for bundlers and single-file packagers that can statically
+ * see module maps, such as `import.meta.glob(..., { eager: true })`, while
+ * still deriving command paths from file-like module keys.
+ *
+ * @param modules Static module map keyed by module path.
+ * @param options Module path derivation options.
+ * @returns Command entries sorted by command path.
+ * @throws {TypeError} If options are invalid, no command modules are found,
+ *         command paths are duplicated, a module does not default-export a
+ *         command created with `defineCommand()`, or an explicit command
+ *         `path` does not match the module-derived path.
+ * @since 1.2.0
+ */
+declare function commandsFromModules(modules: ModuleMap, options?: CommandsFromModulesOptions): readonly ModuleCommand[];
 /**
  * Builds a parser that dispatches to discovered command handlers.
  *
@@ -215,7 +303,7 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  *         duplicated.
  * @since 1.1.0
  */
-declare function createProgramParser(commands: readonly Pick<DiscoveredCommand, "path" | "command">[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
+declare function createProgramParser(commands: readonly CommandEntry[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;
 /**
  * Discovers and runs a command program.
  *
@@ -246,4 +334,4 @@ interface ProgramHelpMetadata {
   readonly footer?: Message;
 }
 //#endregion
-export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, type CommandMetadata, type CommandPath, DiscoverCommandsOptions, DiscoveredCommand, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };
+export { type AnyCommand, type AnyStaticCommand, type Command, type CommandDefinition, CommandEntry, type CommandMetadata, type CommandPath, CommandsFromModulesOptions, DiscoverCommandsOptions, DiscoveredCommand, ModuleCommand, ModuleMap, ProgramHelpMetadata, ProgramInvocation, RunProgramDiscoveryOptions, RunProgramOptions, RunProgramStaticOptions, RuntimeExtensionOptions, type StaticCommand, commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/dist/index.js

@@ -6,7 +6,7 @@ import { command } from "@optique/core/primitives";
 import { mergeHidden } from "@optique/core/usage";
 import { runAsync } from "@optique/run";
 import { readdir, realpath, stat } from "node:fs/promises";
-import { relative, resolve, sep } from "node:path";
+import { posix, relative, resolve, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -62,9 +62,8 @@ async function discoverCommands(options) {
 		}
 		seen.set(key, filePath);
 		const mod = await import(pathToFileURL(filePath).href);
-		const commandDefinition = unwrapCommandExport(mod.default);
-		if (commandDefinition == null) throw new TypeError(`Module ${filePath} default export must be created with defineCommand().`);
-		if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${filePath} declares command path "${displayCommandPath(commandDefinition.path)}" but file path defines "${displayCommandPath(path)}".`);
+		const commandDefinition = commandFromModuleExport(filePath, mod.default);
+		validateDeclaredCommandPath(commandDefinition, path, filePath, "file path");
 		discovered.push({
 			path,
 			filePath,
@@ -74,6 +73,51 @@ async function discoverCommands(options) {
 	return sortCommands(discovered);
 }
 /**
+* Converts a static module map into command entries.
+*
+* This is useful for bundlers and single-file packagers that can statically
+* see module maps, such as `import.meta.glob(..., { eager: true })`, while
+* still deriving command paths from file-like module keys.
+*
+* @param modules Static module map keyed by module path.
+* @param options Module path derivation options.
+* @returns Command entries sorted by command path.
+* @throws {TypeError} If options are invalid, no command modules are found,
+*         command paths are duplicated, a module does not default-export a
+*         command created with `defineCommand()`, or an explicit command
+*         `path` does not match the module-derived path.
+* @since 1.2.0
+*/
+function commandsFromModules(modules, options = {}) {
+	if (modules == null || typeof modules !== "object") throw new TypeError("commandsFromModules() requires a module map object.");
+	const base = normalizeModuleBase(options.base);
+	const extensions = normalizeExtensions(options.extensions ?? getDefaultExtensions());
+	const entryFileName = normalizeEntryFileName(options.entryFileName);
+	const modulePaths = Object.keys(modules).toSorted((a, b) => a.localeCompare(b));
+	const seen = /* @__PURE__ */ new Map();
+	const discovered = [];
+	for (const modulePath of modulePaths) {
+		if (isDeclarationFile(posix.basename(modulePath)) || !extensions.some((ext) => modulePath.endsWith(ext))) continue;
+		const path = commandPathFromModulePath(base, modulePath, extensions, entryFileName);
+		const key = commandPathKey(path);
+		const previous = seen.get(key);
+		if (previous != null) {
+			const displayPath = displayCommandPath(path);
+			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${modulePath}.`);
+		}
+		seen.set(key, modulePath);
+		const commandDefinition = commandFromModuleExport(modulePath, modules[modulePath]);
+		validateDeclaredCommandPath(commandDefinition, path, modulePath, "module path");
+		discovered.push({
+			path,
+			modulePath,
+			command: commandDefinition
+		});
+	}
+	if (discovered.length < 1) throw new TypeError("No command modules found in module map.");
+	return sortCommands(discovered);
+}
+/**
 * Builds a parser that dispatches to discovered command handlers.
 *
 * @param commands Commands to compose.
@@ -148,6 +192,11 @@ function normalizeEntryFileName(entryFileName) {
 	if (normalized.length < 1 || normalized.includes("/") || normalized.includes("\\")) throw new TypeError(`Command entry file name must be a non-empty file name: ${normalized}`);
 	return normalized;
 }
+function normalizeModuleBase(base) {
+	if (base === void 0) return ".";
+	if (typeof base !== "string" || base.length < 1) throw new TypeError(`Module base path must be a non-empty string: ${base}`);
+	return normalizeModulePath(base);
+}
 async function collectCommandFiles(dir, extensions, activeDirs = /* @__PURE__ */ new Set()) {
 	const canonicalDir = await realpath(dir);
 	if (activeDirs.has(canonicalDir)) return [];
@@ -180,12 +229,33 @@ function isDeclarationFile(fileName) {
 	return /\.d\.[cm]?ts$/.test(fileName);
 }
 function commandPathFromFile(rootDir, filePath, extensions, entryFileName) {
-	const matchedExtension = extensions.find((ext) => filePath.endsWith(ext));
-	if (matchedExtension == null) throw new TypeError(`No configured extension matches ${filePath}.`);
-	const withoutExtension = filePath.slice(0, -matchedExtension.length);
+	const withoutExtension = stripCommandExtension(filePath, extensions);
 	const relativePath = relative(rootDir, withoutExtension);
 	const path = relativePath.split(sep).filter((segment) => segment.length > 0);
-	if (path.length < 1) throw new TypeError(`Command file ${filePath} does not define a path.`);
+	return commandPathFromSegments(path, filePath, entryFileName);
+}
+function commandPathFromModulePath(base, modulePath, extensions, entryFileName) {
+	const withoutExtension = stripCommandExtension(modulePath, extensions);
+	const relativePath = relativeModulePath(base, withoutExtension, modulePath);
+	const path = relativePath.split("/").filter((segment) => segment.length > 0);
+	return commandPathFromSegments(path, modulePath, entryFileName);
+}
+function stripCommandExtension(path, extensions) {
+	const matchedExtension = extensions.find((ext) => path.endsWith(ext));
+	if (matchedExtension == null) throw new TypeError(`No configured extension matches ${path}.`);
+	return path.slice(0, -matchedExtension.length);
+}
+function relativeModulePath(base, modulePath, originalModulePath) {
+	const normalizedPath = normalizeModulePath(modulePath);
+	const relativePath = posix.relative(base, normalizedPath);
+	if (relativePath.length < 1 || relativePath === ".." || relativePath.startsWith("../") || posix.isAbsolute(relativePath)) throw new TypeError(`Module path ${originalModulePath} is not under base path ${base}.`);
+	return relativePath;
+}
+function normalizeModulePath(path) {
+	return posix.normalize(path.replaceAll("\\", "/"));
+}
+function commandPathFromSegments(path, source, entryFileName) {
+	if (path.length < 1) throw new TypeError(`Command module ${source} does not define a path.`);
 	if (entryFileName !== false && path[path.length - 1] === entryFileName) return path.slice(0, -1);
 	return path;
 }
@@ -220,23 +290,38 @@ function isStaticRunProgramOptions(options) {
 	return hasCommands;
 }
 function staticCommandsToEntries(commands) {
-	return commands.map((command$1) => {
-		if (!isCommand(command$1)) throw new TypeError("Static command entries must be created with defineCommand().");
-		if (!isCommandPath(command$1.path)) throw new TypeError("Static command entries must declare a path.");
+	return commands.map((entry) => {
+		if (isCommandEntry(entry)) return entry;
+		if (!isCommand(entry)) throw new TypeError("Static command entries must be created with defineCommand().");
+		if (!isCommandPath(entry.path)) throw new TypeError("Static command entries must declare a path.");
 		return {
-			path: command$1.path,
-			command: command$1
+			path: entry.path,
+			command: entry
 		};
 	});
 }
+function isCommandEntry(value) {
+	return value != null && typeof value === "object" && isCommandPath(value.path) && isCommand(value.command);
+}
 function unwrapCommandExport(value) {
-	if (isCommand(value)) return value;
-	if (value != null && typeof value === "object") {
-		const nestedDefault = value.default;
-		if (isCommand(nestedDefault)) return nestedDefault;
+	let current = value;
+	for (let depth = 0; depth < 3; depth++) {
+		if (isCommand(current)) return current;
+		if (current == null || typeof current !== "object") return void 0;
+		const nestedDefault = current.default;
+		if (Object.is(nestedDefault, current)) return void 0;
+		current = nestedDefault;
 	}
 	return void 0;
 }
+function commandFromModuleExport(source, value) {
+	const commandDefinition = unwrapCommandExport(value);
+	if (commandDefinition == null) throw new TypeError(`Module ${source} default export must be created with defineCommand().`);
+	return commandDefinition;
+}
+function validateDeclaredCommandPath(commandDefinition, path, source, sourcePathLabel) {
+	if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${source} declares command path "${displayCommandPath(commandDefinition.path)}" but ${sourcePathLabel} defines "${displayCommandPath(path)}".`);
+}
 function buildCommandTree(commands) {
 	const root = { children: /* @__PURE__ */ new Map() };
 	for (const entry of commands) {
@@ -666,4 +751,4 @@ function isProgramInvocation(value) {
 }
 
 //#endregion
-export { createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };
+export { commandsFromModules, createProgramParser, defineCommand, discoverCommands, getDefaultExtensions, isCommand, runProgram };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/discover",
-  "version": "1.2.0-dev.2167",
+  "version": "1.2.0-dev.2169",
   "description": "Runtime-aware command discovery for Optique CLI programs",
   "keywords": [
     "CLI",
@@ -68,8 +68,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.2.0-dev.2167+d62b9212",
-    "@optique/run": "1.2.0-dev.2167+d62b9212"
+    "@optique/core": "1.2.0-dev.2169+209bc0fc",
+    "@optique/run": "1.2.0-dev.2169+209bc0fc"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",