@optique/discover 1.1.0 → 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,10 +105,20 @@ 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
 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.  `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/{command-DZA06E08.cjs → command-B0lV6NBO.cjs}

@@ -21,10 +21,10 @@ function isCommand(value) {
 	return value != null && typeof value === "object" && value[commandBrand] === true && (value.path == null || isCommandPath(value.path)) && isParser(value.parser) && typeof value.handler === "function";
 }
 function validateCommandPath(path) {
-	if (!isCommandPath(path)) throw new TypeError("Command path must be a non-empty array of non-empty strings.");
+	if (!isCommandPath(path)) throw new TypeError("Command path must be an array of non-empty strings.");
 }
 function isCommandPath(path) {
-	return Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string" && segment.length > 0);
+	return Array.isArray(path) && path.every((segment) => typeof segment === "string" && segment.length > 0);
 }
 function isParser(value) {
 	return value != null && typeof value === "object" && typeof value.parse === "function" && typeof value.complete === "function" && typeof value.suggest === "function" && typeof value.getDocFragments === "function" && (value.mode === "sync" || value.mode === "async");

package/dist/{command-y_A3hG0g.js → command-DO5zgkvS.js}

@@ -20,10 +20,10 @@ function isCommand(value) {
 	return value != null && typeof value === "object" && value[commandBrand] === true && (value.path == null || isCommandPath(value.path)) && isParser(value.parser) && typeof value.handler === "function";
 }
 function validateCommandPath(path) {
-	if (!isCommandPath(path)) throw new TypeError("Command path must be a non-empty array of non-empty strings.");
+	if (!isCommandPath(path)) throw new TypeError("Command path must be an array of non-empty strings.");
 }
 function isCommandPath(path) {
-	return Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string" && segment.length > 0);
+	return Array.isArray(path) && path.every((segment) => typeof segment === "string" && segment.length > 0);
 }
 function isParser(value) {
 	return value != null && typeof value === "object" && typeof value.parse === "function" && typeof value.complete === "function" && typeof value.suggest === "function" && typeof value.getDocFragments === "function" && (value.mode === "sync" || value.mode === "async");

package/dist/{command-2HtR3-TV.d.cts → command-DSHBTa5c.d.cts}

@@ -14,11 +14,13 @@ declare const commandBrand: unique symbol;
  */
 type CommandMetadata = CommandOptions;
 /**
- * Non-empty command path used by static command registration.
+ * Command path used by static command registration.
+ *
+ * An empty path represents the root command.
  *
  * @since 1.1.0
  */
-type CommandPath = readonly [string, ...string[]];
+type CommandPath = readonly string[];
 /**
  * Input accepted by {@link defineCommand}.
  *
@@ -29,6 +31,7 @@ type CommandPath = readonly [string, ...string[]];
 interface CommandDefinition<M extends Mode, T> {
   /**
    * Command path used when commands are passed directly to `runProgram()`.
+   * Use an empty path (`[]`) to register the root command.
    *
    * File-based discovery derives the command path from the file name and uses
    * this field only to validate that the declared path matches.

package/dist/{command-BAVhIzfI.d.ts → command-DyiVIMUh.d.ts}

@@ -14,11 +14,13 @@ declare const commandBrand: unique symbol;
  */
 type CommandMetadata = CommandOptions;
 /**
- * Non-empty command path used by static command registration.
+ * Command path used by static command registration.
+ *
+ * An empty path represents the root command.
  *
  * @since 1.1.0
  */
-type CommandPath = readonly [string, ...string[]];
+type CommandPath = readonly string[];
 /**
  * Input accepted by {@link defineCommand}.
  *
@@ -29,6 +31,7 @@ type CommandPath = readonly [string, ...string[]];
 interface CommandDefinition<M extends Mode, T> {
   /**
    * Command path used when commands are passed directly to `runProgram()`.
+   * Use an empty path (`[]`) to register the root command.
    *
    * File-based discovery derives the command path from the file name and uses
    * this field only to validate that the declared path matches.

package/dist/command.cjs

@@ -1,4 +1,4 @@
-const require_command = require('./command-DZA06E08.cjs');
+const require_command = require('./command-B0lV6NBO.cjs');
 
 exports.defineCommand = require_command.defineCommand;
 exports.isCommand = require_command.isCommand;

package/dist/command.d.cts

@@ -1,2 +1,2 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-2HtR3-TV.cjs";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DSHBTa5c.cjs";
 export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };

package/dist/command.d.ts

@@ -1,2 +1,2 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-BAVhIzfI.js";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DyiVIMUh.js";
 export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };

package/dist/command.js

@@ -1,3 +1,3 @@
-import { defineCommand, isCommand } from "./command-y_A3hG0g.js";
+import { defineCommand, isCommand } from "./command-DO5zgkvS.js";
 
 export { defineCommand, isCommand };