/**
 * Unified CLI argument parsing utilities
 *
 * Provides a single, consistent way to extract and validate CLI arguments.
 *
 * @module cli/shared/args
 */
import type { Schema } from "../../src/extensions/schema/index.js";
import type { ParsedArgs } from "./types.js";
/** Compat type for safeParse result (SafeParseReturnType removed in zod v4). */
export type SafeParseResult<T> = {
    success: true;
    data: T;
    error?: never;
} | {
    success: false;
    data?: never;
    error: Error & {
        issues: unknown[];
    };
};
/**
 * Argument specification for a single option
 */
export interface ArgSpec {
    /** Possible argument keys to check (e.g., ["project-slug", "p"]) */
    keys: string[];
    /** Type of the argument: "array" handles CSV strings and repeated flags */
    type: "string" | "boolean" | "number" | "array";
    /** Positional argument index (0 = first arg after command) */
    positional?: number;
}
/**
 * Map of schema field names to their arg specs
 */
export type ArgMap<T> = {
    [K in keyof T]?: ArgSpec;
};
export interface ArgParserOptions {
    /** Reject option keys that the command parser does not consume. */
    rejectUnknown?: boolean;
}
/**
 * Extract a single argument value from parsed args
 */
export declare function extractArg(args: ParsedArgs, spec: ArgSpec): string | boolean | number | string[] | undefined;
/**
 * Extract all arguments according to an arg map
 */
export declare function extractArgs<T>(args: ParsedArgs, argMap: ArgMap<T>): Record<string, unknown>;
/**
 * Create a typed argument parser for a command
 *
 * @example
 * ```ts
 * const getPullArgsSchema = defineSchema((v) => v.object({
 *   projectSlug: v.string().optional(),
 *   projectDir: v.string().optional(),
 *   force: v.boolean().default(false),
 * }));
 * const PullArgsSchema = getPullArgsSchema();
 *
 * const parsePullArgs = createArgParser(PullArgsSchema, {
 *   projectSlug: { keys: ["project", "p"], type: "string", positional: 0 },
 *   projectDir: { keys: ["project-dir", "dir", "d"], type: "string" },
 *   force: { keys: ["force", "f"], type: "boolean" },
 * });
 *
 * const result = parsePullArgs(args);
 * if (result.success) {
 *   // result.data is typed as PullOptions
 * }
 * ```
 */
export declare function createArgParser<T>(schema: Schema<T>, argMap: ArgMap<T>, options?: ArgParserOptions): (args: ParsedArgs) => SafeParseResult<T>;
/**
 * Parse args with a parser function and throw on failure.
 * Eliminates the repeated parse-validate-throw boilerplate in handlers.
 */
export declare function parseArgsOrThrow<T>(parser: (args: ParsedArgs) => SafeParseResult<T>, commandName: string, args: ParsedArgs): T;
/**
 * Common arg specs for reuse across commands
 */
export declare const CommonArgs: {
    force: {
        keys: string[];
        type: "boolean";
    };
    dryRun: {
        keys: string[];
        type: "boolean";
    };
    branch: {
        keys: string[];
        type: "string";
    };
    env: {
        keys: string[];
        type: "string";
    };
    projectDir: {
        keys: string[];
        type: "string";
    };
    projectSlug: {
        keys: string[];
        type: "string";
    };
    quiet: {
        keys: string[];
        type: "boolean";
    };
    releaseName: {
        keys: string[];
        type: "string";
    };
    into: {
        keys: string[];
        type: "string";
    };
    release: {
        keys: string[];
        type: "string";
    };
    output: {
        keys: string[];
        type: "string";
    };
    json: {
        keys: string[];
        type: "boolean";
    };
};
/** Boolean options accepted by every command, regardless of the command word. */
export declare const GLOBAL_BOOLEAN_FLAGS: ReadonlySet<string>;
/**
 * Boolean options used when the command word cannot resolve an option's arity —
 * an unknown command, or a flag that appears before the command word. Every
 * documented long-name boolean in `COMMANDS` must be listed here, otherwise it
 * is parsed as value-taking and swallows the positional that follows it.
 * `cli/shared/args.test.ts` asserts that invariant.
 */
export declare const BOOLEAN_FLAGS: ReadonlySet<string>;
/** Parse raw CLI arguments into a structured `ParsedArgs` object with aliases. */
export declare function parseCliArgs(args: string[]): ParsedArgs;
//# sourceMappingURL=args.d.ts.map