@alcyone-labs/arg-parser 1.2.0 → 2.1.0

package/dist/src/types.d.ts

@@ -1,165 +0,0 @@
-import { z } from "zod";
-export type ArgParserInstance = any;
-export declare const zodFlagSchema: z.ZodEffects<z.ZodObject<{
-    name: z.ZodString;
-    allowLigature: z.ZodDefault<z.ZodBoolean>;
-    allowMultiple: z.ZodDefault<z.ZodBoolean>;
-    description: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
-    options: z.ZodArray<z.ZodString, "many">;
-    defaultValue: z.ZodOptional<z.ZodAny>;
-    type: z.ZodDefault<z.ZodUnion<[z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodAny>, z.ZodEffects<z.ZodString, string, string>]>>;
-    mandatory: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodBoolean>]>>;
-    flagOnly: z.ZodDefault<z.ZodBoolean>;
-    validate: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodOptional<z.ZodAny>, z.ZodOptional<z.ZodAny>], z.ZodUnknown>, z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodVoid, z.ZodPromise<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodVoid]>>]>>>;
-    enum: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    name: z.ZodString;
-    allowLigature: z.ZodDefault<z.ZodBoolean>;
-    allowMultiple: z.ZodDefault<z.ZodBoolean>;
-    description: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
-    options: z.ZodArray<z.ZodString, "many">;
-    defaultValue: z.ZodOptional<z.ZodAny>;
-    type: z.ZodDefault<z.ZodUnion<[z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodAny>, z.ZodEffects<z.ZodString, string, string>]>>;
-    mandatory: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodBoolean>]>>;
-    flagOnly: z.ZodDefault<z.ZodBoolean>;
-    validate: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodOptional<z.ZodAny>, z.ZodOptional<z.ZodAny>], z.ZodUnknown>, z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodVoid, z.ZodPromise<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodVoid]>>]>>>;
-    enum: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    name: z.ZodString;
-    allowLigature: z.ZodDefault<z.ZodBoolean>;
-    allowMultiple: z.ZodDefault<z.ZodBoolean>;
-    description: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
-    options: z.ZodArray<z.ZodString, "many">;
-    defaultValue: z.ZodOptional<z.ZodAny>;
-    type: z.ZodDefault<z.ZodUnion<[z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodAny>, z.ZodEffects<z.ZodString, string, string>]>>;
-    mandatory: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodBoolean>]>>;
-    flagOnly: z.ZodDefault<z.ZodBoolean>;
-    validate: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodOptional<z.ZodAny>, z.ZodOptional<z.ZodAny>], z.ZodUnknown>, z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodVoid, z.ZodPromise<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodVoid]>>]>>>;
-    enum: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
-}, z.ZodTypeAny, "passthrough">>, {
-    [key: string]: any;
-}, z.objectInputType<{
-    name: z.ZodString;
-    allowLigature: z.ZodDefault<z.ZodBoolean>;
-    allowMultiple: z.ZodDefault<z.ZodBoolean>;
-    description: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
-    options: z.ZodArray<z.ZodString, "many">;
-    defaultValue: z.ZodOptional<z.ZodAny>;
-    type: z.ZodDefault<z.ZodUnion<[z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodEffects<z.ZodAny, any, any>, z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodAny>, z.ZodEffects<z.ZodString, string, string>]>>;
-    mandatory: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodBoolean>]>>;
-    flagOnly: z.ZodDefault<z.ZodBoolean>;
-    validate: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodOptional<z.ZodAny>, z.ZodOptional<z.ZodAny>], z.ZodUnknown>, z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodVoid, z.ZodPromise<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodVoid]>>]>>>;
-    enum: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
-}, z.ZodTypeAny, "passthrough">>;
-/**
- * The raw input type for defining a flag, before Zod processing (aliases, defaults).
- */
-export type IFlagCore = z.input<typeof zodFlagSchema>;
-/**
- * The type of the `type` property in a ProcessedFlagCore object.
- * This represents all valid forms the `type` property can take after Zod processing.
- */
-export type TParsedArgsTypeFromFlagDef = StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor | ((value: string) => any) | "string" | "number" | "boolean" | "array" | "object";
-/**
- * The core type of a flag after Zod processing (defaults applied, aliases resolved),
- * but before some properties are made more specific (like `type` constructor to actual type).
- * This type is output by `zodFlagSchema.parse()`.
- */
-export type ProcessedFlagCore = Omit<z.output<typeof zodFlagSchema>, "type"> & {
-    type: TParsedArgsTypeFromFlagDef;
-};
-/**
- * The user-facing type for defining a flag. It includes aliases like `default` and `required`.
- * The `handler` property is removed as handlers are typically associated with commands/subcommands, not individual flags.
- */
-export type IFlag = IFlagCore & {
-    /** @alias defaultValue */
-    default?: any;
-    /** @alias mandatory */
-    required?: boolean | ((parsedArgs: TParsedArgs<any>) => boolean);
-};
-/**
- * A more refined type for a flag after it has been fully processed by ArgParser,
- * particularly its `type` property and validation/enum/mandatory functions.
- * This is the type that ArgParser would internally work with for parsing and type extraction.
- */
-export type ProcessedFlag = Omit<ProcessedFlagCore, "validate" | "enum" | "mandatory"> & {
-    validate?: (value: any, parsedArgs?: TParsedArgs<ProcessedFlag[]>) => boolean | string | void | Promise<boolean | string | void>;
-    enum?: any[];
-    mandatory?: boolean | ((parsedArgs: TParsedArgs<ProcessedFlag[]>) => boolean);
-};
-/**
- * Resolves the TypeScript type from a flag's `type` definition.
- */
-export type ResolveType<T extends TParsedArgsTypeFromFlagDef> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends ArrayConstructor ? any[] : T extends ObjectConstructor ? Record<string, any> : T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "array" ? any[] : T extends "object" ? Record<string, any> : T extends (value: string) => infer R ? R : any;
-/**
- * Extracts the final TypeScript type for a flag's value based on its definition,
- * considering `flagOnly` and `allowMultiple` properties.
- */
-export type ExtractFlagType<TFlag extends ProcessedFlag> = TFlag["flagOnly"] extends true ? TFlag["allowMultiple"] extends true ? boolean[] : boolean : TFlag["allowMultiple"] extends true ? Array<ResolveType<TFlag["type"]>> : ResolveType<TFlag["type"]>;
-/**
- * Represents the structured object of parsed arguments.
- * Keys are flag names, and values are their parsed and typed values.
- * `TFlags` should be the array of `ProcessedFlag` definitions for the specific command.
- */
-export type TParsedArgs<TFlags extends readonly ProcessedFlag[]> = {
-    [K in TFlags[number]["name"]]: ExtractFlagType<Extract<TFlags[number], {
-        name: K;
-    }>>;
-};
-/**
- * Generic context object passed to command handlers.
- * @template TCurrentCommandArgs Shape of `args` for the current command, derived from its flags.
- * @template TParentCommandArgs Shape of `parentArgs` from the parent command, if any.
- */
-export type IHandlerContext<TCurrentCommandArgs extends Record<string, any> = Record<string, any>, TParentCommandArgs extends Record<string, any> = Record<string, any>> = {
-    /** Parsed arguments specific to the current command. */
-    args: TCurrentCommandArgs;
-    /** Parsed arguments from the parent command, if this is a subcommand. */
-    parentArgs?: TParentCommandArgs;
-    /** The sequence of command names that led to this handler. */
-    commandChain: string[];
-    /** The `ArgParser` instance that invoked this handler (could be a subcommand's parser). */
-    parser: ArgParserInstance;
-    /** The parent `ArgParser` instance, if this is a subcommand handler. */
-    parentParser?: ArgParserInstance;
-    /** Optional: The root `ArgParser` instance of the CLI. */
-    /** Indicates if the handler is being called from MCP mode (true) or CLI mode (false). */
-    isMcp?: boolean;
-};
-/**
- * Generic type for the collection of processed flags that an ArgParser instance manages.
- */
-export type FlagsArray = readonly ProcessedFlag[];
-/**
- * Defines a subcommand within an ArgParser setup.
- * @template TSubCommandFlags Flags defined specifically FOR this subcommand.
- * @template TParentCommandFlags Flags defined for the PARENT of this subcommand.
- * @template THandlerReturn The expected return type of the subcommand's handler.
- */
-export interface ISubCommand<TSubCommandFlags extends FlagsArray = FlagsArray, TParentCommandFlags extends FlagsArray = FlagsArray, THandlerReturn = any> {
-    name: string;
-    description?: string;
-    /** The ArgParser instance for this subcommand, typed with its own flags. */
-    parser: ArgParserInstance;
-    /** Handler function for this subcommand. */
-    handler?: (ctx: IHandlerContext<TParsedArgs<TSubCommandFlags>, TParsedArgs<TParentCommandFlags>>) => THandlerReturn | Promise<THandlerReturn>;
-    /** Internal flag to identify MCP subcommands for proper exclusion from tool generation */
-    isMcp?: boolean;
-    /** MCP server information for DXT generation */
-    mcpServerInfo?: {
-        name: string;
-        version: string;
-        description?: string;
-    };
-    /** MCP tool generation options for DXT generation */
-    mcpToolOptions?: any;
-}
-/**
- * Type for the main handler of an ArgParser instance (root command or a command defined by an ArgParser).
- * @template TParserFlags Flags defined for this ArgParser instance.
- * @template TParentParserFlags Flags of the parent parser, if this parser is used as a subcommand.
- * @template THandlerReturn The expected return type of the handler.
- */
-export type MainHandler<TParserFlags extends FlagsArray = FlagsArray, TParentParserFlags extends FlagsArray = FlagsArray, THandlerReturn = any> = (ctx: IHandlerContext<TParsedArgs<TParserFlags>, TParsedArgs<TParentParserFlags>>) => THandlerReturn | Promise<THandlerReturn>;
-//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}