@alcyone-labs/arg-parser 2.0.0 → 2.1.1

package/dist/{src/core → core}/types.d.ts

@@ -133,6 +133,156 @@ export type IHandlerContext<TCurrentCommandArgs extends Record<string, any> = Re
  * Generic type for the collection of processed flags that an ArgParser instance manages.
  */
 export type FlagsArray = readonly ProcessedFlag[];
+/**
+ * Converts a flag type to a JSON Schema type string.
+ * This function handles all possible flag type formats and returns a valid JSON Schema type.
+ *
+ * @param flagType - The flag type from IFlag or ProcessedFlag
+ * @returns A JSON Schema type string: "string" | "number" | "boolean" | "array" | "object"
+ *
+ * @example
+ * ```typescript
+ * getJsonSchemaTypeFromFlag(String) // returns "string"
+ * getJsonSchemaTypeFromFlag("number") // returns "number"
+ * getJsonSchemaTypeFromFlag((val) => parseInt(val)) // returns "string" (fallback for custom functions)
+ * ```
+ */
+export declare function getJsonSchemaTypeFromFlag(flagType: TParsedArgsTypeFromFlagDef): "string" | "number" | "boolean" | "array" | "object";
+/**
+ * Common output schema patterns for typical CLI/MCP tool responses
+ */
+export declare const OutputSchemaPatterns: {
+    /**
+     * Simple success/error response pattern
+     * @example { success: true, message: "Operation completed" }
+     */
+    readonly successError: () => z.ZodObject<{
+        success: z.ZodBoolean;
+        message: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        success: boolean;
+        message?: string | undefined;
+        error?: string | undefined;
+    }, {
+        success: boolean;
+        message?: string | undefined;
+        error?: string | undefined;
+    }>;
+    /**
+     * Success response with data payload
+     * @example { success: true, data: {...}, message: "Data retrieved" }
+     */
+    readonly successWithData: (dataSchema?: z.ZodTypeAny) => z.ZodObject<{
+        success: z.ZodBoolean;
+        data: z.ZodTypeAny;
+        message: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        success: boolean;
+        message?: string | undefined;
+        error?: string | undefined;
+        data?: any;
+    }, {
+        success: boolean;
+        message?: string | undefined;
+        error?: string | undefined;
+        data?: any;
+    }>;
+    /**
+     * List/array response pattern
+     * @example { items: [...], count: 5, hasMore: false }
+     */
+    readonly list: (itemSchema?: z.ZodTypeAny) => z.ZodObject<{
+        items: z.ZodArray<z.ZodTypeAny, "many">;
+        count: z.ZodOptional<z.ZodNumber>;
+        hasMore: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        items: any[];
+        count?: number | undefined;
+        hasMore?: boolean | undefined;
+    }, {
+        items: any[];
+        count?: number | undefined;
+        hasMore?: boolean | undefined;
+    }>;
+    /**
+     * File operation response pattern
+     * @example { path: "/path/to/file", size: 1024, created: true }
+     */
+    readonly fileOperation: () => z.ZodObject<{
+        path: z.ZodString;
+        size: z.ZodOptional<z.ZodNumber>;
+        created: z.ZodOptional<z.ZodBoolean>;
+        modified: z.ZodOptional<z.ZodBoolean>;
+        exists: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        size?: number | undefined;
+        created?: boolean | undefined;
+        modified?: boolean | undefined;
+        exists?: boolean | undefined;
+    }, {
+        path: string;
+        size?: number | undefined;
+        created?: boolean | undefined;
+        modified?: boolean | undefined;
+        exists?: boolean | undefined;
+    }>;
+    /**
+     * Process execution response pattern
+     * @example { exitCode: 0, stdout: "output", stderr: "", duration: 1500 }
+     */
+    readonly processExecution: () => z.ZodObject<{
+        exitCode: z.ZodNumber;
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        command: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        exitCode: number;
+        stdout?: string | undefined;
+        stderr?: string | undefined;
+        duration?: number | undefined;
+        command?: string | undefined;
+    }, {
+        exitCode: number;
+        stdout?: string | undefined;
+        stderr?: string | undefined;
+        duration?: number | undefined;
+        command?: string | undefined;
+    }>;
+};
+/**
+ * Type for output schema pattern names with auto-completion support
+ */
+export type OutputSchemaPatternName = keyof typeof OutputSchemaPatterns;
+/**
+ * Type for output schema configuration - supports pattern names, Zod schemas, or schema definition objects
+ */
+export type OutputSchemaConfig = OutputSchemaPatternName | z.ZodTypeAny | Record<string, z.ZodTypeAny>;
+/**
+ * Creates a Zod output schema from a pattern or custom definition
+ *
+ * @param pattern - Either a predefined pattern name, a Zod schema, or a schema definition object
+ * @returns A Zod schema for output validation
+ *
+ * @example
+ * ```typescript
+ * // Using a predefined pattern
+ * const schema1 = createOutputSchema('successError');
+ *
+ * // Using a custom Zod schema
+ * const schema2 = createOutputSchema(z.object({ result: z.string() }));
+ *
+ * // Using a schema definition object
+ * const schema3 = createOutputSchema({
+ *   result: z.string().describe("The result"),
+ *   timestamp: z.string().describe("When the operation completed")
+ * });
+ * ```
+ */
+export declare function createOutputSchema(pattern: OutputSchemaConfig): z.ZodTypeAny;
 /**
  * Defines a subcommand within an ArgParser setup.
  * @template TSubCommandFlags Flags defined specifically FOR this subcommand.
@@ -177,6 +327,7 @@ export interface ParseResult<T = any> {
 }
 /**
  * Configuration options for ArgParser behavior
+ * @deprecated Use IArgParserParams for full configuration options. This interface will be removed in v3.0.
  */
 export interface ArgParserOptions {
     /** Whether to automatically call process.exit() based on ParseResult (default: true for backward compatibility) */
@@ -184,6 +335,16 @@ export interface ArgParserOptions {
     /** Whether to handle errors by exiting or throwing (default: true for backward compatibility) */
     handleErrors?: boolean;
 }
+/**
+ * Configuration options for ArgParser runtime behavior
+ * This is a more clearly named version of ArgParserOptions
+ */
+export interface ArgParserBehaviorOptions {
+    /** Whether to automatically call process.exit() based on ParseResult (default: true for backward compatibility) */
+    autoExit?: boolean;
+    /** Whether to handle errors by exiting or throwing (default: true for backward compatibility) */
+    handleErrors?: boolean;
+}
 /**
  * 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.

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

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

package/dist/{src/dxt → dxt}/DxtGenerator.d.ts

@@ -103,10 +103,6 @@ export declare class DxtGenerator {
      * Sets up DXT package files (manifest.json) in the dxt output directory
      */
     private setupDxtPackageFiles;
-    /**
-     * Maps ArgParser flag types to JSON Schema types
-     */
-    private mapFlagTypeToJsonSchema;
     /**
      * Manually copy logo since TSDown's copy option doesn't work programmatically
      */

package/dist/dxt/DxtGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DxtGenerator.d.ts","sourceRoot":"","sources":["../../src/dxt/DxtGenerator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,iBAAiB,CAAM;gBAEnB,iBAAiB,EAAE,GAAG;IAIlC;;OAEG;IACH,OAAO,CAAC,WAAW;IAiBnB;;OAEG;IACU,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,WAAW,CAAC;IAmC7G;;OAEG;YACW,2BAA2B;IA2EzC;;;OAGG;IACU,kBAAkB,CAAC,aAAa,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0FvF;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA8B5B,OAAO,CAAC,sBAAsB;IA8D9B,OAAO,CAAC,iBAAiB;IAiFzB,OAAO,CAAC,mBAAmB;IAuC3B,OAAO,CAAC,kBAAkB;IAqC1B,OAAO,CAAC,oBAAoB;IA8D5B;;OAEG;IACH,OAAO,CAAC,eAAe;IA4CvB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAqF/B,OAAO,CAAC,eAAe;IAkGvB;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAwBnC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA8DhC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAO/B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;YACW,eAAe;IAqF7B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA2D9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAmJ9B;;OAEG;YACW,kBAAkB;IAuHhC;;OAEG;YACW,2BAA2B;IAiIzC;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAyD9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA4BhC;;OAEG;YACW,oBAAoB;IA8JlC;;OAEG;YACW,gBAAgB;CAgC/B"}