@alcyone-labs/arg-parser 3.0.0 → 3.0.1

package/dist/index.mjs

@@ -1,16 +1,31 @@
 import SimpleChalk, { default as chalk } from "@alcyone-labs/simple-chalk";
 import { z } from "zod";
 import * as path from "node:path";
+//#region \0rolldown/runtime.js
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
 	if (typeof require !== "undefined") return require.apply(this, arguments);
-	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function.");
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
 });
-const FlagInheritance = {
+//#endregion
+//#region src/core/types.ts
+/**
+* Core types for ArgParser
+*
+* These types define the shape of flags, commands, and configuration
+* for the argument parser.
+*/
+/**
+* Defines the behavior for flag inheritance in sub-commands.
+*/
+var FlagInheritance = {
 	NONE: "none",
 	DirectParentOnly: "direct-parent-only",
 	AllParents: "all-parents"
 };
-const zodDxtOptionsSchema = z.object({
+/**
+* Zod schema for validating DXT-specific options
+*/
+var zodDxtOptionsSchema = z.object({
 	sensitive: z.boolean().optional(),
 	localDefault: z.string().optional(),
 	type: z.enum([
@@ -32,7 +47,7 @@ const zodDxtOptionsSchema = z.object({
 	message: "min cannot be greater than max",
 	path: ["min"]
 });
-const zodFlagSchema = z.object({
+var zodFlagSchema = z.object({
 	name: z.string().min(1),
 	allowLigature: z.boolean().default(true),
 	allowMultiple: z.boolean().default(false),
@@ -82,7 +97,7 @@ function getJsonSchemaTypeFromFlag(flagType) {
 	}
 	return "string";
 }
-const OutputSchemaPatterns = {
+var OutputSchemaPatterns = {
 	successError: () => z.object({
 		success: z.boolean(),
 		message: z.string().optional(),
@@ -120,6 +135,17 @@ function createOutputSchema(pattern) {
 	if (pattern && typeof pattern === "object") return z.object(pattern);
 	return OutputSchemaPatterns.successError();
 }
+//#endregion
+//#region src/core/FlagManager.ts
+/**
+* FlagManager - Manages flag definitions and collision detection
+*
+* This class handles the registration, storage, and retrieval of CLI flags.
+* It provides collision detection to prevent duplicate flag definitions.
+*/
+/**
+* Manages flag definitions for an ArgParser instance
+*/
 var FlagManager = class {
 	constructor(options = {}, initialFlags = []) {
 		this.flags = /* @__PURE__ */ new Map();
@@ -130,6 +156,9 @@ var FlagManager = class {
 		};
 		for (const flag of initialFlags) this.addFlag(flag);
 	}
+	/**
+	* Add a single flag
+	*/
 	addFlag(flag) {
 		const processedFlag = this.processFlag(flag);
 		if (this.flags.has(processedFlag.name)) {
@@ -146,46 +175,79 @@ var FlagManager = class {
 		}
 		this.flags.set(processedFlag.name, processedFlag);
 	}
+	/**
+	* Add multiple flags
+	*/
 	addFlags(flags) {
 		for (const flag of flags) this.addFlag(flag);
 	}
+	/**
+	* Remove a flag by name
+	*/
 	removeFlag(name) {
 		const flag = this.flags.get(name);
 		if (!flag) return false;
 		for (const option of flag.options) this.optionToFlagMap.delete(option);
 		return this.flags.delete(name);
 	}
+	/**
+	* Check if a flag exists
+	*/
 	hasFlag(name) {
 		return this.flags.has(name);
 	}
+	/**
+	* Get a flag by name
+	*/
 	getFlag(name) {
 		return this.flags.get(name);
 	}
+	/**
+	* Get all flags as an array
+	*/
 	getAllFlags() {
 		return Array.from(this.flags.values());
 	}
+	/**
+	* Get all flag names
+	*/
 	getFlagNames() {
 		return Array.from(this.flags.keys());
 	}
+	/**
+	* Find flag by option
+	*/
 	findFlagByOption(option) {
 		const flagName = this.optionToFlagMap.get(option);
 		if (!flagName) return void 0;
 		return this.flags.get(flagName);
 	}
+	/**
+	* Process a raw flag into a ProcessedFlag
+	*/
 	processFlag(flag) {
 		const rawFlag = { ...flag };
 		if ("default" in rawFlag && rawFlag.default !== void 0 && !("defaultValue" in rawFlag)) rawFlag.defaultValue = rawFlag.default;
 		if ("required" in rawFlag && rawFlag.required !== void 0 && !("mandatory" in rawFlag)) rawFlag.mandatory = rawFlag.required;
 		return zodFlagSchema.parse(rawFlag);
 	}
+	/**
+	* Internal method to set a processed flag directly (for inheritance)
+	*/
 	_setProcessedFlagForInheritance(flag) {
 		this.flags.set(flag.name, flag);
 		for (const option of flag.options) this.optionToFlagMap.set(option, flag.name);
 	}
+	/**
+	* Clear all flags
+	*/
 	clear() {
 		this.flags.clear();
 		this.optionToFlagMap.clear();
 	}
+	/**
+	* Get collision report
+	*/
 	getCollisions() {
 		const collisions = [];
 		const seen = /* @__PURE__ */ new Map();
@@ -201,6 +263,11 @@ var FlagManager = class {
 		return collisions;
 	}
 };
+//#endregion
+//#region src/core/PromptManager.ts
+/**
+* Manages interactive prompts for an ArgParser instance
+*/
 var PromptManager = class {
 	constructor(options = {}) {
 		this.promptableFlags = /* @__PURE__ */ new Map();
@@ -212,20 +279,38 @@ var PromptManager = class {
 	get sequenceOffset() {
 		return this._options.sequenceOffset ?? 0;
 	}
+	/**
+	* Register a promptable flag
+	*/
 	registerPromptableFlag(flag) {
 		this.promptableFlags.set(flag.name, flag);
 	}
+	/**
+	* Unregister a promptable flag
+	*/
 	unregisterPromptableFlag(name) {
 		return this.promptableFlags.delete(name);
 	}
+	/**
+	* Check if a flag has a prompt
+	*/
 	hasPrompt(name) {
 		return this.promptableFlags.has(name);
 	}
+	/**
+	* Get all promptable flags sorted by sequence
+	*/
 	getPromptableFlags() {
 		return Array.from(this.promptableFlags.values()).sort((a, b) => {
 			return (a.promptSequence ?? Infinity) - (b.promptSequence ?? Infinity);
 		});
 	}
+	/**
+	* Execute prompts for missing flags
+	*
+	* This is a placeholder implementation. The actual implementation
+	* would integrate with @clack/prompts.
+	*/
 	async executePrompts(context, missingFlagNames) {
 		const answers = {};
 		const results = [];
@@ -254,10 +339,24 @@ var PromptManager = class {
 			cancelled: false
 		};
 	}
+	/**
+	* Clear all registered flags
+	*/
 	clear() {
 		this.promptableFlags.clear();
 	}
 };
+//#endregion
+//#region src/core/ArgParser.ts
+/**
+* Core ArgParser implementation
+*
+* This is the main ArgParser class with full CLI parsing capabilities.
+* It has NO dependencies on MCP, DXT, or TUI - those are provided by plugins.
+*/
+/**
+* Error thrown by ArgParser
+*/
 var ArgParserError = class extends Error {
 	constructor(message, cmdChain = []) {
 		super(message);
@@ -266,6 +365,16 @@ var ArgParserError = class extends Error {
 		this.commandChain = cmdChain;
 	}
 };
+/**
+* Core ArgParser class
+*
+* Provides complete CLI argument parsing with support for:
+* - Flags (with types, validation, defaults)
+* - Subcommands
+* - Interactive prompts
+* - Help generation
+* - Plugin system
+*/
 var ArgParser = class {
 	#appName = "Argument Parser";
 	#appCommandName;
@@ -307,42 +416,75 @@ var ArgParser = class {
 		});
 		if (params.subCommands) for (const sub of params.subCommands) this.addSubCommand(sub);
 	}
+	/**
+	* Install a plugin
+	*/
 	use(plugin) {
 		if (this.#plugins.has(plugin.name)) throw new Error(`Plugin '${plugin.name}' is already installed`);
 		const result = plugin.install(this);
 		this.#plugins.set(plugin.name, plugin);
 		return result || this;
 	}
+	/**
+	* Check if a plugin is installed
+	*/
 	hasPlugin(name) {
 		return this.#plugins.has(name);
 	}
+	/**
+	* Get an installed plugin
+	*/
 	getPlugin(name) {
 		return this.#plugins.get(name);
 	}
+	/**
+	* List all installed plugins
+	*/
 	listPlugins() {
 		return Array.from(this.#plugins.keys());
 	}
+	/**
+	* Add a flag
+	*/
 	addFlag(flag) {
 		this.#flagManager.addFlag(flag);
 		if ("prompt" in flag && typeof flag.prompt === "function") this.#promptManager.registerPromptableFlag(flag);
 		return this;
 	}
+	/**
+	* Add multiple flags
+	*/
 	addFlags(flags) {
 		for (const flag of flags) this.addFlag(flag);
 		return this;
 	}
+	/**
+	* Check if a flag exists
+	*/
 	hasFlag(name) {
 		return this.#flagManager.hasFlag(name);
 	}
+	/**
+	* Get a flag definition
+	*/
 	getFlagDefinition(name) {
 		return this.#flagManager.getFlag(name);
 	}
+	/**
+	* Get all flags
+	*/
 	get flags() {
 		return this.#flagManager.getAllFlags();
 	}
+	/**
+	* Get all flag names
+	*/
 	get flagNames() {
 		return this.#flagManager.getFlagNames();
 	}
+	/**
+	* Add a subcommand
+	*/
 	addSubCommand(subCommand) {
 		if (this.#subCommands.has(subCommand.name)) throw new Error(`Subcommand '${subCommand.name}' already exists`);
 		const subParser = subCommand.parser;
@@ -354,20 +496,35 @@ var ArgParser = class {
 		this.#subCommands.set(subCommand.name, subCommand);
 		return this;
 	}
+	/**
+	* Get a subcommand
+	*/
 	getSubCommand(name) {
 		return this.#subCommands.get(name);
 	}
+	/**
+	* Get all subcommands
+	*/
 	getSubCommands() {
 		return new Map(this.#subCommands);
 	}
+	/**
+	* Inherit flags to a sub-parser
+	*/
 	inheritFlagsToSubParser(subParser) {
 		const parentFlags = this.#flagManager.getAllFlags();
 		for (const flag of parentFlags) if (!subParser.hasFlag(flag.name)) subParser.#flagManager._setProcessedFlagForInheritance(flag);
 	}
+	/**
+	* Set the handler
+	*/
 	setHandler(handler) {
 		this.#handler = handler;
 		return this;
 	}
+	/**
+	* Get the handler
+	*/
 	getHandler() {
 		return this.#handler;
 	}
@@ -389,6 +546,9 @@ var ArgParser = class {
 	getPromptWhen() {
 		return this.#promptWhen;
 	}
+	/**
+	* Parse command line arguments
+	*/
 	async parse(processArgs, options = {}) {
 		const args = processArgs || process.argv.slice(2);
 		try {
@@ -421,6 +581,9 @@ var ArgParser = class {
 			throw error;
 		}
 	}
+	/**
+	* Parse flags only
+	*/
 	async parseFlags(args, _options = {}) {
 		const result = {};
 		const flags = this.#flagManager.getAllFlags();
@@ -454,6 +617,9 @@ var ArgParser = class {
 		if (missingFlags.length > 0) throw new ArgParserError(`Missing mandatory flags: ${missingFlags.join(", ")}`, [this.#appName]);
 		return result;
 	}
+	/**
+	* Parse a flag value based on type
+	*/
 	parseFlagValue(value, type) {
 		if (type === Boolean || type === "boolean") return /^(true|yes|1)$/i.test(value);
 		if (type === Number || type === "number") return Number(value);
@@ -461,6 +627,9 @@ var ArgParser = class {
 		if (typeof type === "function") return type(value);
 		return value;
 	}
+	/**
+	* Find the command chain for subcommands
+	*/
 	findCommandChain(args) {
 		let currentParser = this;
 		const commandChain = [];
@@ -479,6 +648,9 @@ var ArgParser = class {
 			remainingArgs
 		};
 	}
+	/**
+	* Detect and strip system flags
+	*/
 	detectAndStripSystemFlags(args) {
 		const systemArgs = {};
 		const filteredArgs = [];
@@ -501,6 +673,9 @@ var ArgParser = class {
 			filteredArgs
 		};
 	}
+	/**
+	* Handle exit
+	*/
 	handleExit(exitCode, message, type) {
 		const result = {
 			success: exitCode === 0,
@@ -512,6 +687,9 @@ var ArgParser = class {
 		if (this.#autoExit && typeof process !== "undefined" && process.exit) process.exit(exitCode);
 		return result;
 	}
+	/**
+	* Generate help text
+	*/
 	helpText() {
 		const lines = [];
 		lines.push(chalk.bold(this.#appName));
@@ -540,11 +718,22 @@ var ArgParser = class {
 		return lines.join("\n");
 	}
 };
+//#endregion
+//#region src/plugin/types.ts
+/**
+* Plugin registry for managing installed plugins
+*
+* This class tracks which plugins are installed on a parser instance
+* and provides methods for introspection.
+*/
 var PluginRegistry = class {
 	constructor() {
 		this.plugins = /* @__PURE__ */ new Map();
 		this.metadata = /* @__PURE__ */ new Map();
 	}
+	/**
+	* Register a plugin in the registry
+	*/
 	register(plugin, metadata) {
 		if (this.plugins.has(plugin.name)) {
 			console.warn(`[ArgParser] Plugin '${plugin.name}' is already registered`);
@@ -553,36 +742,74 @@ var PluginRegistry = class {
 		this.plugins.set(plugin.name, plugin);
 		if (metadata) this.metadata.set(plugin.name, metadata);
 	}
+	/**
+	* Get a registered plugin by name
+	*/
 	get(name) {
 		return this.plugins.get(name);
 	}
+	/**
+	* Check if a plugin is registered
+	*/
 	has(name) {
 		return this.plugins.has(name);
 	}
+	/**
+	* List all registered plugin names
+	*/
 	list() {
 		return Array.from(this.plugins.keys());
 	}
+	/**
+	* Get metadata for a plugin
+	*/
 	getMetadata(name) {
 		return this.metadata.get(name);
 	}
+	/**
+	* Unregister a plugin
+	*/
 	unregister(name) {
 		const plugin = this.plugins.get(name);
 		if (plugin?.destroy) plugin.destroy();
 		this.metadata.delete(name);
 		return this.plugins.delete(name);
 	}
+	/**
+	* Clear all registered plugins
+	*/
 	clear() {
 		for (const [, plugin] of this.plugins) if (plugin.destroy) plugin.destroy();
 		this.plugins.clear();
 		this.metadata.clear();
 	}
 };
-const globalPluginRegistry = new PluginRegistry();
+/**
+* Global plugin registry for system-wide plugin management
+*/
+var globalPluginRegistry = new PluginRegistry();
+/**
+* Decorator for plugin methods that should be exposed on the parser
+* 
+* @example
+* ```typescript
+* class MyPlugin implements IArgParserPlugin {
+*   name = 'my-plugin';
+*   
+@expose()
+*   myMethod(parser: ArgParserBase, ...args: any[]) {
+*     // Implementation
+*   }
+* }
+* ```
+*/
 function expose(_target, propertyKey, descriptor) {
 	descriptor.value._isExposed = true;
 	descriptor.value._exposedName = propertyKey;
 	return descriptor;
 }
+//#endregion
+//#region src/config/plugins/index.ts
 var ConfigPlugin = class {};
 var JsonConfigPlugin = class extends ConfigPlugin {
 	constructor(..._args) {
@@ -623,7 +850,7 @@ var ConfigPluginRegistry = class {
 		for (const plugin of this.plugins.values()) if (plugin.canLoad(source)) return plugin;
 	}
 };
-const globalConfigPluginRegistry = new ConfigPluginRegistry();
+var globalConfigPluginRegistry = new ConfigPluginRegistry();
 globalConfigPluginRegistry.register(new JsonConfigPlugin());
 globalConfigPluginRegistry.register(new EnvConfigPlugin());
 async function enableOptionalConfigPlugins() {}
@@ -631,7 +858,15 @@ async function enableOptionalConfigPluginsAsync() {
 	await enableOptionalConfigPlugins();
 }
 function enableConfigPlugins() {}
-const debug = {
+//#endregion
+//#region src/utils/debug-utils.ts
+/**
+* Debug utilities for ArgParser
+*/
+/**
+* Debug logger that only logs when DEBUG environment variable is set
+*/
+var debug = {
 	log: (...args) => {
 		if (process.env["DEBUG"] || process.env["ARG_PARSER_DEBUG"]) console.log("[ArgParser Debug]", ...args);
 	},
@@ -642,10 +877,25 @@ const debug = {
 		if (process.env["DEBUG"] || process.env["ARG_PARSER_DEBUG"]) console.warn("[ArgParser Debug]", ...args);
 	}
 };
+//#endregion
+//#region src/core/log-path-utils.ts
+/**
+* Log path utilities for ArgParser
+*
+* Provides flexible path resolution for log files, supporting
+* relative paths (to entry point or cwd), absolute paths, and
+* configuration objects.
+*/
+/**
+* Detect the entry point of the application
+*/
 function detectEntryPoint() {
 	if (process.argv[1]) return path.resolve(process.argv[1]);
 	return process.cwd();
 }
+/**
+* Get entry point from import.meta.url
+*/
 function getEntryPointFromImportMeta(importMetaUrl) {
 	try {
 		return new URL(importMetaUrl).pathname;
@@ -653,18 +903,21 @@ function getEntryPointFromImportMeta(importMetaUrl) {
 		return process.cwd();
 	}
 }
+/**
+* Resolve a log path to an absolute path
+*/
 function resolveLogPath(logPath) {
 	if (typeof logPath === "string") {
 		if (logPath.startsWith("cwd:")) return path.resolve(process.cwd(), logPath.slice(4));
 		if (logPath.startsWith("entry:")) {
-			const entryPoint$2 = detectEntryPoint();
-			const entryDir$2 = path.dirname(entryPoint$2);
-			return path.resolve(entryDir$2, logPath.slice(6));
+			const entryPoint = detectEntryPoint();
+			const entryDir = path.dirname(entryPoint);
+			return path.resolve(entryDir, logPath.slice(6));
 		}
 		if (path.isAbsolute(logPath)) return logPath;
-		const entryPoint$1 = detectEntryPoint();
-		const entryDir$1 = path.dirname(entryPoint$1);
-		return path.resolve(entryDir$1, logPath);
+		const entryPoint = detectEntryPoint();
+		const entryDir = path.dirname(entryPoint);
+		return path.resolve(entryDir, logPath);
 	}
 	const { path: pathStr, relativeTo = "entry", basePath } = logPath;
 	if (relativeTo === "absolute") return pathStr;
@@ -673,20 +926,33 @@ function resolveLogPath(logPath) {
 	const entryDir = path.dirname(entryPoint);
 	return path.resolve(entryDir, pathStr);
 }
+/**
+* Create a path relative to the entry point
+*/
 function entryRelative(subPath) {
 	const entryPoint = detectEntryPoint();
 	const entryDir = path.dirname(entryPoint);
 	return path.resolve(entryDir, subPath);
 }
+/**
+* Create a path relative to the current working directory
+*/
 function cwdRelative(subPath) {
 	return path.resolve(process.cwd(), subPath);
 }
+/**
+* Create an absolute path
+*/
 function absolutePath(pathStr) {
 	return path.resolve(pathStr);
 }
+/**
+* Legacy cwd-relative path (for backward compatibility)
+*/
 function legacyCwdPath(subPath) {
 	return cwdRelative(subPath);
 }
+//#endregion
 export { ArgParser, ArgParserError, ConfigPlugin, ConfigPluginRegistry, EnvConfigPlugin, FlagInheritance, FlagManager, JsonConfigPlugin, OutputSchemaPatterns, PluginRegistry, PromptManager, SimpleChalk, absolutePath, createOutputSchema, cwdRelative, debug, detectEntryPoint, enableConfigPlugins, enableOptionalConfigPlugins, enableOptionalConfigPluginsAsync, entryRelative, expose, getEntryPointFromImportMeta, getJsonSchemaTypeFromFlag, globalConfigPluginRegistry, globalPluginRegistry, legacyCwdPath, resolveLogPath, zodDxtOptionsSchema, zodFlagSchema };
 
 //# sourceMappingURL=index.mjs.map