@alcyone-labs/arg-parser 3.0.0 → 3.0.1

package/dist/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -19,17 +20,31 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-let __alcyone_labs_simple_chalk = require("@alcyone-labs/simple-chalk");
-__alcyone_labs_simple_chalk = __toESM(__alcyone_labs_simple_chalk);
+//#endregion
+let _alcyone_labs_simple_chalk = require("@alcyone-labs/simple-chalk");
+_alcyone_labs_simple_chalk = __toESM(_alcyone_labs_simple_chalk);
 let zod = require("zod");
 let node_path = require("node:path");
 node_path = __toESM(node_path);
-const FlagInheritance = {
+//#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 = zod.z.object({
+/**
+* Zod schema for validating DXT-specific options
+*/
+var zodDxtOptionsSchema = zod.z.object({
 	sensitive: zod.z.boolean().optional(),
 	localDefault: zod.z.string().optional(),
 	type: zod.z.enum([
@@ -51,7 +66,7 @@ const zodDxtOptionsSchema = zod.z.object({
 	message: "min cannot be greater than max",
 	path: ["min"]
 });
-const zodFlagSchema = zod.z.object({
+var zodFlagSchema = zod.z.object({
 	name: zod.z.string().min(1),
 	allowLigature: zod.z.boolean().default(true),
 	allowMultiple: zod.z.boolean().default(false),
@@ -101,7 +116,7 @@ function getJsonSchemaTypeFromFlag(flagType) {
 	}
 	return "string";
 }
-const OutputSchemaPatterns = {
+var OutputSchemaPatterns = {
 	successError: () => zod.z.object({
 		success: zod.z.boolean(),
 		message: zod.z.string().optional(),
@@ -139,6 +154,17 @@ function createOutputSchema(pattern) {
 	if (pattern && typeof pattern === "object") return zod.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();
@@ -149,6 +175,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)) {
@@ -165,46 +194,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();
@@ -220,6 +282,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();
@@ -231,20 +298,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 = [];
@@ -273,10 +358,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);
@@ -285,6 +384,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;
@@ -326,42 +435,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;
@@ -373,20 +515,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;
 	}
@@ -408,6 +565,9 @@ var ArgParser = class {
 	getPromptWhen() {
 		return this.#promptWhen;
 	}
+	/**
+	* Parse command line arguments
+	*/
 	async parse(processArgs, options = {}) {
 		const args = processArgs || process.argv.slice(2);
 		try {
@@ -434,12 +594,15 @@ var ArgParser = class {
 		} catch (error) {
 			if (error instanceof ArgParserError) {
 				if (!this.#handleErrors) throw error;
-				console.error(__alcyone_labs_simple_chalk.default.red(error.message));
+				console.error(_alcyone_labs_simple_chalk.default.red(error.message));
 				return this.handleExit(1, error.message, "error");
 			}
 			throw error;
 		}
 	}
+	/**
+	* Parse flags only
+	*/
 	async parseFlags(args, _options = {}) {
 		const result = {};
 		const flags = this.#flagManager.getAllFlags();
@@ -473,6 +636,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);
@@ -480,6 +646,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 = [];
@@ -498,6 +667,9 @@ var ArgParser = class {
 			remainingArgs
 		};
 	}
+	/**
+	* Detect and strip system flags
+	*/
 	detectAndStripSystemFlags(args) {
 		const systemArgs = {};
 		const filteredArgs = [];
@@ -520,6 +692,9 @@ var ArgParser = class {
 			filteredArgs
 		};
 	}
+	/**
+	* Handle exit
+	*/
 	handleExit(exitCode, message, type) {
 		const result = {
 			success: exitCode === 0,
@@ -531,18 +706,21 @@ var ArgParser = class {
 		if (this.#autoExit && typeof process !== "undefined" && process.exit) process.exit(exitCode);
 		return result;
 	}
+	/**
+	* Generate help text
+	*/
 	helpText() {
 		const lines = [];
-		lines.push(__alcyone_labs_simple_chalk.default.bold(this.#appName));
+		lines.push(_alcyone_labs_simple_chalk.default.bold(this.#appName));
 		if (this.#description) lines.push(this.#description);
 		lines.push("");
 		const commandName = this.#appCommandName || this.#appName.toLowerCase();
-		lines.push(__alcyone_labs_simple_chalk.default.bold("Usage:"));
+		lines.push(_alcyone_labs_simple_chalk.default.bold("Usage:"));
 		lines.push(`  ${commandName} [options] [command]`);
 		lines.push("");
 		const flags = this.#flagManager.getAllFlags();
 		if (flags.length > 0) {
-			lines.push(__alcyone_labs_simple_chalk.default.bold("Options:"));
+			lines.push(_alcyone_labs_simple_chalk.default.bold("Options:"));
 			for (const flag of flags) {
 				const options = flag.options.join(", ");
 				const defaultStr = flag.defaultValue !== void 0 ? ` (default: ${flag.defaultValue})` : "";
@@ -552,18 +730,29 @@ var ArgParser = class {
 			lines.push("");
 		}
 		if (this.#subCommands.size > 0) {
-			lines.push(__alcyone_labs_simple_chalk.default.bold("Commands:"));
+			lines.push(_alcyone_labs_simple_chalk.default.bold("Commands:"));
 			for (const [name, sub] of this.#subCommands) lines.push(`  ${name.padEnd(20)} ${sub.description || ""}`);
 			lines.push("");
 		}
 		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`);
@@ -572,36 +761,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) {
@@ -642,7 +869,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() {}
@@ -650,7 +877,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);
 	},
@@ -661,10 +896,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 node_path.resolve(process.argv[1]);
 	return process.cwd();
 }
+/**
+* Get entry point from import.meta.url
+*/
 function getEntryPointFromImportMeta(importMetaUrl) {
 	try {
 		return new URL(importMetaUrl).pathname;
@@ -672,18 +922,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 node_path.resolve(process.cwd(), logPath.slice(4));
 		if (logPath.startsWith("entry:")) {
-			const entryPoint$2 = detectEntryPoint();
-			const entryDir$2 = node_path.dirname(entryPoint$2);
-			return node_path.resolve(entryDir$2, logPath.slice(6));
+			const entryPoint = detectEntryPoint();
+			const entryDir = node_path.dirname(entryPoint);
+			return node_path.resolve(entryDir, logPath.slice(6));
 		}
 		if (node_path.isAbsolute(logPath)) return logPath;
-		const entryPoint$1 = detectEntryPoint();
-		const entryDir$1 = node_path.dirname(entryPoint$1);
-		return node_path.resolve(entryDir$1, logPath);
+		const entryPoint = detectEntryPoint();
+		const entryDir = node_path.dirname(entryPoint);
+		return node_path.resolve(entryDir, logPath);
 	}
 	const { path: pathStr, relativeTo = "entry", basePath } = logPath;
 	if (relativeTo === "absolute") return pathStr;
@@ -692,20 +945,33 @@ function resolveLogPath(logPath) {
 	const entryDir = node_path.dirname(entryPoint);
 	return node_path.resolve(entryDir, pathStr);
 }
+/**
+* Create a path relative to the entry point
+*/
 function entryRelative(subPath) {
 	const entryPoint = detectEntryPoint();
 	const entryDir = node_path.dirname(entryPoint);
 	return node_path.resolve(entryDir, subPath);
 }
+/**
+* Create a path relative to the current working directory
+*/
 function cwdRelative(subPath) {
 	return node_path.resolve(process.cwd(), subPath);
 }
+/**
+* Create an absolute path
+*/
 function absolutePath(pathStr) {
 	return node_path.resolve(pathStr);
 }
+/**
+* Legacy cwd-relative path (for backward compatibility)
+*/
 function legacyCwdPath(subPath) {
 	return cwdRelative(subPath);
 }
+//#endregion
 exports.ArgParser = ArgParser;
 exports.ArgParserError = ArgParserError;
 exports.ConfigPlugin = ConfigPlugin;
@@ -720,7 +986,7 @@ exports.PromptManager = PromptManager;
 Object.defineProperty(exports, "SimpleChalk", {
 	enumerable: true,
 	get: function() {
-		return __alcyone_labs_simple_chalk.default;
+		return _alcyone_labs_simple_chalk.default;
 	}
 });
 exports.absolutePath = absolutePath;