@optique/discover 1.1.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025–2026 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+@optique/discover
+=================
+
+Runtime-aware command discovery for Optique CLI programs.
+
+Use *@optique/discover* when your CLI has many commands and you want the
+command tree to come from files instead of one large `or(command(...))`
+definition.  Each command module exports a `defineCommand()` result, and
+`runProgram()` discovers those modules, builds a parser tree, enables help,
+version, and shell completion, then dispatches to the selected command's
+handler.
+
+> [!WARNING]
+> *@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 })`.
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/discover jsr:@optique/core jsr:@optique/run
+npm  add     @optique/discover     @optique/core     @optique/run
+pnpm add     @optique/discover     @optique/core     @optique/run
+yarn add     @optique/discover     @optique/core     @optique/run
+~~~~
+
+
+Quick example
+-------------
+
+Create command modules under a directory:
+
+~~~~ typescript
+// commands/user/add.ts
+import { defineCommand } from "@optique/discover/command";
+import { object } from "@optique/core/constructs";
+import { message } from "@optique/core/message";
+import { option } from "@optique/core/primitives";
+import { string } from "@optique/core/valueparser";
+
+export default defineCommand({
+  parser: object({
+    name: option("--name", string()),
+  }),
+  metadata: {
+    brief: message`Add a user.`,
+  },
+  handler(value) {
+    console.log(`Adding ${value.name}.`);
+  },
+});
+~~~~
+
+Then run the discovered program from your entry point:
+
+~~~~ typescript
+// cli.ts
+import { runProgram } from "@optique/discover";
+import { message } from "@optique/core/message";
+
+await runProgram({
+  dir: new URL("./commands/", import.meta.url),
+  metadata: {
+    name: "admin",
+    version: "1.0.0",
+    brief: message`Administrative command-line tools.`,
+  },
+});
+~~~~
+
+The file path becomes the command path, so the example above is available as:
+
+~~~~ bash
+admin user add --name Ada
+admin --help
+admin completion bash
+~~~~
+
+For bundlers and single-file packagers, import commands manually and declare
+their paths in the command definitions:
+
+~~~~ typescript
+// cli.ts
+import { defineCommand, runProgram } from "@optique/discover";
+import { object } from "@optique/core/constructs";
+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}.`);
+  },
+});
+
+await runProgram({
+  commands: [addUser],
+  metadata: {
+    name: "admin",
+    version: "1.0.0",
+    brief: message`Administrative command-line tools.`,
+  },
+});
+~~~~
+
+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.
+
+For more resources, see the [docs] and the [*examples/*](/examples/)
+directory.
+
+[docs]: https://optique.dev/concepts/discover

package/dist/command-2HtR3-TV.d.cts

@@ -0,0 +1,136 @@
+import { CommandOptions } from "@optique/core/primitives";
+import { Mode, Parser } from "@optique/core/parser";
+
+//#region src/command.d.ts
+declare const commandBrand: unique symbol;
+/**
+ * Metadata shown for a discovered command.
+ *
+ * This uses the same shape as Optique's `command()` options so discovered
+ * commands can provide descriptions, usage overrides, visibility, and custom
+ * command-level errors.
+ *
+ * @since 1.1.0
+ */
+type CommandMetadata = CommandOptions;
+/**
+ * Non-empty command path used by static command registration.
+ *
+ * @since 1.1.0
+ */
+type CommandPath = readonly [string, ...string[]];
+/**
+ * Input accepted by {@link defineCommand}.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @since 1.1.0
+ */
+interface CommandDefinition<M extends Mode, T> {
+  /**
+   * Command path used when commands are passed directly to `runProgram()`.
+   *
+   * File-based discovery derives the command path from the file name and uses
+   * this field only to validate that the declared path matches.
+   */
+  readonly path?: CommandPath;
+  /**
+   * Parser for this command's command-specific arguments and options.
+   */
+  readonly parser: Parser<M, T, unknown>;
+  /**
+   * Metadata used in help output and shell completion.
+   */
+  readonly metadata?: CommandMetadata;
+  /**
+   * Handles the parsed command value.
+   *
+   * @param value Parsed command value.
+   * @returns Nothing, or a promise that resolves when command handling
+   *          completes.
+   */
+  readonly handler: (value: T) => 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.
+ * @since 1.1.0
+ */
+interface Command<M extends Mode, T> extends CommandDefinition<M, T> {
+  /**
+   * Internal marker used to validate discovered modules.
+   *
+   * @internal
+   */
+  readonly [commandBrand]: true;
+}
+/**
+ * A command that declares its own command path.
+ *
+ * Static `runProgram({ commands })` registration accepts this shape.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @since 1.1.0
+ */
+interface StaticCommand<M extends Mode, T> extends Command<M, T> {
+  /**
+   * Command path used by static command registration.
+   */
+  readonly path: CommandPath;
+}
+/**
+ * A command with its handler value type erased.
+ *
+ * This type is used by discovery APIs that collect commands with different
+ * parsed value types.  The handler cannot be called directly without first
+ * recovering the parser's value type.
+ *
+ * @since 1.1.0
+ */
+type AnyCommand = Omit<Command<Mode, unknown>, "handler"> & {
+  /**
+   * Erased command handler.
+   */
+  readonly handler: (value: 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"> & {
+  /**
+   * Erased command handler.
+   */
+  readonly handler: (value: never) => void | Promise<void>;
+};
+/**
+ * Defines a command module for `@optique/discover`.
+ *
+ * This helper returns its argument unchanged while preserving parser value
+ * inference for the handler callback.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @param command The command definition.
+ * @returns The same command definition with inferred types.
+ * @throws {TypeError} If the parser, path, or handler is missing or malformed.
+ * @since 1.1.0
+ */
+declare function defineCommand<M extends Mode, T>(command: CommandDefinition<M, T> & {
+  readonly path: CommandPath;
+}): StaticCommand<M, T>;
+declare function defineCommand<M extends Mode, T>(command: CommandDefinition<M, T>): Command<M, T>;
+/**
+ * Returns whether a value is a command created by {@link defineCommand}.
+ *
+ * @param value The value to inspect.
+ * @returns `true` when the value is a discovered command definition.
+ * @since 1.1.0
+ */
+declare function isCommand(value: unknown): value is AnyCommand;
+//#endregion
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };

package/dist/command-BAVhIzfI.d.ts

@@ -0,0 +1,136 @@
+import { CommandOptions } from "@optique/core/primitives";
+import { Mode, Parser } from "@optique/core/parser";
+
+//#region src/command.d.ts
+declare const commandBrand: unique symbol;
+/**
+ * Metadata shown for a discovered command.
+ *
+ * This uses the same shape as Optique's `command()` options so discovered
+ * commands can provide descriptions, usage overrides, visibility, and custom
+ * command-level errors.
+ *
+ * @since 1.1.0
+ */
+type CommandMetadata = CommandOptions;
+/**
+ * Non-empty command path used by static command registration.
+ *
+ * @since 1.1.0
+ */
+type CommandPath = readonly [string, ...string[]];
+/**
+ * Input accepted by {@link defineCommand}.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @since 1.1.0
+ */
+interface CommandDefinition<M extends Mode, T> {
+  /**
+   * Command path used when commands are passed directly to `runProgram()`.
+   *
+   * File-based discovery derives the command path from the file name and uses
+   * this field only to validate that the declared path matches.
+   */
+  readonly path?: CommandPath;
+  /**
+   * Parser for this command's command-specific arguments and options.
+   */
+  readonly parser: Parser<M, T, unknown>;
+  /**
+   * Metadata used in help output and shell completion.
+   */
+  readonly metadata?: CommandMetadata;
+  /**
+   * Handles the parsed command value.
+   *
+   * @param value Parsed command value.
+   * @returns Nothing, or a promise that resolves when command handling
+   *          completes.
+   */
+  readonly handler: (value: T) => 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.
+ * @since 1.1.0
+ */
+interface Command<M extends Mode, T> extends CommandDefinition<M, T> {
+  /**
+   * Internal marker used to validate discovered modules.
+   *
+   * @internal
+   */
+  readonly [commandBrand]: true;
+}
+/**
+ * A command that declares its own command path.
+ *
+ * Static `runProgram({ commands })` registration accepts this shape.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @since 1.1.0
+ */
+interface StaticCommand<M extends Mode, T> extends Command<M, T> {
+  /**
+   * Command path used by static command registration.
+   */
+  readonly path: CommandPath;
+}
+/**
+ * A command with its handler value type erased.
+ *
+ * This type is used by discovery APIs that collect commands with different
+ * parsed value types.  The handler cannot be called directly without first
+ * recovering the parser's value type.
+ *
+ * @since 1.1.0
+ */
+type AnyCommand = Omit<Command<Mode, unknown>, "handler"> & {
+  /**
+   * Erased command handler.
+   */
+  readonly handler: (value: 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"> & {
+  /**
+   * Erased command handler.
+   */
+  readonly handler: (value: never) => void | Promise<void>;
+};
+/**
+ * Defines a command module for `@optique/discover`.
+ *
+ * This helper returns its argument unchanged while preserving parser value
+ * inference for the handler callback.
+ *
+ * @template M The mode of the command parser.
+ * @template T The parsed value passed to the command handler.
+ * @param command The command definition.
+ * @returns The same command definition with inferred types.
+ * @throws {TypeError} If the parser, path, or handler is missing or malformed.
+ * @since 1.1.0
+ */
+declare function defineCommand<M extends Mode, T>(command: CommandDefinition<M, T> & {
+  readonly path: CommandPath;
+}): StaticCommand<M, T>;
+declare function defineCommand<M extends Mode, T>(command: CommandDefinition<M, T>): Command<M, T>;
+/**
+ * Returns whether a value is a command created by {@link defineCommand}.
+ *
+ * @param value The value to inspect.
+ * @returns `true` when the value is a discovered command definition.
+ * @since 1.1.0
+ */
+declare function isCommand(value: unknown): value is AnyCommand;
+//#endregion
+export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };

package/dist/command-DZA06E08.cjs

@@ -0,0 +1,45 @@
+
+//#region src/command.ts
+const commandBrand = Symbol.for("@optique/discover/command");
+function defineCommand(command) {
+	if (!isParser(command.parser)) throw new TypeError("Command parser must be an Optique parser.");
+	if (command.path != null) validateCommandPath(command.path);
+	if (typeof command.handler !== "function") throw new TypeError("Command handler must be a function.");
+	return {
+		...command,
+		[commandBrand]: true
+	};
+}
+/**
+* Returns whether a value is a command created by {@link defineCommand}.
+*
+* @param value The value to inspect.
+* @returns `true` when the value is a discovered command definition.
+* @since 1.1.0
+*/
+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.");
+}
+function isCommandPath(path) {
+	return Array.isArray(path) && path.length > 0 && 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");
+}
+
+//#endregion
+Object.defineProperty(exports, 'defineCommand', {
+  enumerable: true,
+  get: function () {
+    return defineCommand;
+  }
+});
+Object.defineProperty(exports, 'isCommand', {
+  enumerable: true,
+  get: function () {
+    return isCommand;
+  }
+});

package/dist/command-y_A3hG0g.js

@@ -0,0 +1,33 @@
+//#region src/command.ts
+const commandBrand = Symbol.for("@optique/discover/command");
+function defineCommand(command) {
+	if (!isParser(command.parser)) throw new TypeError("Command parser must be an Optique parser.");
+	if (command.path != null) validateCommandPath(command.path);
+	if (typeof command.handler !== "function") throw new TypeError("Command handler must be a function.");
+	return {
+		...command,
+		[commandBrand]: true
+	};
+}
+/**
+* Returns whether a value is a command created by {@link defineCommand}.
+*
+* @param value The value to inspect.
+* @returns `true` when the value is a discovered command definition.
+* @since 1.1.0
+*/
+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.");
+}
+function isCommandPath(path) {
+	return Array.isArray(path) && path.length > 0 && 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");
+}
+
+//#endregion
+export { defineCommand, isCommand };

package/dist/command.cjs

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

package/dist/command.d.cts

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

package/dist/command.d.ts

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

package/dist/command.js

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