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

package/README.md

@@ -110,6 +110,33 @@ 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,
+  metadata: {
+    name: "admin",
+    version: "1.0.0",
+    brief: message`Administrative command-line tools.`,
+  },
+});
+~~~~
+
+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

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

package/dist/generator-C12pIuFe.js

@@ -0,0 +1,270 @@
+import { getDefaultExtensions } from "./src-Ci75oZo-.js";
+import { mkdir, readdir, realpath, stat, writeFile } from "node:fs/promises";
+import { dirname, posix, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/generator.ts
+/**
+* Generates a TypeScript module that exports command entries.
+*
+* @param options Generation options.
+* @returns The generated source code and command module metadata.
+* @throws {TypeError} If options are invalid or no command modules are found.
+* @since 1.2.0
+*/
+async function generateCommandsModule(options) {
+	const normalized = normalizeGenerateOptions(options);
+	const files = await collectGeneratedCommandFiles(normalized);
+	return generateCommandsModuleFromFiles(normalized, files);
+}
+/**
+* Writes a generated command module to disk.
+*
+* @param options Generation options.
+* @returns The generated source code and command module metadata.
+* @throws {TypeError} If options are invalid or no command modules are found.
+* @throws {Error} If the generated module cannot be written.
+* @since 1.2.0
+*/
+async function writeCommandsModule(options) {
+	const result = await generateCommandsModule(options);
+	await mkdir(dirname(pathFromFile(options.outputFile)), { recursive: true });
+	await writeFile(pathFromFile(options.outputFile), result.code, "utf-8");
+	return result;
+}
+/**
+* Watches the command file set and rewrites the generated module when it
+* changes.
+*
+* Content-only edits do not trigger regeneration because they do not change
+* the static module map.
+*
+* @param options Watch options.
+* @returns A promise that resolves when the watch signal is aborted.
+* @throws {TypeError} If options are invalid.
+* @since 1.2.0
+*/
+async function watchCommandsModule(options) {
+	const normalized = normalizeGenerateOptions(options);
+	const intervalMs = options.intervalMs ?? 250;
+	if (!Number.isInteger(intervalMs) || intervalMs < 1) throw new TypeError(`Watch interval must be a positive integer: ${intervalMs}`);
+	let previousSignature;
+	while (options.signal?.aborted !== true) {
+		try {
+			const files = await collectGeneratedCommandFiles(normalized, { allowEmpty: true });
+			const signature = files.map((file) => file.filePath).join("\0");
+			if (signature !== previousSignature) {
+				const result = generateCommandsModuleFromFiles(normalized, files);
+				await mkdir(dirname(normalized.outputFile), { recursive: true });
+				await writeFile(normalized.outputFile, result.code, "utf-8");
+				options.onGenerate?.(result);
+				previousSignature = signature;
+			}
+		} catch (error) {
+			options.onError?.(error);
+		}
+		await delay(intervalMs, options.signal);
+	}
+}
+async function collectGeneratedCommandFiles(options, collectOptions = {}) {
+	const filePaths = await collectCommandFiles(options.dir, options.extensions, options.outputFile);
+	if (filePaths.length < 1) {
+		if (collectOptions.allowEmpty === true) return [];
+		throw new TypeError(`No command modules found in ${options.dir}.`);
+	}
+	const files = filePaths.map((filePath, index) => {
+		const importSpecifier = relativeImportSpecifier(options.outputDir, filePath);
+		const defaultModulePath = relativeModuleSpecifier(options.outputDir, filePath);
+		const modulePath = options.baseWasProvided ? joinModulePath(options.base, normalizeRelativePath(relative(options.dir, filePath))) : defaultModulePath;
+		return {
+			filePath,
+			importSpecifier,
+			modulePath,
+			identifier: `cmd${index}`
+		};
+	});
+	rejectDuplicateCommandPaths(files, options);
+	return files;
+}
+function generateCommandsModuleFromFiles(options, files) {
+	if (files.length < 1) return {
+		code: "import type { ModuleCommand } from \"@optique/discover\";\n\nexport default [] satisfies readonly ModuleCommand[];\n",
+		files
+	};
+	const imports = files.map(formatCommandModuleImport).join("\n");
+	const entries = files.map((file) => `    ${JSON.stringify(file.modulePath)}: ${file.identifier},`).join("\n");
+	const optionEntries = [
+		`    base: ${JSON.stringify(options.base)},`,
+		`    extensions: ${formatStringArray(options.extensions)},`,
+		...options.entryFileName === void 0 ? [] : [`    entryFileName: ${JSON.stringify(options.entryFileName)},`]
+	].join("\n");
+	return {
+		code: `import { commandsFromModules } from "@optique/discover";\n${imports}\n\nexport default commandsFromModules(\n  {\n${entries}\n  },\n  {\n${optionEntries}\n  },\n);\n`,
+		files
+	};
+}
+function formatCommandModuleImport(file) {
+	const importSpecifier = JSON.stringify(file.importSpecifier);
+	const importDeclaration = `import * as ${file.identifier} from ${importSpecifier};`;
+	if (requiresTypeScriptResolutionIgnore(file.importSpecifier)) return `// @ts-ignore: Percent-encoded import preserves URL-significant command paths.\n${importDeclaration}`;
+	return importDeclaration;
+}
+function requiresTypeScriptResolutionIgnore(specifier) {
+	return specifier.includes("%");
+}
+function normalizeGenerateOptions(options) {
+	const dir = resolve(pathFromFile(options.dir));
+	const outputFile = resolve(pathFromFile(options.outputFile));
+	const outputDir = dirname(outputFile);
+	const baseWasProvided = options.base !== void 0;
+	const base = normalizeBase(options.base ?? relativeModuleSpecifier(outputDir, dir));
+	return {
+		dir,
+		outputFile,
+		outputDir,
+		base,
+		baseWasProvided,
+		extensions: normalizeExtensions(options.extensions ?? getDefaultExtensions()),
+		entryFileName: normalizeEntryFileName(options.entryFileName)
+	};
+}
+function pathFromFile(path) {
+	return typeof path === "string" ? path : fileURLToPath(path);
+}
+function normalizeBase(base) {
+	if (typeof base !== "string" || base.length < 1) throw new TypeError(`Module base path must be a non-empty string: ${base}`);
+	return normalizeModulePath(base);
+}
+function normalizeExtensions(extensions) {
+	if (extensions.length < 1) throw new TypeError("At least one command file extension is required.");
+	const normalized = [];
+	for (const extension of extensions) {
+		if (!extension.startsWith(".") || extension.length < 2) throw new TypeError(`Command file extension must start with a dot: ${extension}`);
+		if (!normalized.includes(extension)) normalized.push(extension);
+	}
+	return normalized.toSorted((a, b) => b.length - a.length || a.localeCompare(b));
+}
+function normalizeEntryFileName(entryFileName) {
+	if (entryFileName === void 0) return void 0;
+	if (entryFileName === false) return false;
+	if (typeof entryFileName !== "string" || entryFileName.length < 1 || entryFileName.includes("/") || entryFileName.includes("\\")) throw new TypeError(`Command entry file name must be a non-empty file name: ${entryFileName}`);
+	return entryFileName;
+}
+async function collectCommandFiles(dir, extensions, excludedFile, activeDirs = /* @__PURE__ */ new Set()) {
+	const canonicalDir = await realpath(dir);
+	if (activeDirs.has(canonicalDir)) return [];
+	const nextActiveDirs = new Set(activeDirs);
+	nextActiveDirs.add(canonicalDir);
+	const entries = await readdir(dir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name))) {
+		const path = resolve(dir, entry.name);
+		const entryType = await getCommandFileEntryType(path, entry);
+		if (entryType === "directory") files.push(...await collectCommandFiles(path, extensions, excludedFile, nextActiveDirs));
+		else if (entryType === "file" && path !== excludedFile && !isDeclarationFile(entry.name) && extensions.some((ext) => entry.name.endsWith(ext))) files.push(path);
+	}
+	return files;
+}
+async function getCommandFileEntryType(path, entry) {
+	if (entry.isDirectory()) return "directory";
+	if (entry.isFile()) return "file";
+	if (!entry.isSymbolicLink()) return void 0;
+	try {
+		const target = await stat(path);
+		if (target.isDirectory()) return "directory";
+		if (target.isFile()) return "file";
+		return void 0;
+	} catch {
+		return void 0;
+	}
+}
+function isDeclarationFile(fileName) {
+	return /\.d\.[cm]?ts$/.test(fileName);
+}
+function rejectDuplicateCommandPaths(files, options) {
+	const entryFileName = options.entryFileName ?? "index";
+	const seen = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const commandPath = commandPathFromModulePath(options.base, file.modulePath, options.extensions, entryFileName);
+		const key = commandPath.join("\0");
+		const previous = seen.get(key);
+		if (previous != null) throw new TypeError(`Duplicate command path "${displayCommandPath(commandPath)}" from ${previous} and ${file.modulePath}.`);
+		seen.set(key, file.modulePath);
+	}
+}
+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 normalizedBase = normalizeDerivedModulePath(base);
+	const normalizedPath = normalizeDerivedModulePath(modulePath);
+	const relativePath = posix.relative(normalizedBase, 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 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;
+}
+function displayCommandPath(path) {
+	return path.length < 1 ? "<root>" : path.join(" ");
+}
+function relativeModuleSpecifier(fromDir, target) {
+	const relativePath = normalizeRelativePath(relative(fromDir, target));
+	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+function relativeImportSpecifier(fromDir, target) {
+	const specifier = relativeModuleSpecifier(fromDir, target);
+	if (requiresEncodedImportSpecifier(specifier)) return encodeImportSpecifier(specifier);
+	return specifier;
+}
+function requiresEncodedImportSpecifier(specifier) {
+	return specifier.includes("#") || specifier.includes("?") || specifier.includes("%");
+}
+function encodeImportSpecifier(specifier) {
+	return specifier.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
+function normalizeRelativePath(path) {
+	return path.replaceAll("\\", "/");
+}
+function normalizeModulePath(path) {
+	return path.replaceAll("\\", "/");
+}
+function normalizeDerivedModulePath(path) {
+	return posix.normalize(normalizeModulePath(path));
+}
+function joinModulePath(base, relativePath) {
+	if (base === "." || base === "./") return `./${relativePath}`;
+	const prefix = base.endsWith("/") ? base.slice(0, -1) : base;
+	return `${prefix}/${relativePath}`;
+}
+function formatStringArray(values) {
+	return `[${values.map((value) => JSON.stringify(value)).join(", ")}]`;
+}
+function delay(ms, signal) {
+	if (signal?.aborted === true) return Promise.resolve();
+	return new Promise((resolve$1) => {
+		const onTimeout = () => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve$1();
+		};
+		const onAbort = () => {
+			clearTimeout(timeout);
+			resolve$1();
+		};
+		const timeout = setTimeout(onTimeout, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+//#endregion
+export { generateCommandsModule, watchCommandsModule, writeCommandsModule };