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

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,52 @@ 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()),
+const modules = import.meta.glob("./commands/**/*.ts", {
+  eager: true,
+});
+
+await runProgram({
+  commands: commandsFromModules(modules, {
+    base: "./commands",
+    extensions: [".ts"],
   }),
   metadata: {
-    brief: message`Add a user.`,
-  },
-  handler(value) {
-    console.log(`Adding ${value.name}.`);
+    name: "admin",
+    version: "1.0.0",
+    brief: message`Administrative command-line tools.`,
   },
 });
+~~~~
+
+`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 })`.
+
+If you do not want to maintain the static module map by hand, generate one:
+
+~~~~ bash
+optique-discover ./commands --output ./commands.generated.ts --extension .ts
+~~~~
+
+Then import the generated module from your CLI entry point:
+
+~~~~ typescript
+// cli.ts
+import { runProgram } from "@optique/discover";
+import { message } from "@optique/core/message";
+import commands from "./commands.generated.ts";
 
 await runProgram({
-  commands: [addUser],
+  commands,
   metadata: {
     name: "admin",
     version: "1.0.0",
@@ -113,6 +134,9 @@ await runProgram({
 });
 ~~~~
 
+Use `--watch` during development to regenerate only when command files are
+added, removed, or renamed.
+
 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 +144,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/chunk-CUT6urMc.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/cli.cjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+require('./command-CUn2_NIA.cjs');
+require('./src-BYGxdHGJ.cjs');
+const require_generator = require('./generator-e4RwnDKG.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"));
+const __optique_core_modifiers = require_chunk.__toESM(require("@optique/core/modifiers"));
+const __optique_core_primitives = require_chunk.__toESM(require("@optique/core/primitives"));
+const __optique_core_program = require_chunk.__toESM(require("@optique/core/program"));
+const __optique_core_valueparser = require_chunk.__toESM(require("@optique/core/valueparser"));
+const __optique_run = require_chunk.__toESM(require("@optique/run"));
+const node_process = require_chunk.__toESM(require("node:process"));
+
+//#region deno.json
+var name = "@optique/discover";
+var version = "1.2.0-dev.2179+919d5ae8";
+var license = "MIT";
+var exports$1 = {
+	".": "./src/index.ts",
+	"./command": "./src/command.ts",
+	"./generator": "./src/generator.ts",
+	"./cli": "./src/cli.ts"
+};
+var imports = { "#src/": "./src/" };
+var exclude = [
+	"dist/",
+	"node_modules",
+	"tsdown.config.ts"
+];
+var tasks = {
+	"build": "pnpm build",
+	"test": "deno test --allow-read --allow-write --allow-env",
+	"test:node": {
+		"dependencies": ["build"],
+		"command": "node --test"
+	},
+	"test:bun": {
+		"dependencies": ["build"],
+		"command": "bun test"
+	},
+	"test-all": { "dependencies": [
+		"test",
+		"test:node",
+		"test:bun"
+	] }
+};
+var deno_default = {
+	name,
+	version,
+	license,
+	exports: exports$1,
+	imports,
+	exclude,
+	tasks
+};
+
+//#endregion
+//#region src/cli.ts
+const EXIT_GENERATION_FAILED = 1;
+const EXIT_INVALID_OPTIONS = 2;
+const cliProgram = (0, __optique_core_program.defineProgram)({
+	parser: (0, __optique_core_constructs.object)({
+		dir: (0, __optique_core_primitives.argument)((0, __optique_core_valueparser.string)({ metavar: "DIR" }), { description: __optique_core_message.message`Directory containing command modules.` }),
+		outputFile: (0, __optique_core_primitives.option)("-o", "--output", (0, __optique_core_valueparser.string)({ metavar: "FILE" }), { description: __optique_core_message.message`Generated TypeScript module path.` }),
+		base: (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)("--base", (0, __optique_core_valueparser.string)({ metavar: "PATH" }), { description: __optique_core_message.message`Module map base path passed to commandsFromModules().
+Defaults to the command directory relative to the generated module.` })),
+		extensions: (0, __optique_core_modifiers.withDefault)((0, __optique_core_modifiers.multiple)((0, __optique_core_primitives.option)("--extension", (0, __optique_core_valueparser.string)({ metavar: "EXT" }))), []),
+		entryFileName: (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)("--entry-file-name", (0, __optique_core_valueparser.string)({ metavar: "NAME" }), { description: __optique_core_message.message`File name that maps to the containing command path.
+Defaults to commandsFromModules() behavior.` })),
+		noEntryFileName: (0, __optique_core_primitives.option)("--no-entry-file-name", { description: __optique_core_message.message`Treat entry files as ordinary command names.` }),
+		watch: (0, __optique_core_primitives.option)("--watch", { description: __optique_core_message.message`Regenerate when command files are added, removed,
+or renamed.` })
+	}),
+	metadata: {
+		name: "optique-discover",
+		version: deno_default.version,
+		brief: __optique_core_message.message`Generate static command modules for @optique/discover`
+	}
+});
+/**
+* Runs the optique-discover command-line interface.
+*
+* @returns A promise that resolves after generation or watch mode finishes.
+* @since 1.2.0
+*/
+async function main() {
+	const args = (0, __optique_run.runSync)(cliProgram, {
+		help: "option",
+		version: {
+			value: deno_default.version,
+			option: true
+		}
+	});
+	if (args.noEntryFileName && args.entryFileName != null) {
+		(0, __optique_run.printError)(__optique_core_message.message`Use either --entry-file-name or --no-entry-file-name, not both.`, { exitCode: EXIT_INVALID_OPTIONS });
+		return;
+	}
+	const options = {
+		dir: args.dir,
+		outputFile: args.outputFile,
+		...args.base != null ? { base: args.base } : {},
+		...args.extensions.length > 0 ? { extensions: args.extensions } : {},
+		...args.noEntryFileName ? { entryFileName: false } : args.entryFileName != null ? { entryFileName: args.entryFileName } : {}
+	};
+	try {
+		if (args.watch) await require_generator.watchCommandsModule({
+			...options,
+			onGenerate(result) {
+				writeGeneratedMessage(result.files.length);
+			},
+			onError(error) {
+				printGenerationError(error);
+			}
+		});
+		else {
+			const result = await require_generator.writeCommandsModule(options);
+			writeGeneratedMessage(result.files.length);
+		}
+	} catch (error) {
+		printGenerationError(error, EXIT_GENERATION_FAILED);
+	}
+}
+function printGenerationError(error, exitCode) {
+	const messageText = error instanceof Error ? error.message : String(error);
+	if (exitCode == null) (0, __optique_run.printError)(__optique_core_message.message`Failed to generate command module: ${messageText}`);
+	else (0, __optique_run.printError)(__optique_core_message.message`Failed to generate command module: ${messageText}`, { exitCode });
+}
+function writeGeneratedMessage(count) {
+	const noun = count === 1 ? "command module" : "command modules";
+	console.log(`Generated ${count} ${noun}.`);
+}
+const isMain = require_main_check.isMainModuleUrl({
+	importMetaMain: "main" in import.meta ? void 0 : void 0,
+	moduleUrl: require("url").pathToFileURL(__filename).href,
+	argvEntry: node_process.default.argv[1]
+});
+if (isMain) main().catch((error) => {
+	printGenerationError(error, EXIT_GENERATION_FAILED);
+});
+
+//#endregion
+exports.main = main;

package/dist/cli.d.cts

@@ -0,0 +1,10 @@
+//#region src/cli.d.ts
+/**
+ * Runs the optique-discover command-line interface.
+ *
+ * @returns A promise that resolves after generation or watch mode finishes.
+ * @since 1.2.0
+ */
+declare function main(): Promise<void>;
+//#endregion
+export { main };

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+//#region src/cli.d.ts
+/**
+ * Runs the optique-discover command-line interface.
+ *
+ * @returns A promise that resolves after generation or watch mode finishes.
+ * @since 1.2.0
+ */
+declare function main(): Promise<void>;
+//#endregion
+export { main };

package/dist/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import "./command-DO5zgkvS.js";
+import "./src-Ci75oZo-.js";
+import { watchCommandsModule, writeCommandsModule } from "./generator-C12pIuFe.js";
+import { isMainModuleUrl } from "./main-check-mMnKfUZs.js";
+import { object } from "@optique/core/constructs";
+import { message } from "@optique/core/message";
+import { multiple, optional, withDefault } from "@optique/core/modifiers";
+import { argument, option } from "@optique/core/primitives";
+import { defineProgram } from "@optique/core/program";
+import { string } from "@optique/core/valueparser";
+import { printError, runSync } from "@optique/run";
+import process from "node:process";
+
+//#region deno.json
+var name = "@optique/discover";
+var version = "1.2.0-dev.2179+919d5ae8";
+var license = "MIT";
+var exports = {
+	".": "./src/index.ts",
+	"./command": "./src/command.ts",
+	"./generator": "./src/generator.ts",
+	"./cli": "./src/cli.ts"
+};
+var imports = { "#src/": "./src/" };
+var exclude = [
+	"dist/",
+	"node_modules",
+	"tsdown.config.ts"
+];
+var tasks = {
+	"build": "pnpm build",
+	"test": "deno test --allow-read --allow-write --allow-env",
+	"test:node": {
+		"dependencies": ["build"],
+		"command": "node --test"
+	},
+	"test:bun": {
+		"dependencies": ["build"],
+		"command": "bun test"
+	},
+	"test-all": { "dependencies": [
+		"test",
+		"test:node",
+		"test:bun"
+	] }
+};
+var deno_default = {
+	name,
+	version,
+	license,
+	exports,
+	imports,
+	exclude,
+	tasks
+};
+
+//#endregion
+//#region src/cli.ts
+const EXIT_GENERATION_FAILED = 1;
+const EXIT_INVALID_OPTIONS = 2;
+const cliProgram = defineProgram({
+	parser: object({
+		dir: argument(string({ metavar: "DIR" }), { description: message`Directory containing command modules.` }),
+		outputFile: option("-o", "--output", string({ metavar: "FILE" }), { description: message`Generated TypeScript module path.` }),
+		base: optional(option("--base", string({ metavar: "PATH" }), { description: message`Module map base path passed to commandsFromModules().
+Defaults to the command directory relative to the generated module.` })),
+		extensions: withDefault(multiple(option("--extension", string({ metavar: "EXT" }))), []),
+		entryFileName: optional(option("--entry-file-name", string({ metavar: "NAME" }), { description: message`File name that maps to the containing command path.
+Defaults to commandsFromModules() behavior.` })),
+		noEntryFileName: option("--no-entry-file-name", { description: message`Treat entry files as ordinary command names.` }),
+		watch: option("--watch", { description: message`Regenerate when command files are added, removed,
+or renamed.` })
+	}),
+	metadata: {
+		name: "optique-discover",
+		version: deno_default.version,
+		brief: message`Generate static command modules for @optique/discover`
+	}
+});
+/**
+* Runs the optique-discover command-line interface.
+*
+* @returns A promise that resolves after generation or watch mode finishes.
+* @since 1.2.0
+*/
+async function main() {
+	const args = runSync(cliProgram, {
+		help: "option",
+		version: {
+			value: deno_default.version,
+			option: true
+		}
+	});
+	if (args.noEntryFileName && args.entryFileName != null) {
+		printError(message`Use either --entry-file-name or --no-entry-file-name, not both.`, { exitCode: EXIT_INVALID_OPTIONS });
+		return;
+	}
+	const options = {
+		dir: args.dir,
+		outputFile: args.outputFile,
+		...args.base != null ? { base: args.base } : {},
+		...args.extensions.length > 0 ? { extensions: args.extensions } : {},
+		...args.noEntryFileName ? { entryFileName: false } : args.entryFileName != null ? { entryFileName: args.entryFileName } : {}
+	};
+	try {
+		if (args.watch) await watchCommandsModule({
+			...options,
+			onGenerate(result) {
+				writeGeneratedMessage(result.files.length);
+			},
+			onError(error) {
+				printGenerationError(error);
+			}
+		});
+		else {
+			const result = await writeCommandsModule(options);
+			writeGeneratedMessage(result.files.length);
+		}
+	} catch (error) {
+		printGenerationError(error, EXIT_GENERATION_FAILED);
+	}
+}
+function printGenerationError(error, exitCode) {
+	const messageText = error instanceof Error ? error.message : String(error);
+	if (exitCode == null) printError(message`Failed to generate command module: ${messageText}`);
+	else printError(message`Failed to generate command module: ${messageText}`, { exitCode });
+}
+function writeGeneratedMessage(count) {
+	const noun = count === 1 ? "command module" : "command modules";
+	console.log(`Generated ${count} ${noun}.`);
+}
+const isMain = isMainModuleUrl({
+	importMetaMain: "main" in import.meta ? import.meta.main : void 0,
+	moduleUrl: import.meta.url,
+	argvEntry: process.argv[1]
+});
+if (isMain) main().catch((error) => {
+	printGenerationError(error, EXIT_GENERATION_FAILED);
+});
+
+//#endregion
+export { main };

package/dist/command.cjs

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

package/dist/command.d.ts

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